@polymer/lit-element

  • Version 0.7.1
  • Published
  • 202 kB
  • 1 dependency
  • BSD-3-Clause license

Install

npm i @polymer/lit-element
yarn add @polymer/lit-element
pnpm add @polymer/lit-element

Overview

Polymer based lit-html custom element

Index

Variables

variable defaultConverter

const defaultConverter: ComplexAttributeConverter<any, any>;

    variable notEqual

    const notEqual: HasChanged;
    • Change function that returns true if value is different from oldValue. This method is used as the default for a property's hasChanged function.

    variable supportsAdoptingStyleSheets

    const supportsAdoptingStyleSheets: boolean;
    • Copyright (c) 2019 The Polymer Project Authors. All rights reserved. This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt Code distributed by Google as part of the polymer project is also subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt

    Functions

    function css

    css: (strings: TemplateStringsArray, ...values: CSSResult[]) => CSSResult;

      function customElement

      customElement: (
      tagName: string
      ) => (classOrDescriptor: ClassDescriptor | Constructor<HTMLElement>) => any;
      • Class decorator factory that defines the decorated class as a custom element.

        Parameter tagName

        the name of the custom element to define

        In TypeScript, the tagName passed to customElement should be a key of the HTMLElementTagNameMap interface. To add your element to the interface, declare the interface in this module:

        @customElement('my-element') export class MyElement extends LitElement {}

        declare global { interface HTMLElementTagNameMap { 'my-element': MyElement; } }

      function eventOptions

      eventOptions: (options: AddEventListenerOptions) => any;
      • Adds event listener options to a method used as an event listener in a lit-html template.

        Parameter options

        An object that specifis event listener options as accepted by EventTarget#addEventListener and EventTarget#removeEventListener.

        Current browsers support the capture, passive, and once options. See: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#Parameters

        Example 1

        class MyElement {

        clicked = false;

        render() { return html<div @click=${this._onClick}>`; }

        @eventOptions({capture: true}) _onClick(e) { this.clicked = true; } }

      function property

      property: (
      options?: PropertyDeclaration<any, any> | undefined
      ) => (
      protoOrDescriptor: Object | ClassElement,
      name?: string | number | symbol | undefined
      ) => any;
      • A property decorator which creates a LitElement property which reflects a corresponding attribute value. A PropertyDeclaration may optionally be supplied to configure property features.

      function query

      query: (
      selector: string
      ) => (
      protoOrDescriptor: Object | ClassElement,
      name?: string | number | symbol | undefined
      ) => any;
      • A property decorator that converts a class property into a getter that executes a querySelector on the element's renderRoot.

      function queryAll

      queryAll: (
      selector: string
      ) => (
      protoOrDescriptor: Object | ClassElement,
      name?: string | number | symbol | undefined
      ) => any;
      • A property decorator that converts a class property into a getter that executes a querySelectorAll on the element's renderRoot.

      Classes

      class CSSResult

      class CSSResult {}

        constructor

        constructor(cssText: string);

          property cssText

          readonly cssText: string;

            property styleSheet

            readonly styleSheet: CSSStyleSheet;

              class LitElement

              class LitElement extends UpdatingElement {}

                property finalized

                protected static finalized: boolean;
                • Ensure this class is marked as finalized as an optimization ensuring it will not needlessly try to finalize.

                property render

                static render: (
                result: TemplateResult,
                container: Element | DocumentFragment,
                options: any
                ) => void;
                • Render method used to render the lit-html TemplateResult to the element's DOM.

                  Parameter Template

                  to render.

                  Parameter Node

                  into which to render.

                  Parameter Element

                  name.

                property renderRoot

                protected renderRoot?: Element | DocumentFragment;
                • Node or ShadowRoot into which element DOM should be rendered. Defaults to an open shadowRoot.

                property styles

                static readonly styles: CSSResult[];
                • Array of styles to apply to the element. The styles should be defined using the css tag function.

                method adoptStyles

                protected adoptStyles: () => void;
                • Applies styling to the element shadowRoot using the static get styles property. Styling will apply using shadowRoot.adoptedStyleSheets where available and will fallback otherwise. When Shadow DOM is polyfilled, ShadyCSS scopes styles and adds them to the document. When Shadow DOM is available but adoptedStyleSheets is not, styles are appended to the end of the shadowRoot to [mimic spec behavior](https://wicg.github.io/construct-stylesheets/#using-constructed-stylesheets).

                method connectedCallback

                connectedCallback: () => void;

                  method createRenderRoot

                  protected createRenderRoot: () => Element | ShadowRoot;
                  • Returns the node into which the element should render and by default creates and returns an open shadowRoot. Implement to customize where the element's DOM is rendered. For example, to render into the element's childNodes, return this.

                    Returns

                    {Element|DocumentFragment} Returns a node into which to render.

                  method initialize

                  protected initialize: () => void;
                  • Performs element initialization. By default this calls createRenderRoot to create the element renderRoot node and captures any pre-set values for registered properties.

                  method render

                  protected render: () => TemplateResult | void;
                  • Invoked on each update to perform rendering tasks. This method must return a lit-html TemplateResult. Setting properties inside this method will *not* trigger the element to update.

                  method update

                  protected update: (changedProperties: PropertyValues) => void;
                  • Updates the element. This method reflects property values to attributes and calls render to render DOM via lit-html. Setting properties inside this method will *not* trigger another update. *

                    Parameter _changedProperties

                    Map of changed properties with old values

                  class UpdatingElement

                  abstract class UpdatingElement extends HTMLElement {}
                  • Base element class which manages element properties and attributes. When properties change, the update method is asynchronously called. This method should be supplied by subclassers to render updates as desired.

                  constructor

                  constructor();

                    property finalized

                    protected static finalized: boolean;
                    • Marks class as having finished creating properties.

                    property hasUpdated

                    protected readonly hasUpdated: number;

                      property observedAttributes

                      static readonly observedAttributes: string[];
                      • Returns a list of attributes corresponding to the registered properties.

                      property properties

                      static properties: PropertyDeclarations;
                      • User-supplied object that maps property names to PropertyDeclaration objects containing options for configuring the property.

                      property updateComplete

                      readonly updateComplete: Promise<unknown>;
                      • Returns a Promise that resolves when the element has completed updating. The Promise value is a boolean that is true if the element completed the update without triggering another update. The Promise result is false if a property was set inside updated(). This getter can be implemented to await additional state. For example, it is sometimes useful to await a rendered element before fulfilling this Promise. To do this, first await super.updateComplete then any subsequent state.

                        Returns

                        {Promise} The Promise returns a boolean that indicates if the update resolved without triggering another update.

                      method attributeChangedCallback

                      attributeChangedCallback: (name: string, old: string, value: string) => void;
                      • Synchronizes property values when attributes change.

                      method connectedCallback

                      connectedCallback: () => void;

                        method createProperty

                        static createProperty: (
                        name: PropertyKey,
                        options?: PropertyDeclaration
                        ) => void;
                        • Creates a property accessor on the element prototype if one does not exist. The property setter calls the property's hasChanged property option or uses a strict identity check to determine whether or not to request an update.

                        method disconnectedCallback

                        disconnectedCallback: () => void;
                        • Allows for super.disconnectedCallback() in extensions while reserving the possibility of making non-breaking feature additions when disconnecting at some point in the future.

                        method firstUpdated

                        protected firstUpdated: (_changedProperties: PropertyValues) => void;
                        • Invoked when the element is first updated. Implement to perform one time work on the element after update.

                          Setting properties inside this method will trigger the element to update again after this update cycle completes.

                          *

                          Parameter _changedProperties

                          Map of changed properties with old values

                        method initialize

                        protected initialize: () => void;
                        • Performs element initialization. By default captures any pre-set values for registered properties.

                        method performUpdate

                        protected performUpdate: () => void | Promise<unknown>;
                        • Performs an element update.

                          You can override this method to change the timing of updates. For instance, to schedule updates to occur just before the next frame:

                          protected async performUpdate(): Promise<unknown> {
                          await new Promise((resolve) => requestAnimationFrame(() => resolve()));
                          super.performUpdate();
                          }

                        method requestUpdate

                        requestUpdate: (name?: PropertyKey, oldValue?: any) => Promise<unknown>;
                        • Requests an update which is processed asynchronously. This should be called when an element should update based on some state not triggered by setting a property. In this case, pass no arguments. It should also be called when manually implementing a property setter. In this case, pass the property name and oldValue to ensure that any configured property options are honored. Returns the updateComplete Promise which is resolved when the update completes.

                          Parameter name

                          (optional) name of requesting property

                          Parameter oldValue

                          (optional) old value of requesting property

                          Returns

                          {Promise} A Promise that is resolved when the update completes.

                        method shouldUpdate

                        protected shouldUpdate: (_changedProperties: PropertyValues) => boolean;
                        • Controls whether or not update should be called when the element requests an update. By default, this method always returns true, but this can be customized to control when to update.

                          *

                          Parameter _changedProperties

                          Map of changed properties with old values

                        method update

                        protected update: (_changedProperties: PropertyValues) => void;
                        • Updates the element. This method reflects property values to attributes. It can be overridden to render and keep updated element DOM. Setting properties inside this method will *not* trigger another update.

                          *

                          Parameter _changedProperties

                          Map of changed properties with old values

                        method updated

                        protected updated: (_changedProperties: PropertyValues) => void;
                        • Invoked whenever the element is updated. Implement to perform post-updating tasks via DOM APIs, for example, focusing an element.

                          Setting properties inside this method will trigger the element to update again after this update cycle completes.

                          *

                          Parameter _changedProperties

                          Map of changed properties with old values

                        Interfaces

                        interface ComplexAttributeConverter

                        interface ComplexAttributeConverter<Type = any, TypeHint = any> {}
                        • Converts property values to and from attribute values.

                        method fromAttribute

                        fromAttribute: (value: string, type?: TypeHint) => Type;
                        • Function called to convert an attribute value to a property value.

                        method toAttribute

                        toAttribute: (value: Type, type?: TypeHint) => string | null;
                        • Function called to convert a property value to an attribute value.

                        interface HasChanged

                        interface HasChanged {}

                          call signature

                          (value: unknown, old: unknown): boolean;

                            interface PropertyDeclaration

                            interface PropertyDeclaration<Type = any, TypeHint = any> {}
                            • Defines options for a property accessor.

                            property attribute

                            attribute?: boolean | string;
                            • Indicates how and whether the property becomes an observed attribute. If the value is false, the property is not added to observedAttributes. If true or absent, the lowercased property name is observed (e.g. fooBar becomes foobar). If a string, the string value is observed (e.g attribute: 'foo-bar').

                            property converter

                            converter?: AttributeConverter<Type, TypeHint>;
                            • Indicates how to convert the attribute to/from a property. If this value is a function, it is used to convert the attribute value a the property value. If it's an object, it can have keys for fromAttribute and toAttribute. If no toAttribute function is provided and reflect is set to true, the property value is set directly to the attribute. A default converter is used if none is provided; it supports Boolean, String, Number, Object, and Array. Note, when a property changes and the converter is used to update the attribute, the property is never updated again as a result of the attribute changing, and vice versa.

                            property noAccessor

                            noAccessor?: boolean;
                            • Indicates whether an accessor will be created for this property. By default, an accessor will be generated for this property that requests an update when set. If this flag is true, no accessor will be created, and it will be the user's responsibility to call this.requestUpdate(propertyName, oldValue) to request an update when the property changes.

                            property reflect

                            reflect?: boolean;
                            • Indicates if the property should reflect to an attribute. If true, when the property is set, the attribute is set using the attribute name determined according to the rules for the attribute property option and the value of the property converted using the rules from the converter property option.

                            property type

                            type?: TypeHint;
                            • Indicates the type of the property. This is used only as a hint for the converter to determine how to convert the attribute to/from a property.

                            method hasChanged

                            hasChanged: (value: Type, oldValue: Type) => boolean;
                            • A function that indicates if a property should be considered changed when it is set. The function should take the newValue and oldValue and return true if an update should be requested.

                            interface PropertyDeclarations

                            interface PropertyDeclarations {}
                            • Map of properties to PropertyDeclaration options. For each property an accessor is made, and the property is processed according to the PropertyDeclaration options.

                            index signature

                            [key: string]: PropertyDeclaration;

                              Type Aliases

                              type Constructor

                              type Constructor<T> = {
                              new (...args: any[]): T;
                              };

                                type PropertyValues

                                type PropertyValues = Map<PropertyKey, unknown>;

                                  Package Files (4)

                                  Dependencies (1)

                                  Dev Dependencies (20)

                                  Peer Dependencies (0)

                                  No peer dependencies.

                                  Badge

                                  To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                  You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@polymer/lit-element.

                                  • Markdown
                                    [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@polymer/lit-element)
                                  • HTML
                                    <a href="https://www.jsdocs.io/package/@polymer/lit-element"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>