@microsoft/fast-element 1.10.1 → 2.0.0-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. package/.eslintrc.json +1 -12
  2. package/CHANGELOG.json +432 -1
  3. package/CHANGELOG.md +74 -2
  4. package/README.md +2 -2
  5. package/dist/dts/components/attributes.d.ts +4 -1
  6. package/dist/dts/components/controller.d.ts +12 -11
  7. package/dist/dts/components/fast-definitions.d.ts +10 -2
  8. package/dist/dts/components/fast-element.d.ts +12 -5
  9. package/dist/dts/context.d.ts +157 -0
  10. package/dist/dts/debug.d.ts +1 -0
  11. package/dist/dts/hooks.d.ts +20 -0
  12. package/dist/dts/index.d.ts +16 -15
  13. package/dist/dts/index.debug.d.ts +2 -0
  14. package/dist/dts/index.rollup.d.ts +2 -0
  15. package/dist/dts/index.rollup.debug.d.ts +3 -0
  16. package/dist/dts/interfaces.d.ts +144 -0
  17. package/dist/dts/metadata.d.ts +25 -0
  18. package/dist/dts/observation/arrays.d.ts +207 -0
  19. package/dist/dts/observation/behavior.d.ts +4 -4
  20. package/dist/dts/observation/notifier.d.ts +18 -18
  21. package/dist/dts/observation/observable.d.ts +56 -18
  22. package/dist/dts/observation/splice-strategies.d.ts +13 -0
  23. package/dist/dts/observation/update-queue.d.ts +40 -0
  24. package/dist/dts/platform.d.ts +18 -67
  25. package/dist/dts/polyfills.d.ts +8 -0
  26. package/dist/dts/styles/css-directive.d.ts +43 -5
  27. package/dist/dts/styles/css.d.ts +19 -3
  28. package/dist/dts/styles/element-styles.d.ts +42 -62
  29. package/dist/dts/templating/binding-signal.d.ts +38 -0
  30. package/dist/dts/templating/binding-two-way.d.ts +56 -0
  31. package/dist/dts/templating/binding.d.ts +233 -65
  32. package/dist/dts/templating/children.d.ts +18 -15
  33. package/dist/dts/templating/compiler.d.ts +46 -28
  34. package/dist/dts/templating/dom.d.ts +41 -0
  35. package/dist/dts/templating/html-directive.d.ts +179 -43
  36. package/dist/dts/templating/markup.d.ts +48 -0
  37. package/dist/dts/templating/node-observation.d.ts +45 -29
  38. package/dist/dts/templating/ref.d.ts +6 -12
  39. package/dist/dts/templating/repeat.d.ts +26 -14
  40. package/dist/dts/templating/slotted.d.ts +13 -14
  41. package/dist/dts/templating/template.d.ts +27 -21
  42. package/dist/dts/templating/view.d.ts +15 -22
  43. package/dist/{tsdoc-metadata.json → dts/tsdoc-metadata.json} +1 -1
  44. package/dist/dts/utilities.d.ts +40 -0
  45. package/dist/esm/components/attributes.js +25 -24
  46. package/dist/esm/components/controller.js +77 -57
  47. package/dist/esm/components/fast-definitions.js +16 -22
  48. package/dist/esm/components/fast-element.js +10 -2
  49. package/dist/esm/context.js +159 -0
  50. package/dist/esm/debug.js +29 -0
  51. package/dist/esm/hooks.js +32 -0
  52. package/dist/esm/index.debug.js +2 -0
  53. package/dist/esm/index.js +19 -14
  54. package/dist/esm/index.rollup.debug.js +3 -0
  55. package/dist/esm/index.rollup.js +2 -0
  56. package/dist/esm/interfaces.js +8 -1
  57. package/dist/esm/metadata.js +60 -0
  58. package/dist/esm/observation/arrays.js +269 -0
  59. package/dist/esm/observation/notifier.js +75 -83
  60. package/dist/esm/observation/observable.js +93 -68
  61. package/dist/esm/observation/{array-change-records.js → splice-strategies.js} +136 -62
  62. package/dist/esm/observation/update-queue.js +67 -0
  63. package/dist/esm/platform.js +36 -42
  64. package/dist/esm/polyfills.js +85 -0
  65. package/dist/esm/styles/css-directive.js +29 -13
  66. package/dist/esm/styles/css.js +27 -40
  67. package/dist/esm/styles/element-styles.js +65 -104
  68. package/dist/esm/templating/binding-signal.js +84 -0
  69. package/dist/esm/templating/binding-two-way.js +76 -0
  70. package/dist/esm/templating/binding.js +306 -153
  71. package/dist/esm/templating/children.js +33 -23
  72. package/dist/esm/templating/compiler.js +235 -152
  73. package/dist/esm/templating/dom.js +49 -0
  74. package/dist/esm/templating/html-directive.js +125 -40
  75. package/dist/esm/templating/markup.js +75 -0
  76. package/dist/esm/templating/node-observation.js +50 -45
  77. package/dist/esm/templating/ref.js +7 -16
  78. package/dist/esm/templating/repeat.js +39 -36
  79. package/dist/esm/templating/slotted.js +23 -20
  80. package/dist/esm/templating/template.js +51 -95
  81. package/dist/esm/templating/view.js +44 -43
  82. package/dist/esm/templating/when.js +2 -1
  83. package/dist/esm/utilities.js +139 -0
  84. package/dist/fast-element.api.json +11789 -5377
  85. package/dist/fast-element.d.ts +1177 -531
  86. package/dist/fast-element.debug.js +3717 -0
  87. package/dist/fast-element.debug.min.js +1 -0
  88. package/dist/fast-element.js +3466 -4022
  89. package/dist/fast-element.min.js +1 -1
  90. package/dist/fast-element.untrimmed.d.ts +2697 -0
  91. package/docs/api-report.md +472 -219
  92. package/docs/fast-element-2-changes.md +15 -0
  93. package/docs/guide/declaring-templates.md +5 -4
  94. package/docs/guide/defining-elements.md +3 -2
  95. package/docs/guide/leveraging-css.md +1 -0
  96. package/docs/guide/next-steps.md +3 -2
  97. package/docs/guide/observables-and-state.md +2 -1
  98. package/docs/guide/using-directives.md +2 -1
  99. package/docs/guide/working-with-shadow-dom.md +1 -0
  100. package/karma.conf.cjs +6 -17
  101. package/package.json +65 -15
  102. package/dist/dts/dom.d.ts +0 -112
  103. package/dist/dts/observation/array-change-records.d.ts +0 -48
  104. package/dist/dts/observation/array-observer.d.ts +0 -9
  105. package/dist/esm/dom.js +0 -207
  106. package/dist/esm/observation/array-observer.js +0 -173
@@ -1,10 +1,3 @@
1
- /**
2
- * A reference to globalThis, with support
3
- * for browsers that don't yet support the spec.
4
- * @public
5
- */
6
- export declare const $global: Global;
7
-
8
1
  /**
9
2
  * Represents a getter/setter property accessor on an object.
10
3
  * @public
@@ -28,43 +21,132 @@ export declare interface Accessor {
28
21
  }
29
22
 
30
23
  /**
31
- * A directive that attaches special behavior to an element via a custom attribute.
24
+ * Used to add behaviors when constructing styles.
32
25
  * @public
33
26
  */
34
- export declare class AttachedBehaviorHTMLDirective<T = any> extends HTMLDirective {
35
- private name;
36
- private behavior;
37
- private options;
27
+ export declare type AddBehavior = (behavior: Behavior<HTMLElement>) => void;
28
+
29
+ /**
30
+ * Used to add behavior factories when constructing templates.
31
+ * @public
32
+ */
33
+ export declare type AddViewBehaviorFactory = (factory: ViewBehaviorFactory) => string;
34
+
35
+ /* Excluded from this release type: AdoptedStyleSheetsStrategy */
36
+
37
+ /**
38
+ * An observer for arrays.
39
+ * @public
40
+ */
41
+ export declare interface ArrayObserver extends SubscriberSet {
38
42
  /**
39
- *
40
- * @param name - The name of the behavior; used as a custom attribute on the element.
41
- * @param behavior - The behavior to instantiate and attach to the element.
42
- * @param options - Options to pass to the behavior during creation.
43
+ * The strategy to use for tracking changes.
43
44
  */
44
- constructor(name: string, behavior: AttachedBehaviorType<T>, options: T);
45
+ strategy: SpliceStrategy | null;
45
46
  /**
46
- * Creates a placeholder string based on the directive's index within the template.
47
- * @param index - The index of the directive within the template.
48
- * @remarks
49
- * Creates a custom attribute placeholder.
47
+ * The length observer for the array.
50
48
  */
51
- createPlaceholder(index: number): string;
49
+ readonly lengthObserver: LengthObserver;
52
50
  /**
53
- * Creates a behavior for the provided target node.
54
- * @param target - The node instance to create the behavior for.
55
- * @remarks
56
- * Creates an instance of the `behavior` type this directive was constructed with
57
- * and passes the target and options to that `behavior`'s constructor.
51
+ * Adds a splice to the list of changes.
52
+ * @param splice - The splice to add.
53
+ */
54
+ addSplice(splice: Splice): void;
55
+ /**
56
+ * Indicates that a reset change has occurred.
57
+ * @param oldCollection - The collection as it was before the reset.
58
+ */
59
+ reset(oldCollection: any[] | undefined): void;
60
+ /**
61
+ * Flushes the changes to subscribers.
58
62
  */
59
- createBehavior(target: Node): Behavior;
63
+ flush(): void;
60
64
  }
61
65
 
62
66
  /**
63
- * Describes the shape of a behavior constructor that can be created by
64
- * an {@link AttachedBehaviorHTMLDirective}.
67
+ * An observer for arrays.
68
+ * @public
69
+ */
70
+ export declare const ArrayObserver: Readonly<{
71
+ /**
72
+ * Enables the array observation mechanism.
73
+ * @remarks
74
+ * Array observation is enabled automatically when using the
75
+ * {@link RepeatDirective}, so calling this API manually is
76
+ * not typically necessary.
77
+ */
78
+ readonly enable: () => void;
79
+ }>;
80
+
81
+ /**
82
+ * The type of HTML aspect to target.
83
+ * @public
84
+ */
85
+ export declare const Aspect: Readonly<{
86
+ /**
87
+ * Not aspected.
88
+ */
89
+ readonly none: 0;
90
+ /**
91
+ * An attribute.
92
+ */
93
+ readonly attribute: 1;
94
+ /**
95
+ * A boolean attribute.
96
+ */
97
+ readonly booleanAttribute: 2;
98
+ /**
99
+ * A property.
100
+ */
101
+ readonly property: 3;
102
+ /**
103
+ * Content
104
+ */
105
+ readonly content: 4;
106
+ /**
107
+ * A token list.
108
+ */
109
+ readonly tokenList: 5;
110
+ /**
111
+ * An event.
112
+ */
113
+ readonly event: 6;
114
+ /**
115
+ *
116
+ * @param directive - The directive to assign the aspect to.
117
+ * @param value - The value to base the aspect determination on.
118
+ */
119
+ readonly assign: (directive: Aspected, value: string) => void;
120
+ }>;
121
+
122
+ /**
123
+ * The type of HTML aspect to target.
65
124
  * @public
66
125
  */
67
- export declare type AttachedBehaviorType<T = any> = new (target: any, options: T) => Behavior;
126
+ export declare type Aspect = typeof Aspect[Exclude<keyof typeof Aspect, "assign" | "none">];
127
+
128
+ /**
129
+ * Represents something that applies to a specific aspect of the DOM.
130
+ * @public
131
+ */
132
+ export declare interface Aspected {
133
+ /**
134
+ * The original source aspect exactly as represented in markup.
135
+ */
136
+ sourceAspect: string;
137
+ /**
138
+ * The evaluated target aspect, determined after processing the source.
139
+ */
140
+ targetAspect: string;
141
+ /**
142
+ * The type of aspect to target.
143
+ */
144
+ aspectType: Aspect;
145
+ /**
146
+ * A binding if one is associated with the aspect.
147
+ */
148
+ binding?: Binding;
149
+ }
68
150
 
69
151
  /**
70
152
  * Decorator: Specifies an HTML attribute.
@@ -145,16 +227,9 @@ export declare class AttributeDefinition implements Accessor {
145
227
  * @param source - The source element to access.
146
228
  */
147
229
  getValue(source: HTMLElement): any;
148
- /** @internal */
149
- onAttributeChangedCallback(element: HTMLElement, value: any): void;
230
+ /* Excluded from this release type: onAttributeChangedCallback */
150
231
  private tryReflectToAttribute;
151
- /**
152
- * Collects all attribute definitions associated with the owner.
153
- * @param Owner - The class constructor to collect attribute for.
154
- * @param attributeLists - Any existing attributes to collect and merge with those associated with the owner.
155
- * @internal
156
- */
157
- static collect(Owner: Function, ...attributeLists: (ReadonlyArray<string | AttributeConfiguration> | undefined)[]): ReadonlyArray<AttributeDefinition>;
232
+ /* Excluded from this release type: collect */
158
233
  }
159
234
 
160
235
  /**
@@ -168,27 +243,36 @@ export declare class AttributeDefinition implements Accessor {
168
243
  * changes in the DOM, but does not reflect property changes back.
169
244
  * @public
170
245
  */
171
- export declare type AttributeMode = "reflect" | "boolean" | "fromView";
246
+ export declare type AttributeMode = typeof reflectMode | typeof booleanMode | "fromView";
172
247
 
173
248
  /**
174
- * Represents and object that can contribute behavior to a view or
249
+ * Represents an object that can contribute behavior to a view or
175
250
  * element's bind/unbind operations.
176
251
  * @public
177
252
  */
178
- export declare interface Behavior {
253
+ export declare interface Behavior<TSource = any, TParent = any> {
179
254
  /**
180
255
  * Bind this behavior to the source.
181
256
  * @param source - The source to bind to.
182
257
  * @param context - The execution context that the binding is operating within.
183
258
  */
184
- bind(source: unknown, context: ExecutionContext): void;
259
+ bind(source: TSource, context: ExecutionContext<TParent>): void;
185
260
  /**
186
261
  * Unbinds this behavior from the source.
187
262
  * @param source - The source to unbind from.
188
263
  */
189
- unbind(source: unknown): void;
264
+ unbind(source: TSource, context: ExecutionContext<TParent>): void;
190
265
  }
191
266
 
267
+ /**
268
+ * Creates a binding directive with the specified configuration.
269
+ * @param binding - The binding expression.
270
+ * @param config - The binding configuration.
271
+ * @returns A binding directive.
272
+ * @public
273
+ */
274
+ export declare function bind<T = any>(binding: Binding<T>, config?: BindingConfig | DefaultBindingOptions): CaptureType<T>;
275
+
192
276
  /**
193
277
  * The signature of an arrow function capable of being evaluated
194
278
  * as part of a template binding update.
@@ -197,80 +281,86 @@ export declare interface Behavior {
197
281
  export declare type Binding<TSource = any, TReturn = any, TParent = any> = (source: TSource, context: ExecutionContext<TParent>) => TReturn;
198
282
 
199
283
  /**
200
- * A behavior that updates content and attributes based on a configured
201
- * BindingDirective.
202
- * @public
203
- */
204
- export declare class BindingBehavior implements Behavior {
205
- /** @internal */
206
- source: unknown;
207
- /** @internal */
208
- context: ExecutionContext | null;
209
- /** @internal */
210
- bindingObserver: BindingObserver | null;
211
- /** @internal */
212
- classVersions: Record<string, number>;
213
- /** @internal */
214
- version: number;
215
- /** @internal */
216
- target: any;
217
- /** @internal */
218
- binding: Binding;
219
- /** @internal */
220
- isBindingVolatile: boolean;
221
- /** @internal */
222
- updateTarget: typeof updatePropertyTarget;
223
- /** @internal */
224
- targetName?: string;
284
+ * Describes the configuration for a binding expression.
285
+ * @public
286
+ */
287
+ export declare interface BindingConfig<T = any> {
225
288
  /**
226
- * Bind this behavior to the source.
227
- * @param source - The source to bind to.
228
- * @param context - The execution context that the binding is operating within.
289
+ * The binding mode to configure the binding with.
229
290
  */
230
- bind: typeof normalBind;
291
+ mode: BindingMode;
231
292
  /**
232
- * Unbinds this behavior from the source.
233
- * @param source - The source to unbind from.
293
+ * Options to be supplied to the binding behaviors.
234
294
  */
235
- unbind: typeof normalUnbind;
236
- /**
237
- * Creates an instance of BindingBehavior.
238
- * @param target - The target of the data updates.
239
- * @param binding - The binding that returns the latest value for an update.
240
- * @param isBindingVolatile - Indicates whether the binding has volatile dependencies.
241
- * @param bind - The operation to perform during binding.
242
- * @param unbind - The operation to perform during unbinding.
243
- * @param updateTarget - The operation to perform when updating.
244
- * @param targetName - The name of the target attribute or property to update.
245
- */
246
- constructor(target: any, binding: Binding, isBindingVolatile: boolean, bind: typeof normalBind, unbind: typeof normalUnbind, updateTarget: typeof updatePropertyTarget, targetName?: string);
247
- /** @internal */
248
- handleChange(): void;
249
- /** @internal */
250
- handleEvent(event: Event): void;
295
+ options: T;
251
296
  }
252
297
 
298
+ /**
299
+ * Describes the configuration for a binding expression.
300
+ * @public
301
+ */
302
+ export declare const BindingConfig: Readonly<{
303
+ /**
304
+ * Creates a binding configuration based on the provided mode and options.
305
+ * @param mode - The mode to use for the configuration.
306
+ * @param defaultOptions - The default options to use for the configuration.
307
+ * @returns A new binding configuration.
308
+ */
309
+ define<T>(mode: BindingMode, defaultOptions: T): BindingConfig<T> & BindingConfigResolver<T>;
310
+ }>;
311
+
312
+ /**
313
+ * Creates a new binding configuration based on the supplied options.
314
+ * @public
315
+ */
316
+ export declare type BindingConfigResolver<T> = (options: T) => BindingConfig<T>;
317
+
318
+ /**
319
+ * Describes how aspects of an HTML element will be affected by bindings.
320
+ * @public
321
+ */
322
+ export declare type BindingMode = Record<Aspect, (directive: HTMLBindingDirective) => Pick<ViewBehaviorFactory, "createBehavior">>;
323
+
324
+ /**
325
+ * Describes how aspects of an HTML element will be affected by bindings.
326
+ * @public
327
+ */
328
+ export declare const BindingMode: Readonly<{
329
+ /**
330
+ * Creates a binding mode based on the supplied behavior types.
331
+ * @param UpdateType - The base behavior type used to update aspects.
332
+ * @param EventType - The base behavior type used to respond to events.
333
+ * @returns A new binding mode.
334
+ */
335
+ define(UpdateType: typeof UpdateBinding, EventType?: typeof EventBinding): BindingMode;
336
+ }>;
337
+
253
338
  /**
254
339
  * Enables evaluation of and subscription to a binding.
255
340
  * @public
256
341
  */
257
- export declare interface BindingObserver<TSource = any, TReturn = any, TParent = any> extends Notifier {
342
+ export declare interface BindingObserver<TSource = any, TReturn = any, TParent = any> extends Notifier, Disposable {
258
343
  /**
259
344
  * Begins observing the binding for the source and returns the current value.
260
345
  * @param source - The source that the binding is based on.
261
346
  * @param context - The execution context to execute the binding within.
262
347
  * @returns The value of the binding.
263
348
  */
264
- observe(source: TSource, context: ExecutionContext<TParent>): TReturn;
265
- /**
266
- * Unsubscribe from all dependent observables of the binding.
267
- */
268
- disconnect(): void;
349
+ observe(source: TSource, context?: ExecutionContext<TParent>): TReturn;
269
350
  /**
270
351
  * Gets {@link ObservationRecord|ObservationRecords} that the {@link BindingObserver}
271
352
  * is observing.
272
353
  */
273
354
  records(): IterableIterator<ObservationRecord>;
355
+ /**
356
+ * Sets the update mode used by the observer.
357
+ * @param isAsync - Indicates whether updates should be asynchronous.
358
+ * @remarks
359
+ * By default, the update mode is asynchronous, since that provides the best
360
+ * performance for template rendering scenarios. Passing false to setMode will
361
+ * instead cause the observer to notify subscribers immediately when changes occur.
362
+ */
363
+ setMode(isAsync: boolean): void;
274
364
  }
275
365
 
276
366
  /**
@@ -281,6 +371,8 @@ export declare interface BindingObserver<TSource = any, TReturn = any, TParent =
281
371
  */
282
372
  export declare const booleanConverter: ValueConverter;
283
373
 
374
+ declare const booleanMode = "boolean";
375
+
284
376
  /**
285
377
  * Represents a callable type such as a function or an object with a "call" method.
286
378
  * @public
@@ -297,11 +389,47 @@ export declare type Callable = typeof Function.prototype.call | {
297
389
  export declare interface CaptureType<TSource> {
298
390
  }
299
391
 
392
+ /**
393
+ * A binding behavior for bindings that change.
394
+ * @public
395
+ */
396
+ export declare class ChangeBinding extends UpdateBinding {
397
+ private isBindingVolatile;
398
+ private observerProperty;
399
+ /**
400
+ * Creates an instance of ChangeBinding.
401
+ * @param directive - The directive that has the configuration for this behavior.
402
+ * @param updateTarget - The function used to update the target with the latest value.
403
+ */
404
+ constructor(directive: HTMLBindingDirective, updateTarget: UpdateTarget);
405
+ /**
406
+ * Returns the binding observer used to update the node.
407
+ * @param target - The target node.
408
+ * @returns A BindingObserver.
409
+ */
410
+ protected getObserver(target: Node): BindingObserver;
411
+ /**
412
+ * Bind this behavior to the source.
413
+ * @param source - The source to bind to.
414
+ * @param context - The execution context that the binding is operating within.
415
+ * @param targets - The targets that behaviors in a view can attach to.
416
+ */
417
+ bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
418
+ /**
419
+ * Unbinds this behavior from the source.
420
+ * @param source - The source to unbind from.
421
+ * @param context - The execution context that the binding is operating within.
422
+ * @param targets - The targets that behaviors in a view can attach to.
423
+ */
424
+ unbind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
425
+ /* Excluded from this release type: handleChange */
426
+ }
427
+
300
428
  /**
301
429
  * The options used to configure child list observation.
302
430
  * @public
303
431
  */
304
- export declare interface ChildListBehaviorOptions<T = any> extends NodeBehaviorOptions<T>, Omit<MutationObserverInit, "subtree" | "childList"> {
432
+ export declare interface ChildListDirectiveOptions<T = any> extends NodeBehaviorOptions<T>, Omit<MutationObserverInit, "subtree" | "childList"> {
305
433
  }
306
434
 
307
435
  /**
@@ -310,78 +438,97 @@ export declare interface ChildListBehaviorOptions<T = any> extends NodeBehaviorO
310
438
  * @param propertyOrOptions - The options used to configure child node observation.
311
439
  * @public
312
440
  */
313
- export declare function children<T = any>(propertyOrOptions: (keyof T & string) | ChildrenBehaviorOptions<keyof T & string>): CaptureType<T>;
441
+ export declare function children<T = any>(propertyOrOptions: (keyof T & string) | ChildrenDirectiveOptions<keyof T & string>): CaptureType<T>;
314
442
 
315
443
  /**
316
444
  * The runtime behavior for child node observation.
317
445
  * @public
318
446
  */
319
- export declare class ChildrenBehavior extends NodeObservationBehavior<ChildrenBehaviorOptions> {
320
- private observer;
447
+ export declare class ChildrenDirective extends NodeObservationDirective<ChildrenDirectiveOptions> {
448
+ private observerProperty;
321
449
  /**
322
- * Creates an instance of ChildrenBehavior.
323
- * @param target - The element target to observe children on.
324
- * @param options - The options to use when observing the element children.
450
+ * Creates an instance of ChildrenDirective.
451
+ * @param options - The options to use in configuring the child observation behavior.
325
452
  */
326
- constructor(target: HTMLElement, options: ChildrenBehaviorOptions);
453
+ constructor(options: ChildrenDirectiveOptions);
327
454
  /**
328
455
  * Begins observation of the nodes.
456
+ * @param target - The target to observe.
329
457
  */
330
- observe(): void;
458
+ observe(target: any): void;
331
459
  /**
332
460
  * Disconnects observation of the nodes.
461
+ * @param target - The target to unobserve.
333
462
  */
334
- disconnect(): void;
463
+ disconnect(target: any): void;
335
464
  /**
336
- * Retrieves the nodes that should be assigned to the target.
465
+ * Retrieves the raw nodes that should be assigned to the source property.
466
+ * @param target - The target to get the node to.
337
467
  */
338
- protected getNodes(): ChildNode[];
468
+ getNodes(target: Element): Node[];
469
+ private handleEvent;
339
470
  }
340
471
 
341
472
  /**
342
473
  * The options used to configure child/subtree node observation.
343
474
  * @public
344
475
  */
345
- export declare type ChildrenBehaviorOptions<T = any> = ChildListBehaviorOptions<T> | SubtreeBehaviorOptions<T>;
476
+ export declare type ChildrenDirectiveOptions<T = any> = ChildListDirectiveOptions<T> | SubtreeDirectiveOptions<T>;
346
477
 
347
478
  /**
348
- * The result of compiling a template and its directives.
349
- * @beta
479
+ * A function capable of compiling a template from the preprocessed form produced
480
+ * by the html template function into a result that can instantiate views.
481
+ * @public
482
+ */
483
+ export declare type CompilationStrategy = (
484
+ /**
485
+ * The preprocessed HTML string or template to compile.
350
486
  */
351
- export declare interface CompilationResult {
487
+ html: string | HTMLTemplateElement,
488
+ /**
489
+ * The behavior factories used within the html that is being compiled.
490
+ */
491
+ factories: Record<string, ViewBehaviorFactory>) => HTMLTemplateCompilationResult;
492
+
493
+ /**
494
+ * Common APIs related to compilation.
495
+ * @public
496
+ */
497
+ export declare const Compiler: {
352
498
  /**
353
- * A cloneable DocumentFragment representing the compiled HTML.
499
+ * Sets the HTML trusted types policy used by the compiler.
500
+ * @param policy - The policy to set for HTML.
501
+ * @remarks
502
+ * This API can only be called once, for security reasons. It should be
503
+ * called by the application developer at the start of their program.
354
504
  */
355
- fragment: DocumentFragment;
505
+ setHTMLPolicy(policy: TrustedTypesPolicy): void;
356
506
  /**
357
- * The behaviors that should be applied to the template's HTML.
507
+ * Compiles a template and associated directives into a compilation
508
+ * result which can be used to create views.
509
+ * @param html - The html string or template element to compile.
510
+ * @param directives - The directives referenced by the template.
511
+ * @remarks
512
+ * The template that is provided for compilation is altered in-place
513
+ * and cannot be compiled again. If the original template must be preserved,
514
+ * it is recommended that you clone the original and pass the clone to this API.
515
+ * @public
358
516
  */
359
- viewBehaviorFactories: NodeBehaviorFactory[];
517
+ compile<TSource = any, TParent = any>(html: string | HTMLTemplateElement, directives: Record<string, ViewBehaviorFactory>): HTMLTemplateCompilationResult<TSource, TParent>;
360
518
  /**
361
- * The behaviors that should be applied to the host element that
362
- * the template is rendered into.
519
+ * Sets the default compilation strategy that will be used by the ViewTemplate whenever
520
+ * it needs to compile a view preprocessed with the html template function.
521
+ * @param strategy - The compilation strategy to use when compiling templates.
363
522
  */
364
- hostBehaviorFactories: NodeBehaviorFactory[];
523
+ setDefaultStrategy(strategy: CompilationStrategy): void;
365
524
  /**
366
- * An index offset to apply to BehaviorFactory target indexes when
367
- * matching factories to targets.
525
+ * Aggregates an array of strings and directives into a single directive.
526
+ * @param parts - A heterogeneous array of static strings interspersed with
527
+ * directives.
528
+ * @returns A single inline directive that aggregates the behavior of all the parts.
368
529
  */
369
- targetOffset: number;
370
- }
371
-
372
- /**
373
- * Compiles a template and associated directives into a raw compilation
374
- * result which include a cloneable DocumentFragment and factories capable
375
- * of attaching runtime behavior to nodes within the fragment.
376
- * @param template - The template to compile.
377
- * @param directives - The directives referenced by the template.
378
- * @remarks
379
- * The template that is provided for compilation is altered in-place
380
- * and cannot be compiled again. If the original template must be preserved,
381
- * it is recommended that you clone the original and pass the clone to this API.
382
- * @public
383
- */
384
- export declare function compileTemplate(template: HTMLTemplateElement, directives: ReadonlyArray<HTMLDirective>): CompilationResult;
530
+ aggregate(parts: (string | ViewBehaviorFactory)[]): ViewBehaviorFactory;
531
+ };
385
532
 
386
533
  /**
387
534
  * Represents styles that can be composed into the ShadowDOM of a custom element.
@@ -398,14 +545,27 @@ export declare type Constructable<T = {}> = {
398
545
  new (...args: any[]): T;
399
546
  };
400
547
 
548
+ /**
549
+ * A type that instantiates a StyleStrategy.
550
+ * @public
551
+ */
552
+ export declare type ConstructibleStyleStrategy = {
553
+ /**
554
+ * Creates an instance of the strategy.
555
+ * @param styles - The styles to initialize the strategy with.
556
+ */
557
+ new (styles: (string | CSSStyleSheet)[]): StyleStrategy;
558
+ };
559
+
401
560
  /**
402
561
  * Controls the lifecycle and rendering of a `FASTElement`.
403
562
  * @public
404
563
  */
405
- export declare class Controller extends PropertyChangeNotifier {
564
+ export declare class Controller<TElement extends HTMLElement = HTMLElement> extends PropertyChangeNotifier {
406
565
  private boundObservables;
407
566
  private behaviors;
408
567
  private needsInitialization;
568
+ private hasExistingShadowRoot;
409
569
  private _template;
410
570
  private _styles;
411
571
  private _isConnected;
@@ -421,7 +581,7 @@ export declare class Controller extends PropertyChangeNotifier {
421
581
  /**
422
582
  * The element being controlled by this controller.
423
583
  */
424
- readonly element: HTMLElement;
584
+ readonly element: TElement;
425
585
  /**
426
586
  * The element definition that instructs this controller
427
587
  * in how to handle rendering and other platform integrations.
@@ -432,7 +592,7 @@ export declare class Controller extends PropertyChangeNotifier {
432
592
  * @remarks
433
593
  * If `null` then the element is managing its own rendering.
434
594
  */
435
- readonly view: ElementView | null;
595
+ readonly view: ElementView<TElement> | null;
436
596
  /**
437
597
  * Indicates whether or not the custom element has been
438
598
  * connected to the document.
@@ -444,8 +604,8 @@ export declare class Controller extends PropertyChangeNotifier {
444
604
  * @remarks
445
605
  * This value can only be accurately read after connect but can be set at any time.
446
606
  */
447
- get template(): ElementViewTemplate | null;
448
- set template(value: ElementViewTemplate | null);
607
+ get template(): ElementViewTemplate<TElement> | null;
608
+ set template(value: ElementViewTemplate<TElement> | null);
449
609
  /**
450
610
  * Gets/sets the primary styles used for the component.
451
611
  * @remarks
@@ -453,35 +613,28 @@ export declare class Controller extends PropertyChangeNotifier {
453
613
  */
454
614
  get styles(): ElementStyles | null;
455
615
  set styles(value: ElementStyles | null);
456
- /**
457
- * Creates a Controller to control the specified element.
458
- * @param element - The element to be controlled by this controller.
459
- * @param definition - The element definition metadata that instructs this
460
- * controller in how to handle rendering and other platform integrations.
461
- * @internal
462
- */
463
- constructor(element: HTMLElement, definition: FASTElementDefinition);
616
+ /* Excluded from this release type: __constructor */
464
617
  /**
465
618
  * Adds styles to this element. Providing an HTMLStyleElement will attach the element instance to the shadowRoot.
466
619
  * @param styles - The styles to add.
467
620
  */
468
- addStyles(styles: ElementStyles | HTMLStyleElement): void;
621
+ addStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
469
622
  /**
470
623
  * Removes styles from this element. Providing an HTMLStyleElement will detach the element instance from the shadowRoot.
471
624
  * @param styles - the styles to remove.
472
625
  */
473
- removeStyles(styles: ElementStyles | HTMLStyleElement): void;
626
+ removeStyles(styles: ElementStyles | HTMLStyleElement | null | undefined): void;
474
627
  /**
475
628
  * Adds behaviors to this element.
476
629
  * @param behaviors - The behaviors to add.
477
630
  */
478
- addBehaviors(behaviors: ReadonlyArray<Behavior>): void;
631
+ addBehaviors(behaviors: ReadonlyArray<Behavior<TElement>>): void;
479
632
  /**
480
633
  * Removes behaviors from this element.
481
634
  * @param behaviors - The behaviors to remove.
482
635
  * @param force - Forces unbinding of behaviors.
483
636
  */
484
- removeBehaviors(behaviors: ReadonlyArray<Behavior>, force?: boolean): void;
637
+ removeBehaviors(behaviors: ReadonlyArray<Behavior<TElement>>, force?: boolean): void;
485
638
  /**
486
639
  * Runs connected lifecycle behavior on the associated element.
487
640
  */
@@ -496,7 +649,7 @@ export declare class Controller extends PropertyChangeNotifier {
496
649
  * @param oldValue - The previous value of the attribute.
497
650
  * @param newValue - The new value of the attribute.
498
651
  */
499
- onAttributeChangedCallback(name: string, oldValue: string, newValue: string): void;
652
+ onAttributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
500
653
  /**
501
654
  * Emits a custom HTML event.
502
655
  * @param type - The type name of the event.
@@ -519,6 +672,8 @@ export declare class Controller extends PropertyChangeNotifier {
519
672
  static forCustomElement(element: HTMLElement): Controller;
520
673
  }
521
674
 
675
+ /* Excluded from this release type: createTypeRegistry */
676
+
522
677
  /**
523
678
  * Transforms a template literal string into styles.
524
679
  * @param strings - The string fragments that are interpolated with the values.
@@ -527,33 +682,85 @@ export declare class Controller extends PropertyChangeNotifier {
527
682
  * The css helper supports interpolation of strings and ElementStyle instances.
528
683
  * @public
529
684
  */
530
- export declare function css(strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]): ElementStyles;
685
+ export declare const css: CSSTemplateTag;
531
686
 
532
687
  /**
533
688
  * Directive for use in {@link css}.
534
689
  *
535
690
  * @public
536
691
  */
537
- export declare class CSSDirective {
692
+ export declare interface CSSDirective {
538
693
  /**
539
694
  * Creates a CSS fragment to interpolate into the CSS document.
540
695
  * @returns - the string to interpolate into CSS
541
696
  */
542
- createCSS(): ComposableStyles;
697
+ createCSS(add: AddBehavior): ComposableStyles;
698
+ }
699
+
700
+ /**
701
+ * Instructs the css engine to provide dynamic styles or
702
+ * associate behaviors with styles.
703
+ * @public
704
+ */
705
+ export declare const CSSDirective: Readonly<{
706
+ /**
707
+ * Gets the directive definition associated with the instance.
708
+ * @param instance - The directive instance to retrieve the definition for.
709
+ */
710
+ getForInstance: (object: any) => CSSDirectiveDefinition<Constructable<CSSDirective>> | undefined;
711
+ /**
712
+ * Gets the directive definition associated with the specified type.
713
+ * @param type - The directive type to retrieve the definition for.
714
+ */
715
+ getByType: (key: Function) => CSSDirectiveDefinition<Constructable<CSSDirective>> | undefined;
543
716
  /**
544
- * Creates a behavior to bind to the host element.
545
- * @returns - the behavior to bind to the host element, or undefined.
717
+ * Defines a CSSDirective.
718
+ * @param type - The type to define as a directive.
546
719
  */
547
- createBehavior(): Behavior | undefined;
720
+ define<TType extends Constructable<CSSDirective>>(type: any): TType;
721
+ }>;
722
+
723
+ /**
724
+ * Decorator: Defines a CSSDirective.
725
+ * @public
726
+ */
727
+ export declare function cssDirective(): (type: Constructable<CSSDirective>) => void;
728
+
729
+ /**
730
+ * Defines metadata for a CSSDirective.
731
+ * @public
732
+ */
733
+ export declare interface CSSDirectiveDefinition<TType extends Constructable<CSSDirective> = Constructable<CSSDirective>> {
734
+ /**
735
+ * The type that the definition provides metadata for.
736
+ */
737
+ readonly type: TType;
548
738
  }
549
739
 
550
740
  /**
551
- * Transforms a template literal string into partial CSS.
741
+ * @deprecated Use css.partial instead.
742
+ * @public
743
+ */
744
+ export declare const cssPartial: (strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]) => CSSDirective;
745
+
746
+ /**
747
+ * Transforms a template literal string into styles.
552
748
  * @param strings - The string fragments that are interpolated with the values.
553
749
  * @param values - The values that are interpolated with the string fragments.
750
+ * @remarks
751
+ * The css helper supports interpolation of strings and ElementStyle instances.
752
+ * Use the .partial method to create partial CSS fragments.
554
753
  * @public
555
754
  */
556
- export declare function cssPartial(strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]): CSSDirective;
755
+ export declare type CSSTemplateTag = ((strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]) => ElementStyles) & {
756
+ /**
757
+ * Transforms a template literal string into partial CSS.
758
+ * @param strings - The string fragments that are interpolated with the values.
759
+ * @param values - The values that are interpolated with the string fragments.
760
+ * @public
761
+ */
762
+ partial(strings: TemplateStringsArray, ...values: (ComposableStyles | CSSDirective)[]): CSSDirective;
763
+ };
557
764
 
558
765
  /**
559
766
  * Decorator: Defines a platform custom element based on `FASTElement`.
@@ -561,7 +768,7 @@ export declare function cssPartial(strings: TemplateStringsArray, ...values: (Co
561
768
  * that describes the element to define.
562
769
  * @public
563
770
  */
564
- export declare function customElement(nameOrDef: string | PartialFASTElementDefinition): (type: Function) => void;
771
+ export declare function customElement(nameOrDef: string | PartialFASTElementDefinition): (type: Constructable<HTMLElement>) => void;
565
772
 
566
773
  /**
567
774
  * Metadata used to configure a custom attribute's behavior through a decorator.
@@ -570,87 +777,42 @@ export declare function customElement(nameOrDef: string | PartialFASTElementDefi
570
777
  export declare type DecoratorAttributeConfiguration = Omit<AttributeConfiguration, "property">;
571
778
 
572
779
  /**
573
- * The default execution context used in binding expressions.
780
+ * The default binding options.
574
781
  * @public
575
782
  */
576
- export declare const defaultExecutionContext: ExecutionContext<any, any>;
783
+ export declare type DefaultBindingOptions = AddEventListenerOptions;
577
784
 
578
785
  /**
579
- * Common DOM APIs.
786
+ * Provides a mechanism for releasing resources.
580
787
  * @public
581
788
  */
582
- export declare const DOM: Readonly<{
583
- /**
584
- * Indicates whether the DOM supports the adoptedStyleSheets feature.
585
- */
586
- supportsAdoptedStyleSheets: boolean;
587
- /**
588
- * Sets the HTML trusted types policy used by the templating engine.
589
- * @param policy - The policy to set for HTML.
590
- * @remarks
591
- * This API can only be called once, for security reasons. It should be
592
- * called by the application developer at the start of their program.
593
- */
594
- setHTMLPolicy(policy: TrustedTypesPolicy): void;
789
+ export declare interface Disposable {
595
790
  /**
596
- * Turns a string into trusted HTML using the configured trusted types policy.
597
- * @param html - The string to turn into trusted HTML.
598
- * @remarks
599
- * Used internally by the template engine when creating templates
600
- * and setting innerHTML.
791
+ * Disposes the resources.
601
792
  */
602
- createHTML(html: string): string;
603
- /**
604
- * Determines if the provided node is a template marker used by the runtime.
605
- * @param node - The node to test.
606
- */
607
- isMarker(node: Node): node is Comment;
608
- /**
609
- * Given a marker node, extract the {@link HTMLDirective} index from the placeholder.
610
- * @param node - The marker node to extract the index from.
611
- */
612
- extractDirectiveIndexFromMarker(node: Comment): number;
613
- /**
614
- * Creates a placeholder string suitable for marking out a location *within*
615
- * an attribute value or HTML content.
616
- * @param index - The directive index to create the placeholder for.
617
- * @remarks
618
- * Used internally by binding directives.
619
- */
620
- createInterpolationPlaceholder(index: number): string;
621
- /**
622
- * Creates a placeholder that manifests itself as an attribute on an
623
- * element.
624
- * @param attributeName - The name of the custom attribute.
625
- * @param index - The directive index to create the placeholder for.
626
- * @remarks
627
- * Used internally by attribute directives such as `ref`, `slotted`, and `children`.
628
- */
629
- createCustomAttributePlaceholder(attributeName: string, index: number): string;
630
- /**
631
- * Creates a placeholder that manifests itself as a marker within the DOM structure.
632
- * @param index - The directive index to create the placeholder for.
633
- * @remarks
634
- * Used internally by structural directives such as `repeat`.
635
- */
636
- createBlockPlaceholder(index: number): string;
793
+ dispose(): void;
794
+ }
795
+
796
+ /**
797
+ * Common DOM APIs.
798
+ * @public
799
+ */
800
+ export declare const DOM: Readonly<{
637
801
  /**
638
- * Schedules DOM update work in the next async batch.
639
- * @param callable - The callable function or object to queue.
802
+ * @deprecated
803
+ * Use Updates.enqueue().
640
804
  */
641
805
  queueUpdate: (callable: Callable) => void;
642
806
  /**
643
- * Immediately processes all work previously scheduled
644
- * through queueUpdate.
645
- * @remarks
646
- * This also forces nextUpdate promises
647
- * to resolve.
807
+ * @deprecated
808
+ * Use Updates.next()
648
809
  */
649
- processUpdates: () => void;
810
+ nextUpdate: () => Promise<void>;
650
811
  /**
651
- * Resolves with the next DOM update.
812
+ * @deprecated
813
+ * Use Updates.process()
652
814
  */
653
- nextUpdate(): Promise<void>;
815
+ processUpdates: () => void;
654
816
  /**
655
817
  * Sets an attribute value on an element.
656
818
  * @param element - The element to set the attribute value on.
@@ -670,16 +832,6 @@ export declare const DOM: Readonly<{
670
832
  * If the value is true, the attribute is added; otherwise it is removed.
671
833
  */
672
834
  setBooleanAttribute(element: HTMLElement, attributeName: string, value: boolean): void;
673
- /**
674
- * Removes all the child nodes of the provided parent node.
675
- * @param parent - The node to remove the children from.
676
- */
677
- removeChildNodes(parent: Node): void;
678
- /**
679
- * Creates a TreeWalker configured to walk a template fragment.
680
- * @param fragment - The fragment to walk.
681
- */
682
- createTemplateWalker(fragment: DocumentFragment): TreeWalker;
683
835
  }>;
684
836
 
685
837
  /**
@@ -687,7 +839,7 @@ export declare const DOM: Readonly<{
687
839
  * @param selector - An optional selector to restrict the filter to.
688
840
  * @public
689
841
  */
690
- export declare function elements(selector?: string): ElementsFilter;
842
+ export declare const elements: (selector?: string) => ElementsFilter;
691
843
 
692
844
  /**
693
845
  * Elements filter function type.
@@ -696,44 +848,56 @@ export declare function elements(selector?: string): ElementsFilter;
696
848
  */
697
849
  export declare type ElementsFilter = (value: Node, index: number, array: Node[]) => boolean;
698
850
 
699
- /**
700
- * Creates an ElementStyles instance for an array of ComposableStyles.
701
- * @public
702
- */
703
- export declare type ElementStyleFactory = (styles: ReadonlyArray<ComposableStyles>) => ElementStyles;
704
-
705
851
  /**
706
852
  * Represents styles that can be applied to a custom element.
707
853
  * @public
708
854
  */
709
- export declare abstract class ElementStyles {
855
+ export declare class ElementStyles {
856
+ readonly styles: ReadonlyArray<ComposableStyles>;
710
857
  private targets;
711
- /** @internal */
712
- abstract readonly styles: ReadonlyArray<ComposableStyles>;
713
- /** @internal */
714
- abstract readonly behaviors: ReadonlyArray<Behavior> | null;
715
- /** @internal */
716
- addStylesTo(target: StyleTarget): void;
717
- /** @internal */
718
- removeStylesFrom(target: StyleTarget): void;
719
- /** @internal */
720
- isAttachedTo(target: StyleTarget): boolean;
858
+ private _strategy;
859
+ /**
860
+ * The behaviors associated with this set of styles.
861
+ */
862
+ readonly behaviors: ReadonlyArray<Behavior<HTMLElement>> | null;
863
+ /**
864
+ * Gets the StyleStrategy associated with these element styles.
865
+ */
866
+ get strategy(): StyleStrategy;
867
+ /**
868
+ * Creates an instance of ElementStyles.
869
+ * @param styles - The styles that will be associated with elements.
870
+ */
871
+ constructor(styles: ReadonlyArray<ComposableStyles>);
872
+ /* Excluded from this release type: addStylesTo */
873
+ /* Excluded from this release type: removeStylesFrom */
874
+ /* Excluded from this release type: isAttachedTo */
721
875
  /**
722
876
  * Associates behaviors with this set of styles.
723
877
  * @param behaviors - The behaviors to associate.
724
878
  */
725
- withBehaviors(...behaviors: Behavior[]): this;
879
+ withBehaviors(...behaviors: Behavior<HTMLElement>[]): this;
880
+ /**
881
+ * Sets the strategy that handles adding/removing these styles for an element.
882
+ * @param strategy - The strategy to use.
883
+ */
884
+ withStrategy(Strategy: ConstructibleStyleStrategy): this;
726
885
  /**
727
- * Create ElementStyles from ComposableStyles.
886
+ * Sets the default strategy type to use when creating style strategies.
887
+ * @param Strategy - The strategy type to construct.
728
888
  */
729
- static readonly create: ElementStyleFactory;
889
+ static setDefaultStrategy(Strategy: ConstructibleStyleStrategy): void;
890
+ /**
891
+ * Indicates whether the DOM supports the adoptedStyleSheets feature.
892
+ */
893
+ static readonly supportsAdoptedStyleSheets: boolean;
730
894
  }
731
895
 
732
896
  /**
733
897
  * A View representing DOM nodes specifically for rendering the view of a custom element.
734
898
  * @public
735
899
  */
736
- export declare interface ElementView extends View {
900
+ export declare interface ElementView<TSource = any, TParent = any> extends View<TSource, TParent> {
737
901
  /**
738
902
  * Appends the view's DOM nodes to the referenced node.
739
903
  * @param node - The parent node to append the view's DOM nodes to.
@@ -745,12 +909,12 @@ export declare interface ElementView extends View {
745
909
  * A template capable of creating views specifically for rendering custom elements.
746
910
  * @public
747
911
  */
748
- export declare interface ElementViewTemplate {
912
+ export declare interface ElementViewTemplate<TSource = any, TParent = any> {
749
913
  /**
750
914
  * Creates an ElementView instance based on this template definition.
751
915
  * @param hostBindingTarget - The element that host behaviors will be bound to.
752
916
  */
753
- create(hostBindingTarget: Element): ElementView;
917
+ create(hostBindingTarget: Element): ElementView<TSource, TParent>;
754
918
  /**
755
919
  * Creates an HTMLView from this template, binds it to the source, and then appends it to the host.
756
920
  * @param source - The data source to bind the template to.
@@ -758,7 +922,7 @@ export declare interface ElementViewTemplate {
758
922
  * @param hostBindingTarget - An HTML element to target the host bindings at if different from the
759
923
  * host that the template is being attached to.
760
924
  */
761
- render(source: any, host: Node, hostBindingTarget?: Element): HTMLView;
925
+ render(source: TSource, host: Node, hostBindingTarget?: Element): ElementView<TSource, TParent>;
762
926
  }
763
927
 
764
928
  /**
@@ -766,25 +930,54 @@ export declare interface ElementViewTemplate {
766
930
  * @remarks
767
931
  * Typically returned by APIs that return arrays when there are
768
932
  * no actual items to return.
769
- * @internal
933
+ * @public
770
934
  */
771
935
  export declare const emptyArray: readonly never[];
772
936
 
773
937
  /**
774
- * Enables the array observation mechanism.
775
- * @remarks
776
- * Array observation is enabled automatically when using the
777
- * {@link RepeatDirective}, so calling this API manually is
778
- * not typically necessary.
938
+ * A binding behavior for handling events.
779
939
  * @public
780
940
  */
781
- export declare function enableArrayObservation(): void;
941
+ export declare class EventBinding {
942
+ readonly directive: HTMLBindingDirective;
943
+ private contextProperty;
944
+ private sourceProperty;
945
+ /**
946
+ * Creates an instance of EventBinding.
947
+ * @param directive - The directive that has the configuration for this behavior.
948
+ */
949
+ constructor(directive: HTMLBindingDirective);
950
+ /**
951
+ * Bind this behavior to the source.
952
+ * @param source - The source to bind to.
953
+ * @param context - The execution context that the binding is operating within.
954
+ * @param targets - The targets that behaviors in a view can attach to.
955
+ */
956
+ bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
957
+ /**
958
+ * Unbinds this behavior from the source.
959
+ * @param source - The source to unbind from.
960
+ * @param context - The execution context that the binding is operating within.
961
+ * @param targets - The targets that behaviors in a view can attach to.
962
+ */
963
+ unbind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
964
+ /**
965
+ * Creates a behavior.
966
+ * @param targets - The targets available for behaviors to be attached to.
967
+ */
968
+ createBehavior(targets: ViewBehaviorTargets): ViewBehavior;
969
+ /* Excluded from this release type: handleEvent */
970
+ }
782
971
 
783
972
  /**
784
973
  * Provides additional contextual information available to behaviors and expressions.
785
974
  * @public
786
975
  */
787
- export declare class ExecutionContext<TParent = any, TGrandparent = any> {
976
+ export declare class ExecutionContext<TParentSource = any> {
977
+ /**
978
+ * The default execution context.
979
+ */
980
+ static readonly default: ExecutionContext<any>;
788
981
  /**
789
982
  * The index of the current item within a repeat context.
790
983
  */
@@ -794,13 +987,14 @@ export declare class ExecutionContext<TParent = any, TGrandparent = any> {
794
987
  */
795
988
  length: number;
796
989
  /**
797
- * The parent data object within a repeat context.
990
+ * The parent data source within a nested context.
798
991
  */
799
- parent: TParent;
992
+ readonly parent: TParentSource;
800
993
  /**
801
994
  * The parent execution context when in nested context scenarios.
802
995
  */
803
- parentContext: ExecutionContext<TGrandparent>;
996
+ readonly parentContext: ExecutionContext<TParentSource>;
997
+ private constructor();
804
998
  /**
805
999
  * The current event within an event handler.
806
1000
  */
@@ -831,24 +1025,47 @@ export declare class ExecutionContext<TParent = any, TGrandparent = any> {
831
1025
  */
832
1026
  get isLast(): boolean;
833
1027
  /**
834
- * Sets the event for the current execution context.
835
- * @param event - The event to set.
836
- * @internal
1028
+ * Returns the typed event detail of a custom event.
1029
+ */
1030
+ eventDetail<TDetail>(): TDetail;
1031
+ /**
1032
+ * Returns the typed event target of the event.
1033
+ */
1034
+ eventTarget<TTarget extends EventTarget>(): TTarget;
1035
+ /**
1036
+ * Updates the position/size on a context associated with a list item.
1037
+ * @param index - The new index of the item.
1038
+ * @param length - The new length of the list.
1039
+ */
1040
+ updatePosition(index: number, length: number): void;
1041
+ /**
1042
+ * Creates a new execution context descendent from the current context.
1043
+ * @param source - The source for the context if different than the parent.
1044
+ * @returns A child execution context.
1045
+ */
1046
+ createChildContext<TParentSource>(parentSource: TParentSource): ExecutionContext<TParentSource>;
1047
+ /**
1048
+ * Creates a new execution context descent suitable for use in list rendering.
1049
+ * @param item - The list item to serve as the source.
1050
+ * @param index - The index of the item in the list.
1051
+ * @param length - The length of the list.
1052
+ */
1053
+ createItemContext(index: number, length: number): ExecutionContext<TParentSource>;
1054
+ /* Excluded from this release type: setEvent */
1055
+ /**
1056
+ * Creates a new root execution context.
1057
+ * @returns A new execution context.
837
1058
  */
838
- static setEvent(event: Event | null): void;
1059
+ static create(): ExecutionContext;
839
1060
  }
840
1061
 
841
- /**
842
- * The FAST global.
843
- * @internal
844
- */
845
- export declare const FAST: FASTGlobal;
1062
+ /* Excluded from this release type: FAST */
846
1063
 
847
1064
  /**
848
1065
  * Represents a custom element based on the FASTElement infrastructure.
849
1066
  * @public
850
1067
  */
851
- export declare interface FASTElement {
1068
+ export declare interface FASTElement extends HTMLElement {
852
1069
  /**
853
1070
  * The underlying controller that handles the lifecycle and rendering of
854
1071
  * this FASTElement.
@@ -886,7 +1103,7 @@ export declare interface FASTElement {
886
1103
  * This method is invoked by the platform whenever an observed
887
1104
  * attribute of FASTElement has a value change.
888
1105
  */
889
- attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
1106
+ attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
890
1107
  }
891
1108
 
892
1109
  /**
@@ -910,14 +1127,20 @@ export declare const FASTElement: (new () => HTMLElement & FASTElement) & {
910
1127
  * @param nameOrDef - The name of the element to define or a definition object
911
1128
  * that describes the element to define.
912
1129
  */
913
- define<TType extends Function>(type: TType, nameOrDef?: string | PartialFASTElementDefinition | undefined): TType;
1130
+ define<TType extends Constructable<HTMLElement>>(type: TType, nameOrDef?: string | PartialFASTElementDefinition): TType;
1131
+ /**
1132
+ * Defines metadata for a FASTElement which can be used to later define the element.
1133
+ * IMPORTANT: This API will be renamed to "compose" in a future beta.
1134
+ * @public
1135
+ */
1136
+ metadata<TType_1 extends Constructable<HTMLElement> = Constructable<HTMLElement>>(type: TType_1, nameOrDef?: string | PartialFASTElementDefinition): FASTElementDefinition<TType_1>;
914
1137
  };
915
1138
 
916
1139
  /**
917
1140
  * Defines metadata for a FASTElement.
918
1141
  * @public
919
1142
  */
920
- export declare class FASTElementDefinition<TType extends Function = Function> {
1143
+ export declare class FASTElementDefinition<TType extends Constructable<HTMLElement> = Constructable<HTMLElement>> {
921
1144
  private observedAttributes;
922
1145
  /**
923
1146
  * The type this element definition describes.
@@ -969,51 +1192,26 @@ export declare class FASTElementDefinition<TType extends Function = Function> {
969
1192
  /**
970
1193
  * Defines a custom element based on this definition.
971
1194
  * @param registry - The element registry to define the element in.
1195
+ * @remarks
1196
+ * This operation is idempotent per registry.
972
1197
  */
973
1198
  define(registry?: CustomElementRegistry): this;
974
1199
  /**
975
1200
  * Gets the element definition associated with the specified type.
976
1201
  * @param type - The custom element type to retrieve the definition for.
977
1202
  */
978
- static readonly forType: <TType_1 extends Function>(key: TType_1) => FASTElementDefinition<Function> | undefined;
979
- }
980
-
981
- /**
982
- * The FAST global.
983
- * @internal
984
- */
985
- export declare interface FASTGlobal {
986
- /**
987
- * The list of loaded versions.
988
- */
989
- readonly versions: string[];
1203
+ static readonly getByType: (key: Function) => FASTElementDefinition<Constructable<HTMLElement>> | undefined;
990
1204
  /**
991
- * Gets a kernel value.
992
- * @param id - The id to get the value for.
993
- * @param initialize - Creates the initial value for the id if not already existing.
1205
+ * Gets the element definition associated with the instance.
1206
+ * @param instance - The custom element instance to retrieve the definition for.
994
1207
  */
995
- getById<T>(id: string | number): T | null;
996
- getById<T>(id: string | number, initialize: () => T): T;
1208
+ static readonly getForInstance: (object: any) => FASTElementDefinition<Constructable<HTMLElement>> | undefined;
997
1209
  }
998
1210
 
999
- /**
1000
- * The platform global type.
1001
- * @public
1002
- */
1003
- export declare type Global = typeof globalThis & {
1004
- /**
1005
- * Enables working with trusted types.
1006
- */
1007
- trustedTypes: TrustedTypes;
1008
- /**
1009
- * The FAST global.
1010
- * @internal
1011
- */
1012
- readonly FAST: FASTGlobal;
1013
- };
1211
+ /* Excluded from this release type: FASTGlobal */
1014
1212
 
1015
1213
  /**
1016
- * Transforms a template literal string into a renderable ViewTemplate.
1214
+ * Transforms a template literal string into a ViewTemplate.
1017
1215
  * @param strings - The string fragments that are interpolated with the values.
1018
1216
  * @param values - The values that are interpolated with the string fragments.
1019
1217
  * @remarks
@@ -1024,77 +1222,135 @@ export declare type Global = typeof globalThis & {
1024
1222
  export declare function html<TSource = any, TParent = any>(strings: TemplateStringsArray, ...values: TemplateValue<TSource, TParent>[]): ViewTemplate<TSource, TParent>;
1025
1223
 
1026
1224
  /**
1027
- * A directive that configures data binding to element content and attributes.
1225
+ * A directive that applies bindings.
1028
1226
  * @public
1029
1227
  */
1030
- export declare class HTMLBindingDirective extends TargetedHTMLDirective {
1228
+ export declare class HTMLBindingDirective implements HTMLDirective, ViewBehaviorFactory, Aspected {
1031
1229
  binding: Binding;
1032
- private cleanedTargetName?;
1033
- private originalTargetName?;
1034
- private bind;
1035
- private unbind;
1036
- private updateTarget;
1037
- private isBindingVolatile;
1230
+ mode: BindingMode;
1231
+ options: any;
1232
+ private factory;
1233
+ /**
1234
+ * The unique id of the factory.
1235
+ */
1236
+ id: string;
1237
+ /**
1238
+ * The structural id of the DOM node to which the created behavior will apply.
1239
+ */
1240
+ nodeId: string;
1241
+ /**
1242
+ * The original source aspect exactly as represented in markup.
1243
+ */
1244
+ sourceAspect: string;
1245
+ /**
1246
+ * The evaluated target aspect, determined after processing the source.
1247
+ */
1248
+ targetAspect: string;
1038
1249
  /**
1039
- * Creates an instance of BindingDirective.
1040
- * @param binding - A binding that returns the data used to update the DOM.
1250
+ * The type of aspect to target.
1041
1251
  */
1042
- constructor(binding: Binding);
1252
+ aspectType: Aspect;
1043
1253
  /**
1044
- * Gets/sets the name of the attribute or property that this
1045
- * binding is targeting.
1254
+ * Creates an instance of HTMLBindingDirective.
1255
+ * @param binding - The binding to apply.
1256
+ * @param mode - The binding mode to use when applying the binding.
1257
+ * @param options - The options to configure the binding with.
1046
1258
  */
1047
- get targetName(): string | undefined;
1048
- set targetName(value: string | undefined);
1259
+ constructor(binding: Binding, mode: BindingMode, options: any);
1049
1260
  /**
1050
- * Makes this binding target the content of an element rather than
1051
- * a particular attribute or property.
1261
+ * Creates HTML to be used within a template.
1262
+ * @param add - Can be used to add behavior factories to a template.
1052
1263
  */
1053
- targetAtContent(): void;
1264
+ createHTML(add: AddViewBehaviorFactory): string;
1054
1265
  /**
1055
- * Creates the runtime BindingBehavior instance based on the configuration
1056
- * information stored in the BindingDirective.
1057
- * @param target - The target node that the binding behavior should attach to.
1266
+ * Creates a behavior.
1267
+ * @param targets - The targets available for behaviors to be attached to.
1058
1268
  */
1059
- createBehavior(target: Node): BindingBehavior;
1269
+ createBehavior(targets: ViewBehaviorTargets): ViewBehavior;
1060
1270
  }
1061
1271
 
1062
1272
  /**
1063
1273
  * Instructs the template engine to apply behavior to a node.
1064
1274
  * @public
1065
1275
  */
1066
- export declare abstract class HTMLDirective implements NodeBehaviorFactory {
1276
+ export declare interface HTMLDirective {
1067
1277
  /**
1068
- * The index of the DOM node to which the created behavior will apply.
1278
+ * Creates HTML to be used within a template.
1279
+ * @param add - Can be used to add behavior factories to a template.
1069
1280
  */
1070
- targetIndex: number;
1281
+ createHTML(add: AddViewBehaviorFactory): string;
1282
+ }
1283
+
1284
+ /**
1285
+ * Instructs the template engine to apply behavior to a node.
1286
+ * @public
1287
+ */
1288
+ export declare const HTMLDirective: Readonly<{
1071
1289
  /**
1072
- * Creates a placeholder string based on the directive's index within the template.
1073
- * @param index - The index of the directive within the template.
1290
+ * Gets the directive definition associated with the instance.
1291
+ * @param instance - The directive instance to retrieve the definition for.
1074
1292
  */
1075
- abstract createPlaceholder(index: number): string;
1293
+ getForInstance: (object: any) => HTMLDirectiveDefinition<Constructable<HTMLDirective>> | undefined;
1076
1294
  /**
1077
- * Creates a behavior for the provided target node.
1078
- * @param target - The node instance to create the behavior for.
1295
+ * Gets the directive definition associated with the specified type.
1296
+ * @param type - The directive type to retrieve the definition for.
1079
1297
  */
1080
- abstract createBehavior(target: Node): Behavior;
1298
+ getByType: (key: Function) => HTMLDirectiveDefinition<Constructable<HTMLDirective>> | undefined;
1299
+ /**
1300
+ * Defines an HTMLDirective based on the options.
1301
+ * @param type - The type to define as a directive.
1302
+ * @param options - Options that specify the directive's application.
1303
+ */
1304
+ define<TType extends Constructable<HTMLDirective>>(type: TType, options?: PartialHTMLDirectiveDefinition): TType;
1305
+ }>;
1306
+
1307
+ /**
1308
+ * Decorator: Defines an HTMLDirective.
1309
+ * @param options - Provides options that specify the directive's application.
1310
+ * @public
1311
+ */
1312
+ export declare function htmlDirective(options?: PartialHTMLDirectiveDefinition): (type: Constructable<HTMLDirective>) => void;
1313
+
1314
+ /**
1315
+ * Defines metadata for an HTMLDirective.
1316
+ * @public
1317
+ */
1318
+ export declare interface HTMLDirectiveDefinition<TType extends Constructable<HTMLDirective> = Constructable<HTMLDirective>> extends Required<PartialHTMLDirectiveDefinition> {
1319
+ /**
1320
+ * The type that the definition provides metadata for.
1321
+ */
1322
+ readonly type: TType;
1323
+ }
1324
+
1325
+ /**
1326
+ * The result of a template compilation operation.
1327
+ * @public
1328
+ */
1329
+ export declare interface HTMLTemplateCompilationResult<TSource = any, TParent = any> {
1330
+ /**
1331
+ * Creates a view instance.
1332
+ * @param hostBindingTarget - The host binding target for the view.
1333
+ */
1334
+ createView(hostBindingTarget?: Element): HTMLView<TSource, TParent>;
1081
1335
  }
1082
1336
 
1083
1337
  /**
1084
1338
  * The standard View implementation, which also implements ElementView and SyntheticView.
1085
1339
  * @public
1086
1340
  */
1087
- export declare class HTMLView implements ElementView, SyntheticView {
1341
+ export declare class HTMLView<TSource = any, TParent = any> implements ElementView<TSource, TParent>, SyntheticView<TSource, TParent> {
1088
1342
  private fragment;
1343
+ private factories;
1344
+ private targets;
1089
1345
  private behaviors;
1090
1346
  /**
1091
1347
  * The data that the view is bound to.
1092
1348
  */
1093
- source: any | null;
1349
+ source: TSource | null;
1094
1350
  /**
1095
1351
  * The execution context the view is running within.
1096
1352
  */
1097
- context: ExecutionContext | null;
1353
+ context: ExecutionContext<TParent> | null;
1098
1354
  /**
1099
1355
  * The first DOM node in the range of nodes that make up the view.
1100
1356
  */
@@ -1108,7 +1364,7 @@ export declare class HTMLView implements ElementView, SyntheticView {
1108
1364
  * @param fragment - The html fragment that contains the nodes for this view.
1109
1365
  * @param behaviors - The behaviors to be applied to this view.
1110
1366
  */
1111
- constructor(fragment: DocumentFragment, behaviors: Behavior[]);
1367
+ constructor(fragment: DocumentFragment, factories: ReadonlyArray<ViewBehaviorFactory>, targets: ViewBehaviorTargets);
1112
1368
  /**
1113
1369
  * Appends the view's DOM nodes to the referenced node.
1114
1370
  * @param node - The parent node to append the view's DOM nodes to.
@@ -1134,7 +1390,7 @@ export declare class HTMLView implements ElementView, SyntheticView {
1134
1390
  * @param source - The binding source for the view's binding behaviors.
1135
1391
  * @param context - The execution context to run the behaviors within.
1136
1392
  */
1137
- bind(source: unknown, context: ExecutionContext): void;
1393
+ bind(source: TSource, context: ExecutionContext<TParent>): void;
1138
1394
  /**
1139
1395
  * Unbinds a view's behaviors from its binding source.
1140
1396
  */
@@ -1147,40 +1403,56 @@ export declare class HTMLView implements ElementView, SyntheticView {
1147
1403
  }
1148
1404
 
1149
1405
  /**
1150
- * Core services shared across FAST instances.
1151
- * @internal
1406
+ * Observes array lengths.
1407
+ * @public
1152
1408
  */
1153
- export declare const enum KernelServiceId {
1154
- updateQueue = 1,
1155
- observable = 2,
1156
- contextEvent = 3,
1157
- elementRegistry = 4
1409
+ export declare interface LengthObserver extends Subscriber {
1410
+ /**
1411
+ * The length of the observed array.
1412
+ */
1413
+ length: number;
1158
1414
  }
1159
1415
 
1160
1416
  /**
1161
- * Reverses all readonly members, making them mutable.
1162
- * @internal
1417
+ * Enables observing the length of an array.
1418
+ * @param array - The array to observe the length of.
1419
+ * @returns The length of the array.
1420
+ * @public
1163
1421
  */
1164
- export declare type Mutable<T> = {
1165
- -readonly [P in keyof T]: T[P];
1166
- };
1422
+ export declare function lengthOf<T>(array: readonly T[]): number;
1167
1423
 
1168
1424
  /**
1169
- * A factory that can create a {@link Behavior} associated with a particular
1170
- * location within a DOM fragment.
1425
+ * Common APIs related to markup generation.
1171
1426
  * @public
1172
1427
  */
1173
- export declare interface NodeBehaviorFactory {
1428
+ export declare const Markup: Readonly<{
1174
1429
  /**
1175
- * The index of the DOM node to which the created behavior will apply.
1430
+ * Creates a placeholder string suitable for marking out a location *within*
1431
+ * an attribute value or HTML content.
1432
+ * @param index - The directive index to create the placeholder for.
1433
+ * @remarks
1434
+ * Used internally by binding directives.
1176
1435
  */
1177
- targetIndex: number;
1436
+ interpolation: (id: string) => string;
1178
1437
  /**
1179
- * Creates a behavior for the provided target node.
1180
- * @param target - The node instance to create the behavior for.
1438
+ * Creates a placeholder that manifests itself as an attribute on an
1439
+ * element.
1440
+ * @param attributeName - The name of the custom attribute.
1441
+ * @param index - The directive index to create the placeholder for.
1442
+ * @remarks
1443
+ * Used internally by attribute directives such as `ref`, `slotted`, and `children`.
1181
1444
  */
1182
- createBehavior(target: Node): Behavior;
1183
- }
1445
+ attribute: (id: string) => string;
1446
+ /**
1447
+ * Creates a placeholder that manifests itself as a marker within the DOM structure.
1448
+ * @param index - The directive index to create the placeholder for.
1449
+ * @remarks
1450
+ * Used internally by structural directives such as `repeat`.
1451
+ */
1452
+ comment: (id: string) => string;
1453
+ }>;
1454
+
1455
+ /* Excluded from this release type: Mutable */
1184
1456
 
1185
1457
  /**
1186
1458
  * Options for configuring node observation behavior.
@@ -1203,61 +1475,72 @@ export declare interface NodeBehaviorOptions<T = any> {
1203
1475
 
1204
1476
  /**
1205
1477
  * A base class for node observation.
1206
- * @internal
1478
+ * @public
1479
+ * @remarks
1480
+ * Internally used by the SlottedDirective and the ChildrenDirective.
1207
1481
  */
1208
- declare abstract class NodeObservationBehavior<T extends NodeBehaviorOptions> implements Behavior {
1209
- protected target: HTMLElement;
1210
- protected options: T;
1211
- private source;
1212
- private shouldUpdate;
1482
+ export declare abstract class NodeObservationDirective<T extends NodeBehaviorOptions> extends StatelessAttachedAttributeDirective<T> {
1483
+ private sourceProperty;
1213
1484
  /**
1214
- * Creates an instance of NodeObservationBehavior.
1215
- * @param target - The target to assign the nodes property on.
1216
- * @param options - The options to use in configuring node observation.
1485
+ * Bind this behavior to the source.
1486
+ * @param source - The source to bind to.
1487
+ * @param context - The execution context that the binding is operating within.
1488
+ * @param targets - The targets that behaviors in a view can attach to.
1217
1489
  */
1218
- constructor(target: HTMLElement, options: T);
1490
+ bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
1219
1491
  /**
1220
- * Begins observation of the nodes.
1492
+ * Unbinds this behavior from the source.
1493
+ * @param source - The source to unbind from.
1494
+ * @param context - The execution context that the binding is operating within.
1495
+ * @param targets - The targets that behaviors in a view can attach to.
1221
1496
  */
1222
- abstract observe(): void;
1497
+ unbind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
1223
1498
  /**
1224
- * Disconnects observation of the nodes.
1499
+ * Gets the data source for the target.
1500
+ * @param target - The target to get the source for.
1501
+ * @returns The source.
1225
1502
  */
1226
- abstract disconnect(): void;
1503
+ protected getSource(target: Node): any;
1227
1504
  /**
1228
- * Retrieves the nodes that should be assigned to the target.
1505
+ * Updates the source property with the computed nodes.
1506
+ * @param source - The source object to assign the nodes property to.
1507
+ * @param value - The nodes to assign to the source object property.
1229
1508
  */
1230
- protected abstract getNodes(): Node[];
1509
+ protected updateTarget(source: any, value: ReadonlyArray<any>): void;
1231
1510
  /**
1232
- * Bind this behavior to the source.
1233
- * @param source - The source to bind to.
1234
- * @param context - The execution context that the binding is operating within.
1511
+ * Computes the set of nodes that should be assigned to the source property.
1512
+ * @param target - The target to compute the nodes for.
1513
+ * @returns The computed nodes.
1514
+ * @remarks
1515
+ * Applies filters if provided.
1235
1516
  */
1236
- bind(source: any): void;
1517
+ protected computeNodes(target: any): Node[];
1237
1518
  /**
1238
- * Unbinds this behavior from the source.
1239
- * @param source - The source to unbind from.
1519
+ * Begins observation of the nodes.
1520
+ * @param target - The target to observe.
1240
1521
  */
1241
- unbind(): void;
1242
- /** @internal */
1243
- handleEvent(): void;
1244
- private computeNodes;
1245
- private updateTarget;
1522
+ protected abstract observe(target: any): void;
1523
+ /**
1524
+ * Disconnects observation of the nodes.
1525
+ * @param target - The target to unobserve.
1526
+ */
1527
+ protected abstract disconnect(target: any): void;
1528
+ /**
1529
+ * Retrieves the raw nodes that should be assigned to the source property.
1530
+ * @param target - The target to get the node to.
1531
+ */
1532
+ protected abstract getNodes(target: any): Node[];
1246
1533
  }
1247
1534
 
1248
- declare function normalBind(this: BindingBehavior, source: unknown, context: ExecutionContext): void;
1249
-
1250
- declare function normalUnbind(this: BindingBehavior): void;
1251
-
1252
1535
  /**
1253
- * Provides change notification for a source object.
1536
+ * Provides change notifications for an observed subject.
1254
1537
  * @public
1255
1538
  */
1256
1539
  export declare interface Notifier {
1257
1540
  /**
1258
- * The source object that this notifier provides change notification for.
1541
+ * The object that subscribers will receive notifications for.
1259
1542
  */
1260
- readonly source: any;
1543
+ readonly subject: any;
1261
1544
  /**
1262
1545
  * Notifies all subscribers, based on the args.
1263
1546
  * @param args - Data passed along to subscribers during notification.
@@ -1298,16 +1581,12 @@ export declare const nullableNumberConverter: ValueConverter;
1298
1581
  * @public
1299
1582
  */
1300
1583
  export declare const Observable: Readonly<{
1301
- /**
1302
- * @internal
1303
- * @param factory - The factory used to create array observers.
1304
- */
1305
- setArrayObserverFactory(factory: (collection: any[]) => Notifier): void;
1584
+ /* Excluded from this release type: setArrayObserverFactory */
1306
1585
  /**
1307
1586
  * Gets a notifier for an object or Array.
1308
1587
  * @param source - The object or Array to get the notifier for.
1309
1588
  */
1310
- getNotifier: (source: any) => Notifier;
1589
+ getNotifier: <T extends Notifier = Notifier>(source: any) => T;
1311
1590
  /**
1312
1591
  * Records a property change for a source object.
1313
1592
  * @param source - The object to record the change against.
@@ -1345,13 +1624,13 @@ export declare const Observable: Readonly<{
1345
1624
  * @param initialSubscriber - An initial subscriber to changes in the binding value.
1346
1625
  * @param isVolatileBinding - Indicates whether the binding's dependency list must be re-evaluated on every value evaluation.
1347
1626
  */
1348
- binding<TSource = any, TReturn = any, TParent = any>(binding: Binding<TSource, TReturn, TParent>, initialSubscriber?: Subscriber | undefined, isVolatileBinding?: boolean): BindingObserver<TSource, TReturn, TParent>;
1627
+ binding<TSource = any, TReturn = any>(binding: Binding<TSource, TReturn, any>, initialSubscriber?: Subscriber, isVolatileBinding?: boolean): BindingObserver<TSource, TReturn, any>;
1349
1628
  /**
1350
1629
  * Determines whether a binding expression is volatile and needs to have its dependency list re-evaluated
1351
1630
  * on every evaluation of the value.
1352
1631
  * @param binding - The binding to inspect.
1353
1632
  */
1354
- isVolatileBinding<TSource_1 = any, TReturn_1 = any, TParent_1 = any>(binding: Binding<TSource_1, TReturn_1, TParent_1>): boolean;
1633
+ isVolatileBinding<TSource_1 = any, TReturn_1 = any>(binding: Binding<TSource_1, TReturn_1, any>): boolean;
1355
1634
  }>;
1356
1635
 
1357
1636
  /**
@@ -1377,6 +1656,48 @@ export declare interface ObservationRecord {
1377
1656
  propertyName: string;
1378
1657
  }
1379
1658
 
1659
+ /**
1660
+ * The default onChange binding configuration.
1661
+ * @public
1662
+ */
1663
+ export declare const onChange: BindingConfig<AddEventListenerOptions> & BindingConfigResolver<AddEventListenerOptions>;
1664
+
1665
+ /**
1666
+ * The default onTime binding configuration.
1667
+ * @public
1668
+ */
1669
+ export declare const oneTime: BindingConfig<AddEventListenerOptions> & BindingConfigResolver<AddEventListenerOptions>;
1670
+
1671
+ /**
1672
+ * A binding behavior for one-time bindings.
1673
+ * @public
1674
+ */
1675
+ export declare class OneTimeBinding extends UpdateBinding {
1676
+ /**
1677
+ * Bind this behavior to the source.
1678
+ * @param source - The source to bind to.
1679
+ * @param context - The execution context that the binding is operating within.
1680
+ * @param targets - The targets that behaviors in a view can attach to.
1681
+ */
1682
+ bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
1683
+ }
1684
+
1685
+ /**
1686
+ * Common APIs related to content parsing.
1687
+ * @public
1688
+ */
1689
+ export declare const Parser: Readonly<{
1690
+ /**
1691
+ * Parses text content or HTML attribute content, separating out the static strings
1692
+ * from the directives.
1693
+ * @param value - The content or attribute string to parse.
1694
+ * @param factories - A list of directives to search for in the string.
1695
+ * @returns A heterogeneous array of static strings interspersed with
1696
+ * directives or null if no directives are found in the string.
1697
+ */
1698
+ parse(value: string, factories: Record<string, ViewBehaviorFactory>): (string | ViewBehaviorFactory)[] | null;
1699
+ }>;
1700
+
1380
1701
  /**
1381
1702
  * Represents metadata configuration for a custom element.
1382
1703
  * @public
@@ -1408,6 +1729,18 @@ export declare interface PartialFASTElementDefinition {
1408
1729
  readonly elementOptions?: ElementDefinitionOptions;
1409
1730
  }
1410
1731
 
1732
+ /**
1733
+ * Represents metadata configuration for an HTMLDirective.
1734
+ * @public
1735
+ */
1736
+ export declare interface PartialHTMLDirectiveDefinition {
1737
+ /**
1738
+ * Indicates whether the directive needs access to template contextual information
1739
+ * such as the sourceAspect, targetAspect, and aspectType.
1740
+ */
1741
+ aspected?: boolean;
1742
+ }
1743
+
1411
1744
  /**
1412
1745
  * An implementation of Notifier that allows subscribers to be notified
1413
1746
  * of individual property changes on an object.
@@ -1415,16 +1748,16 @@ export declare interface PartialFASTElementDefinition {
1415
1748
  */
1416
1749
  export declare class PropertyChangeNotifier implements Notifier {
1417
1750
  private subscribers;
1418
- private sourceSubscribers;
1751
+ private subjectSubscribers;
1419
1752
  /**
1420
- * The source that property changes are being notified for.
1753
+ * The subject that property changes are being notified for.
1421
1754
  */
1422
- readonly source: any;
1755
+ readonly subject: any;
1423
1756
  /**
1424
- * Creates an instance of PropertyChangeNotifier for the specified source.
1425
- * @param source - The object source that subscribers will receive notifications from.
1757
+ * Creates an instance of PropertyChangeNotifier for the specified subject.
1758
+ * @param subject - The object that subscribers will receive notifications for.
1426
1759
  */
1427
- constructor(source: any);
1760
+ constructor(subject: any);
1428
1761
  /**
1429
1762
  * Notifies all subscribers, based on the specified property.
1430
1763
  * @param propertyName - The property name, passed along to subscribers during notification.
@@ -1449,27 +1782,20 @@ export declare class PropertyChangeNotifier implements Notifier {
1449
1782
  * @param propertyName - The name of the property to assign the reference to.
1450
1783
  * @public
1451
1784
  */
1452
- export declare function ref<T = any>(propertyName: keyof T & string): CaptureType<T>;
1785
+ export declare const ref: <T = any>(propertyName: keyof T & string) => CaptureType<T>;
1453
1786
 
1454
1787
  /**
1455
1788
  * The runtime behavior for template references.
1456
1789
  * @public
1457
1790
  */
1458
- export declare class RefBehavior implements Behavior {
1459
- private target;
1460
- private propertyName;
1461
- /**
1462
- * Creates an instance of RefBehavior.
1463
- * @param target - The element to reference.
1464
- * @param propertyName - The name of the property to assign the reference to.
1465
- */
1466
- constructor(target: HTMLElement, propertyName: string);
1791
+ export declare class RefDirective extends StatelessAttachedAttributeDirective<string> {
1467
1792
  /**
1468
1793
  * Bind this behavior to the source.
1469
1794
  * @param source - The source to bind to.
1470
1795
  * @param context - The execution context that the binding is operating within.
1796
+ * @param targets - The targets that behaviors in a view can attach to.
1471
1797
  */
1472
- bind(source: any): void;
1798
+ bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
1473
1799
  /**
1474
1800
  * Unbinds this behavior from the source.
1475
1801
  * @param source - The source to unbind from.
@@ -1477,6 +1803,8 @@ export declare class RefBehavior implements Behavior {
1477
1803
  unbind(): void;
1478
1804
  }
1479
1805
 
1806
+ declare const reflectMode = "reflect";
1807
+
1480
1808
  /**
1481
1809
  * A directive that enables list rendering.
1482
1810
  * @param itemsBinding - The array to render.
@@ -1485,7 +1813,7 @@ export declare class RefBehavior implements Behavior {
1485
1813
  * @param options - Options used to turn on special repeat features.
1486
1814
  * @public
1487
1815
  */
1488
- export declare function repeat<TSource = any, TItem = any>(itemsBinding: Binding<TSource, readonly TItem[]>, templateOrTemplateBinding: SyntheticViewTemplate | Binding<TSource, SyntheticViewTemplate>, options?: RepeatOptions): CaptureType<TSource>;
1816
+ export declare function repeat<TSource = any, TArray extends ReadonlyArray<any> = ReadonlyArray<any>>(itemsBinding: Binding<TSource, TArray, ExecutionContext<TSource>>, templateOrTemplateBinding: ViewTemplate | Binding<TSource, ViewTemplate>, options?: RepeatOptions): CaptureType<TSource>;
1489
1817
 
1490
1818
  /**
1491
1819
  * A behavior that renders a template for each item in an array.
@@ -1503,7 +1831,7 @@ export declare class RepeatBehavior<TSource = any> implements Behavior, Subscrib
1503
1831
  private items;
1504
1832
  private itemsObserver;
1505
1833
  private itemsBindingObserver;
1506
- private originalContext;
1834
+ private context;
1507
1835
  private childContext;
1508
1836
  private bindView;
1509
1837
  /**
@@ -1527,7 +1855,11 @@ export declare class RepeatBehavior<TSource = any> implements Behavior, Subscrib
1527
1855
  * @param source - The source to unbind from.
1528
1856
  */
1529
1857
  unbind(): void;
1530
- /** @internal */
1858
+ /**
1859
+ * Handles changes in the array, its items, and the repeat template.
1860
+ * @param source - The source of the change.
1861
+ * @param args - The details about what was changed.
1862
+ */
1531
1863
  handleChange(source: any, args: Splice[]): void;
1532
1864
  private observeItems;
1533
1865
  private updateViews;
@@ -1539,17 +1871,25 @@ export declare class RepeatBehavior<TSource = any> implements Behavior, Subscrib
1539
1871
  * A directive that configures list rendering.
1540
1872
  * @public
1541
1873
  */
1542
- export declare class RepeatDirective<TSource = any> extends HTMLDirective {
1543
- private itemsBinding;
1544
- private templateBinding;
1545
- private options;
1874
+ export declare class RepeatDirective<TSource = any> implements HTMLDirective, ViewBehaviorFactory {
1875
+ readonly itemsBinding: Binding;
1876
+ readonly templateBinding: Binding<TSource, SyntheticViewTemplate>;
1877
+ readonly options: RepeatOptions;
1546
1878
  private isItemsBindingVolatile;
1547
1879
  private isTemplateBindingVolatile;
1880
+ /**
1881
+ * The unique id of the factory.
1882
+ */
1883
+ id: string;
1884
+ /**
1885
+ * The structural id of the DOM node to which the created behavior will apply.
1886
+ */
1887
+ nodeId: string;
1548
1888
  /**
1549
1889
  * Creates a placeholder string based on the directive's index within the template.
1550
1890
  * @param index - The index of the directive within the template.
1551
1891
  */
1552
- createPlaceholder: (index: number) => string;
1892
+ createHTML(add: AddViewBehaviorFactory): string;
1553
1893
  /**
1554
1894
  * Creates an instance of RepeatDirective.
1555
1895
  * @param itemsBinding - The binding that provides the array to render.
@@ -1561,7 +1901,7 @@ export declare class RepeatDirective<TSource = any> extends HTMLDirective {
1561
1901
  * Creates a behavior for the provided target node.
1562
1902
  * @param target - The node instance to create the behavior for.
1563
1903
  */
1564
- createBehavior(target: Node): RepeatBehavior<TSource>;
1904
+ createBehavior(targets: ViewBehaviorTargets): RepeatBehavior<TSource>;
1565
1905
  }
1566
1906
 
1567
1907
  /**
@@ -1585,57 +1925,251 @@ export declare interface RepeatOptions {
1585
1925
  * @param propertyOrOptions - The options used to configure slotted node observation.
1586
1926
  * @public
1587
1927
  */
1588
- export declare function slotted<T = any>(propertyOrOptions: (keyof T & string) | SlottedBehaviorOptions<keyof T & string>): CaptureType<T>;
1928
+ export declare function slotted<T = any>(propertyOrOptions: (keyof T & string) | SlottedDirectiveOptions<keyof T & string>): CaptureType<T>;
1589
1929
 
1590
1930
  /**
1591
1931
  * The runtime behavior for slotted node observation.
1592
1932
  * @public
1593
1933
  */
1594
- export declare class SlottedBehavior extends NodeObservationBehavior<SlottedBehaviorOptions> {
1595
- /**
1596
- * Creates an instance of SlottedBehavior.
1597
- * @param target - The slot element target to observe.
1598
- * @param options - The options to use when observing the slot.
1599
- */
1600
- constructor(target: HTMLSlotElement, options: SlottedBehaviorOptions);
1934
+ export declare class SlottedDirective extends NodeObservationDirective<SlottedDirectiveOptions> {
1601
1935
  /**
1602
1936
  * Begins observation of the nodes.
1937
+ * @param target - The target to observe.
1603
1938
  */
1604
- observe(): void;
1939
+ observe(target: EventSource): void;
1605
1940
  /**
1606
1941
  * Disconnects observation of the nodes.
1942
+ * @param target - The target to unobserve.
1607
1943
  */
1608
- disconnect(): void;
1944
+ disconnect(target: EventSource): void;
1609
1945
  /**
1610
- * Retrieves the nodes that should be assigned to the target.
1946
+ * Retrieves the raw nodes that should be assigned to the source property.
1947
+ * @param target - The target to get the node to.
1611
1948
  */
1612
- protected getNodes(): Node[];
1949
+ getNodes(target: HTMLSlotElement): Node[];
1950
+ /* Excluded from this release type: handleEvent */
1613
1951
  }
1614
1952
 
1615
1953
  /**
1616
1954
  * The options used to configure slotted node observation.
1617
1955
  * @public
1618
1956
  */
1619
- export declare interface SlottedBehaviorOptions<T = any> extends NodeBehaviorOptions<T>, AssignedNodesOptions {
1957
+ export declare interface SlottedDirectiveOptions<T = any> extends NodeBehaviorOptions<T>, AssignedNodesOptions {
1620
1958
  }
1621
1959
 
1622
1960
  /**
1623
- * Represents a set of splice-based changes against an Array.
1961
+ * A splice map is a representation of how a previous array of items
1962
+ * was transformed into a new array of items. Conceptually it is a list of
1963
+ * tuples of
1964
+ *
1965
+ * (index, removed, addedCount)
1966
+ *
1967
+ * which are kept in ascending index order of. The tuple represents that at
1968
+ * the |index|, |removed| sequence of items were removed, and counting forward
1969
+ * from |index|, |addedCount| items were added.
1624
1970
  * @public
1625
1971
  */
1626
- export declare interface Splice {
1972
+ export declare class Splice {
1973
+ index: number;
1974
+ removed: any[];
1975
+ addedCount: number;
1627
1976
  /**
1628
- * The index that the splice occurs at.
1977
+ * Indicates that this splice represents a complete array reset.
1629
1978
  */
1630
- index: number;
1979
+ reset?: boolean;
1631
1980
  /**
1632
- * The items that were removed.
1981
+ * Creates a splice.
1982
+ * @param index - The index that the splice occurs at.
1983
+ * @param removed - The items that were removed.
1984
+ * @param addedCount - The number of items that were added.
1633
1985
  */
1634
- removed: any[];
1986
+ constructor(index: number, removed: any[], addedCount: number);
1635
1987
  /**
1636
- * The number of items that were added.
1988
+ * Adjusts the splice index based on the provided array.
1989
+ * @param array - The array to adjust to.
1990
+ * @returns The same splice, mutated based on the reference array.
1637
1991
  */
1638
- addedCount: number;
1992
+ adjustTo(array: any[]): this;
1993
+ }
1994
+
1995
+ /**
1996
+ * An approach to tracking changes in an array.
1997
+ * @public
1998
+ */
1999
+ export declare interface SpliceStrategy {
2000
+ /**
2001
+ * The level of feature support the splice strategy provides.
2002
+ */
2003
+ readonly support: SpliceStrategySupport;
2004
+ /**
2005
+ * Normalizes the splices before delivery to array change subscribers.
2006
+ * @param previous - The previous version of the array if a reset has taken place.
2007
+ * @param current - The current version of the array.
2008
+ * @param changes - The set of changes tracked against the array.
2009
+ */
2010
+ normalize(previous: unknown[] | undefined, current: unknown[], changes: Splice[] | undefined): readonly Splice[];
2011
+ /**
2012
+ * Performs and tracks a pop operation on an array.
2013
+ * @param array - The array to track the change for.
2014
+ * @param observer - The observer to register the change with.
2015
+ * @param pop - The operation to perform.
2016
+ * @param args - The arguments for the operation.
2017
+ */
2018
+ pop(array: any[], observer: ArrayObserver, pop: typeof Array.prototype.pop, args: any[]): any;
2019
+ /**
2020
+ * Performs and tracks a push operation on an array.
2021
+ * @param array - The array to track the change for.
2022
+ * @param observer - The observer to register the change with.
2023
+ * @param push - The operation to perform.
2024
+ * @param args - The arguments for the operation.
2025
+ */
2026
+ push(array: any[], observer: ArrayObserver, push: typeof Array.prototype.push, args: any[]): any;
2027
+ /**
2028
+ * Performs and tracks a reverse operation on an array.
2029
+ * @param array - The array to track the change for.
2030
+ * @param observer - The observer to register the change with.
2031
+ * @param reverse - The operation to perform.
2032
+ * @param args - The arguments for the operation.
2033
+ */
2034
+ reverse(array: any[], observer: ArrayObserver, reverse: typeof Array.prototype.reverse, args: any[]): any;
2035
+ /**
2036
+ * Performs and tracks a shift operation on an array.
2037
+ * @param array - The array to track the change for.
2038
+ * @param observer - The observer to register the change with.
2039
+ * @param shift - The operation to perform.
2040
+ * @param args - The arguments for the operation.
2041
+ */
2042
+ shift(array: any[], observer: ArrayObserver, shift: typeof Array.prototype.shift, args: any[]): any;
2043
+ /**
2044
+ * Performs and tracks a sort operation on an array.
2045
+ * @param array - The array to track the change for.
2046
+ * @param observer - The observer to register the change with.
2047
+ * @param sort - The operation to perform.
2048
+ * @param args - The arguments for the operation.
2049
+ */
2050
+ sort(array: any[], observer: ArrayObserver, sort: typeof Array.prototype.sort, args: any[]): any[];
2051
+ /**
2052
+ * Performs and tracks a splice operation on an array.
2053
+ * @param array - The array to track the change for.
2054
+ * @param observer - The observer to register the change with.
2055
+ * @param splice - The operation to perform.
2056
+ * @param args - The arguments for the operation.
2057
+ */
2058
+ splice(array: any[], observer: ArrayObserver, splice: typeof Array.prototype.splice, args: any[]): any;
2059
+ /**
2060
+ * Performs and tracks an unshift operation on an array.
2061
+ * @param array - The array to track the change for.
2062
+ * @param observer - The observer to register the change with.
2063
+ * @param unshift - The operation to perform.
2064
+ * @param args - The arguments for the operation.
2065
+ */
2066
+ unshift(array: any[], observer: ArrayObserver, unshift: typeof Array.prototype.unshift, args: any[]): any[];
2067
+ }
2068
+
2069
+ /**
2070
+ * Functionality related to tracking changes in arrays.
2071
+ * @public
2072
+ */
2073
+ export declare const SpliceStrategy: Readonly<{
2074
+ /**
2075
+ * A set of changes that represent a full array reset.
2076
+ */
2077
+ readonly reset: Splice[];
2078
+ /**
2079
+ * Sets the default strategy to use for array observers.
2080
+ * @param strategy - The splice strategy to use.
2081
+ */
2082
+ readonly setDefaultStrategy: (strategy: SpliceStrategy) => void;
2083
+ }>;
2084
+
2085
+ /**
2086
+ * Indicates what level of feature support the splice
2087
+ * strategy provides.
2088
+ * @public
2089
+ */
2090
+ export declare const SpliceStrategySupport: Readonly<{
2091
+ /**
2092
+ * Only supports resets.
2093
+ */
2094
+ readonly reset: 1;
2095
+ /**
2096
+ * Supports tracking splices and resets.
2097
+ */
2098
+ readonly splice: 2;
2099
+ /**
2100
+ * Supports tracking splices and resets, while applying some form
2101
+ * of optimization, such as merging, to the splices.
2102
+ */
2103
+ readonly optimized: 3;
2104
+ }>;
2105
+
2106
+ /**
2107
+ * The available values for SpliceStrategySupport.
2108
+ * @public
2109
+ */
2110
+ export declare type SpliceStrategySupport = typeof SpliceStrategySupport[keyof typeof SpliceStrategySupport];
2111
+
2112
+ /**
2113
+ * A base class used for attribute directives that don't need internal state.
2114
+ * @public
2115
+ */
2116
+ export declare abstract class StatelessAttachedAttributeDirective<T> implements HTMLDirective, ViewBehaviorFactory, ViewBehavior {
2117
+ protected options: T;
2118
+ /**
2119
+ * The unique id of the factory.
2120
+ */
2121
+ id: string;
2122
+ /**
2123
+ * The structural id of the DOM node to which the created behavior will apply.
2124
+ */
2125
+ nodeId: string;
2126
+ /**
2127
+ * Creates an instance of RefDirective.
2128
+ * @param options - The options to use in configuring the directive.
2129
+ */
2130
+ constructor(options: T);
2131
+ /**
2132
+ * Creates a behavior.
2133
+ * @param targets - The targets available for behaviors to be attached to.
2134
+ */
2135
+ createBehavior(targets: ViewBehaviorTargets): ViewBehavior;
2136
+ /**
2137
+ * Creates a placeholder string based on the directive's index within the template.
2138
+ * @param index - The index of the directive within the template.
2139
+ * @remarks
2140
+ * Creates a custom attribute placeholder.
2141
+ */
2142
+ createHTML(add: AddViewBehaviorFactory): string;
2143
+ /**
2144
+ * Bind this behavior to the source.
2145
+ * @param source - The source to bind to.
2146
+ * @param context - The execution context that the binding is operating within.
2147
+ * @param targets - The targets that behaviors in a view can attach to.
2148
+ */
2149
+ abstract bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
2150
+ /**
2151
+ * Unbinds this behavior from the source.
2152
+ * @param source - The source to unbind from.
2153
+ */
2154
+ abstract unbind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
2155
+ }
2156
+
2157
+ /**
2158
+ * Implemented to provide specific behavior when adding/removing styles
2159
+ * for elements.
2160
+ * @public
2161
+ */
2162
+ export declare interface StyleStrategy {
2163
+ /**
2164
+ * Adds styles to the target.
2165
+ * @param target - The target to add the styles to.
2166
+ */
2167
+ addStylesTo(target: StyleTarget): void;
2168
+ /**
2169
+ * Removes styles from the target.
2170
+ * @param target - The target to remove the styles from.
2171
+ */
2172
+ removeStylesFrom(target: StyleTarget): void;
1639
2173
  }
1640
2174
 
1641
2175
  /**
@@ -1652,12 +2186,6 @@ export declare interface StyleTarget {
1652
2186
  * @param styles - The styles element to add.
1653
2187
  */
1654
2188
  append(styles: HTMLStyleElement): void;
1655
- /**
1656
- * Adds styles to the target by prepending the styles.
1657
- * @param styles - The styles element to add.
1658
- * @deprecated - use append()
1659
- */
1660
- prepend(styles: HTMLStyleElement): void;
1661
2189
  /**
1662
2190
  * Removes styles from the target.
1663
2191
  * @param styles - The styles element to remove.
@@ -1676,17 +2204,17 @@ export declare interface StyleTarget {
1676
2204
  */
1677
2205
  export declare interface Subscriber {
1678
2206
  /**
1679
- * Called when a source this instance has subscribed to changes.
1680
- * @param source - The source of the change.
2207
+ * Called when a subject this instance has subscribed to changes.
2208
+ * @param subject - The subject of the change.
1681
2209
  * @param args - The event args detailing the change that occurred.
1682
2210
  */
1683
- handleChange(source: any, args: any): void;
2211
+ handleChange(subject: any, args: any): void;
1684
2212
  }
1685
2213
 
1686
2214
  /**
1687
2215
  * An implementation of {@link Notifier} that efficiently keeps track of
1688
2216
  * subscribers interested in a specific change notification on an
1689
- * observable source.
2217
+ * observable subject.
1690
2218
  *
1691
2219
  * @remarks
1692
2220
  * This set is optimized for the most common scenario of 1 or 2 subscribers.
@@ -1699,15 +2227,15 @@ export declare class SubscriberSet implements Notifier {
1699
2227
  private sub2;
1700
2228
  private spillover;
1701
2229
  /**
1702
- * The source that this subscriber set is reporting changes for.
2230
+ * The object that subscribers will receive notifications for.
1703
2231
  */
1704
- readonly source: any;
2232
+ readonly subject: any;
1705
2233
  /**
1706
- * Creates an instance of SubscriberSet for the specified source.
1707
- * @param source - The object source that subscribers will receive notifications from.
2234
+ * Creates an instance of SubscriberSet for the specified subject.
2235
+ * @param subject - The subject that subscribers will receive notifications from.
1708
2236
  * @param initialSubscriber - An initial subscriber to changes.
1709
2237
  */
1710
- constructor(source: any, initialSubscriber?: Subscriber);
2238
+ constructor(subject: any, initialSubscriber?: Subscriber);
1711
2239
  /**
1712
2240
  * Checks whether the provided subscriber has been added to this set.
1713
2241
  * @param subscriber - The subscriber to test for inclusion in this set.
@@ -1734,7 +2262,7 @@ export declare class SubscriberSet implements Notifier {
1734
2262
  * The options used to configure subtree observation.
1735
2263
  * @public
1736
2264
  */
1737
- export declare interface SubtreeBehaviorOptions<T = any> extends Omit<NodeBehaviorOptions<T>, "filter">, Omit<MutationObserverInit, "subtree" | "childList"> {
2265
+ export declare interface SubtreeDirectiveOptions<T = any> extends NodeBehaviorOptions<T>, Omit<MutationObserverInit, "subtree" | "childList"> {
1738
2266
  /**
1739
2267
  * Indicates that child subtrees should be observed for changes.
1740
2268
  */
@@ -1750,7 +2278,7 @@ export declare interface SubtreeBehaviorOptions<T = any> extends Omit<NodeBehavi
1750
2278
  * A view representing a range of DOM nodes which can be added/removed ad hoc.
1751
2279
  * @public
1752
2280
  */
1753
- export declare interface SyntheticView extends View {
2281
+ export declare interface SyntheticView<TSource = any, TParent = any> extends View<TSource, TParent> {
1754
2282
  /**
1755
2283
  * The first DOM node in the range of nodes that make up the view.
1756
2284
  */
@@ -1769,11 +2297,6 @@ export declare interface SyntheticView extends View {
1769
2297
  * The nodes are not disposed and the view can later be re-inserted.
1770
2298
  */
1771
2299
  remove(): void;
1772
- /**
1773
- * Removes the view and unbinds its behaviors, disposing of DOM nodes afterward.
1774
- * Once a view has been disposed, it cannot be inserted or bound again.
1775
- */
1776
- dispose(): void;
1777
2300
  }
1778
2301
 
1779
2302
  /**
@@ -1784,31 +2307,14 @@ export declare interface SyntheticViewTemplate<TSource = any, TParent = any> {
1784
2307
  /**
1785
2308
  * Creates a SyntheticView instance based on this template definition.
1786
2309
  */
1787
- create(): SyntheticView;
1788
- }
1789
-
1790
- /**
1791
- * A {@link HTMLDirective} that targets a named attribute or property on a node.
1792
- * @public
1793
- */
1794
- export declare abstract class TargetedHTMLDirective extends HTMLDirective {
1795
- /**
1796
- * Gets/sets the name of the attribute or property that this
1797
- * directive is targeting on the associated node.
1798
- */
1799
- abstract targetName: string | undefined;
1800
- /**
1801
- * Creates a placeholder string based on the directive's index within the template.
1802
- * @param index - The index of the directive within the template.
1803
- */
1804
- createPlaceholder: (index: number) => string;
2310
+ create(): SyntheticView<TSource, TParent>;
1805
2311
  }
1806
2312
 
1807
2313
  /**
1808
2314
  * Represents the types of values that can be interpolated into a template.
1809
2315
  * @public
1810
2316
  */
1811
- export declare type TemplateValue<TScope, TParent = any> = Binding<TScope, any, TParent> | string | number | HTMLDirective | CaptureType<TScope>;
2317
+ export declare type TemplateValue<TSource, TParent = any> = Binding<TSource, any, TParent> | HTMLDirective | CaptureType<TSource>;
1812
2318
 
1813
2319
  /**
1814
2320
  * Enables working with trusted types.
@@ -1835,7 +2341,107 @@ export declare type TrustedTypesPolicy = {
1835
2341
  createHTML(html: string): string;
1836
2342
  };
1837
2343
 
1838
- declare function updatePropertyTarget(this: BindingBehavior, value: unknown): void;
2344
+ /* Excluded from this release type: TypeDefinition */
2345
+
2346
+ /* Excluded from this release type: TypeRegistry */
2347
+
2348
+ /**
2349
+ * A base binding behavior for DOM updates.
2350
+ * @public
2351
+ */
2352
+ export declare class UpdateBinding implements ViewBehavior {
2353
+ readonly directive: HTMLBindingDirective;
2354
+ protected updateTarget: UpdateTarget;
2355
+ /**
2356
+ * Creates an instance of UpdateBinding.
2357
+ * @param directive - The directive that has the configuration for this behavior.
2358
+ * @param updateTarget - The function used to update the target with the latest value.
2359
+ */
2360
+ constructor(directive: HTMLBindingDirective, updateTarget: UpdateTarget);
2361
+ /**
2362
+ * Bind this behavior to the source.
2363
+ * @param source - The source to bind to.
2364
+ * @param context - The execution context that the binding is operating within.
2365
+ * @param targets - The targets that behaviors in a view can attach to.
2366
+ */
2367
+ bind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
2368
+ /**
2369
+ * Unbinds this behavior from the source.
2370
+ * @param source - The source to unbind from.
2371
+ * @param context - The execution context that the binding is operating within.
2372
+ * @param targets - The targets that behaviors in a view can attach to.
2373
+ */
2374
+ unbind(source: any, context: ExecutionContext, targets: ViewBehaviorTargets): void;
2375
+ /**
2376
+ * Creates a behavior.
2377
+ * @param targets - The targets available for behaviors to be attached to.
2378
+ */
2379
+ createBehavior(targets: ViewBehaviorTargets): ViewBehavior;
2380
+ }
2381
+
2382
+ /**
2383
+ * A work queue used to synchronize writes to the DOM.
2384
+ * @public
2385
+ */
2386
+ export declare interface UpdateQueue {
2387
+ /**
2388
+ * Schedules DOM update work in the next batch.
2389
+ * @param callable - The callable function or object to queue.
2390
+ */
2391
+ enqueue(callable: Callable): void;
2392
+ /**
2393
+ * Resolves with the next DOM update.
2394
+ */
2395
+ next(): Promise<void>;
2396
+ /**
2397
+ * Immediately processes all work previously scheduled
2398
+ * through enqueue.
2399
+ * @remarks
2400
+ * This also forces next() promises
2401
+ * to resolve.
2402
+ */
2403
+ process(): void;
2404
+ /**
2405
+ * Sets the update mode used by enqueue.
2406
+ * @param isAsync - Indicates whether DOM updates should be asynchronous.
2407
+ * @remarks
2408
+ * By default, the update mode is asynchronous, since that provides the best
2409
+ * performance in the browser. Passing false to setMode will instead cause
2410
+ * the queue to be immediately processed for each call to enqueue. However,
2411
+ * ordering will still be preserved so that nested tasks do not run until
2412
+ * after parent tasks complete.
2413
+ */
2414
+ setMode(isAsync: boolean): void;
2415
+ }
2416
+
2417
+ /**
2418
+ * The default UpdateQueue.
2419
+ * @public
2420
+ */
2421
+ export declare const Updates: UpdateQueue;
2422
+
2423
+ /**
2424
+ * A target update function.
2425
+ * @param this - The "this" context for the update.
2426
+ * @param target - The node that is targeted by the update.
2427
+ * @param aspect - The aspect of the node that is being targeted.
2428
+ * @param value - The value to assign to the aspect.
2429
+ * @param source - The source object that the value was derived from.
2430
+ * @param context - The execution context that the binding is being run under.
2431
+ * @public
2432
+ */
2433
+ export declare type UpdateTarget = (this: UpdateTargetThis, target: Node, aspect: string, value: any, source: any, context: ExecutionContext) => void;
2434
+
2435
+ /**
2436
+ * The "this" context for an update target function.
2437
+ * @public
2438
+ */
2439
+ export declare interface UpdateTargetThis {
2440
+ /**
2441
+ * The directive configuration for the update.
2442
+ */
2443
+ directive: HTMLBindingDirective;
2444
+ }
1839
2445
 
1840
2446
  /**
1841
2447
  * Represents objects that can convert values to and from
@@ -1859,43 +2465,83 @@ export declare interface ValueConverter {
1859
2465
  * Represents a collection of DOM nodes which can be bound to a data source.
1860
2466
  * @public
1861
2467
  */
1862
- export declare interface View {
2468
+ export declare interface View<TSource = any, TParent = any> extends Disposable {
1863
2469
  /**
1864
2470
  * The execution context the view is running within.
1865
2471
  */
1866
- readonly context: ExecutionContext | null;
2472
+ readonly context: ExecutionContext<TParent> | null;
1867
2473
  /**
1868
2474
  * The data that the view is bound to.
1869
2475
  */
1870
- readonly source: any | null;
2476
+ readonly source: TSource | null;
1871
2477
  /**
1872
2478
  * Binds a view's behaviors to its binding source.
1873
2479
  * @param source - The binding source for the view's binding behaviors.
1874
2480
  * @param context - The execution context to run the view within.
1875
2481
  */
1876
- bind(source: unknown, context: ExecutionContext): void;
2482
+ bind(source: TSource, context: ExecutionContext<TParent>): void;
1877
2483
  /**
1878
2484
  * Unbinds a view's behaviors from its binding source and context.
1879
2485
  */
1880
2486
  unbind(): void;
2487
+ }
2488
+
2489
+ /**
2490
+ * Represents an object that can contribute behavior to a view.
2491
+ * @public
2492
+ */
2493
+ export declare interface ViewBehavior<TSource = any, TParent = any> {
1881
2494
  /**
1882
- * Removes the view and unbinds its behaviors, disposing of DOM nodes afterward.
1883
- * Once a view has been disposed, it cannot be inserted or bound again.
2495
+ * Bind this behavior to the source.
2496
+ * @param source - The source to bind to.
2497
+ * @param context - The execution context that the binding is operating within.
2498
+ * @param targets - The targets that behaviors in a view can attach to.
1884
2499
  */
1885
- dispose(): void;
2500
+ bind(source: TSource, context: ExecutionContext<TParent>, targets: ViewBehaviorTargets): void;
2501
+ /**
2502
+ * Unbinds this behavior from the source.
2503
+ * @param source - The source to unbind from.
2504
+ * @param context - The execution context that the binding is operating within.
2505
+ * @param targets - The targets that behaviors in a view can attach to.
2506
+ */
2507
+ unbind(source: TSource, context: ExecutionContext<TParent>, targets: ViewBehaviorTargets): void;
2508
+ }
2509
+
2510
+ /**
2511
+ * A factory that can create a {@link Behavior} associated with a particular
2512
+ * location within a DOM fragment.
2513
+ * @public
2514
+ */
2515
+ export declare interface ViewBehaviorFactory {
2516
+ /**
2517
+ * The unique id of the factory.
2518
+ */
2519
+ id: string;
2520
+ /**
2521
+ * The structural id of the DOM node to which the created behavior will apply.
2522
+ */
2523
+ nodeId: string;
2524
+ /**
2525
+ * Creates a behavior.
2526
+ * @param targets - The targets available for behaviors to be attached to.
2527
+ */
2528
+ createBehavior(targets: ViewBehaviorTargets): Behavior | ViewBehavior;
1886
2529
  }
1887
2530
 
2531
+ /**
2532
+ * The target nodes available to a behavior.
2533
+ * @public
2534
+ */
2535
+ export declare type ViewBehaviorTargets = {
2536
+ [id: string]: Node;
2537
+ };
2538
+
1888
2539
  /**
1889
2540
  * A template capable of creating HTMLView instances or rendering directly to DOM.
1890
2541
  * @public
1891
2542
  */
1892
- export declare class ViewTemplate<TSource = any, TParent = any> implements ElementViewTemplate, SyntheticViewTemplate {
1893
- private behaviorCount;
1894
- private hasHostBehaviors;
1895
- private fragment;
1896
- private targetOffset;
1897
- private viewBehaviorFactories;
1898
- private hostBehaviorFactories;
2543
+ export declare class ViewTemplate<TSource = any, TParent = any> implements ElementViewTemplate<TSource, TParent>, SyntheticViewTemplate<TSource, TParent> {
2544
+ private result;
1899
2545
  /**
1900
2546
  * The html representing what this template will
1901
2547
  * instantiate, including placeholders for directives.
@@ -1904,18 +2550,18 @@ export declare class ViewTemplate<TSource = any, TParent = any> implements Eleme
1904
2550
  /**
1905
2551
  * The directives that will be connected to placeholders in the html.
1906
2552
  */
1907
- readonly directives: ReadonlyArray<HTMLDirective>;
2553
+ readonly factories: Record<string, ViewBehaviorFactory>;
1908
2554
  /**
1909
2555
  * Creates an instance of ViewTemplate.
1910
2556
  * @param html - The html representing what this template will instantiate, including placeholders for directives.
1911
- * @param directives - The directives that will be connected to placeholders in the html.
2557
+ * @param factories - The directives that will be connected to placeholders in the html.
1912
2558
  */
1913
- constructor(html: string | HTMLTemplateElement, directives: ReadonlyArray<HTMLDirective>);
2559
+ constructor(html: string | HTMLTemplateElement, factories: Record<string, ViewBehaviorFactory>);
1914
2560
  /**
1915
2561
  * Creates an HTMLView instance based on this template definition.
1916
2562
  * @param hostBindingTarget - The element that host behaviors will be bound to.
1917
2563
  */
1918
- create(hostBindingTarget?: Element): HTMLView;
2564
+ create(hostBindingTarget?: Element): HTMLView<TSource, TParent>;
1919
2565
  /**
1920
2566
  * Creates an HTMLView from this template, binds it to the source, and then appends it to the host.
1921
2567
  * @param source - The data source to bind the template to.
@@ -1923,7 +2569,7 @@ export declare class ViewTemplate<TSource = any, TParent = any> implements Eleme
1923
2569
  * @param hostBindingTarget - An HTML element to target the host bindings at if different from the
1924
2570
  * host that the template is being attached to.
1925
2571
  */
1926
- render(source: TSource, host: Node | string, hostBindingTarget?: Element): HTMLView;
2572
+ render(source: TSource, host: Node, hostBindingTarget?: Element, context?: ExecutionContext): HTMLView<TSource, TParent>;
1927
2573
  }
1928
2574
 
1929
2575
  /**