/** * @license * Copyright 2019 Google LLC * SPDX-License-Identifier: BSD-3-Clause */ /** * Whether the current browser supports `adoptedStyleSheets`. */ declare const supportsAdoptingStyleSheets: boolean; /** * A CSSResult or native CSSStyleSheet. * * In browsers that support constructible CSS style sheets, CSSStyleSheet * object can be used for styling along side CSSResult from the `css` * template tag. */ type CSSResultOrNative = CSSResult | CSSStyleSheet; type CSSResultArray = Array; /** * A single CSSResult, CSSStyleSheet, or an array or nested arrays of those. */ type CSSResultGroup = CSSResultOrNative | CSSResultArray; /** * A container for a string of CSS text, that may be used to create a CSSStyleSheet. * * CSSResult is the return value of `css`-tagged template literals and * `unsafeCSS()`. In order to ensure that CSSResults are only created via the * `css` tag and `unsafeCSS()`, CSSResult cannot be constructed directly. */ declare class CSSResult { ['_$cssResult$']: boolean; readonly cssText: string; private _styleSheet?; private _strings; private constructor(); get styleSheet(): CSSStyleSheet | undefined; toString(): string; } /** * Wrap a value for interpolation in a {@linkcode css} tagged template literal. * * This is unsafe because untrusted CSS text can be used to phone home * or exfiltrate data to an attacker controlled site. Take care to only use * this with trusted input. */ declare const unsafeCSS: (value: unknown) => CSSResult; /** * A template literal tag which can be used with LitElement's * {@linkcode LitElement.styles} property to set element styles. * * For security reasons, only literal string values and number may be used in * embedded expressions. To incorporate non-literal values {@linkcode unsafeCSS} * may be used inside an expression. */ declare const css: (strings: TemplateStringsArray, ...values: (CSSResultGroup | number)[]) => CSSResult; /** * Applies the given styles to a `shadowRoot`. When Shadow DOM is * available but `adoptedStyleSheets` is not, styles are appended to the * `shadowRoot` to [mimic the native feature](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/adoptedStyleSheets). * Note, when shimming is used, any styles that are subsequently placed into * the shadowRoot should be placed *before* any shimmed adopted styles. This * will match spec behavior that gives adopted sheets precedence over styles in * shadowRoot. */ declare const adoptStyles: (renderRoot: ShadowRoot, styles: Array) => void; declare const getCompatibleStyle: (s: CSSResultOrNative) => CSSResultOrNative; /** * @license * Copyright 2021 Google LLC * SPDX-License-Identifier: BSD-3-Clause */ /** * An object that can host Reactive Controllers and call their lifecycle * callbacks. */ interface ReactiveControllerHost { /** * Adds a controller to the host, which sets up the controller's lifecycle * methods to be called with the host's lifecycle. */ addController(controller: ReactiveController): void; /** * Removes a controller from the host. */ removeController(controller: ReactiveController): void; /** * Requests a host update which is processed asynchronously. The update can * be waited on via the `updateComplete` property. */ requestUpdate(): void; /** * Returns a Promise that resolves when the host 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()`. If the Promise is rejected, an * exception was thrown during the update. * * @return A promise of a boolean that indicates if the update resolved * without triggering another update. */ readonly updateComplete: Promise; } /** * A Reactive Controller is an object that enables sub-component code * organization and reuse by aggregating the state, behavior, and lifecycle * hooks related to a single feature. * * Controllers are added to a host component, or other object that implements * the `ReactiveControllerHost` interface, via the `addController()` method. * They can hook their host components's lifecycle by implementing one or more * of the lifecycle callbacks, or initiate an update of the host component by * calling `requestUpdate()` on the host. */ interface ReactiveController { /** * Called when the host is connected to the component tree. For custom * element hosts, this corresponds to the `connectedCallback()` lifecycle, * which is only called when the component is connected to the document. */ hostConnected?(): void; /** * Called when the host is disconnected from the component tree. For custom * element hosts, this corresponds to the `disconnectedCallback()` lifecycle, * which is called the host or an ancestor component is disconnected from the * document. */ hostDisconnected?(): void; /** * Called during the client-side host update, just before the host calls * its own update. * * Code in `update()` can depend on the DOM as it is not called in * server-side rendering. */ hostUpdate?(): void; /** * Called after a host update, just before the host calls firstUpdated and * updated. It is not called in server-side rendering. * */ hostUpdated?(): void; } /** * @license * Copyright 2017 Google LLC * SPDX-License-Identifier: BSD-3-Clause */ /** * Use this module if you want to create your own base class extending * {@link ReactiveElement}. * @packageDocumentation */ /** * Contains types that are part of the unstable debug API. * * Everything in this API is not stable and may change or be removed in the future, * even on patch releases. */ declare namespace ReactiveUnstable { /** * When Lit is running in dev mode and `window.emitLitDebugLogEvents` is true, * we will emit 'lit-debug' events to window, with live details about the update and render * lifecycle. These can be useful for writing debug tooling and visualizations. * * Please be aware that running with window.emitLitDebugLogEvents has performance overhead, * making certain operations that are normally very cheap (like a no-op render) much slower, * because we must copy data and dispatch events. */ namespace DebugLog { type Entry = Update; interface Update { kind: 'update'; } } } /** * Converts property values to and from attribute values. */ interface ComplexAttributeConverter { /** * Called to convert an attribute value to a property * value. */ fromAttribute?(value: string | null, type?: TypeHint): Type; /** * Called to convert a property value to an attribute * value. * * It returns unknown instead of string, to be compatible with * https://github.com/WICG/trusted-types (and similar efforts). */ toAttribute?(value: Type, type?: TypeHint): unknown; } type AttributeConverter = ComplexAttributeConverter | ((value: string | null, type?: TypeHint) => Type); /** * Defines options for a property accessor. */ interface PropertyDeclaration { /** * When set to `true`, indicates the property is internal private state. The * property should not be set by users. When using TypeScript, this property * should be marked as `private` or `protected`, and it is also a common * practice to use a leading `_` in the name. The property is not added to * `observedAttributes`. */ readonly state?: boolean; /** * 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'`). */ readonly attribute?: boolean | string; /** * 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. */ readonly 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. */ readonly converter?: AttributeConverter; /** * 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. */ readonly reflect?: 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. */ hasChanged?(value: Type, oldValue: Type): 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. */ readonly noAccessor?: boolean; /** * When `true`, uses the initial value of the property as the default value, * which changes how attributes are handled: * - The initial value does *not* reflect, even if the `reflect` option is `true`. * Subsequent changes to the property will reflect, even if they are equal to the * default value. * - When the attribute is removed, the property is set to the default value * - The initial value will not trigger an old value in the `changedProperties` map * argument to update lifecycle methods. * * When set, properties must be initialized, either with a field initializer, or an * assignment in the constructor. Not initializing the property may lead to * improper handling of subsequent property assignments. * * While this behavior is opt-in, most properties that reflect to attributes should * use `useDefault: true` so that their initial values do not reflect. */ useDefault?: boolean; } /** * Map of properties to PropertyDeclaration options. For each property an * accessor is made, and the property is processed according to the * PropertyDeclaration options. */ interface PropertyDeclarations { readonly [key: string]: PropertyDeclaration; } type PropertyDeclarationMap = Map; /** * A Map of property keys to values. * * Takes an optional type parameter T, which when specified as a non-any, * non-unknown type, will make the Map more strongly-typed, associating the map * keys with their corresponding value type on T. * * Use `PropertyValues` when overriding ReactiveElement.update() and * other lifecycle methods in order to get stronger type-checking on keys * and values. */ type PropertyValues = T extends object ? PropertyValueMap : Map; /** * Do not use, instead prefer {@linkcode PropertyValues}. */ interface PropertyValueMap extends Map { get(k: K): T[K] | undefined; set(key: K, value: T[K]): this; has(k: K): boolean; delete(k: K): boolean; } declare const defaultConverter: ComplexAttributeConverter; interface HasChanged { (value: unknown, old: unknown): boolean; } /** * Change function that returns true if `value` is different from `oldValue`. * This method is used as the default for a property's `hasChanged` function. */ declare const notEqual: HasChanged; /** * A string representing one of the supported dev mode warning categories. */ type WarningKind = 'change-in-update' | 'migration' | 'async-perform-update'; type Initializer = (element: ReactiveElement) => void; declare global { interface SymbolConstructor { readonly metadata: unique symbol; } } declare global { var litPropertyMetadata: WeakMap>; } /** * Base element class which manages element properties and attributes. When * properties change, the `update` method is asynchronously called. This method * should be supplied by subclasses to render updates as desired. * @noInheritDoc */ declare abstract class ReactiveElement extends HTMLElement implements ReactiveControllerHost { /** * Read or set all the enabled warning categories for this class. * * This property is only used in development builds. * * @nocollapse * @category dev-mode */ static enabledWarnings?: WarningKind[]; /** * Enable the given warning category for this class. * * This method only exists in development builds, so it should be accessed * with a guard like: * * ```ts * // Enable for all ReactiveElement subclasses * ReactiveElement.enableWarning?.('migration'); * * // Enable for only MyElement and subclasses * MyElement.enableWarning?.('migration'); * ``` * * @nocollapse * @category dev-mode */ static enableWarning?: (warningKind: WarningKind) => void; /** * Disable the given warning category for this class. * * This method only exists in development builds, so it should be accessed * with a guard like: * * ```ts * // Disable for all ReactiveElement subclasses * ReactiveElement.disableWarning?.('migration'); * * // Disable for only MyElement and subclasses * MyElement.disableWarning?.('migration'); * ``` * * @nocollapse * @category dev-mode */ static disableWarning?: (warningKind: WarningKind) => void; /** * Adds an initializer function to the class that is called during instance * construction. * * This is useful for code that runs against a `ReactiveElement` * subclass, such as a decorator, that needs to do work for each * instance, such as setting up a `ReactiveController`. * * ```ts * const myDecorator = (target: typeof ReactiveElement, key: string) => { * target.addInitializer((instance: ReactiveElement) => { * // This is run during construction of the element * new MyController(instance); * }); * } * ``` * * Decorating a field will then cause each instance to run an initializer * that adds a controller: * * ```ts * class MyElement extends LitElement { * @myDecorator foo; * } * ``` * * Initializers are stored per-constructor. Adding an initializer to a * subclass does not add it to a superclass. Since initializers are run in * constructors, initializers will run in order of the class hierarchy, * starting with superclasses and progressing to the instance's class. * * @nocollapse */ static addInitializer(initializer: Initializer): void; static _initializers?: Initializer[]; /** * Maps attribute names to properties; for example `foobar` attribute to * `fooBar` property. Created lazily on user subclasses when finalizing the * class. * @nocollapse */ private static __attributeToPropertyMap; /** * Marks class as having been finalized, which includes creating properties * from `static properties`, but does *not* include all properties created * from decorators. * @nocollapse */ protected static finalized: true | undefined; /** * Memoized list of all element properties, including any superclass * properties. Created lazily on user subclasses when finalizing the class. * * @nocollapse * @category properties */ static elementProperties: PropertyDeclarationMap; /** * User-supplied object that maps property names to `PropertyDeclaration` * objects containing options for configuring reactive properties. When * a reactive property is set the element will update and render. * * By default properties are public fields, and as such, they should be * considered as primarily settable by element users, either via attribute or * the property itself. * * Generally, properties that are changed by the element should be private or * protected fields and should use the `state: true` option. Properties * marked as `state` do not reflect from the corresponding attribute * * However, sometimes element code does need to set a public property. This * should typically only be done in response to user interaction, and an event * should be fired informing the user; for example, a checkbox sets its * `checked` property when clicked and fires a `changed` event. Mutating * public properties should typically not be done for non-primitive (object or * array) properties. In other cases when an element needs to manage state, a * private property set with the `state: true` option should be used. When * needed, state properties can be initialized via public properties to * facilitate complex interactions. * @nocollapse * @category properties */ static properties: PropertyDeclarations; /** * Memoized list of all element styles. * Created lazily on user subclasses when finalizing the class. * @nocollapse * @category styles */ static elementStyles: Array; /** * Array of styles to apply to the element. The styles should be defined * using the {@linkcode css} tag function, via constructible stylesheets, or * imported from native CSS module scripts. * * Note on Content Security Policy: * * Element styles are implemented with `