171 lines
7.7 KiB
TypeScript
171 lines
7.7 KiB
TypeScript
/**
|
|
* @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
|