diff options
Diffstat (limited to 'chromium/third_party/node/node_modules/lit-html/async-directive.d.ts')
| -rw-r--r-- | chromium/third_party/node/node_modules/lit-html/async-directive.d.ts | 171 |
1 files changed, 171 insertions, 0 deletions
diff --git a/chromium/third_party/node/node_modules/lit-html/async-directive.d.ts b/chromium/third_party/node/node_modules/lit-html/async-directive.d.ts new file mode 100644 index 00000000000..2b14fd3f8ea --- /dev/null +++ b/chromium/third_party/node/node_modules/lit-html/async-directive.d.ts @@ -0,0 +1,171 @@ +/** + * @license + * Copyright 2017 Google LLC + * SPDX-License-Identifier: BSD-3-Clause + */ +/** + * Overview: + * + * This module is designed to add support for an async `setValue` API and + * `disconnected` callback to directives with the least impact on the core + * runtime or payload when that feature is not used. + * + * The strategy is to introduce a `AsyncDirective` subclass of + * `Directive` that climbs the "parent" tree in its constructor to note which + * branches of lit-html's "logical tree" of data structures contain such + * directives and thus need to be crawled when a subtree is being cleared (or + * manually disconnected) in order to run the `disconnected` callback. + * + * The "nodes" of the logical tree include Parts, TemplateInstances (for when a + * TemplateResult is committed to a value of a ChildPart), and Directives; these + * all implement a common interface called `DisconnectableChild`. Each has a + * `_$parent` reference which is set during construction in the core code, and a + * `_$disconnectableChildren` field which is initially undefined. + * + * The sparse tree created by means of the `AsyncDirective` constructor + * crawling up the `_$parent` tree and placing a `_$disconnectableChildren` Set + * on each parent that includes each child that contains a + * `AsyncDirective` directly or transitively via its children. In order to + * notify connection state changes and disconnect (or reconnect) a tree, the + * `_$notifyConnectionChanged` API is patched onto ChildParts as a directive + * climbs the parent tree, which is called by the core when clearing a part if + * it exists. When called, that method iterates over the sparse tree of + * Set<DisconnectableChildren> built up by AsyncDirectives, and calls + * `_$notifyDirectiveConnectionChanged` on any directives that are encountered + * in that tree, running the required callbacks. + * + * A given "logical tree" of lit-html data-structures might look like this: + * + * ChildPart(N1) _$dC=[D2,T3] + * ._directive + * AsyncDirective(D2) + * ._value // user value was TemplateResult + * TemplateInstance(T3) _$dC=[A4,A6,N10,N12] + * ._$parts[] + * AttributePart(A4) _$dC=[D5] + * ._directives[] + * AsyncDirective(D5) + * AttributePart(A6) _$dC=[D7,D8] + * ._directives[] + * AsyncDirective(D7) + * Directive(D8) _$dC=[D9] + * ._directive + * AsyncDirective(D9) + * ChildPart(N10) _$dC=[D11] + * ._directive + * AsyncDirective(D11) + * ._value + * string + * ChildPart(N12) _$dC=[D13,N14,N16] + * ._directive + * AsyncDirective(D13) + * ._value // user value was iterable + * Array<ChildPart> + * ChildPart(N14) _$dC=[D15] + * ._value + * string + * ChildPart(N16) _$dC=[D17,T18] + * ._directive + * AsyncDirective(D17) + * ._value // user value was TemplateResult + * TemplateInstance(T18) _$dC=[A19,A21,N25] + * ._$parts[] + * AttributePart(A19) _$dC=[D20] + * ._directives[] + * AsyncDirective(D20) + * AttributePart(A21) _$dC=[22,23] + * ._directives[] + * AsyncDirective(D22) + * Directive(D23) _$dC=[D24] + * ._directive + * AsyncDirective(D24) + * ChildPart(N25) _$dC=[D26] + * ._directive + * AsyncDirective(D26) + * ._value + * string + * + * Example 1: The directive in ChildPart(N12) updates and returns `nothing`. The + * ChildPart will _clear() itself, and so we need to disconnect the "value" of + * the ChildPart (but not its directive). In this case, when `_clear()` calls + * `_$notifyConnectionChanged()`, we don't iterate all of the + * _$disconnectableChildren, rather we do a value-specific disconnection: i.e. + * since the _value was an Array<ChildPart> (because an iterable had been + * committed), we iterate the array of ChildParts (N14, N16) and run + * `setConnected` on them (which does recurse down the full tree of + * `_$disconnectableChildren` below it, and also removes N14 and N16 from N12's + * `_$disconnectableChildren`). Once the values have been disconnected, we then + * check whether the ChildPart(N12)'s list of `_$disconnectableChildren` is empty + * (and would remove it from its parent TemplateInstance(T3) if so), but since + * it would still contain its directive D13, it stays in the disconnectable + * tree. + * + * Example 2: In the course of Example 1, `setConnected` will reach + * ChildPart(N16); in this case the entire part is being disconnected, so we + * simply iterate all of N16's `_$disconnectableChildren` (D17,T18) and + * recursively run `setConnected` on them. Note that we only remove children + * from `_$disconnectableChildren` for the top-level values being disconnected + * on a clear; doing this bookkeeping lower in the tree is wasteful since it's + * all being thrown away. + * + * Example 3: If the LitElement containing the entire tree above becomes + * disconnected, it will run `childPart.setConnected()` (which calls + * `childPart._$notifyConnectionChanged()` if it exists); in this case, we + * recursively run `setConnected()` over the entire tree, without removing any + * children from `_$disconnectableChildren`, since this tree is required to + * re-connect the tree, which does the same operation, simply passing + * `isConnected: true` down the tree, signaling which callback to run. + */ +import { Disconnectable, Part } from './lit-html.js'; +import { Directive } from './directive.js'; +export * from './directive.js'; +/** + * An abstract `Directive` base class whose `disconnected` method will be + * called when the part containing the directive is cleared as a result of + * re-rendering, or when the user calls `part.setConnected(false)` on + * a part that was previously rendered containing the directive (as happens + * when e.g. a LitElement disconnects from the DOM). + * + * If `part.setConnected(true)` is subsequently called on a + * containing part, the directive's `reconnected` method will be called prior + * to its next `update`/`render` callbacks. When implementing `disconnected`, + * `reconnected` should also be implemented to be compatible with reconnection. + * + * Note that updates may occur while the directive is disconnected. As such, + * directives should generally check the `this.isConnected` flag during + * render/update to determine whether it is safe to subscribe to resources + * that may prevent garbage collection. + */ +export declare abstract class AsyncDirective extends Directive { + /** + * The connection state for this Directive. + */ + isConnected: boolean; + /** + * Initialize the part with internal fields + * @param part + * @param parent + * @param attributeIndex + */ + _$initialize(part: Part, parent: Disconnectable, attributeIndex: number | undefined): void; + /** + * Sets the value of the directive's Part outside the normal `update`/`render` + * lifecycle of a directive. + * + * This method should not be called synchronously from a directive's `update` + * or `render`. + * + * @param directive The directive to update + * @param value The value to set + */ + setValue(value: unknown): void; + /** + * User callbacks for implementing logic to release any resources/subscriptions + * that may have been retained by this directive. Since directives may also be + * re-connected, `reconnected` should also be implemented to restore the + * working state of the directive prior to the next render. + */ + protected disconnected(): void; + protected reconnected(): void; +} +//# sourceMappingURL=async-directive.d.ts.map
\ No newline at end of file |