1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
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
|
