@lushly-dev/fast-element 3.0.1-preview.0 → 3.0.1-preview.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 (250) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/dist/command/command.api.json +7857 -0
  3. package/dist/context/context.api.json +1084 -0
  4. package/dist/declarative/declarative.api.json +8130 -0
  5. package/dist/definition-schema/definition-schema.api.json +2689 -0
  6. package/dist/di/di.api.json +4945 -0
  7. package/dist/dts/arrays.d.ts +2 -0
  8. package/dist/dts/binding/binding.d.ts +59 -0
  9. package/dist/dts/binding/exports.d.ts +9 -0
  10. package/dist/dts/binding/normalize.d.ts +9 -0
  11. package/dist/dts/binding/one-time.d.ts +11 -0
  12. package/dist/dts/binding/one-way.d.ts +20 -0
  13. package/dist/dts/binding/signal.d.ts +36 -0
  14. package/dist/dts/binding/two-way.d.ts +44 -0
  15. package/dist/dts/command/behavior.d.ts +94 -0
  16. package/dist/dts/command/behaviors/confirm-behavior.d.ts +139 -0
  17. package/dist/dts/command/behaviors/undo-behavior.d.ts +178 -0
  18. package/dist/dts/command/command.d.ts +79 -0
  19. package/dist/dts/command/component-registry.d.ts +50 -0
  20. package/dist/dts/command/components/confirm-dialog.d.ts +117 -0
  21. package/dist/dts/command/index.d.ts +21 -0
  22. package/dist/dts/command/registry.d.ts +201 -0
  23. package/dist/dts/command/schema-validation.d.ts +45 -0
  24. package/dist/dts/command/types.d.ts +332 -0
  25. package/dist/dts/command/validation.d.ts +116 -0
  26. package/dist/dts/command/weak-ref.d.ts +11 -0
  27. package/dist/dts/components/attributes.d.ts +153 -0
  28. package/dist/dts/components/definition-schema-transforms.d.ts +9 -0
  29. package/dist/dts/components/element-controller.d.ts +349 -0
  30. package/dist/dts/components/element-hydration.d.ts +2 -0
  31. package/dist/dts/components/enable-hydration.d.ts +66 -0
  32. package/dist/dts/components/fast-definitions.d.ts +211 -0
  33. package/dist/dts/components/fast-element-registry.d.ts +23 -0
  34. package/dist/dts/components/fast-element.d.ts +91 -0
  35. package/dist/dts/components/hydration-tracker.d.ts +110 -0
  36. package/dist/dts/components/hydration.d.ts +52 -0
  37. package/dist/dts/components/schema.d.ts +205 -0
  38. package/dist/dts/context.d.ts +171 -0
  39. package/dist/dts/debug.d.ts +5 -0
  40. package/dist/dts/declarative/attribute-map.d.ts +58 -0
  41. package/dist/dts/declarative/debug.d.ts +4 -0
  42. package/dist/dts/declarative/index.d.ts +14 -0
  43. package/dist/dts/declarative/interfaces.d.ts +8 -0
  44. package/dist/dts/declarative/observer-map-utilities.d.ts +58 -0
  45. package/dist/dts/declarative/observer-map.d.ts +89 -0
  46. package/dist/dts/declarative/runtime.d.ts +5 -0
  47. package/dist/dts/declarative/syntax.d.ts +21 -0
  48. package/dist/dts/declarative/template-bridge.d.ts +33 -0
  49. package/dist/dts/declarative/template-parser.d.ts +98 -0
  50. package/dist/dts/declarative/template.d.ts +9 -0
  51. package/dist/dts/declarative/utilities.d.ts +358 -0
  52. package/dist/dts/definition-schema/api.d.ts +42 -0
  53. package/dist/dts/definition-schema/cem.d.ts +78 -0
  54. package/dist/dts/definition-schema/extension.d.ts +18 -0
  55. package/dist/dts/definition-schema/extract.d.ts +38 -0
  56. package/dist/dts/definition-schema/index.d.ts +9 -0
  57. package/dist/dts/definition-schema/storage.d.ts +35 -0
  58. package/dist/dts/definition-schema/types.d.ts +176 -0
  59. package/dist/dts/dev-mode.d.ts +13 -0
  60. package/dist/dts/di/di.d.ts +894 -0
  61. package/dist/dts/dom-policy.d.ts +101 -0
  62. package/dist/dts/dom.d.ts +88 -0
  63. package/dist/dts/hydration/diagnostics.d.ts +93 -0
  64. package/dist/dts/hydration/exports.d.ts +18 -0
  65. package/dist/dts/hydration/hydration-debugger.d.ts +35 -0
  66. package/dist/dts/hydration/messages.d.ts +62 -0
  67. package/dist/dts/hydration/runtime.d.ts +7 -0
  68. package/dist/dts/hydration/target-builder.d.ts +107 -0
  69. package/dist/dts/index.d.ts +51 -0
  70. package/dist/dts/index.debug.d.ts +1 -0
  71. package/dist/dts/index.rollup.d.ts +1 -0
  72. package/dist/dts/index.rollup.debug.d.ts +1 -0
  73. package/dist/dts/interfaces.d.ts +106 -0
  74. package/dist/dts/metadata.d.ts +26 -0
  75. package/dist/dts/observation/arrays.d.ts +248 -0
  76. package/dist/dts/observation/notifier.d.ts +127 -0
  77. package/dist/dts/observation/observable.d.ts +276 -0
  78. package/dist/dts/observation/update-queue.d.ts +40 -0
  79. package/dist/dts/observation/volatile.d.ts +9 -0
  80. package/dist/dts/platform.d.ts +87 -0
  81. package/dist/dts/registry.d.ts +2 -0
  82. package/dist/dts/render.d.ts +7 -0
  83. package/dist/dts/schema.d.ts +1 -0
  84. package/dist/dts/scoped/detection.d.ts +55 -0
  85. package/dist/dts/scoped/index.d.ts +68 -0
  86. package/dist/dts/scoped/mixin.d.ts +118 -0
  87. package/dist/dts/scoped/registry.d.ts +76 -0
  88. package/dist/dts/scoped/types.d.ts +48 -0
  89. package/dist/dts/state/exports.d.ts +3 -0
  90. package/dist/dts/state/reactive.d.ts +8 -0
  91. package/dist/dts/state/state.d.ts +141 -0
  92. package/dist/dts/state/visitor.d.ts +6 -0
  93. package/dist/dts/state/watch.d.ts +10 -0
  94. package/dist/dts/styles/css-directive.d.ts +50 -0
  95. package/dist/dts/styles/css.d.ts +34 -0
  96. package/dist/dts/styles/element-styles.d.ts +61 -0
  97. package/dist/dts/styles/host.d.ts +65 -0
  98. package/dist/dts/styles/style-strategy.d.ts +42 -0
  99. package/dist/dts/templating/children.d.ts +62 -0
  100. package/dist/dts/templating/compiler.d.ts +54 -0
  101. package/dist/dts/templating/html-binding-directive.d.ts +155 -0
  102. package/dist/dts/templating/html-directive.d.ts +218 -0
  103. package/dist/dts/templating/html.d.ts +1 -0
  104. package/dist/dts/templating/hydration-view.d.ts +130 -0
  105. package/dist/dts/templating/markup.d.ts +48 -0
  106. package/dist/dts/templating/node-observation.d.ts +99 -0
  107. package/dist/dts/templating/ref.d.ts +23 -0
  108. package/dist/dts/templating/render.d.ts +318 -0
  109. package/dist/dts/templating/repeat.d.ts +131 -0
  110. package/dist/dts/templating/slotted.d.ts +38 -0
  111. package/dist/dts/templating/template.d.ts +221 -0
  112. package/dist/dts/templating/view.d.ts +268 -0
  113. package/dist/dts/templating/when.d.ts +12 -0
  114. package/dist/dts/testing/exports.d.ts +3 -0
  115. package/dist/dts/testing/fakes.d.ts +16 -0
  116. package/dist/dts/testing/fixture.d.ts +84 -0
  117. package/dist/dts/testing/models.d.ts +20 -0
  118. package/dist/dts/testing/timeout.d.ts +7 -0
  119. package/dist/dts/trust/index.d.ts +8 -0
  120. package/dist/dts/trust/types.d.ts +48 -0
  121. package/dist/dts/trust/utils.d.ts +26 -0
  122. package/dist/dts/tsdoc-metadata.json +11 -0
  123. package/dist/dts/utilities.d.ts +76 -0
  124. package/dist/esm/arrays.js +1 -0
  125. package/dist/esm/binding/binding.js +18 -0
  126. package/dist/esm/binding/exports.js +6 -0
  127. package/dist/esm/binding/normalize.js +17 -0
  128. package/dist/esm/binding/one-time.js +21 -0
  129. package/dist/esm/binding/one-way.js +30 -0
  130. package/dist/esm/binding/signal.js +99 -0
  131. package/dist/esm/binding/two-way.js +109 -0
  132. package/dist/esm/command/behavior.js +155 -0
  133. package/dist/esm/command/behaviors/confirm-behavior.js +225 -0
  134. package/dist/esm/command/behaviors/undo-behavior.js +313 -0
  135. package/dist/esm/command/command.js +104 -0
  136. package/dist/esm/command/component-registry.js +107 -0
  137. package/dist/esm/command/components/confirm-dialog.js +370 -0
  138. package/dist/esm/command/index.js +22 -0
  139. package/dist/esm/command/registry.js +755 -0
  140. package/dist/esm/command/schema-validation.js +194 -0
  141. package/dist/esm/command/types.js +86 -0
  142. package/dist/esm/command/validation.js +508 -0
  143. package/dist/esm/command/weak-ref.js +5 -0
  144. package/dist/esm/components/attributes.js +219 -0
  145. package/dist/esm/components/definition-schema-transforms.js +23 -0
  146. package/dist/esm/components/element-controller.js +840 -0
  147. package/dist/esm/components/element-hydration.js +2 -0
  148. package/dist/esm/components/enable-hydration.js +123 -0
  149. package/dist/esm/components/fast-definitions.js +294 -0
  150. package/dist/esm/components/fast-element-registry.js +67 -0
  151. package/dist/esm/components/fast-element.js +82 -0
  152. package/dist/esm/components/hydration-tracker.js +211 -0
  153. package/dist/esm/components/hydration.js +187 -0
  154. package/dist/esm/components/schema.js +253 -0
  155. package/dist/esm/context.js +185 -0
  156. package/dist/esm/debug.js +71 -0
  157. package/dist/esm/declarative/attribute-map.js +122 -0
  158. package/dist/esm/declarative/debug.js +4 -0
  159. package/dist/esm/declarative/index.js +10 -0
  160. package/dist/esm/declarative/interfaces.js +9 -0
  161. package/dist/esm/declarative/observer-map-utilities.js +565 -0
  162. package/dist/esm/declarative/observer-map.js +216 -0
  163. package/dist/esm/declarative/runtime.js +14 -0
  164. package/dist/esm/declarative/syntax.js +36 -0
  165. package/dist/esm/declarative/template-bridge.js +160 -0
  166. package/dist/esm/declarative/template-parser.js +306 -0
  167. package/dist/esm/declarative/template.js +116 -0
  168. package/dist/esm/declarative/utilities.js +1069 -0
  169. package/dist/esm/definition-schema/api.js +129 -0
  170. package/dist/esm/definition-schema/cem.js +89 -0
  171. package/dist/esm/definition-schema/extension.js +53 -0
  172. package/dist/esm/definition-schema/extract.js +167 -0
  173. package/dist/esm/definition-schema/index.js +8 -0
  174. package/dist/esm/definition-schema/storage.js +58 -0
  175. package/dist/esm/definition-schema/types.js +8 -0
  176. package/dist/esm/dev-mode.js +22 -0
  177. package/dist/esm/di/di.js +1441 -0
  178. package/dist/esm/dom-policy.js +374 -0
  179. package/dist/esm/dom.js +101 -0
  180. package/dist/esm/hydration/diagnostics.js +50 -0
  181. package/dist/esm/hydration/exports.js +6 -0
  182. package/dist/esm/hydration/hydration-debugger.js +112 -0
  183. package/dist/esm/hydration/messages.js +84 -0
  184. package/dist/esm/hydration/runtime.js +33 -0
  185. package/dist/esm/hydration/target-builder.js +264 -0
  186. package/dist/esm/index.debug.js +3 -0
  187. package/dist/esm/index.js +49 -0
  188. package/dist/esm/index.rollup.debug.js +6 -0
  189. package/dist/esm/index.rollup.js +4 -0
  190. package/dist/esm/interfaces.js +55 -0
  191. package/dist/esm/metadata.js +57 -0
  192. package/dist/esm/observation/arrays.js +661 -0
  193. package/dist/esm/observation/notifier.js +162 -0
  194. package/dist/esm/observation/observable.js +324 -0
  195. package/dist/esm/observation/update-queue.js +56 -0
  196. package/dist/esm/observation/volatile.js +16 -0
  197. package/dist/esm/platform.js +98 -0
  198. package/dist/esm/registry.js +2 -0
  199. package/dist/esm/render.js +1 -0
  200. package/dist/esm/schema.js +1 -0
  201. package/dist/esm/scoped/detection.js +102 -0
  202. package/dist/esm/scoped/index.js +69 -0
  203. package/dist/esm/scoped/mixin.js +127 -0
  204. package/dist/esm/scoped/registry.js +125 -0
  205. package/dist/esm/scoped/types.js +4 -0
  206. package/dist/esm/state/exports.js +3 -0
  207. package/dist/esm/state/reactive.js +34 -0
  208. package/dist/esm/state/state.js +148 -0
  209. package/dist/esm/state/visitor.js +28 -0
  210. package/dist/esm/state/watch.js +36 -0
  211. package/dist/esm/styles/css-directive.js +36 -0
  212. package/dist/esm/styles/css.js +56 -0
  213. package/dist/esm/styles/element-styles.js +144 -0
  214. package/dist/esm/styles/host.js +1 -0
  215. package/dist/esm/styles/style-strategy.js +1 -0
  216. package/dist/esm/templating/children.js +67 -0
  217. package/dist/esm/templating/compiler.js +359 -0
  218. package/dist/esm/templating/html-binding-directive.js +288 -0
  219. package/dist/esm/templating/html-directive.js +113 -0
  220. package/dist/esm/templating/html.js +1 -0
  221. package/dist/esm/templating/hydration-view.js +228 -0
  222. package/dist/esm/templating/markup.js +83 -0
  223. package/dist/esm/templating/node-observation.js +84 -0
  224. package/dist/esm/templating/ref.js +21 -0
  225. package/dist/esm/templating/render.js +468 -0
  226. package/dist/esm/templating/repeat.js +434 -0
  227. package/dist/esm/templating/slotted.js +49 -0
  228. package/dist/esm/templating/template.js +206 -0
  229. package/dist/esm/templating/view.js +298 -0
  230. package/dist/esm/templating/when.js +22 -0
  231. package/dist/esm/testing/exports.js +3 -0
  232. package/dist/esm/testing/fakes.js +107 -0
  233. package/dist/esm/testing/fixture.js +86 -0
  234. package/dist/esm/testing/models.js +58 -0
  235. package/dist/esm/testing/timeout.js +24 -0
  236. package/dist/esm/trust/index.js +7 -0
  237. package/dist/esm/trust/types.js +6 -0
  238. package/dist/esm/trust/utils.js +126 -0
  239. package/dist/esm/utilities.js +140 -0
  240. package/dist/fast-element.api.json +26798 -0
  241. package/dist/fast-element.d.ts +3985 -0
  242. package/dist/fast-element.debug.js +7604 -0
  243. package/dist/fast-element.debug.min.js +3 -0
  244. package/dist/fast-element.js +7603 -0
  245. package/dist/fast-element.min.js +3 -0
  246. package/dist/fast-element.untrimmed.d.ts +4103 -0
  247. package/dist/observation/arrays/arrays.api.json +2621 -0
  248. package/dist/scoped/scoped.api.json +891 -0
  249. package/dist/trust/trust.api.json +629 -0
  250. package/package.json +21 -23
@@ -0,0 +1,101 @@
1
+ import { DOMAspect, type DOMSink } from "./dom.js";
2
+ import { type TrustedTypesPolicy } from "./interfaces.js";
3
+ /**
4
+ * A policy that controls whether values can be written to DOM sinks.
5
+ * @public
6
+ */
7
+ export interface DOMPolicy {
8
+ /**
9
+ * Creates safe HTML from the provided value.
10
+ * @param value - The source to convert to safe HTML.
11
+ */
12
+ createHTML(value: string): string;
13
+ /**
14
+ * Protects a DOM sink that intends to write to the DOM.
15
+ * @param tagName - The tag name for the element to write to.
16
+ * @param aspect - The aspect of the DOM to write to.
17
+ * @param aspectName - The name of the aspect to write to.
18
+ * @param sink - The sink that is used to write to the DOM.
19
+ */
20
+ protect(tagName: string | null, aspect: DOMAspect, aspectName: string, sink: DOMSink): DOMSink;
21
+ }
22
+ /**
23
+ * A specific DOM sink guard for a node aspect.
24
+ * @public
25
+ */
26
+ export type DOMSinkGuards = Record<string, (tagName: string | null, aspect: DOMAspect, aspectName: string, sink: DOMSink) => DOMSink>;
27
+ /**
28
+ * Aspect-specific guards for a DOM Policy.
29
+ * @public
30
+ */
31
+ export type DOMAspectGuards = {
32
+ /**
33
+ * Guards for attributes.
34
+ */
35
+ [DOMAspect.attribute]?: DOMSinkGuards;
36
+ /**
37
+ * Guards for boolean attributes.
38
+ */
39
+ [DOMAspect.booleanAttribute]?: DOMSinkGuards;
40
+ /**
41
+ * Guards for properties.
42
+ */
43
+ [DOMAspect.property]?: DOMSinkGuards;
44
+ /**
45
+ * Guards for content.
46
+ */
47
+ [DOMAspect.content]?: DOMSinkGuards;
48
+ /**
49
+ * Guards for token list manipulation.
50
+ */
51
+ [DOMAspect.tokenList]?: DOMSinkGuards;
52
+ /**
53
+ * Guards for events.
54
+ */
55
+ [DOMAspect.event]?: DOMSinkGuards;
56
+ };
57
+ /**
58
+ * Element-specific guards for a DOM Policy.
59
+ * @public
60
+ */
61
+ export type DOMElementGuards = Record<string, DOMAspectGuards>;
62
+ /**
63
+ * Guard configuration for a DOM Policy.
64
+ * @public
65
+ */
66
+ export type DOMGuards = {
67
+ /**
68
+ * Guards for specific elements.
69
+ */
70
+ elements: DOMElementGuards;
71
+ /**
72
+ * General aspect guards independent of the element type.
73
+ */
74
+ aspects: DOMAspectGuards;
75
+ };
76
+ /**
77
+ * Options for creating a DOM Policy.
78
+ * @public
79
+ */
80
+ export type DOMPolicyOptions = {
81
+ /**
82
+ * The trusted type to use for HTML creation.
83
+ */
84
+ trustedType?: TrustedTypesPolicy;
85
+ /**
86
+ * The DOM guards used to override or extend the defaults.
87
+ */
88
+ guards?: Partial<DOMGuards>;
89
+ };
90
+ /**
91
+ * A helper for creating DOM policies.
92
+ * @public
93
+ */
94
+ export declare const DOMPolicy: Readonly<{
95
+ /**
96
+ * Creates a new DOM Policy object.
97
+ * @param options - The options to use in creating the policy.
98
+ * @returns The newly created DOMPolicy.
99
+ */
100
+ create(options?: DOMPolicyOptions): Readonly<DOMPolicy>;
101
+ }>;
@@ -0,0 +1,88 @@
1
+ import type { DOMPolicy as DOMPolicyDefinition } from "./dom-policy.js";
2
+ /**
3
+ * The type of HTML aspect to target.
4
+ * @public
5
+ */
6
+ export declare const DOMAspect: Readonly<{
7
+ /**
8
+ * Not aspected.
9
+ */
10
+ readonly none: 0;
11
+ /**
12
+ * An attribute.
13
+ */
14
+ readonly attribute: 1;
15
+ /**
16
+ * A boolean attribute.
17
+ */
18
+ readonly booleanAttribute: 2;
19
+ /**
20
+ * A property.
21
+ */
22
+ readonly property: 3;
23
+ /**
24
+ * Content
25
+ */
26
+ readonly content: 4;
27
+ /**
28
+ * A token list.
29
+ */
30
+ readonly tokenList: 5;
31
+ /**
32
+ * An event.
33
+ */
34
+ readonly event: 6;
35
+ }>;
36
+ /**
37
+ * The type of HTML aspect to target.
38
+ * @public
39
+ */
40
+ export type DOMAspect = (typeof DOMAspect)[Exclude<keyof typeof DOMAspect, "none">];
41
+ /**
42
+ * A function used to send values to a DOM sink.
43
+ * @public
44
+ */
45
+ export type DOMSink = (target: Node, aspectName: string, value: any, ...args: any[]) => void;
46
+ /**
47
+ * A security policy that FAST can use to interact with the DOM.
48
+ * @public
49
+ */
50
+ export interface DOMPolicy extends DOMPolicyDefinition {
51
+ }
52
+ /**
53
+ * Common DOM APIs.
54
+ * @public
55
+ */
56
+ export declare const DOM: Readonly<{
57
+ /**
58
+ * Gets the dom policy used by the templating system.
59
+ */
60
+ readonly policy: DOMPolicyDefinition;
61
+ /**
62
+ * Sets the dom policy used by the templating system.
63
+ * @param policy - The policy to set.
64
+ * @remarks
65
+ * This API can only be called once, for security reasons. It should be
66
+ * called by the application developer at the start of their program.
67
+ */
68
+ setPolicy(value: DOMPolicyDefinition): void;
69
+ /**
70
+ * Sets an attribute value on an element.
71
+ * @param element - The element to set the attribute value on.
72
+ * @param attributeName - The attribute name to set.
73
+ * @param value - The value of the attribute to set.
74
+ * @remarks
75
+ * If the value is `null` or `undefined`, the attribute is removed, otherwise
76
+ * it is set to the provided value using the standard `setAttribute` API.
77
+ */
78
+ setAttribute(element: HTMLElement, attributeName: string, value: any): void;
79
+ /**
80
+ * Sets a boolean attribute value.
81
+ * @param element - The element to set the boolean attribute value on.
82
+ * @param attributeName - The attribute name to set.
83
+ * @param value - The value of the attribute to set.
84
+ * @remarks
85
+ * If the value is true, the attribute is added; otherwise it is removed.
86
+ */
87
+ setBooleanAttribute(element: HTMLElement, attributeName: string, value: boolean): void;
88
+ }>;
@@ -0,0 +1,93 @@
1
+ import type { ViewBehaviorFactory } from "../templating/html-directive.js";
2
+ /**
3
+ * Structured description of the binding hydration was expecting to apply when
4
+ * a mismatch is detected.
5
+ * @public
6
+ */
7
+ export interface HydrationMismatchExpectation {
8
+ /**
9
+ * The tag name of the element the binding was expecting (e.g. `"SPAN"`),
10
+ * or `null` when the binding does not target a specific element (host or
11
+ * template-level bindings).
12
+ */
13
+ tagName: string | null;
14
+ /**
15
+ * Human-readable description of the binding aspect, for example
16
+ * `"content"`, `"property className"`, or `"attribute aria-label"`.
17
+ */
18
+ aspect: string;
19
+ }
20
+ /**
21
+ * Structured description of the DOM hydration actually encountered at the
22
+ * mismatch point.
23
+ * @public
24
+ */
25
+ export interface HydrationMismatchActual {
26
+ /**
27
+ * Serialized HTML snippet of the server-rendered DOM where the mismatch
28
+ * was detected. Truncated with an ellipsis when long.
29
+ */
30
+ html: string;
31
+ }
32
+ /**
33
+ * Result of a hydration-mismatch diagnostic format call.
34
+ * @public
35
+ */
36
+ export interface HydrationDiagnosticResult {
37
+ /**
38
+ * The error message to attach to the thrown hydration error.
39
+ */
40
+ message: string;
41
+ /**
42
+ * Structured description of the binding the hydration walk was
43
+ * attempting to apply. The default diagnostic leaves this `undefined`;
44
+ * install `hydrationDebugger()` to populate it.
45
+ */
46
+ expected?: HydrationMismatchExpectation | string;
47
+ /**
48
+ * Structured description of the server-rendered DOM that was
49
+ * encountered at the mismatch point. The default diagnostic leaves
50
+ * this `undefined`; install `hydrationDebugger()` to populate it.
51
+ */
52
+ received?: HydrationMismatchActual;
53
+ }
54
+ /**
55
+ * Pluggable formatter for hydration mismatch errors. The default
56
+ * implementation is a minimal one-line message; install
57
+ * {@link hydrationDebugger} to swap in the rich "Expected … / Received …"
58
+ * formatter with an HTML snippet of the SSR DOM.
59
+ * @public
60
+ */
61
+ export interface HydrationDiagnostic {
62
+ /**
63
+ * Format a binding-resolution mismatch (a factory whose `targetNodeId`
64
+ * has no entry in the resolved targets after the SSR DOM walk).
65
+ */
66
+ formatBindingMismatch(factory: ViewBehaviorFactory, firstChild: Node, lastChild: Node, hostName: string | undefined): HydrationDiagnosticResult;
67
+ /**
68
+ * Format a structural error encountered during the SSR DOM walk
69
+ * (e.g. attribute binding count overflow, missing close marker).
70
+ */
71
+ formatStructuralError(node: Node, hostName: string | undefined, expectedDescription: string): HydrationDiagnosticResult;
72
+ }
73
+ /**
74
+ * Installs a {@link HydrationDiagnostic} as the active formatter for
75
+ * hydration mismatch errors. Called by `enableHydration()` when an opt-in
76
+ * debugger configuration is supplied; not exposed as `@public` because
77
+ * library consumers should always go through `enableHydration` to install
78
+ * a debugger.
79
+ * @internal
80
+ */
81
+ export declare function installHydrationDiagnostic(diagnostic: HydrationDiagnostic): void;
82
+ /**
83
+ * Returns the currently active {@link HydrationDiagnostic} — either the
84
+ * minimal default or one installed by an opt-in debugger.
85
+ * @internal
86
+ */
87
+ export declare function getHydrationDiagnostic(): HydrationDiagnostic;
88
+ /**
89
+ * Reads the host element's tag name from any node inside a hydration view.
90
+ * Returns `undefined` when the node is not inside a shadow root.
91
+ * @internal
92
+ */
93
+ export declare function getHostName(node: Node | null | undefined): string | undefined;
@@ -0,0 +1,18 @@
1
+ export type { HydrationController, HydrationOptions, } from "../components/enable-hydration.js";
2
+ export { deferHydrationAttribute, enableHydration, StopHydration, } from "../components/enable-hydration.js";
3
+ export { isHydratable } from "../components/hydration.js";
4
+ export { HydrationTracker } from "../components/hydration-tracker.js";
5
+ export type { DOMAspect, DOMSink, } from "../dom.js";
6
+ export { type DOMAspectGuards, type DOMElementGuards, type DOMGuards, DOMPolicy, type DOMPolicyOptions, type DOMSinkGuards, } from "../dom-policy.js";
7
+ export type { Disposable, TrustedTypesPolicy } from "../interfaces.js";
8
+ export type { ExecutionContext, ExpressionController, SourceLifetime, } from "../observation/observable.js";
9
+ export type { ContentTemplate, ContentView, HydratableContentTemplate, } from "../templating/html-binding-directive.js";
10
+ export type { ViewBehavior, ViewBehaviorFactory, ViewBehaviorTargets, ViewController, } from "../templating/html-directive.js";
11
+ export type { HydratableView, HydratableViewController, ViewNodes, } from "../templating/hydration-view.js";
12
+ export { HydrationBindingError, HydrationStage, } from "../templating/hydration-view.js";
13
+ export type { CaptureType, ElementViewTemplate, HydratableElementViewTemplate, HydratableSyntheticViewTemplate, SyntheticViewTemplate, } from "../templating/template.js";
14
+ export type { DefaultExecutionContext, ElementView, SyntheticView, View, } from "../templating/view.js";
15
+ export type { HydrationDiagnostic, HydrationDiagnosticResult, HydrationMismatchActual, HydrationMismatchExpectation, } from "./diagnostics.js";
16
+ export type { HydrationDebugger } from "./hydration-debugger.js";
17
+ export { hydrationDebugger } from "./hydration-debugger.js";
18
+ export type { ViewBehaviorBoundaries, ViewBoundaries, } from "./target-builder.js";
@@ -0,0 +1,35 @@
1
+ import type { HydrationDiagnostic } from "./diagnostics.js";
2
+ /**
3
+ * Opt-in hydration debugger configuration. Pass to `enableHydration` to
4
+ * install the rich "Expected / Received" hydration mismatch formatter:
5
+ *
6
+ * ```ts
7
+ * import { enableHydration, hydrationDebugger } from "@lushly-dev/fast-element/hydration.js";
8
+ *
9
+ * enableHydration({ debugger: hydrationDebugger() });
10
+ * ```
11
+ *
12
+ * @public
13
+ */
14
+ export interface HydrationDebugger {
15
+ /**
16
+ * The {@link HydrationDiagnostic} the debugger installs when consumed
17
+ * by `enableHydration`.
18
+ */
19
+ readonly diagnostic: HydrationDiagnostic;
20
+ }
21
+ /**
22
+ * Returns a {@link HydrationDebugger} that, when supplied to
23
+ * `enableHydration({ debugger })`, installs the rich hydration mismatch
24
+ * formatter: a single-line "Expected … / Received …" message plus an HTML
25
+ * snippet of the SSR DOM and structured `expected`/`received` fields on
26
+ * the thrown error (both `HydrationBindingError` and
27
+ * `HydrationTargetElementError`).
28
+ *
29
+ * Without the debugger, hydration errors emit only a minimal one-line
30
+ * message pointing at this function — keeping the runtime hydration cost
31
+ * small for production bundles that do not need rich diagnostics.
32
+ *
33
+ * @public
34
+ */
35
+ export declare function hydrationDebugger(): HydrationDebugger;
@@ -0,0 +1,62 @@
1
+ /**
2
+ * Centralized hydration mismatch message strings used by both the default
3
+ * minimal `HydrationDiagnostic` and the opt-in `hydrationDebugger` rich
4
+ * formatter, and by the structural-error throw sites in
5
+ * `target-builder.ts`.
6
+ *
7
+ * Static text is exported as a plain `const`; interpolated text is exported
8
+ * as a small builder function. Plain `export const` declarations tree-shake
9
+ * better than frozen-object property bags, so unused strings drop out of
10
+ * bundles cleanly.
11
+ */
12
+ /**
13
+ * Fallback host tag name used when a hydration mismatch is detected on a
14
+ * node that is not inside a shadow root.
15
+ */
16
+ export declare const unknownHostName = "unknown";
17
+ export declare const aspectLabelAttribute = "attribute";
18
+ export declare const aspectLabelBooleanAttribute = "boolean attribute";
19
+ export declare const aspectLabelProperty = "property";
20
+ export declare const aspectLabelContent = "content";
21
+ export declare const aspectLabelTokenList = "token list";
22
+ export declare const aspectLabelEvent = "event";
23
+ /** Fallback used when the aspectType is missing or unknown. */
24
+ export declare const aspectLabelUnknown = "binding";
25
+ /**
26
+ * Combines an aspect label with the original source aspect identifier from
27
+ * markup (e.g. `"property className"`). Returns the bare label when no
28
+ * source aspect was captured.
29
+ */
30
+ export declare function formatAspect(label: string, sourceAspect: string | undefined): string;
31
+ /**
32
+ * Formats the "Expected" half of the rich hydration mismatch message, e.g.
33
+ * `"<span> with content binding"` or `"content binding"` when no tag is
34
+ * associated with the binding factory.
35
+ */
36
+ export declare function formatExpectedTarget(tagName: string | null, aspect: string): string;
37
+ /**
38
+ * Default minimal hydration mismatch message used when the
39
+ * `hydrationDebugger` opt-in is not installed. The optional `detail` string
40
+ * carries the structural expectation surfaced by `target-builder.ts`.
41
+ */
42
+ export declare function formatDefaultMismatchMessage(hostName: string, detail: string | undefined): string;
43
+ /**
44
+ * Rich `Expected … / Received …` hydration mismatch message format produced
45
+ * by the `hydrationDebugger` formatter.
46
+ */
47
+ export declare function formatRichMismatchMessage(hostName: string, expectedText: string, receivedHtml: string): string;
48
+ export declare const expectedContentAfterStartMarker = "content following `<!--fe:b-->` content binding marker";
49
+ export declare const expectedContentEndMarker = "matching `<!--fe:/b-->` content binding close marker";
50
+ export declare const expectedElementBoundaryEndMarker = "matching `<!--fe:/e-->` element boundary close marker";
51
+ /**
52
+ * Builds the "no more attribute bindings" structural expectation message
53
+ * thrown when an element's `data-fe` count claims more attribute bindings
54
+ * than the compiled template defines.
55
+ */
56
+ export declare function formatNoMoreAttributeBindings(factoryCount: number): string;
57
+ /**
58
+ * Builds the "no more content bindings" structural expectation message
59
+ * thrown when the SSR DOM contains more content binding markers than the
60
+ * compiled template defines.
61
+ */
62
+ export declare function formatNoMoreContentBindings(factoryCount: number): string;
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Installs the hydration runtime on `ViewTemplate.prototype`,
3
+ * making all templates hydratable. Call this before any hydration
4
+ * occurs. Safe to call multiple times — subsequent calls are no-ops.
5
+ * @internal
6
+ */
7
+ export declare function ensureHydrationRuntime(): void;
@@ -0,0 +1,107 @@
1
+ import type { CompiledViewBehaviorFactory, ViewBehaviorFactory, ViewBehaviorTargets } from "../templating/html-directive.js";
2
+ import { type HydrationMismatchActual, type HydrationMismatchExpectation } from "./diagnostics.js";
3
+ export declare class HydrationTargetElementError extends Error {
4
+ /**
5
+ * The Compiled View Behavior Factories that belong to the view.
6
+ */
7
+ readonly factories: CompiledViewBehaviorFactory[];
8
+ /**
9
+ * The node to target factory.
10
+ */
11
+ readonly node: Node;
12
+ /**
13
+ * Structured description of the binding the hydration walk was
14
+ * attempting to apply when the mismatch was detected. Free-form
15
+ * string for structural errors that do not correspond to a single
16
+ * binding factory.
17
+ */
18
+ readonly expected?: HydrationMismatchExpectation | string | undefined;
19
+ /**
20
+ * Structured description of the server-rendered DOM that was
21
+ * encountered at the mismatch point.
22
+ */
23
+ readonly received?: HydrationMismatchActual | undefined;
24
+ /**
25
+ * String representation of the HTML in the template that
26
+ * threw the target element error.
27
+ */
28
+ templateString?: string;
29
+ constructor(
30
+ /**
31
+ * The error message
32
+ */
33
+ message: string | undefined,
34
+ /**
35
+ * The Compiled View Behavior Factories that belong to the view.
36
+ */
37
+ factories: CompiledViewBehaviorFactory[],
38
+ /**
39
+ * The node to target factory.
40
+ */
41
+ node: Node,
42
+ /**
43
+ * Structured description of the binding the hydration walk was
44
+ * attempting to apply when the mismatch was detected. Free-form
45
+ * string for structural errors that do not correspond to a single
46
+ * binding factory.
47
+ */
48
+ expected?: HydrationMismatchExpectation | string | undefined,
49
+ /**
50
+ * Structured description of the server-rendered DOM that was
51
+ * encountered at the mismatch point.
52
+ */
53
+ received?: HydrationMismatchActual | undefined);
54
+ }
55
+ /**
56
+ * Represents the DOM boundaries controlled by a view
57
+ * @public
58
+ */
59
+ export interface ViewBoundaries {
60
+ first: Node;
61
+ last: Node;
62
+ }
63
+ /**
64
+ * Stores relationships between a {@link ViewBehaviorFactory} and
65
+ * the {@link ViewBoundaries} the factory created.
66
+ * @public
67
+ */
68
+ export interface ViewBehaviorBoundaries {
69
+ [factoryId: string]: ViewBoundaries;
70
+ }
71
+ /**
72
+ * Returns a range object inclusive of all nodes including and between the
73
+ * provided first and last node.
74
+ * @param first - The first node
75
+ * @param last - This last node
76
+ * @returns
77
+ */
78
+ export declare function createRangeForNodes(first: Node, last: Node): Range;
79
+ /**
80
+ * Maps compiled ViewBehaviorFactory IDs to their corresponding DOM nodes in the
81
+ * server-rendered shadow root. Uses a TreeWalker to scan the existing DOM between
82
+ * firstNode and lastNode, processing data-free sequential hydration markers.
83
+ *
84
+ * A sequential factory pointer advances through the factories array in DFS order.
85
+ * Since the template compiler and hydration walker both traverse the DOM in
86
+ * identical depth-first order, no embedded indices are needed in markers.
87
+ *
88
+ * For element nodes: parses `data-fe="N"` to determine the count of attribute
89
+ * binding factories, then consumes N factories sequentially.
90
+ *
91
+ * For comment nodes: `fe:b` markers consume the next factory for content bindings,
92
+ * using balanced depth counting for nested marker pairing. `fe:e` markers cause
93
+ * the walker to skip nested custom element subtrees.
94
+ *
95
+ * Host bindings (targetNodeId='h') appear at the start of the factories array but
96
+ * have no SSR markers — getHydrationIndexOffset() computes the initial pointer value.
97
+ *
98
+ * @param firstNode - The first node of the view.
99
+ * @param lastNode - The last node of the view.
100
+ * @param factories - The Compiled View Behavior Factories that belong to the view.
101
+ * @returns - A {@link ViewBehaviorTargets } object for the factories in the view.
102
+ */
103
+ export declare function buildViewBindingTargets(firstNode: Node, lastNode: Node, factories: CompiledViewBehaviorFactory[]): {
104
+ targets: ViewBehaviorTargets;
105
+ boundaries: ViewBehaviorBoundaries;
106
+ };
107
+ export declare function targetFactory(factory: ViewBehaviorFactory, node: Node, targets: ViewBehaviorTargets): void;
@@ -0,0 +1,51 @@
1
+ /**
2
+ * Core APIs for building standards-based Web Components with FAST Element.
3
+ * @packageDocumentation
4
+ */
5
+ export { Binding, type BindingDirective } from "./binding/binding.js";
6
+ export { normalizeBinding } from "./binding/normalize.js";
7
+ export { oneTime } from "./binding/one-time.js";
8
+ export { listener, oneWay } from "./binding/one-way.js";
9
+ export { Signal, signal } from "./binding/signal.js";
10
+ export { type TwoWayBindingOptions, TwoWaySettings, twoWay, } from "./binding/two-way.js";
11
+ export { AttributeConfiguration, AttributeDefinition, type AttributeMode, attr, booleanConverter, type DecoratorAttributeConfiguration, nullableBooleanConverter, nullableNumberConverter, type ValueConverter, } from "./components/attributes.js";
12
+ export type { ElementControllerStrategy } from "./components/element-controller.js";
13
+ export { ElementController, Stages, } from "./components/element-controller.js";
14
+ export type { FASTElementExtension, FASTElementTemplateResolver, PartialFASTElementDefinition, ShadowRootOptions, TypeDefinition, TypeRegistry, } from "./components/fast-definitions.js";
15
+ export { FASTElementDefinition } from "./components/fast-definitions.js";
16
+ export { customElement, FASTElement, type FASTElementConstructor, } from "./components/fast-element.js";
17
+ export { type FASTElementRegistry, fastElementRegistry, } from "./components/fast-element-registry.js";
18
+ export { enableDebug } from "./debug.js";
19
+ export { DOM, DOMAspect, type DOMSink } from "./dom.js";
20
+ export { type DOMAspectGuards, type DOMElementGuards, type DOMGuards, DOMPolicy, type DOMPolicyOptions, type DOMSinkGuards, } from "./dom-policy.js";
21
+ export type { Callable, Class, Constructable, Disposable, TrustedTypesPolicy, } from "./interfaces.js";
22
+ export { ArrayObserver, type LengthObserver, lengthOf, Sort, type SortObserver, Splice, SpliceStrategy, SpliceStrategySupport, sortedCount, } from "./observation/arrays.js";
23
+ export { type Notifier, PropertyChangeNotifier, type Subscriber, SubscriberSet, } from "./observation/notifier.js";
24
+ export type { Accessor, Expression, ExpressionController, ExpressionNotifier, ExpressionObserver, ObservationRecord, } from "./observation/observable.js";
25
+ export { ExecutionContext, Observable, observable, SourceLifetime, } from "./observation/observable.js";
26
+ export { type UpdateQueue, Updates } from "./observation/update-queue.js";
27
+ export { volatile } from "./observation/volatile.js";
28
+ export { emptyArray, FAST } from "./platform.js";
29
+ export { type AccessCachedPath, type CachedPath, type CachedPathCommon, type CachedPathMap, type ChildrenMap, type DefaultCachedPath, type EventCachedPath, type JSONSchema, type JSONSchemaCommon, type JSONSchemaDefinition, type RegisterPathConfig, type RepeatCachedPath, Schema, schemaRegistry, } from "./schema.js";
30
+ export * from "./state/exports.js";
31
+ export { type CSSTemplateTag, type CSSValue, css } from "./styles/css.js";
32
+ export { CSSDirective, type CSSDirectiveDefinition, cssDirective, } from "./styles/css-directive.js";
33
+ export type { ComposableStyles, ConstructibleStyleStrategy, } from "./styles/element-styles.js";
34
+ export { ElementStyles } from "./styles/element-styles.js";
35
+ export type { HostBehavior, HostController } from "./styles/host.js";
36
+ export type { StyleStrategy, StyleTarget } from "./styles/style-strategy.js";
37
+ export { type ChildListDirectiveOptions, ChildrenDirective, type ChildrenDirectiveOptions, children, type SubtreeDirectiveOptions, } from "./templating/children.js";
38
+ export { type CompilationStrategy, Compiler } from "./templating/compiler.js";
39
+ export { type ContentTemplate, type ContentView, HTMLBindingDirective, } from "./templating/html-binding-directive.js";
40
+ export { type AddViewBehaviorFactory, type Aspected, type CompiledViewBehaviorFactory, HTMLDirective, type HTMLDirectiveDefinition, htmlDirective, type PartialHTMLDirectiveDefinition, StatelessAttachedAttributeDirective, type ViewBehavior, type ViewBehaviorFactory, type ViewBehaviorTargets, type ViewController, } from "./templating/html-directive.js";
41
+ export { Markup, Parser } from "./templating/markup.js";
42
+ export { type ElementsFilter, elements, type NodeBehaviorOptions, NodeObservationDirective, } from "./templating/node-observation.js";
43
+ export { RefDirective, ref } from "./templating/ref.js";
44
+ export { RenderBehavior, RenderDirective, render } from "./templating/render.js";
45
+ export { RepeatBehavior, RepeatDirective, type RepeatOptions, repeat, } from "./templating/repeat.js";
46
+ export { SlottedDirective, type SlottedDirectiveOptions, slotted, } from "./templating/slotted.js";
47
+ export { type CaptureType, type ElementViewTemplate, type HTMLTemplateCompilationResult, type HTMLTemplateTag, html, InlineTemplateDirective, type SyntheticViewTemplate, type TemplateValue, ViewTemplate, } from "./templating/template.js";
48
+ export { DefaultExecutionContext, type ElementView, HTMLView, type SyntheticView, type View, } from "./templating/view.js";
49
+ export { when } from "./templating/when.js";
50
+ export type { TrustEmitOptions, TrustSignals, Warning, WarningSeverity, } from "./trust/types.js";
51
+ export * from "./utilities.js";
@@ -0,0 +1 @@
1
+ export * from "./index.js";
@@ -0,0 +1 @@
1
+ export * from "./index.js";
@@ -0,0 +1 @@
1
+ export * from "./index.js";