/**
* @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
Codebase Browser
chromium