@opentf/afw 0.0.0-stage → 0.33.0

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 (73) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +123 -2
  3. package/components/Link.d.ts +12 -0
  4. package/components/Link.jsx +54 -0
  5. package/core/context.d.ts +7 -0
  6. package/core/context.js +60 -0
  7. package/core/dev.js +27 -0
  8. package/core/errors.d.ts +14 -0
  9. package/core/errors.js +48 -0
  10. package/core/html.js +10 -0
  11. package/core/metadata.js +186 -0
  12. package/core/reactive.d.ts +5 -0
  13. package/core/reactive.js +190 -0
  14. package/core/render-context.js +11 -0
  15. package/core/signals.d.ts +8 -0
  16. package/core/signals.js +264 -0
  17. package/index.d.ts +5 -0
  18. package/index.js +13 -0
  19. package/jsx-runtime.d.ts +37 -0
  20. package/package.json +66 -4
  21. package/runtime/clipboard.d.ts +7 -0
  22. package/runtime/clipboard.js +47 -0
  23. package/runtime/code-block.d.ts +14 -0
  24. package/runtime/code-block.js +76 -0
  25. package/runtime/context.browser.js +163 -0
  26. package/runtime/context.d.ts +13 -0
  27. package/runtime/context.js +44 -0
  28. package/runtime/dom.browser.js +423 -0
  29. package/runtime/dom.d.ts +142 -0
  30. package/runtime/dom.js +670 -0
  31. package/runtime/error-boundary.browser.js +140 -0
  32. package/runtime/error-boundary.d.ts +19 -0
  33. package/runtime/error-boundary.js +123 -0
  34. package/runtime/events.browser.js +29 -0
  35. package/runtime/events.d.ts +1 -0
  36. package/runtime/events.js +17 -0
  37. package/runtime/head.js +29 -0
  38. package/runtime/hmr.js +199 -0
  39. package/runtime/hydrate.browser.js +144 -0
  40. package/runtime/hydrate.d.ts +179 -0
  41. package/runtime/hydrate.js +584 -0
  42. package/runtime/index.d.ts +14 -0
  43. package/runtime/index.js +24 -0
  44. package/runtime/lifecycle.d.ts +6 -0
  45. package/runtime/lifecycle.js +14 -0
  46. package/runtime/mount.d.ts +20 -0
  47. package/runtime/mount.js +88 -0
  48. package/runtime/portal.browser.js +85 -0
  49. package/runtime/portal.d.ts +12 -0
  50. package/runtime/portal.js +74 -0
  51. package/runtime/raw-html.d.ts +11 -0
  52. package/runtime/raw-html.js +55 -0
  53. package/runtime/resource.d.ts +9 -0
  54. package/runtime/resource.js +139 -0
  55. package/runtime/route-data.d.ts +15 -0
  56. package/runtime/route-data.js +64 -0
  57. package/runtime/router.d.ts +149 -0
  58. package/runtime/router.js +807 -0
  59. package/server/adapters/node.d.ts +28 -0
  60. package/server/adapters/node.js +74 -0
  61. package/server/api.d.ts +175 -0
  62. package/server/api.js +233 -0
  63. package/server/builtins.js +42 -0
  64. package/server/cookies.d.ts +44 -0
  65. package/server/cookies.js +122 -0
  66. package/server/head.js +9 -0
  67. package/server/index.d.ts +155 -0
  68. package/server/index.js +31 -0
  69. package/server/loader.js +201 -0
  70. package/server/middleware.js +119 -0
  71. package/server/render-context.js +30 -0
  72. package/server/render.js +175 -0
  73. package/server/ssg-runtime.js +297 -0
@@ -0,0 +1,144 @@
1
+ import { describe, expect, test } from "../../afw-test/browser-runner.js";
2
+
3
+ import { signal } from "../core/signals.js";
4
+ import { bindText } from "./dom.js";
5
+ import {
6
+ HydrationMismatch,
7
+ claimElement,
8
+ claimText,
9
+ cursor,
10
+ isHydrating,
11
+ runHydration,
12
+ skipNode,
13
+ } from "./hydrate.js";
14
+
15
+ // Build a real DOM subtree from a server HTML string (as the browser would on load).
16
+ function serverDom(html) {
17
+ const host = document.createElement("div");
18
+ host.innerHTML = html;
19
+ return host;
20
+ }
21
+
22
+ describe("the hydration flag", () => {
23
+ test("isHydrating is false outside a pass and true inside runHydration", () => {
24
+ expect(isHydrating()).toBe(false);
25
+ let inside = null;
26
+ runHydration(() => (inside = isHydrating()));
27
+ expect(inside).toBe(true);
28
+ expect(isHydrating()).toBe(false);
29
+ });
30
+
31
+ test("runHydration restores the prior value (nesting-safe) and returns fn's result", () => {
32
+ const seen = [];
33
+ const out = runHydration(() => {
34
+ seen.push(isHydrating()); // true
35
+ runHydration(() => seen.push(isHydrating())); // true
36
+ seen.push(isHydrating()); // still true after the inner pass
37
+ return 42;
38
+ });
39
+ expect(seen).toEqual([true, true, true]);
40
+ expect(out).toBe(42);
41
+ expect(isHydrating()).toBe(false);
42
+ });
43
+ });
44
+
45
+ describe("claimElement", () => {
46
+ test("claims the next element, asserts its tag, and advances the cursor", () => {
47
+ const host = serverDom("<section></section><span></span>");
48
+ const cur = cursor(host);
49
+ const section = claimElement(cur, "section");
50
+ expect(section).toBe(host.firstChild);
51
+ const span = claimElement(cur, "span");
52
+ expect(span.tagName.toLowerCase()).toBe("span");
53
+ expect(cur.node).toBe(null); // walked off the end
54
+ });
55
+
56
+ test("throws HydrationMismatch on a wrong tag or a missing node", () => {
57
+ const host = serverDom("<p></p>");
58
+ const cur = cursor(host);
59
+ expect(() => claimElement(cur, "div")).toThrow(HydrationMismatch);
60
+ const empty = cursor(serverDom(""));
61
+ expect(() => claimElement(empty, "div")).toThrow(HydrationMismatch);
62
+ });
63
+ });
64
+
65
+ describe("claimText", () => {
66
+ test("adopts the server text node inside <!--$-->…<!--/--> markers", () => {
67
+ const host = serverDom("Count <!--$-->5<!--/-->");
68
+ const cur = cursor(host);
69
+ skipNode(cur); // the static "Count " text
70
+ const textNode = claimText(cur);
71
+ expect(textNode.nodeType).toBe(3);
72
+ expect(textNode.data).toBe("5");
73
+ expect(cur.node).toBe(null); // advanced past the closing marker
74
+ });
75
+
76
+ test("synthesizes an empty anchor when the server rendered no value", () => {
77
+ const host = serverDom("<!--$--><!--/-->");
78
+ const cur = cursor(host);
79
+ const textNode = claimText(cur);
80
+ expect(textNode.nodeType).toBe(3);
81
+ expect(textNode.data).toBe("");
82
+ // The synthesized node lives between the markers, in the real tree.
83
+ expect(textNode.parentNode).toBe(host);
84
+ });
85
+
86
+ test("throws when the start marker is absent", () => {
87
+ const cur = cursor(serverDom("<span></span>"));
88
+ expect(() => claimText(cur)).toThrow(HydrationMismatch);
89
+ });
90
+ });
91
+
92
+ describe("skipNode", () => {
93
+ test("advances past a static text node and returns it", () => {
94
+ const cur = cursor(serverDom("hi<span></span>"));
95
+ const skipped = skipNode(cur);
96
+ expect(skipped.nodeType).toBe(3);
97
+ expect(cur.node.tagName.toLowerCase()).toBe("span"); // advanced to the next node
98
+ });
99
+
100
+ test("throws when the aligned node is not static text (cursor misalignment)", () => {
101
+ // A step meant for a static `ViewNode::Text` must land on a real text node; an
102
+ // element/comment/absent node there means the walk desynced — surface it here.
103
+ expect(() => skipNode(cursor(serverDom("<span></span>")))).toThrow(HydrationMismatch);
104
+ expect(() => skipNode(cursor(serverDom("")))).toThrow(HydrationMismatch);
105
+ });
106
+ });
107
+
108
+ describe("integrated walk — adopt, don't rebuild", () => {
109
+ test("hydrating <div><h1>Count {n}</h1></div> adopts nodes and wires reactivity", () => {
110
+ // What the SSG/SSR backend emits for `<div class="box"><h1>Count {n}</h1></div>`
111
+ // with n initially 3.
112
+ const host = serverDom('<div class="box"><h1>Count <!--$-->3<!--/--></h1></div>');
113
+ const div = host.firstChild;
114
+ const h1 = div.firstChild;
115
+ const serverText = h1.childNodes[2]; // "Count ", <!--$-->, "3", <!--/-->
116
+
117
+ const n = signal(3); // client signal initializes to the same value the server used
118
+ let boundNode = null;
119
+
120
+ runHydration(() => {
121
+ const root = cursor(host);
122
+ const claimedDiv = claimElement(root, "div");
123
+ const inner = cursor(claimedDiv);
124
+ const claimedH1 = claimElement(inner, "h1");
125
+ const h1cur = cursor(claimedH1);
126
+ skipNode(h1cur); // "Count "
127
+ boundNode = claimText(h1cur);
128
+ bindText(boundNode, () => n.value);
129
+ });
130
+
131
+ // Adoption: the very same server nodes were claimed — nothing was re-created.
132
+ expect(boundNode).toBe(serverText);
133
+ expect(host.firstChild).toBe(div);
134
+ expect(div.firstChild).toBe(h1);
135
+ expect(host.querySelectorAll("div").length).toBe(1);
136
+ expect(host.querySelectorAll("h1").length).toBe(1);
137
+
138
+ // Reactivity is now live on the adopted text node.
139
+ n.value = 7;
140
+ expect(serverText.data).toBe("7");
141
+ // Still the same node identity after the update (no replacement).
142
+ expect(h1.childNodes[2]).toBe(serverText);
143
+ });
144
+ });
@@ -0,0 +1,179 @@
1
+ /** Is the client mid-hydration right now? */
2
+ export function isHydrating(): boolean;
3
+ /** Whether `el` carries the hydrate sentinel for markup rendered at `pathname`. */
4
+ export function renderedForPath(el: Element | null | undefined, pathname?: string | null): boolean;
5
+ /**
6
+ * Run `fn` with the hydration flag *cleared*, restoring the prior value (nesting-safe).
7
+ *
8
+ * The build/adopt decision hangs on one module-global flag, but the invariant it must
9
+ * encode is narrower: `isHydrating()` may be true only while the DOM being processed is
10
+ * the server's. The moment a component builds fresh DOM — because its view isn't
11
+ * adoptable (`RebuildIfServerChildren`), or its adopt hit a mismatch and it's recovering,
12
+ * or it's a nested build — that fresh subtree is *not* server-rendered. Its child custom
13
+ * elements upgrade synchronously during `appendChild` inside this build, and if they still
14
+ * saw `isHydrating()` true they'd try to *adopt* content their parent just `createElement`'d
15
+ * → a guaranteed `HydrationMismatch` cascade (a non-adoptable layout would tear the whole
16
+ * page's islands into rebuild-storms). Bracketing every build path with this makes the
17
+ * children build too, matching the DOM they're actually handed. Synchronous only — builds
18
+ * never await — so a plain global save/restore is correct even when builds nest.
19
+ */
20
+ export function runBuild(fn: any): any;
21
+ /** Run `fn` with the hydration flag set, restoring the prior value (nesting-safe).
22
+ * Synchronous only — for the async first-paint pass use {@link beginHydration} /
23
+ * {@link endHydration}, which span the route module's `import()`. */
24
+ export function runHydration(fn: any): any;
25
+ /** Begin the first-paint hydration pass; pair with {@link endHydration}. Set *before*
26
+ * the route module is imported so every server host upgrading at `customElements.define`
27
+ * observes it and adopts (docs/HYDRATION.md §3.4). */
28
+ export function beginHydration(): void;
29
+ /** End the first-paint hydration pass — subsequent client navigations build fresh.
30
+ * Also flushes any {@link afterHydration} callbacks queued during the pass. */
31
+ export function endHydration(): void;
32
+ /** Run `fn` after first-paint hydration completes (at {@link endHydration}); run it
33
+ * synchronously when not hydrating (a CSR build / SPA navigation). */
34
+ export function afterHydration(fn: any): void;
35
+ /**
36
+ * The rich hydration props recorded for host `el` (keyed by its `data-h` id), or `null`
37
+ * when there is no payload for it — a client-`createElement`'d element on SPA navigation,
38
+ * or a plain CSR build. A hydrate-target component constructor reads this to initialize
39
+ * its prop signals, falling back to attributes/defaults when it returns `null`.
40
+ */
41
+ export function hydrationProps(el: any): any;
42
+ /** Reset the cached payload (tests only — a fresh document between cases). */
43
+ export function __resetHydrationPayload(): void;
44
+ /** A walker over `parent`'s children, positioned at the next node to claim. */
45
+ export function cursor(parent: any): {
46
+ node: any;
47
+ };
48
+ /** Advance past the next node without claiming it (a static text node between
49
+ * dynamic siblings), returning it. The template only emits a skip for a static
50
+ * `ViewNode::Text`, which the server renders as a real text node; assert that so a
51
+ * cursor misalignment surfaces *here* (with a clear message) instead of downstream at
52
+ * an unrelated claim. Throws {@link HydrationMismatch} on a wrong/absent node. */
53
+ export function skipNode(cur: any): any;
54
+ /**
55
+ * Claim the next node as an element, optionally asserting its tag, and advance the
56
+ * cursor past it. Returns the element so the caller can claim its children with a
57
+ * fresh `cursor(el)`. A wrong/absent node throws {@link HydrationMismatch}.
58
+ */
59
+ export function claimElement(cur: any, tag: any): any;
60
+ /**
61
+ * Claim a dynamic text hole delimited by `<!--$-->…<!--/-->`, returning the text node
62
+ * to bind onto (created empty when the server rendered no value), and advance the
63
+ * cursor past the closing marker. Wire reactivity with `bindText(node, fn)` from
64
+ * dom.js — the binding logic is shared with CSR; only the node is adopted, not built.
65
+ *
66
+ * A text hole may hold a *node*, not text: `{expr}` whose value is a JSX element or an
67
+ * array of them (e.g. a code example stored in a data array and rendered `{ex.body}`).
68
+ * The compiler can't distinguish that statically, so it emits the text path for both; the
69
+ * SSG backend renders such a value's markup inline in the hole, and `bindText`'s node arm
70
+ * *rebuilds* it fresh on the client (dom.js) rather than adopting. So any element/comment
71
+ * left inside the hole is server content the client will not reuse — it must be removed
72
+ * here, or it lingers beside the rebuilt node as a duplicate (the whole example appears
73
+ * twice). Only a single text node is a genuine adopt target; strip everything else.
74
+ */
75
+ export function claimText(cur: any): any;
76
+ /**
77
+ * Claim the text node of a **raw text** element (`<textarea>`, `<title>`, `<style>`,
78
+ * `<script>`) — the one place a text hole carries no `<!--$-->…<!--/-->` markers.
79
+ *
80
+ * The tokenizer does not parse markup inside these elements, so a marker comment written
81
+ * in there comes back as literal characters (it would be *visible* in a textarea, and the
82
+ * walk would be hunting for a comment node that is really text). The SSG backend
83
+ * therefore emits the content bare (`ssg::raw_text`), and everything written between the
84
+ * tags — however many static and dynamic pieces — arrives as a single text node. That
85
+ * node is the whole content, so it is claimed from the element rather than off a cursor;
86
+ * the compiler only emits this call for the one-hole shape, which `reparse_hazard` is
87
+ * what guarantees. A server-rendered empty value leaves no text node at all, so one is
88
+ * created to bind onto.
89
+ */
90
+ export function claimRawText(el: any): any;
91
+ /**
92
+ * Adopt a **JSX-value hole** — a `{expr}` whose value is a JSX-value local (`const x =
93
+ * <T/>`), server-rendered in place between the text-hole markers `<!--$-->…<!--/-->`
94
+ * (docs/HYDRATION.md §3.1, 2.1e). Unlike {@link claimText} — which treats a node-valued
95
+ * hole as *stray* server content, strips it, and lets `bindText` rebuild it fresh (a flash,
96
+ * plus a rebuild cascade through any island the node contains) — this *adopts* the server
97
+ * subtree in place: `adoptFn(inner)` claims it off a cursor seeded just after the opening
98
+ * marker, advancing to the closing marker. A JSX-value local is a `const` bound to a literal,
99
+ * so the hole never reactively re-renders — there is no build/swap arm, only the one-shot
100
+ * adopt. Advances `cur` past `<!--/-->`. Throws {@link HydrationMismatch} on a wrong/absent
101
+ * marker.
102
+ */
103
+ export function hydrateHole(cur: any, adoptFn: any): void;
104
+ /** Claim the `<!--[-->` marker that opens a server-rendered region (list or conditional),
105
+ * advancing the cursor past it. Throws {@link HydrationMismatch} on a wrong/absent node. */
106
+ export function claimRegionStart(cur: any): any;
107
+ /** Claim the `<!--]-->` marker that closes a region and return it — it becomes the
108
+ * reconcile/swap anchor (`hydrateList`/`hydrateChild` insert later nodes before it).
109
+ * Advances the cursor past it. Throws {@link HydrationMismatch} on a wrong/absent node. */
110
+ export function claimRegionEnd(cur: any): any;
111
+ /** Step a component's own adopt walk past its `{children}` slot — claim the
112
+ * `<!--c[-->`…`<!--c]-->` markers and skip the slotted nodes (the parent owns their
113
+ * reactivity, wired separately by {@link hydrateSlot}), leaving them in place. Advances the
114
+ * cursor past the closing marker. Throws {@link HydrationMismatch} on a missing start marker.
115
+ *
116
+ * Returns the slotted nodes. Adoption never captures light-DOM children the way a CSR build
117
+ * does (they are already in place), but a JSX-value local's `build` fallback still closes over
118
+ * the children local — so codegen seeds that binding from this return value, giving a later
119
+ * reactive rebuild the real nodes to re-slot instead of a `ReferenceError`. */
120
+ export function skipSlot(cur: any): any[];
121
+ /**
122
+ * The nodes sitting in `host`'s own `{children}` slot in the server DOM, or `null` when the
123
+ * host has no slot markers. Non-destructive — the nodes stay where they are.
124
+ *
125
+ * This is the rescue path for a component that *can't* adopt (a view shape the hydrate
126
+ * backend doesn't support yet, or an adopt walk that hit a mismatch and is recovering). Such
127
+ * a component rebuilds via CSR, and its build captures `this.childNodes` as the call-site
128
+ * children — but on a server-rendered host those children are the *rendered view*, not the
129
+ * slotted content. Clearing first and capturing after (what the generated code used to do)
130
+ * therefore didn't just rebuild the component, it **lost the page content inside it**. Pulling
131
+ * the slot region out first gives the rebuild the real children to re-slot: still a flash,
132
+ * but nothing disappears.
133
+ */
134
+ export function slotChildren(host: any): ChildNode[] | null;
135
+ /**
136
+ * Adopt a component's slotted children — the *parent's* JSX, server-rendered inside the
137
+ * component host at its `{children}` slot. The parent owns their reactivity but the
138
+ * component decides where they sit, so the parent locates the slot by its `<!--c[-->` marker
139
+ * within `host` and adopts from the first slotted node via `adoptFn(cursor)`. Independent of
140
+ * when the component upgrades: the markers are static server DOM and adoption only *wires*
141
+ * (never moves) nodes, so it commutes with the component's own `skipSlot`. A missing marker
142
+ * (a rebuilt component, or no children) is a no-op.
143
+ */
144
+ export function hydrateSlot(host: any, adoptFn: any): void;
145
+ /** Comment markers bounding a dynamic text hole in server HTML. */
146
+ export const HOLE_START: "$";
147
+ export const HOLE_END: "/";
148
+ /** Comment markers bounding a variable structural region — a list or a conditional —
149
+ * in server HTML (docs/HYDRATION.md §3.1): `<!--[-->` opens, `<!--]-->` closes. A list
150
+ * holds one item root node per item; a conditional holds the currently rendered branch
151
+ * (or nothing). The closing marker becomes the reconcile/swap anchor on hydration. */
152
+ export const REGION_START: "[";
153
+ export const REGION_END: "]";
154
+ /** Markers bounding a *component's* light-DOM `{children}` slot (docs/HYDRATION.md §3.1,
155
+ * 2.1d) — distinct bytes from the list/conditional region markers so a component's own
156
+ * internal regions never collide with its slot. The slot's content is the *parent's* JSX
157
+ * (server-rendered here), so the parent finds this slot by its `<!--c[-->` marker within the
158
+ * host and adopts the children (its reactivity), while the component steps over the slot.
159
+ *
160
+ * Each marker is **labeled with the owning host's tag** — `<!--c[afw-card-8e61e2ff-->` — because
161
+ * slot regions nest: a component that forwards `{children}` into another component
162
+ * (`Card` → `<Link>{children}</Link>`) emits its markers *inside* that component's, and a
163
+ * forwarding parent adds a third pair at the same position. Unlabeled, a component's walk
164
+ * stopped at the first close it met (a nested one) and the parent's slot lookup had to guess
165
+ * by tree order — both wrong in the forwarding shape. The label makes each side's pair exact. */
166
+ export const SLOT_START: "c[";
167
+ export const SLOT_END: "c]";
168
+ /** Thrown when the server DOM doesn't match the template at a claim site. The
169
+ * component boundary catches this and recovers by rebuilding via CSR (never silent;
170
+ * see docs/HYDRATION.md §3.5). */
171
+ export class HydrationMismatch extends Error {
172
+ constructor(message: any);
173
+ }
174
+ /**
175
+ * Adopt a `<p>` holding a component, past its `<!--p]-->` end marker: kept as served when
176
+ * the parser left it intact, rebuilt with `build()` when a block element in a component
177
+ * made the parser close it early. Compiler-emitted.
178
+ */
179
+ export function hydrateParagraph(cur: any, adopt: (el: any) => void, build: () => any): any;