@opentf/afw-docs 0.0.0-stage → 0.31.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 (61) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +141 -2
  3. package/build/blog-posts-plugin.js +154 -0
  4. package/build/docs-nav-plugin.js +200 -0
  5. package/build/feed.js +176 -0
  6. package/build/frontmatter.js +45 -0
  7. package/build/host.js +54 -0
  8. package/build/index.js +13 -0
  9. package/build/last-updated-plugin.js +107 -0
  10. package/build/last-updated.js +40 -0
  11. package/build/llms.js +176 -0
  12. package/build/publish.js +29 -0
  13. package/build/reading-time.js +16 -0
  14. package/build/search.js +27 -0
  15. package/components/BlogLayout.jsx +104 -0
  16. package/components/Breadcrumbs.jsx +71 -0
  17. package/components/Callout.jsx +29 -0
  18. package/components/Card.jsx +21 -0
  19. package/components/Cards.jsx +11 -0
  20. package/components/CodeBlock.jsx +39 -0
  21. package/components/DocsLayout.jsx +106 -0
  22. package/components/FeedLinks.jsx +47 -0
  23. package/components/Footer.jsx +25 -0
  24. package/components/LastUpdated.jsx +20 -0
  25. package/components/NavIcon.jsx +34 -0
  26. package/components/Navbar.jsx +64 -0
  27. package/components/NavbarLink.jsx +40 -0
  28. package/components/Pagination.jsx +49 -0
  29. package/components/PostBanner.jsx +25 -0
  30. package/components/PostCard.jsx +24 -0
  31. package/components/PostList.jsx +25 -0
  32. package/components/PostMeta.jsx +37 -0
  33. package/components/ReadingTime.jsx +6 -0
  34. package/components/Search.jsx +191 -0
  35. package/components/SearchTrigger.jsx +32 -0
  36. package/components/Sidebar.jsx +199 -0
  37. package/components/SidebarNode.jsx +143 -0
  38. package/components/SidebarToggle.jsx +47 -0
  39. package/components/Steps.jsx +14 -0
  40. package/components/Table.jsx +10 -0
  41. package/components/Tabs.jsx +77 -0
  42. package/components/ThemeToggle.jsx +164 -0
  43. package/components/Toc.jsx +106 -0
  44. package/components/Tooltip.jsx +19 -0
  45. package/components/format.js +21 -0
  46. package/components/post-dates.js +21 -0
  47. package/components/sidebar-collapse.js +38 -0
  48. package/config.js +77 -0
  49. package/index.js +69 -0
  50. package/nav-virtual.js +18 -0
  51. package/package.json +79 -4
  52. package/posts-virtual.js +17 -0
  53. package/search.js +285 -0
  54. package/theme/index.css +1843 -0
  55. package/types/config.d.ts +39 -0
  56. package/types/index.d.ts +70 -0
  57. package/types/nav.d.ts +9 -0
  58. package/types/posts.d.ts +17 -0
  59. package/types/search.d.ts +28 -0
  60. package/types/updated.d.ts +4 -0
  61. package/updated-virtual.js +10 -0
@@ -0,0 +1,143 @@
1
+ // One node of the sidebar tree — a link, a collapsible group, or both. Recurses into
2
+ // `item.items`. Groups with children get a chevron toggle; the branch containing the
3
+ // active route stays open, and top-level groups start expanded. Open/closed state is
4
+ // per-session only (no persistence) — a reload resets to this derived default.
5
+ //
6
+ // The sidebar's "collapse all" button drives every node at once through the shared
7
+ // `collapseAll` signal (components/sidebar-collapse.js).
8
+
9
+ import { Link, router } from "@opentf/afw";
10
+
11
+ import { collapseAll } from "./sidebar-collapse.js";
12
+
13
+ // True when `path` is `node` itself or lives somewhere in its subtree.
14
+ function treeContainsPath(node, path) {
15
+ if (!node) return false;
16
+ if (node.path === path) return true;
17
+ if (!node.items || !node.items.length) return false;
18
+ return node.items.some((child) => treeContainsPath(child, path));
19
+ }
20
+
21
+ export default function SidebarNode(props) {
22
+ const item = props.item || {};
23
+ const depth = props.depth || 0;
24
+ // Deterministic position path ("0", "0-2", "0-2-1") — unique and identical on
25
+ // server/client, so the aria-controls id is collision-free and hydration-safe.
26
+ const nodeId = props.nodeId || "0";
27
+ const hasChildren = item.items && item.items.length > 0;
28
+ const panelId = `afw-nav-${nodeId}`;
29
+
30
+ const containsActive = () => treeContainsPath(item, router.pathname);
31
+ let expanded = $state(hasChildren && (containsActive() || depth === 0));
32
+
33
+ // Re-open the branch that holds the active route whenever navigation enters it.
34
+ $effect(() => {
35
+ if (hasChildren && containsActive()) expanded = true;
36
+ });
37
+
38
+ // Follow the sidebar's "collapse all" / "expand all" button. A press collapses *every*
39
+ // group, the active branch included — otherwise, reading a page inside the only open
40
+ // branch, the press would visibly change nothing. Navigation under a standing
41
+ // collapse-all is the other case: there the branch holding the new route opens, exactly
42
+ // as it does without the button. Deciding both here (rather than leaning on the effect
43
+ // above) keeps the two independent of the order they run in.
44
+ // A command already standing when this node is created isn't a press — it's the tree
45
+ // being rebuilt under one.
46
+ let seenSeq = collapseAll.command ? collapseAll.command.seq : 0;
47
+ $effect(() => {
48
+ const cmd = collapseAll.command;
49
+ if (!hasChildren || !cmd) return;
50
+ const isPress = cmd.seq !== seenSeq;
51
+ seenSeq = cmd.seq;
52
+ expanded = cmd.expanded || (!isPress && containsActive());
53
+ });
54
+
55
+ const toggle = () => (expanded = !expanded);
56
+ const chevronClass = () =>
57
+ expanded ? "afwd-sidebar-chevron is-open" : "afwd-sidebar-chevron";
58
+
59
+ return (
60
+ <li class={hasChildren ? "afwd-sidebar-node afwd-sidebar-group" : "afwd-sidebar-node"}>
61
+ {hasChildren ? (
62
+ item.path ? (
63
+ // Group that is also a page: leading chevron toggles, the link navigates.
64
+ // Chevron on the left mirrors the label-only groups below (no leading dot —
65
+ // the chevron already marks the row).
66
+ <div class="afwd-sidebar-group-row">
67
+ <button
68
+ type="button"
69
+ class="afwd-sidebar-group-toggle afwd-sidebar-group-toggle--icon"
70
+ aria-expanded={expanded ? "true" : "false"}
71
+ aria-controls={panelId}
72
+ aria-label={expanded ? `Collapse ${item.title}` : `Expand ${item.title}`}
73
+ onclick={toggle}
74
+ >
75
+ <svg
76
+ class={chevronClass()}
77
+ width="14"
78
+ height="14"
79
+ viewBox="0 0 24 24"
80
+ fill="none"
81
+ stroke="currentColor"
82
+ stroke-width="2"
83
+ stroke-linecap="round"
84
+ stroke-linejoin="round"
85
+ aria-hidden="true"
86
+ >
87
+ <polyline points="9 18 15 12 9 6" />
88
+ </svg>
89
+ </button>
90
+ <Link
91
+ href={item.path}
92
+ class={router.pathname === item.path ? "afwd-sidebar-link afwd-active" : "afwd-sidebar-link"}
93
+ >
94
+ {item.title}
95
+ </Link>
96
+ </div>
97
+ ) : (
98
+ // Section title with no page of its own — the whole row toggles.
99
+ <button
100
+ type="button"
101
+ class="afwd-sidebar-group-toggle"
102
+ aria-expanded={expanded ? "true" : "false"}
103
+ aria-controls={panelId}
104
+ onclick={toggle}
105
+ >
106
+ <svg
107
+ class={chevronClass()}
108
+ width="14"
109
+ height="14"
110
+ viewBox="0 0 24 24"
111
+ fill="none"
112
+ stroke="currentColor"
113
+ stroke-width="2"
114
+ stroke-linecap="round"
115
+ stroke-linejoin="round"
116
+ aria-hidden="true"
117
+ >
118
+ <polyline points="9 18 15 12 9 6" />
119
+ </svg>
120
+ <span class="afwd-sidebar-group-label">{item.title}</span>
121
+ </button>
122
+ )
123
+ ) : item.path ? (
124
+ <Link
125
+ href={item.path}
126
+ class={router.pathname === item.path ? "afwd-sidebar-link afwd-active" : "afwd-sidebar-link"}
127
+ >
128
+ <span class="afwd-sidebar-dot" aria-hidden="true"></span>
129
+ {item.title}
130
+ </Link>
131
+ ) : (
132
+ <span class="afwd-sidebar-group-title">{item.title}</span>
133
+ )}
134
+ {hasChildren && expanded ? (
135
+ <ul id={panelId} class="afwd-sidebar-sublist">
136
+ {item.items.map((child, i) => (
137
+ <SidebarNode item={child} depth={depth + 1} nodeId={`${nodeId}-${i}`} />
138
+ ))}
139
+ </ul>
140
+ ) : null}
141
+ </li>
142
+ );
143
+ }
@@ -0,0 +1,47 @@
1
+ // Hamburger button in the navbar that opens the mobile sidebar drawer. Like
2
+ // SearchTrigger, it is decoupled from the thing it controls: the <Sidebar> installs
3
+ // `window.__afwToggleSidebar` and emits an `afw:sidebar` event, so this button works
4
+ // even when the navbar and the sidebar live in different layouts (the website renders
5
+ // the navbar at its root, the sidebar only inside the docs/api sections).
6
+ //
7
+ // The button is hidden by default and revealed by CSS only on small screens and only
8
+ // while a Sidebar is mounted (`:root[data-afw-has-sidebar]`), so it never shows on a
9
+ // page without a drawer (e.g. the marketing home).
10
+
11
+ import { onMount } from "@opentf/afw";
12
+
13
+ export default function SidebarToggle() {
14
+ let expanded = $state(false);
15
+
16
+ onMount(() => {
17
+ // Mirror the drawer's real state so aria-expanded stays correct however it was
18
+ // toggled (button, backdrop, Escape, navigation, resize).
19
+ const onState = (e) => (expanded = !!(e.detail && e.detail.open));
20
+ window.addEventListener("afw:sidebar", onState);
21
+ return () => window.removeEventListener("afw:sidebar", onState);
22
+ });
23
+
24
+ const toggle = () => window.__afwToggleSidebar?.();
25
+
26
+ return (
27
+ <button
28
+ class="afwd-navbar-icon afwd-navbar-burger"
29
+ onclick={toggle}
30
+ aria-label="Toggle navigation"
31
+ aria-controls="afw-sidebar"
32
+ aria-expanded={expanded ? "true" : "false"}
33
+ >
34
+ {() =>
35
+ expanded ? (
36
+ <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true">
37
+ <path d="M6 6l12 12M18 6L6 18" />
38
+ </svg>
39
+ ) : (
40
+ <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true">
41
+ <path d="M3 6h18M3 12h18M3 18h18" />
42
+ </svg>
43
+ )
44
+ }
45
+ </button>
46
+ );
47
+ }
@@ -0,0 +1,14 @@
1
+ // Numbered, vertically-connected steps for walkthroughs. Each child heading
2
+ // (`<h3>`/`<h4>`) becomes a numbered step via a CSS counter, so it composes with
3
+ // plain Markdown inside MDX:
4
+ //
5
+ // <Steps>
6
+ // ### Install
7
+ // …
8
+ // ### Run the dev server
9
+ // …
10
+ // </Steps>
11
+
12
+ export default function Steps(props) {
13
+ return <div class="afwd-steps">{props.children}</div>;
14
+ }
@@ -0,0 +1,10 @@
1
+ // Styled, horizontally-scrollable table wrapper. (MDX GFM tables already emit
2
+ // the same wrapper around a theme-styled <table>; use <Table> in JSX pages.)
3
+
4
+ export default function Table(props) {
5
+ return (
6
+ <div class="afw-table-wrap" tabindex="0">
7
+ <table class="afwd-table">{props.children}</table>
8
+ </div>
9
+ );
10
+ }
@@ -0,0 +1,77 @@
1
+ // Generic tabbed panel. `tabs` is an array of `{ label, content }`. `content` is
2
+ // rendered as-is: a string is plain text, a node is the node. For a code panel with a
3
+ // copy button, pass a `CodeBlock`: `{ label, content: <CodeBlock code="…" /> }`.
4
+ //
5
+ // <Tabs label="Package manager" tabs={[{ label: "npm", content: <CodeBlock code="npm i …" /> }, …]} />
6
+ //
7
+ // Follows the WAI-ARIA tabs pattern: one tab stop for the list (roving `tabindex`),
8
+ // Arrow Left/Right (wrapping), Home and End move focus and select the tab, and each
9
+ // tab names and controls its panel. Ids are assigned on mount so a server-rendered
10
+ // tab set and its hydrated copy never disagree.
11
+
12
+ let instances = 0;
13
+
14
+ export default function Tabs(props) {
15
+ let active = $state(0);
16
+ let list = $ref();
17
+ const tabs = $derived(props.tabs || []);
18
+
19
+ onMount(() => {
20
+ const id = `afw-tabs-${++instances}`;
21
+ const buttons = list.querySelectorAll('[role="tab"]');
22
+ const panels = list.nextElementSibling.children;
23
+ buttons.forEach((button, i) => {
24
+ button.id = `${id}-tab-${i}`;
25
+ button.setAttribute("aria-controls", `${id}-panel-${i}`);
26
+ });
27
+ Array.from(panels).forEach((panel, i) => {
28
+ panel.id = `${id}-panel-${i}`;
29
+ panel.setAttribute("aria-labelledby", `${id}-tab-${i}`);
30
+ });
31
+ });
32
+
33
+ function onKeyDown(event) {
34
+ const last = tabs.length - 1;
35
+ const next = {
36
+ ArrowRight: active === last ? 0 : active + 1,
37
+ ArrowLeft: active === 0 ? last : active - 1,
38
+ Home: 0,
39
+ End: last,
40
+ }[event.key];
41
+ if (next === undefined || last < 0) return;
42
+ event.preventDefault();
43
+ active = next;
44
+ list.querySelectorAll('[role="tab"]')[next]?.focus();
45
+ }
46
+
47
+ return (
48
+ <div class="afwd-tabs">
49
+ <div class="afwd-tabs-list" role="tablist" aria-label={props.label} ref={list} onkeydown={onKeyDown}>
50
+ {tabs.map((tab, i) => (
51
+ <button
52
+ type="button"
53
+ role="tab"
54
+ class={active === i ? "afwd-tab afwd-active" : "afwd-tab"}
55
+ aria-selected={active === i ? "true" : "false"}
56
+ tabindex={active === i ? "0" : "-1"}
57
+ onclick={() => (active = i)}
58
+ >
59
+ {tab.label}
60
+ </button>
61
+ ))}
62
+ </div>
63
+ <div class="afwd-tabs-panels">
64
+ {tabs.map((tab, i) => (
65
+ <div
66
+ role="tabpanel"
67
+ tabindex="0"
68
+ class={active === i ? "afwd-tab-panel" : "afwd-tab-panel afwd-hidden"}
69
+ hidden={active !== i}
70
+ >
71
+ {tab.content}
72
+ </div>
73
+ ))}
74
+ </div>
75
+ </div>
76
+ );
77
+ }
@@ -0,0 +1,164 @@
1
+ // Theme switcher: a subtle ghost icon button that opens a Light / Dark / System menu.
2
+ //
3
+ // The chosen *mode* is persisted to localStorage("theme") as "light" | "dark" |
4
+ // "system" (default "system"). The applied theme is the resolved value — in System
5
+ // mode it follows the OS and live-updates when the OS preference flips. The trigger
6
+ // shows the mode's icon; in System mode it shows the monitor icon plus a small badge of
7
+ // the currently resolved icon (sun/moon), so you can see both the choice and the result.
8
+ //
9
+ // Pair with the no-flash inline script in index.html, which must resolve "system"/none
10
+ // to a concrete theme on first paint.
11
+
12
+ import { onMount } from "@opentf/afw";
13
+
14
+ import Tooltip from "./Tooltip.jsx";
15
+
16
+ const STORAGE_KEY = "theme";
17
+ const prefersDark = () =>
18
+ typeof window !== "undefined" && window.matchMedia("(prefers-color-scheme: dark)").matches;
19
+
20
+ export default function ThemeToggle() {
21
+ let mode = $state("system"); // "light" | "dark" | "system"
22
+ let resolved = $state("light"); // "light" | "dark"
23
+ let openMenu = $state(false);
24
+
25
+ const rootRef = $ref();
26
+
27
+ const resolve = (m) => (m === "system" ? (prefersDark() ? "dark" : "light") : m);
28
+
29
+ const apply = (m) => {
30
+ resolved = resolve(m);
31
+ if (typeof document !== "undefined") {
32
+ document.documentElement.setAttribute("data-theme", resolved);
33
+ }
34
+ };
35
+
36
+ const setMode = (m) => {
37
+ mode = m;
38
+ openMenu = false;
39
+ try {
40
+ localStorage.setItem(STORAGE_KEY, m);
41
+ } catch {}
42
+ apply(m);
43
+ };
44
+
45
+ onMount(() => {
46
+ const saved = (() => {
47
+ try {
48
+ return localStorage.getItem(STORAGE_KEY);
49
+ } catch {
50
+ return null;
51
+ }
52
+ })();
53
+ mode = saved === "light" || saved === "dark" || saved === "system" ? saved : "system";
54
+ apply(mode);
55
+
56
+ // Follow the OS while in System mode.
57
+ const mql = window.matchMedia("(prefers-color-scheme: dark)");
58
+ const onOS = () => mode === "system" && apply("system");
59
+ mql.addEventListener?.("change", onOS);
60
+
61
+ // Close the menu on outside click / Escape.
62
+ const onDocClick = (e) => {
63
+ if (openMenu && rootRef && !rootRef.contains(e.target)) openMenu = false;
64
+ };
65
+ const onKey = (e) => e.key === "Escape" && (openMenu = false);
66
+ document.addEventListener("click", onDocClick);
67
+ document.addEventListener("keydown", onKey);
68
+
69
+ return () => {
70
+ mql.removeEventListener?.("change", onOS);
71
+ document.removeEventListener("click", onDocClick);
72
+ document.removeEventListener("keydown", onKey);
73
+ };
74
+ });
75
+
76
+ return (
77
+ <div class="afwd-theme" ref={rootRef}>
78
+ <Tooltip text="Change theme">
79
+ <button
80
+ class="afwd-navbar-icon afwd-theme-trigger"
81
+ onclick={(e) => {
82
+ e.stopPropagation();
83
+ openMenu = !openMenu;
84
+ }}
85
+ aria-label="Change theme"
86
+ aria-haspopup="menu"
87
+ aria-expanded={openMenu ? "true" : "false"}
88
+ >
89
+ {() =>
90
+ mode === "system" ? (
91
+ <span class="afwd-theme-trigger-system">
92
+ <MonitorIcon />
93
+ <span class="afwd-theme-trigger-badge">
94
+ {resolved === "dark" ? <MoonIcon small /> : <SunIcon small />}
95
+ </span>
96
+ </span>
97
+ ) : mode === "dark" ? (
98
+ <MoonIcon />
99
+ ) : (
100
+ <SunIcon />
101
+ )
102
+ }
103
+ </button>
104
+ </Tooltip>
105
+
106
+ {() =>
107
+ openMenu ? (
108
+ <div class="afwd-theme-menu" role="menu">
109
+ <MenuItem active={mode === "light"} onclick={() => setMode("light")}>
110
+ <SunIcon small /> Light
111
+ </MenuItem>
112
+ <MenuItem active={mode === "dark"} onclick={() => setMode("dark")}>
113
+ <MoonIcon small /> Dark
114
+ </MenuItem>
115
+ <MenuItem active={mode === "system"} onclick={() => setMode("system")}>
116
+ <MonitorIcon small /> System
117
+ </MenuItem>
118
+ </div>
119
+ ) : null
120
+ }
121
+ </div>
122
+ );
123
+ }
124
+
125
+ function MenuItem(props) {
126
+ return (
127
+ <button
128
+ class={props.active ? "afwd-theme-item is-active" : "afwd-theme-item"}
129
+ role="menuitemradio"
130
+ aria-checked={props.active ? "true" : "false"}
131
+ onclick={props.onclick}
132
+ >
133
+ {props.children}
134
+ </button>
135
+ );
136
+ }
137
+
138
+ function SunIcon(props) {
139
+ const s = props.small ? 15 : 17;
140
+ return (
141
+ <svg width={s} height={s} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
142
+ <path stroke-linecap="round" stroke-linejoin="round" d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364-6.364l-.707.707M6.343 17.657l-.707.707m12.728 0l-.707-.707M6.343 6.343l-.707-.707M12 5a7 7 0 100 14 7 7 0 000-14z" />
143
+ </svg>
144
+ );
145
+ }
146
+
147
+ function MoonIcon(props) {
148
+ const s = props.small ? 15 : 17;
149
+ return (
150
+ <svg width={s} height={s} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
151
+ <path stroke-linecap="round" stroke-linejoin="round" d="M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z" />
152
+ </svg>
153
+ );
154
+ }
155
+
156
+ function MonitorIcon(props) {
157
+ const s = props.small ? 15 : 17;
158
+ return (
159
+ <svg width={s} height={s} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
160
+ <rect x="2" y="3" width="20" height="14" rx="2" />
161
+ <path d="M8 21h8M12 17v4" />
162
+ </svg>
163
+ );
164
+ }
@@ -0,0 +1,106 @@
1
+ // "On this page" table of contents, with scroll-spy highlighting via IntersectionObserver.
2
+ // Rebuilds on route change.
3
+ //
4
+ // The outline comes from the page's `toc` export (`router.toc`, emitted by the MDX
5
+ // front-end), so it is in the served HTML and adopted at hydration: no pop-in, no layout
6
+ // shift. A page without one (plain JSX) falls back to reading its headings from the DOM
7
+ // after mount, as before.
8
+
9
+ import { isHydrating, onMount, router } from "@opentf/afw";
10
+
11
+ const sameOutline = (a, b) =>
12
+ a.length === b.length && a.every((h, i) => h.id === b[i].id && h.text === b[i].text && h.sub === b[i].sub);
13
+
14
+ export default function Toc() {
15
+ const fromPage = () =>
16
+ (router.toc ?? [])
17
+ .filter((h) => h.depth === 2 || h.depth === 3)
18
+ .map((h) => ({ id: h.id, text: h.text, sub: h.depth === 3 }));
19
+
20
+ // A server-rendered `<Toc>` upgrades the moment its module defines it, which is during
21
+ // the router's route import and so before `router.toc` is set. It takes the outline the
22
+ // server rendered into it instead, so the adopt walk always sees the markup it expects.
23
+ const fromServer = () =>
24
+ Array.from(document.querySelectorAll("nav.afwd-toc .afwd-toc-link"), (a) => ({
25
+ id: decodeURIComponent((a.getAttribute("href") || "").slice(1)),
26
+ text: a.textContent || "",
27
+ sub: a.parentElement?.classList.contains("afwd-toc-sub") ?? false,
28
+ }));
29
+
30
+ let items = $state(isHydrating() && typeof document !== "undefined" ? fromServer() : fromPage());
31
+ let activeId = $state("");
32
+ let observer = null;
33
+
34
+ // `initial`: an outline already rendered (served, then adopted) is kept as is. Assigning
35
+ // an equal array would rebuild the list the server sent, and `router.toc` may not be set
36
+ // yet when this first runs.
37
+ const build = (initial = false) => {
38
+ if (typeof document === "undefined") return;
39
+ const root = document.getElementById("afw-content");
40
+ if (!root) return;
41
+ const hs = Array.from(root.querySelectorAll("h2[id], h3[id]"));
42
+ const page = fromPage();
43
+ if (!(initial && items.length > 0)) {
44
+ const next = page.length > 0
45
+ ? page
46
+ : hs.map((h) => ({ id: h.id, text: h.textContent || "", sub: h.tagName === "H3" }));
47
+ // Only a real change replaces the list: the router publishing the same headings
48
+ // (at startup, after the served outline was adopted) must not rebuild it.
49
+ if (!sameOutline(items, next)) items = next;
50
+ }
51
+ if (observer) observer.disconnect();
52
+ observer = new IntersectionObserver(
53
+ (entries) => {
54
+ for (const e of entries) if (e.isIntersecting) activeId = e.target.id;
55
+ },
56
+ { rootMargin: "-10% 0px -80% 0px", threshold: 0 },
57
+ );
58
+ for (const h of hs) observer.observe(h);
59
+ };
60
+
61
+ onMount(() => {
62
+ build(true);
63
+ return () => observer && observer.disconnect();
64
+ });
65
+
66
+ // Rebuild when the route or its headings change (content swaps under the same layout). Effects run at
67
+ // construction — before `onMount` — so the first run would schedule a second, redundant
68
+ // build of the same headings: on first paint the outline was built once by `onMount` and
69
+ // then torn down and rebuilt a frame later, a visible flicker on every docs page. Skip that
70
+ // run and let `onMount` do the initial build.
71
+ let routed = false;
72
+ $effect(() => {
73
+ router.pathname;
74
+ // A hot refresh of the page publishes its new headings without a navigation.
75
+ router.toc;
76
+ if (!routed) {
77
+ routed = true;
78
+ return;
79
+ }
80
+ if (typeof requestAnimationFrame !== "undefined") requestAnimationFrame(() => build());
81
+ });
82
+
83
+ return (
84
+ <nav class="afwd-toc" aria-label="On this page">
85
+ {() =>
86
+ items.length > 0 ? (
87
+ <div class="afwd-toc-inner">
88
+ <div class="afwd-toc-heading">On this page</div>
89
+ <ul class="afwd-toc-list">
90
+ {items.map((h) => (
91
+ <li class={h.sub ? "afwd-toc-item afwd-toc-sub" : "afwd-toc-item"}>
92
+ <a
93
+ href={"#" + h.id}
94
+ class={activeId === h.id ? "afwd-toc-link afwd-active" : "afwd-toc-link"}
95
+ >
96
+ {h.text}
97
+ </a>
98
+ </li>
99
+ ))}
100
+ </ul>
101
+ </div>
102
+ ) : null
103
+ }
104
+ </nav>
105
+ );
106
+ }
@@ -0,0 +1,19 @@
1
+ // A small hover/focus tooltip. CSS-driven (no JS state) — wrap any element and pass
2
+ // `text`; the bubble shows on hover or keyboard focus of the wrapped content.
3
+ //
4
+ // <Tooltip text="Change theme"><button>…</button></Tooltip>
5
+ //
6
+ // `placement` is "bottom" (default) or "top". The bubble is aria-hidden decorative
7
+ // chrome; give the wrapped control its own `aria-label` for assistive tech.
8
+
9
+ export default function Tooltip(props) {
10
+ const placement = props.placement === "top" ? "afwd-tooltip-top" : "afwd-tooltip-bottom";
11
+ return (
12
+ <span class={`afwd-tooltip ${placement}`}>
13
+ {props.children}
14
+ <span class="afwd-tooltip-bubble" role="tooltip" aria-hidden="true">
15
+ {props.text}
16
+ </span>
17
+ </span>
18
+ );
19
+ }
@@ -0,0 +1,21 @@
1
+ // Small shared formatting helpers for the docs/blog components.
2
+
3
+ const DATE_OPTIONS = { year: "numeric", month: "long", day: "numeric" };
4
+
5
+ // `2026-06-24` (or any Date-parseable value) → `June 24, 2026`. Date-only values are
6
+ // calendar dates, not instants, so they format in UTC and no viewer time zone can
7
+ // shift them to another day; timestamps render in the viewer's zone. Anything the
8
+ // Date constructor can't parse falls back to the raw value so it still renders.
9
+ // Uses `Date` rather than Temporal, which Safari does not ship.
10
+ export function formatDate(value) {
11
+ if (!value) return "";
12
+ if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
13
+ const day = new Date(`${value}T00:00:00Z`);
14
+ // Some engines roll an impossible day over (2026-02-30 → March 2); keep it raw.
15
+ if (Number.isNaN(day.getTime()) || day.toISOString().slice(0, 10) !== value) return value;
16
+ return day.toLocaleDateString("en-US", { ...DATE_OPTIONS, timeZone: "UTC" });
17
+ }
18
+ const date = value instanceof Date ? value : new Date(value);
19
+ if (Number.isNaN(date.getTime())) return String(value);
20
+ return date.toLocaleDateString("en-US", DATE_OPTIONS);
21
+ }
@@ -0,0 +1,21 @@
1
+ // Date rules shared by the blog components.
2
+
3
+ /** The UTC calendar day of a date value as `YYYY-MM-DD`, or `null` when invalid. */
4
+ function utcDay(value) {
5
+ const date = new Date(value);
6
+ return Number.isNaN(date.getTime()) ? null : date.toISOString().slice(0, 10);
7
+ }
8
+
9
+ /**
10
+ * True when a post was edited on a later calendar day than it was published, so a
11
+ * "Last updated" line adds information. An update on the publish day, or one dated
12
+ * before publication (a stale git timestamp, a backdated post), shows nothing.
13
+ * Days compare in UTC because a frontmatter `date: 2026-10-03` parses as UTC midnight.
14
+ * Without a valid publish date, any valid update is shown.
15
+ */
16
+ export function editedAfterPublish(updated, published) {
17
+ const updatedDay = updated ? utcDay(updated) : null;
18
+ if (!updatedDay) return false;
19
+ const publishedDay = published ? utcDay(published) : null;
20
+ return !publishedDay || updatedDay > publishedDay;
21
+ }
@@ -0,0 +1,38 @@
1
+ // Shared "collapse all / expand all" state for the docs sidebar tree.
2
+ //
3
+ // The button lives in <Sidebar>, but the open/closed state lives in each <SidebarNode>,
4
+ // so the two are coupled through this module-scope signal rather than by prop-drilling
5
+ // through a recursive tree (the same decoupling the drawer uses for the navbar burger).
6
+ // Every group node runs an effect on `collapseAll.command`; the button flips it.
7
+ //
8
+ // State is per-session only, like the per-node default — a reload starts over. It does
9
+ // persist across SPA navigation, so a collapsed tree stays collapsed while you read
10
+ // (except the branch holding the active route, which SidebarNode always keeps open).
11
+
12
+ import { signal } from "@opentf/afw";
13
+
14
+ // `{ expanded, seq }`. `seq` makes every press a distinct value so the effect re-runs:
15
+ // expanding one group by hand and pressing "collapse all" again must re-collapse it.
16
+ const command = signal(null);
17
+ let seq = 0;
18
+
19
+ export const collapseAll = {
20
+ /** The last command, or `null` when the tree is still at its derived default. */
21
+ get command() {
22
+ return command.value;
23
+ },
24
+ /** True while "collapse all" is in effect — drives the button's icon and label. */
25
+ get collapsed() {
26
+ const c = command.value;
27
+ return !!c && !c.expanded;
28
+ },
29
+ /** Broadcast `expanded` to every group node. */
30
+ set(expanded) {
31
+ command.value = { expanded, seq: (seq += 1) };
32
+ },
33
+ /** Drop the command; nodes fall back to their derived default. For tests. */
34
+ reset() {
35
+ command.value = null;
36
+ seq = 0;
37
+ },
38
+ };