/**
* @license
* Copyright 2017 Google LLC
* SPDX-License-Identifier: BSD-3-Clause
*/
///
import type { Directive } from './directive.js';
/**
* Used to sanitize any value before it is written into the DOM. This can be
* used to implement a security policy of allowed and disallowed values in
* order to prevent XSS attacks.
*
* One way of using this callback would be to check attributes and properties
* against a list of high risk fields, and require that values written to such
* fields be instances of a class which is safe by construction. Closure's Safe
* HTML Types is one implementation of this technique (
* https://github.com/google/safe-html-types/blob/master/doc/safehtml-types.md).
* The TrustedTypes polyfill in API-only mode could also be used as a basis
* for this technique (https://github.com/WICG/trusted-types).
*
* @param node The HTML node (usually either a #text node or an Element) that
* is being written to. Note that this is just an exemplar node, the write
* may take place against another instance of the same class of node.
* @param name The name of an attribute or property (for example, 'href').
* @param type Indicates whether the write that's about to be performed will
* be to a property or a node.
* @return A function that will sanitize this class of writes.
*/
export declare type SanitizerFactory = (node: Node, name: string, type: 'property' | 'attribute') => ValueSanitizer;
/**
* A function which can sanitize values that will be written to a specific kind
* of DOM sink.
*
* See SanitizerFactory.
*
* @param value The value to sanitize. Will be the actual value passed into
* the lit-html template literal, so this could be of any type.
* @return The value to write to the DOM. Usually the same as the input value,
* unless sanitization is needed.
*/
export declare type ValueSanitizer = (value: unknown) => unknown;
/** TemplateResult types */
declare const HTML_RESULT = 1;
declare const SVG_RESULT = 2;
declare type ResultType = typeof HTML_RESULT | typeof SVG_RESULT;
/**
* The return type of the template tag functions.
*/
export declare type TemplateResult = {
['_$litType$']: T;
strings: TemplateStringsArray;
values: unknown[];
};
export declare type HTMLTemplateResult = TemplateResult;
export declare type SVGTemplateResult = TemplateResult;
export interface CompiledTemplateResult {
['_$litType$']: CompiledTemplate;
values: unknown[];
}
export interface CompiledTemplate extends Omit {
el?: HTMLTemplateElement;
h: TrustedHTML;
}
/**
* Interprets a template literal as an HTML template that can efficiently
* render to and update a container.
*
* ```ts
* const header = (title: string) => html`
${title}
`;
* ```
*
* The `html` tag returns a description of the DOM to render as a value. It is
* lazy, meaning no work is done until the template is rendered. When rendering,
* if a template comes from the same expression as a previously rendered result,
* it's efficiently updated instead of replaced.
*/
export declare const html: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult<1>;
/**
* Interprets a template literal as an SVG template that can efficiently
* render to and update a container.
*/
export declare const svg: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult<2>;
/**
* A sentinel value that signals that a value was handled by a directive and
* should not be written to the DOM.
*/
export declare const noChange: unique symbol;
/**
* A sentinel value that signals a ChildPart to fully clear its content.
*
* ```ts
* const button = html`${
* user.isAdmin
* ? html``
* : nothing
* }`;
* ```
*
* Prefer using `nothing` over other falsy values as it provides a consistent
* behavior between various expression binding contexts.
*
* In child expressions, `undefined`, `null`, `''`, and `nothing` all behave the
* same and render no nodes. In attribute expressions, `nothing` _removes_ the
* attribute, while `undefined` and `null` will render an empty string. In
* property expressions `nothing` becomes `undefined`.
*/
export declare const nothing: unique symbol;
/**
* Object specifying options for controlling lit-html rendering. Note that
* while `render` may be called multiple times on the same `container` (and
* `renderBefore` reference node) to efficiently update the rendered content,
* only the options passed in during the first render are respected during
* the lifetime of renders to that unique `container` + `renderBefore`
* combination.
*/
export interface RenderOptions {
/**
* An object to use as the `this` value for event listeners. It's often
* useful to set this to the host component rendering a template.
*/
host?: object;
/**
* A DOM node before which to render content in the container.
*/
renderBefore?: ChildNode | null;
/**
* Node used for cloning the template (`importNode` will be called on this
* node). This controls the `ownerDocument` of the rendered DOM, along with
* any inherited context. Defaults to the global `document`.
*/
creationScope?: {
importNode(node: Node, deep?: boolean): Node;
};
/**
* The initial connected state for the top-level part being rendered. If no
* `isConnected` option is set, `AsyncDirective`s will be connected by
* default. Set to `false` if the initial render occurs in a disconnected tree
* and `AsyncDirective`s should see `isConnected === false` for their initial
* render. The `part.setConnected()` method must be used subsequent to initial
* render to change the connected state of the part.
*/
isConnected?: boolean;
}
/**
* Renders a value, usually a lit-html TemplateResult, to the container.
* @param value
* @param container
* @param options
*/
export declare const render: {
(value: unknown, container: HTMLElement | DocumentFragment, options?: RenderOptions | undefined): RootPart;
setSanitizer: (newSanitizer: SanitizerFactory) => void;
createSanitizer: SanitizerFactory;
_testOnlyClearSanitizerFactoryDoNotCallOrElse: () => void;
};
export interface DirectiveParent {
_$parent?: DirectiveParent;
_$isConnected: boolean;
__directive?: Directive;
__directives?: Array;
}
declare class Template {
constructor({ strings, ['_$litType$']: type }: TemplateResult, options?: RenderOptions);
/** @nocollapse */
static createElement(html: TrustedHTML, _options?: RenderOptions): HTMLTemplateElement;
}
export interface Disconnectable {
_$parent?: Disconnectable;
_$disconnectableChildren?: Set;
_$isConnected: boolean;
}
declare function resolveDirective(part: ChildPart | AttributePart | ElementPart, value: unknown, parent?: DirectiveParent, attributeIndex?: number): unknown;
/**
* An updateable instance of a Template. Holds references to the Parts used to
* update the template instance.
*/
declare class TemplateInstance implements Disconnectable {
constructor(template: Template, parent: ChildPart);
get parentNode(): Node;
get _$isConnected(): boolean;
_clone(options: RenderOptions | undefined): Node;
_update(values: Array): void;
}
export declare type Part = ChildPart | AttributePart | PropertyPart | BooleanAttributePart | ElementPart | EventPart;
export type { ChildPart };
declare class ChildPart implements Disconnectable {
readonly type = 2;
readonly options: RenderOptions | undefined;
_$committedValue: unknown;
private _textSanitizer;
get _$isConnected(): boolean;
constructor(startNode: ChildNode, endNode: ChildNode | null, parent: TemplateInstance | ChildPart | undefined, options: RenderOptions | undefined);
/**
* The parent node into which the part renders its content.
*
* A ChildPart's content consists of a range of adjacent child nodes of
* `.parentNode`, possibly bordered by 'marker nodes' (`.startNode` and
* `.endNode`).
*
* - If both `.startNode` and `.endNode` are non-null, then the part's content
* consists of all siblings between `.startNode` and `.endNode`, exclusively.
*
* - If `.startNode` is non-null but `.endNode` is null, then the part's
* content consists of all siblings following `.startNode`, up to and
* including the last child of `.parentNode`. If `.endNode` is non-null, then
* `.startNode` will always be non-null.
*
* - If both `.endNode` and `.startNode` are null, then the part's content
* consists of all child nodes of `.parentNode`.
*/
get parentNode(): Node;
/**
* The part's leading marker node, if any. See `.parentNode` for more
* information.
*/
get startNode(): Node | null;
/**
* The part's trailing marker node, if any. See `.parentNode` for more
* information.
*/
get endNode(): Node | null;
_$setValue(value: unknown, directiveParent?: DirectiveParent): void;
private _insert;
private _commitNode;
private _commitText;
private _commitTemplateResult;
private _commitIterable;
}
/**
* A top-level `ChildPart` returned from `render` that manages the connected
* state of `AsyncDirective`s created throughout the tree below it.
*/
export interface RootPart extends ChildPart {
/**
* Sets the connection state for `AsyncDirective`s contained within this root
* ChildPart.
*
* lit-html does not automatically monitor the connectedness of DOM rendered;
* as such, it is the responsibility of the caller to `render` to ensure that
* `part.setConnected(false)` is called before the part object is potentially
* discarded, to ensure that `AsyncDirective`s have a chance to dispose of
* any resources being held. If a `RootPart` that was prevously
* disconnected is subsequently re-connected (and its `AsyncDirective`s should
* re-connect), `setConnected(true)` should be called.
*
* @param isConnected Whether directives within this tree should be connected
* or not
*/
setConnected(isConnected: boolean): void;
}
export type { AttributePart };
declare class AttributePart implements Disconnectable {
readonly type: 1 | 3 | 4 | 5;
readonly element: HTMLElement;
readonly name: string;
readonly options: RenderOptions | undefined;
/**
* If this attribute part represents an interpolation, this contains the
* static strings of the interpolation. For single-value, complete bindings,
* this is undefined.
*/
readonly strings?: ReadonlyArray;
protected _sanitizer: ValueSanitizer | undefined;
get tagName(): string;
get _$isConnected(): boolean;
constructor(element: HTMLElement, name: string, strings: ReadonlyArray, parent: Disconnectable, options: RenderOptions | undefined);
}
export type { PropertyPart };
declare class PropertyPart extends AttributePart {
readonly type = 3;
}
export type { BooleanAttributePart };
declare class BooleanAttributePart extends AttributePart {
readonly type = 4;
}
/**
* An AttributePart that manages an event listener via add/removeEventListener.
*
* This part works by adding itself as the event listener on an element, then
* delegating to the value passed to it. This reduces the number of calls to
* add/removeEventListener if the listener changes frequently, such as when an
* inline function is used as a listener.
*
* Because event options are passed when adding listeners, we must take case
* to add and remove the part as a listener when the event options change.
*/
export type { EventPart };
declare class EventPart extends AttributePart {
readonly type = 5;
constructor(element: HTMLElement, name: string, strings: ReadonlyArray, parent: Disconnectable, options: RenderOptions | undefined);
handleEvent(event: Event): void;
}
export type { ElementPart };
declare class ElementPart implements Disconnectable {
element: Element;
readonly type = 6;
_$committedValue: undefined;
options: RenderOptions | undefined;
constructor(element: Element, parent: Disconnectable, options: RenderOptions | undefined);
get _$isConnected(): boolean;
_$setValue(value: unknown): void;
}
/**
* END USERS SHOULD NOT RELY ON THIS OBJECT.
*
* Private exports for use by other Lit packages, not intended for use by
* external users.
*
* We currently do not make a mangled rollup build of the lit-ssr code. In order
* to keep a number of (otherwise private) top-level exports mangled in the
* client side code, we export a _$LH object containing those members (or
* helper methods for accessing private fields of those members), and then
* re-export them for use in lit-ssr. This keeps lit-ssr agnostic to whether the
* client-side code is being used in `dev` mode or `prod` mode.
*
* This has a unique name, to disambiguate it from private exports in
* lit-element, which re-exports all of lit-html.
*
* @private
*/
export declare const _$LH: {
_boundAttributeSuffix: string;
_marker: string;
_markerMatch: string;
_HTML_RESULT: number;
_getTemplateHtml: (strings: TemplateStringsArray, type: ResultType) => [TrustedHTML, Array];
_TemplateInstance: typeof TemplateInstance;
_isIterable: (value: unknown) => value is Iterable;
_resolveDirective: typeof resolveDirective;
_ChildPart: typeof ChildPart;
_AttributePart: typeof AttributePart;
_BooleanAttributePart: typeof BooleanAttributePart;
_EventPart: typeof EventPart;
_PropertyPart: typeof PropertyPart;
_ElementPart: typeof ElementPart;
};
//# sourceMappingURL=lit-html.d.ts.map