@opentf/afw-docs 0.39.0 → 0.40.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.
@@ -11,7 +11,7 @@
11
11
  import { childRoute } from "./route-url.js";
12
12
  import { cwd, join, readEntries, relative, resolve, runOut } from "./host.js";
13
13
  import { readFrontmatter } from "./frontmatter.js";
14
- import { resolveLastUpdated } from "./last-updated.js";
14
+ import { gitLastUpdatedAll, resolveLastUpdated } from "./last-updated.js";
15
15
  import { frontmatterUpdated } from "./publish.js";
16
16
 
17
17
  const VIRTUAL_ID = "@opentf/afw-docs/updated";
@@ -82,6 +82,10 @@ async function collect(appDir, exclude, watch, blogDir) {
82
82
  const updated = {};
83
83
  const editPaths = {};
84
84
  const root0 = await gitRoot(appDir);
85
+ // Every page's git date from one `git log` over app/, read once a page needs it: a
86
+ // process per page took seconds on a cold disk (79 pages: 3s; one log: a fraction).
87
+ let gitDates = null;
88
+ const gitDate = async (file) => (await (gitDates ??= gitLastUpdatedAll(appDir))).get(file) ?? null;
85
89
  // One walk over every page under app/ — covers all sections (and the home page).
86
90
  await walk(appDir, "", exclude, async (file, route) => {
87
91
  watch.push(file);
@@ -91,7 +95,7 @@ async function collect(appDir, exclude, watch, blogDir) {
91
95
  const post = blogDir && route.startsWith(`/${blogDir}/`);
92
96
  const iso = post
93
97
  ? (frontmatterUpdated(fm) ? await resolveLastUpdated(file, frontmatterUpdated(fm)) : null)
94
- : await resolveLastUpdated(file, fm.lastUpdated);
98
+ : await resolveLastUpdated(file, fm.lastUpdated, gitDate);
95
99
  if (iso) updated[route] = iso;
96
100
  // Repo-relative path (POSIX separators) for the "Edit this page" link.
97
101
  if (root0) editPaths[route] = relative(root0, file).split(/[\\/]/).join("/");
@@ -8,7 +8,7 @@
8
8
  // isn't in git history the value is simply null and the UI omits it. This runs in dev
9
9
  // and build alike — the displayed time is always the real last content change.
10
10
 
11
- import { dirname, runOut } from "./host.js";
11
+ import { dirname, join, runOut } from "./host.js";
12
12
 
13
13
  /** Last git commit (committer ISO-8601) that touched `file`, or null. */
14
14
  export async function gitLastUpdated(file) {
@@ -18,6 +18,29 @@ export async function gitLastUpdated(file) {
18
18
  return out || null;
19
19
  }
20
20
 
21
+ /**
22
+ * The last commit (committer ISO-8601) of every file under `dir`, from one `git log`:
23
+ * `Map<path, ISO>`, each path `join(dir, <its path under dir>)`. History is read newest
24
+ * first, so a file's first sighting is its last commit, the one `gitLastUpdated` names.
25
+ * Empty when `dir` is not in a git repository or git is unavailable.
26
+ */
27
+ export async function gitLastUpdatedAll(dir) {
28
+ // `-z`: paths as written, each NUL-terminated; `--relative`: under `dir`. Every commit
29
+ // opens with \x01<date>.
30
+ const out = await runOut("git", ["log", "-z", "--relative", "--name-only", "--format=%x01%cI", "--", "."], dir);
31
+ const dates = new Map();
32
+ let date = null;
33
+ for (const token of (out ?? "").split("\0")) {
34
+ const field = token.replace(/^\n/, "");
35
+ if (field.startsWith("\x01")) date = field.slice(1);
36
+ else if (field && date) {
37
+ const file = join(dir, field);
38
+ if (!dates.has(file)) dates.set(file, date);
39
+ }
40
+ }
41
+ return dates;
42
+ }
43
+
21
44
  /** Normalize a frontmatter override to ISO-8601, or keep the raw string if unparseable. */
22
45
  function normalize(value) {
23
46
  const d = new Date(value);
@@ -29,10 +52,12 @@ function normalize(value) {
29
52
  *
30
53
  * @param {string} file Absolute path to the page file.
31
54
  * @param {*} [frontmatter] The frontmatter `lastUpdated` value, if any.
55
+ * @param {(file: string) => Promise<string|null>} [gitDate] The file's git date; by default
56
+ * its own `git log` (a page scan passes a lookup into `gitLastUpdatedAll`).
32
57
  * @returns {string|null} ISO-8601 (or a raw override string), or null to omit.
33
58
  */
34
- export async function resolveLastUpdated(file, frontmatter) {
59
+ export async function resolveLastUpdated(file, frontmatter, gitDate = gitLastUpdated) {
35
60
  if (frontmatter === false) return null; // explicit opt-out for this page
36
61
  if (frontmatter != null && frontmatter !== true) return normalize(frontmatter);
37
- return gitLastUpdated(file);
62
+ return gitDate(file);
38
63
  }
@@ -2,6 +2,8 @@
2
2
 
3
3
  import { Link, RawHtml, router } from "@opentf/afw";
4
4
 
5
+ import { sectionTree } from "./nav-source.js";
6
+
5
7
  // Structured data for crawlers: the visible trail above as a BreadcrumbList.
6
8
  // Emitted beside the nav (JSON-LD is discovered wherever it sits). `siteUrl`
7
9
  // (optional site origin) absolutizes the item URLs; without it they stay
@@ -28,7 +30,7 @@ function breadcrumbJsonLd(trail, siteUrl) {
28
30
  }
29
31
 
30
32
  export default function Breadcrumbs(props) {
31
- const nav = props.nav || [];
33
+ const nav = sectionTree(props.nav, router.pathname);
32
34
  const siteUrl = props.siteUrl || "";
33
35
 
34
36
  const findTrail = (items, path, trail) => {
@@ -7,8 +7,8 @@
7
7
  //
8
8
  // That's the whole thing — any folder becomes a documentation section just by giving it
9
9
  // a layout that renders `DocsLayout`. The sidebar/breadcrumbs/prev-next come from the
10
- // generated nav (`@opentf/afw-docs/nav`, imported here), and the layout scopes them to
11
- // the current section by route. So every section shares the same traits, and the docs
10
+ // generated nav (`@opentf/afw-docs/nav`, read through nav-source.js), scoped to the
11
+ // current section by route. So every section shares the same traits, and the docs
12
12
  // and api layout files are identical. (Pass a `nav` prop only to override.)
13
13
  //
14
14
  // `frame` (default true) renders the full chrome (navbar + footer). Pass
@@ -16,9 +16,9 @@
16
16
  // the navbar/footer — only the sidebar · content · TOC grid is rendered.
17
17
 
18
18
  import { router } from "@opentf/afw";
19
- import navMap from "@opentf/afw-docs/nav";
20
19
  import updated, { editPaths } from "@opentf/afw-docs/updated";
21
20
 
21
+ import { pickSection } from "./nav-source.js";
22
22
  import Navbar from "./Navbar.jsx";
23
23
  import Sidebar from "./Sidebar.jsx";
24
24
  import Toc from "./Toc.jsx";
@@ -33,14 +33,15 @@ import LastUpdated from "./LastUpdated.jsx";
33
33
 
34
34
  export default function DocsLayout(props) {
35
35
  const config = props.config || {};
36
- const nav = props.nav || navMap;
37
36
  const frame = props.frame !== false;
38
37
 
39
- // The sidebar/breadcrumbs/prev-next operate on the *current section's* tree. `nav` is
40
- // a section map keyed by base path; pick the branch whose base prefixes the route
41
- // (longest match wins). A bare array means a single, unscoped section. Each section is
42
- // its own layout instance, so resolving once at mount is correct.
43
- const sectionNav = pickSection(nav, router.pathname);
38
+ // The sidebar/breadcrumbs/prev-next operate on the *current section's* tree. With the
39
+ // generated nav they look it up themselves (nav-source.js), so the tree is never a prop
40
+ // and never lands in the page's hydration payload. Only an overriding `nav` prop is
41
+ // passed down, as its section: a map keyed by base path (longest prefix wins) or a bare
42
+ // array for one section. Each section is its own layout instance, so resolving once at
43
+ // mount is correct.
44
+ const sectionNav = props.nav ? pickSection(props.nav, router.pathname) : undefined;
44
45
 
45
46
  // Last-updated time for the current page, looked up in the build-time map keyed by
46
47
  // route (same exact-path match Pagination uses). `$derived` so it tracks navigation.
@@ -88,19 +89,3 @@ export default function DocsLayout(props) {
88
89
  body
89
90
  );
90
91
  }
91
-
92
- // Resolve the section tree for `pathname` from a `{ [base]: tree }` map. Longest base
93
- // prefix wins ("/" matches anything). Tolerates a bare array (single section).
94
- function pickSection(nav, pathname) {
95
- if (Array.isArray(nav)) return nav;
96
- let best = null;
97
- let bestLen = -1;
98
- for (const base in nav) {
99
- const match = base === "/" ? true : pathname === base || pathname.startsWith(base + "/");
100
- if (match && base.length > bestLen) {
101
- best = nav[base];
102
- bestLen = base.length;
103
- }
104
- }
105
- return best || nav[Object.keys(nav)[0]] || [];
106
- }
@@ -2,8 +2,10 @@
2
2
 
3
3
  import { Link, router } from "@opentf/afw";
4
4
 
5
+ import { sectionTree } from "./nav-source.js";
6
+
5
7
  export default function Pagination(props) {
6
- const nav = props.nav || [];
8
+ const nav = sectionTree(props.nav, router.pathname);
7
9
 
8
10
  const flat = [];
9
11
  const walk = (items) => {
@@ -22,13 +22,43 @@
22
22
  // Above the tree sits a single icon button that collapses (or re-expands) every group at
23
23
  // once — it drives the nodes through the shared `collapseAll` signal, since they are
24
24
  // rendered recursively by SidebarNode.
25
+ //
26
+ // Size: the tree comes from the cached nav module (nav-source.js), not from props, and
27
+ // each node is given only its position; its links are plain `<a>`s whose clicks and
28
+ // prefetch this component handles once for the whole tree. A large tree opens only the
29
+ // branch holding the current page. So a page's sidebar costs its open branch, not the site.
25
30
 
26
- import { onMount, router } from "@opentf/afw";
31
+ import { navigate, onMount, prefetch, router, shouldInterceptNav } from "@opentf/afw";
27
32
 
28
33
  import SidebarNode from "./SidebarNode.jsx";
29
34
  import NavbarLink from "./NavbarLink.jsx";
35
+ import { EXPAND_ALL_LIMIT, countLinks, sectionTree } from "./nav-source.js";
30
36
  import { collapseAll } from "./sidebar-collapse.js";
31
37
 
38
+ // A sidebar link this event concerns: an `<a href>` inside the tree.
39
+ const linkOf = (event) => event.target?.closest?.(".afwd-sidebar-nav a[href]");
40
+
41
+ // Client-side navigation for the tree's links, as `<Link>` does for one: modified or
42
+ // non-primary clicks, other origins, and full-page (MPA) mode are left to the browser.
43
+ function onNavClick(event) {
44
+ const link = linkOf(event);
45
+ if (!link) return;
46
+ if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || event.button !== 0) return;
47
+ if (link.target && link.target !== "_self") return;
48
+ const url = new URL(link.href, location.href);
49
+ if (url.origin !== location.origin || !shouldInterceptNav()) return;
50
+ event.preventDefault();
51
+ navigate(url.pathname + url.search + url.hash);
52
+ }
53
+
54
+ // Warm the route on hover or focus, as `<Link>`'s default "intent" prefetch does.
55
+ function onNavIntent(event) {
56
+ const link = linkOf(event);
57
+ if (!link || !shouldInterceptNav()) return;
58
+ const url = new URL(link.href, location.href);
59
+ if (url.origin === location.origin) prefetch(url.pathname + url.search);
60
+ }
61
+
32
62
  const DESKTOP_QUERY = "(min-width: 768px)";
33
63
 
34
64
  // How many Sidebars are mounted right now. On SPA navigation a new section's Sidebar can
@@ -38,7 +68,11 @@ const DESKTOP_QUERY = "(min-width: 768px)";
38
68
  let liveSidebars = 0;
39
69
 
40
70
  export default function Sidebar(props) {
41
- const nav = props.nav || [];
71
+ const nav = sectionTree(props.nav, router.pathname);
72
+ // Given a `nav` prop, the nodes take their items as props; otherwise they look them up.
73
+ const given = !!props.nav;
74
+ // Top-level groups start open on a small tree; on a large one only the current branch does.
75
+ const openTopLevel = countLinks(nav) <= EXPAND_ALL_LIMIT;
42
76
  // Top-level site links (config.nav). On desktop they live in the navbar; on mobile the
43
77
  // navbar hides them and the drawer surfaces them above the section tree, so the whole
44
78
  // nav is reachable from one place.
@@ -159,7 +193,7 @@ export default function Sidebar(props) {
159
193
  // Defer a frame so the newly-active class (and any auto-expanded branch) is in the DOM.
160
194
  const raf = requestAnimationFrame(() => {
161
195
  const aside = asideRef;
162
- const active = aside && aside.querySelector(".afwd-sidebar-nav .afwd-active");
196
+ const active = aside && aside.querySelector(".afwd-sidebar-nav [aria-current=\"page\"]");
163
197
  if (!active) return;
164
198
  const a = active.getBoundingClientRect();
165
199
  const c = aside.getBoundingClientRect();
@@ -245,10 +279,10 @@ export default function Sidebar(props) {
245
279
  </button>
246
280
  </div>
247
281
  ) : null}
248
- <nav class="afwd-sidebar-nav" aria-label="Documentation">
282
+ <nav class="afwd-sidebar-nav" aria-label="Documentation" onclick={onNavClick} onpointerover={onNavIntent} onfocusin={onNavIntent}>
249
283
  <ul class="afwd-sidebar-list">
250
284
  {nav.map((item, i) => (
251
- <SidebarNode item={item} nodeId={String(i)} />
285
+ <SidebarNode item={given ? item : undefined} nodeId={String(i)} open={openTopLevel} />
252
286
  ))}
253
287
  </ul>
254
288
  </nav>
@@ -1,13 +1,23 @@
1
1
  // One node of the sidebar tree — a link, a collapsible group, or both. Recurses into
2
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.
3
+ // active route stays open, and top-level groups start expanded unless the Sidebar says the
4
+ // tree is large (`open={false}`, past EXPAND_ALL_LIMIT links), where only the active branch
5
+ // does. A closed group renders no
6
+ // children: they are built in the browser, from the cached nav module, when it opens.
7
+ // Open/closed state is per-session only (no persistence) — a reload resets to this
8
+ // derived default.
9
+ //
10
+ // The node's only prop is its position (`nodeId`); it looks its item up in the section
11
+ // tree (nav-source.js), so the page's hydration payload holds no tree. Given an `item`
12
+ // prop (the Sidebar was given a `nav`), it uses that instead. Links are plain `<a>`s:
13
+ // the Sidebar routes their clicks.
5
14
  //
6
15
  // The sidebar's "collapse all" button drives every node at once through the shared
7
16
  // `collapseAll` signal (components/sidebar-collapse.js).
8
17
 
9
- import { Link, router } from "@opentf/afw";
18
+ import { localizePath, router } from "@opentf/afw";
10
19
 
20
+ import { nodeAt, sectionTree } from "./nav-source.js";
11
21
  import { collapseAll } from "./sidebar-collapse.js";
12
22
 
13
23
  // True when `path` is `node` itself or lives somewhere in its subtree.
@@ -19,16 +29,21 @@ function treeContainsPath(node, path) {
19
29
  }
20
30
 
21
31
  export default function SidebarNode(props) {
22
- const item = props.item || {};
23
- const depth = props.depth || 0;
24
32
  // Deterministic position path ("0", "0-2", "0-2-1") — unique and identical on
25
33
  // server/client, so the aria-controls id is collision-free and hydration-safe.
26
34
  const nodeId = props.nodeId || "0";
35
+ const given = !!props.item;
36
+ const tree = given ? null : sectionTree(undefined, router.pathname);
37
+ const item = props.item || nodeAt(tree, nodeId) || {};
38
+ const depth = nodeId.split("-").length - 1;
27
39
  const hasChildren = item.items && item.items.length > 0;
28
40
  const panelId = `afw-nav-${nodeId}`;
41
+ // `open` (top-level nodes only): the Sidebar's call — false on a large tree, where only
42
+ // the branch holding the current page starts open.
43
+ const openTopLevel = props.open !== false;
29
44
 
30
45
  const containsActive = () => treeContainsPath(item, router.pathname);
31
- let expanded = $state(hasChildren && (containsActive() || depth === 0));
46
+ let expanded = $state(hasChildren && (containsActive() || (depth === 0 && openTopLevel)));
32
47
 
33
48
  // Re-open the branch that holds the active route whenever navigation enters it.
34
49
  $effect(() => {
@@ -53,6 +68,10 @@ export default function SidebarNode(props) {
53
68
  });
54
69
 
55
70
  const toggle = () => (expanded = !expanded);
71
+ // The current page: `aria-current="page"` (the styling hook), plus the legacy class.
72
+ const isCurrent = () => router.pathname === item.path;
73
+ const current = () => (isCurrent() ? "page" : undefined);
74
+ const linkClass = () => (isCurrent() ? "afwd-sidebar-link afwd-active" : "afwd-sidebar-link");
56
75
  const chevronClass = () =>
57
76
  expanded ? "afwd-sidebar-chevron is-open" : "afwd-sidebar-chevron";
58
77
 
@@ -87,12 +106,9 @@ export default function SidebarNode(props) {
87
106
  <polyline points="9 18 15 12 9 6" />
88
107
  </svg>
89
108
  </button>
90
- <Link
91
- href={item.path}
92
- class={router.pathname === item.path ? "afwd-sidebar-link afwd-active" : "afwd-sidebar-link"}
93
- >
109
+ <a href={localizePath(item.path)} class={linkClass()} aria-current={current()}>
94
110
  {item.title}
95
- </Link>
111
+ </a>
96
112
  </div>
97
113
  ) : (
98
114
  // Section title with no page of its own — the whole row toggles.
@@ -121,20 +137,17 @@ export default function SidebarNode(props) {
121
137
  </button>
122
138
  )
123
139
  ) : item.path ? (
124
- <Link
125
- href={item.path}
126
- class={router.pathname === item.path ? "afwd-sidebar-link afwd-active" : "afwd-sidebar-link"}
127
- >
140
+ <a href={localizePath(item.path)} class={linkClass()} aria-current={current()}>
128
141
  <span class="afwd-sidebar-dot" aria-hidden="true"></span>
129
142
  {item.title}
130
- </Link>
143
+ </a>
131
144
  ) : (
132
145
  <span class="afwd-sidebar-group-title">{item.title}</span>
133
146
  )}
134
147
  {hasChildren && expanded ? (
135
148
  <ul id={panelId} class="afwd-sidebar-sublist">
136
149
  {item.items.map((child, i) => (
137
- <SidebarNode item={child} depth={depth + 1} nodeId={`${nodeId}-${i}`} />
150
+ <SidebarNode item={given ? child : undefined} nodeId={`${nodeId}-${i}`} />
138
151
  ))}
139
152
  </ul>
140
153
  ) : null}
@@ -60,13 +60,18 @@ export default function Tabs(props) {
60
60
  </button>
61
61
  ))}
62
62
  </div>
63
+ {/* `until-found`: an inactive panel stays out of view, but find-in-page can match its
64
+ text (and the search index includes it). The browser reveals the panel and fires
65
+ `beforematch` first, so the tab list follows. Browsers without it treat the value
66
+ as plain `hidden`. */}
63
67
  <div class="afwd-tabs-panels">
64
68
  {tabs.map((tab, i) => (
65
69
  <div
66
70
  role="tabpanel"
67
71
  tabindex="0"
68
- class={active === i ? "afwd-tab-panel" : "afwd-tab-panel afwd-hidden"}
69
- hidden={active !== i}
72
+ class="afwd-tab-panel"
73
+ hidden={active !== i ? "until-found" : undefined}
74
+ onbeforematch={() => (active = i)}
70
75
  >
71
76
  {tab.content}
72
77
  </div>
@@ -0,0 +1,67 @@
1
+ // Where the docs components get the nav tree.
2
+ //
3
+ // The tree comes from the generated `@opentf/afw-docs/nav` module: one JavaScript chunk
4
+ // the browser caches for the whole site. A component that is not given a `nav` prop looks
5
+ // its section up there, so a server-rendered page carries no copy of the tree in its
6
+ // hydration payload (it used to carry several, plus every sidebar node's subtree, which
7
+ // made each page grow with the size of the site).
8
+ //
9
+ // Sidebar nodes name their place in the tree by position ("0", "0-2", "0-2-1"), so a node's
10
+ // only prop is that id.
11
+
12
+ import navMap from "@opentf/afw-docs/nav";
13
+
14
+ /**
15
+ * The section tree for `pathname` in a `{ [base]: tree }` map: the longest base that
16
+ * prefixes the path ("/" matches anything). A bare array is a single section.
17
+ */
18
+ export function pickSection(nav, pathname) {
19
+ if (Array.isArray(nav)) return nav;
20
+ let best = null;
21
+ let bestLen = -1;
22
+ for (const base in nav) {
23
+ const match = base === "/" ? true : pathname === base || pathname.startsWith(base + "/");
24
+ if (match && base.length > bestLen) {
25
+ best = nav[base];
26
+ bestLen = base.length;
27
+ }
28
+ }
29
+ return best || nav[Object.keys(nav)[0]] || [];
30
+ }
31
+
32
+ /** The tree a component shows: its `nav` prop, else the generated nav's section for the path. */
33
+ export function sectionTree(nav, pathname) {
34
+ return nav || pickSection(navMap, pathname);
35
+ }
36
+
37
+ /** The node at a position id ("0-2-1") in `tree`, or undefined. */
38
+ export function nodeAt(tree, nodeId) {
39
+ let items = tree;
40
+ let node;
41
+ for (const part of String(nodeId).split("-")) {
42
+ node = items?.[Number(part)];
43
+ items = node?.items;
44
+ }
45
+ return node;
46
+ }
47
+
48
+ /**
49
+ * A tree with more links than this starts with only the branch holding the current page
50
+ * open; the rest are one row each until expanded. A smaller tree opens every top-level
51
+ * group, as before.
52
+ */
53
+ export const EXPAND_ALL_LIMIT = 150;
54
+
55
+ const counts = new WeakMap();
56
+
57
+ /** How many links (`path` entries) `tree` holds. */
58
+ export function countLinks(tree) {
59
+ if (!Array.isArray(tree)) return 0;
60
+ let n = counts.get(tree);
61
+ if (n === undefined) {
62
+ n = 0;
63
+ for (const item of tree) n += (item.path ? 1 : 0) + countLinks(item.items);
64
+ counts.set(tree, n);
65
+ }
66
+ return n;
67
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@opentf/afw-docs",
3
- "version": "0.39.0",
3
+ "version": "0.40.0",
4
4
  "description": "Documentation and blog sites built as ordinary AFW apps.",
5
5
  "type": "module",
6
6
  "scripts": {
@@ -69,19 +69,19 @@
69
69
  "bugs": "https://github.com/Open-Tech-Foundation/afw/issues",
70
70
  "license": "MIT",
71
71
  "peerDependencies": {
72
- "@opentf/afw": "0.40.0"
72
+ "@opentf/afw": "0.41.0"
73
73
  },
74
74
  "publishConfig": {
75
75
  "access": "public"
76
76
  },
77
77
  "dependencies": {
78
- "@opentf/afw-compiler": "0.27.0",
78
+ "@opentf/afw-compiler": "0.28.0",
79
79
  "@opentf/syntax-highlighter": "0.5.0"
80
80
  },
81
81
  "devDependencies": {
82
- "@opentf/afw": "0.40.0",
83
- "@opentf/afw-test": "1.36.0",
84
- "@opentf/vite-plugin-afw": "0.9.0",
82
+ "@opentf/afw": "0.41.0",
83
+ "@opentf/afw-test": "1.37.0",
84
+ "@opentf/vite-plugin-afw": "0.10.0",
85
85
  "vite": "8.3.5"
86
86
  },
87
87
  "types": "./types/index.d.ts"
package/search.js CHANGED
@@ -2,10 +2,12 @@
2
2
  /** @typedef {{ limit?: number, maxSectionsPerPage?: number, signal?: AbortSignal }} SearchOptions */
3
3
  /** @typedef {{ url: string, title: string, text: string, section: string, excerpt: string, highlights: number[][], meta: Record<string, string>, anchors: Array<{ id: string, text: string, pos: number }>, score: number }} SearchResult */
4
4
  const encoder = new TextEncoder();
5
- // Rust's String ordering is UTF-8 byte ordering, not locale collation.
5
+ // Rust's String ordering is UTF-8 byte ordering, not locale collation. Takes strings or
6
+ // already-encoded bytes (the chunk boundaries are encoded once, not on every comparison).
6
7
  function compare(a, b) {
7
- const x = encoder.encode(a), y = encoder.encode(b);
8
- for (let i = 0; i < Math.min(x.length, y.length); i++) if (x[i] !== y[i]) return x[i] - y[i];
8
+ const x = typeof a === "string" ? encoder.encode(a) : a, y = typeof b === "string" ? encoder.encode(b) : b;
9
+ const n = Math.min(x.length, y.length);
10
+ for (let i = 0; i < n; i++) if (x[i] !== y[i]) return x[i] - y[i];
9
11
  return x.length - y.length;
10
12
  }
11
13
  function cursor(bytes, position = 0) {
@@ -39,33 +41,87 @@ function decodeChunk(bytes) {
39
41
  rows.push([decoder.decode(term), input.read(), input.read()]);
40
42
  previous = term;
41
43
  }
42
- const postings = new Map(), blob = input.position;
43
- for (const [term, count, offset] of rows) {
44
- const list = [], input = cursor(bytes, blob + offset);
45
- let doc = 0;
46
- for (let i = 0; i < count; i++) {
47
- doc += input.read();
48
- const tf = input.read(), positions = [];
49
- let position = 0;
50
- for (let j = 0; j < tf; j++) {
51
- const packed = input.read();
52
- position += Math.floor(packed / 8);
53
- positions.push([position, packed % 8]);
54
- }
55
- list.push([doc, tf, positions]);
44
+ // Only the term table is read now. A term's postings are decoded the first time it is
45
+ // looked up: a query reads a few terms of the 750 in a chunk.
46
+ const table = new Map(), blob = input.position;
47
+ for (const [term, count, offset] of rows) table.set(term, { count, offset, list: null });
48
+ return {
49
+ terms: () => table.keys(),
50
+ df: (term) => table.get(term)?.count ?? 0,
51
+ get(term) {
52
+ const row = table.get(term);
53
+ if (!row) return undefined;
54
+ if (!row.list) row.list = decodePostings(bytes, blob + row.offset, row.count);
55
+ return row.list;
56
+ },
57
+ };
58
+ }
59
+ function decodePostings(bytes, offset, count) {
60
+ const list = [], input = cursor(bytes, offset);
61
+ let doc = 0;
62
+ for (let i = 0; i < count; i++) {
63
+ doc += input.read();
64
+ const tf = input.read(), positions = [];
65
+ let position = 0;
66
+ for (let j = 0; j < tf; j++) {
67
+ const packed = input.read();
68
+ position += Math.floor(packed / 8);
69
+ positions.push([position, packed % 8]);
70
+ }
71
+ list.push([doc, tf, positions]);
72
+ }
73
+ return list;
74
+ }
75
+ // The tokenizer: the same rules as the Rust writer (crates/afw_cli docs_indexing.rs
76
+ // `word_groups`), checked against search/tokenizer-vectors.json on both sides.
77
+ const WORD = /[\p{L}\p{N}\p{M}_.-]+/gu;
78
+ const MAX_TERM_BYTES = 64;
79
+ const EDGE = /^[.-]+|[.-]+$/g;
80
+ // Characters written without spaces between words (Han, Hiragana, Katakana), by code
81
+ // point as in Rust, so the two never disagree on a Unicode version.
82
+ const isCJK = (cp) => (cp >= 0x3005 && cp <= 0x3007) || cp === 0x303b || (cp >= 0x3041 && cp <= 0x30ff) ||
83
+ (cp >= 0x31f0 && cp <= 0x31ff) || (cp >= 0x3400 && cp <= 0x4dbf) || (cp >= 0x4e00 && cp <= 0x9fff) ||
84
+ (cp >= 0xf900 && cp <= 0xfaff) || (cp >= 0x20000 && cp <= 0x3134f);
85
+ // A spaced word's alternatives: lowercase, accent-folded, identifier parts (camelCase,
86
+ // acronyms, `_`, `-`, `.`), none longer than 64 UTF-8 bytes.
87
+ function latinGroup(normalized) {
88
+ const whole = normalized.toLowerCase();
89
+ if (!/[\p{L}\p{N}]/u.test(whole)) return null;
90
+ const folded = whole.normalize("NFD").replace(/\p{M}/gu, "");
91
+ const parts = normalized.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/([A-Z])(?=[A-Z][a-z])/g, "$1 ")
92
+ .split(/[_.\-\s]+/).filter(Boolean).map((part) => part.toLowerCase());
93
+ const group = [...new Set([whole, folded, ...parts])].filter((term) => encoder.encode(term).length <= MAX_TERM_BYTES);
94
+ return group.length ? group : null;
95
+ }
96
+ // One word's groups: one group of alternatives, or, for a run of CJK characters (no
97
+ // spaces to split on), one group per overlapping pair of characters, all required.
98
+ function groupsOf(word) {
99
+ const trimmed = word.replace(EDGE, "");
100
+ if (!trimmed) return [];
101
+ const groups = [];
102
+ let run = "", runIsCJK = false;
103
+ const flush = () => {
104
+ if (!run) return;
105
+ if (runIsCJK) {
106
+ const chars = [...run];
107
+ if (chars.length === 1) groups.push([run]);
108
+ else for (let i = 0; i + 1 < chars.length; i++) groups.push([chars[i] + chars[i + 1]]);
109
+ } else {
110
+ const group = latinGroup(run.replace(EDGE, ""));
111
+ if (group) groups.push(group);
56
112
  }
57
- postings.set(term, list);
113
+ run = "";
114
+ };
115
+ for (const ch of trimmed.normalize("NFKC")) {
116
+ const cjk = isCJK(ch.codePointAt(0));
117
+ if (cjk !== runIsCJK) { flush(); runIsCJK = cjk; }
118
+ run += ch;
58
119
  }
59
- return postings;
120
+ flush();
121
+ return groups;
60
122
  }
61
123
  function wordGroups(text) {
62
- return (text.match(/[\p{L}\p{N}\p{M}_.-]+/gu) || []).map((word) => {
63
- const normalized = word.normalize("NFKC"), whole = normalized.toLowerCase();
64
- if (!/[\p{L}\p{N}]/u.test(whole)) return [];
65
- const folded = whole.normalize("NFD").replace(/\p{M}/gu, "");
66
- const parts = normalized.replace(/([a-z])([A-Z])/g, "$1 $2").split(/[_.\-\s]+/).filter(Boolean).map((part) => part.toLowerCase());
67
- return [...new Set([whole, folded, ...parts])];
68
- }).filter((group) => group.length);
124
+ return (text.match(WORD) || []).flatMap(groupsOf);
69
125
  }
70
126
  export function tokenize(text) {
71
127
  return [...new Set(wordGroups(text).flat())];
@@ -99,7 +155,7 @@ function excerptFor(fragment, groups, match) {
99
155
  // Highlight complete visible words; normalization handles accents and identifiers
100
156
  // without using normalized string offsets against the original display text.
101
157
  for (const word of excerpt.matchAll(/[\p{L}\p{N}\p{M}_.-]+/gu)) {
102
- const variants = wordGroups(word[0])[0] || [];
158
+ const variants = wordGroups(word[0]).flat();
103
159
  if (groups.some((group) => variants.some((variant) => variant.startsWith(group[0]) ||
104
160
  variant.startsWith(group[0].normalize("NFD").replace(/\p{M}/gu, ""))))) {
105
161
  highlights.push([word.index, word.index + word[0].length]);
@@ -156,13 +212,16 @@ export function createSearch({ base = "/_search/" } = {}) {
156
212
  const root = base.replace(/\/$/, "");
157
213
  let initialized;
158
214
  const chunkCache = new Map();
215
+ // Fragments are immutable within a generation (its directory is content-hashed), so a
216
+ // page's fragment is fetched once, not again on every keystroke.
217
+ const fragmentCache = new Map();
159
218
  const throwIfAborted = (signal) => {
160
219
  if (signal?.aborted) throw new DOMException("Search query aborted", "AbortError");
161
220
  };
162
221
  const fetchIndex = async (path, options) => {
163
222
  const response = await fetch(`${root}/${path}`, options);
164
223
  if (!response.ok) {
165
- if (response.status === 404 && path !== "manifest.json") { initialized = undefined; chunkCache.clear(); }
224
+ if (response.status === 404 && path !== "manifest.json") { initialized = undefined; chunkCache.clear(); fragmentCache.clear(); }
166
225
  throw new Error(`Search index unavailable (${response.status})`);
167
226
  }
168
227
  return response;
@@ -171,8 +230,9 @@ export function createSearch({ base = "/_search/" } = {}) {
171
230
  const manifest = await (await fetchIndex("manifest.json", { cache: "no-cache" })).json();
172
231
  if (manifest.v !== undefined && manifest.v !== 1) throw new Error("Unsupported search index version");
173
232
  if (!Array.isArray(manifest.chunks) || !manifest.docsFile) throw new Error("Invalid search manifest");
233
+ for (const chunk of manifest.chunks) chunk.firstBytes = encoder.encode(chunk.first);
174
234
  for (let i = 1; i < manifest.chunks.length; i++) {
175
- if (compare(manifest.chunks[i - 1].first, manifest.chunks[i].first) >= 0) throw new Error("Unsorted search shards");
235
+ if (compare(manifest.chunks[i - 1].firstBytes, manifest.chunks[i].firstBytes) >= 0) throw new Error("Unsorted search shards");
176
236
  }
177
237
  const bytes = new Uint8Array(await (await fetchIndex(manifest.docsFile)).arrayBuffer());
178
238
  const input = cursor(bytes), lengths = [];
@@ -187,10 +247,11 @@ export function createSearch({ base = "/_search/" } = {}) {
187
247
  return chunkCache.get(file);
188
248
  };
189
249
  const findChunk = (chunks, term) => {
250
+ const bytes = encoder.encode(term);
190
251
  let low = 0, high = chunks.length - 1, answer = 0;
191
252
  while (low <= high) {
192
253
  const mid = (low + high) >>> 1;
193
- if (compare(chunks[mid].first, term) <= 0) { answer = mid; low = mid + 1; }
254
+ if (compare(chunks[mid].firstBytes, bytes) <= 0) { answer = mid; low = mid + 1; }
194
255
  else high = mid - 1;
195
256
  }
196
257
  return answer;
@@ -213,22 +274,29 @@ export function createSearch({ base = "/_search/" } = {}) {
213
274
  for (let i = index + 1; i < chunks.length && chunks[i].first.startsWith(word); i++) selected.add(chunks[i].file);
214
275
  }
215
276
  }));
216
- const postings = new Map();
217
- for (const shard of await Promise.all([...selected].map(loadChunk))) for (const [term, list] of shard) postings.set(term, list);
277
+ const shards = await Promise.all([...selected].map(loadChunk));
218
278
  throwIfAborted(signal);
219
279
  const scores = new Map(), matches = new Map(), locations = new Map(), matchedPositions = new Map();
220
280
  const totalDocs = state.lengths.length, avgdl = state.manifest.avgdl || 1;
221
281
  const fieldWeights = [8, 5, 4, 2.5, 3, 2, 1, 0.5];
222
282
  groups.forEach((group, groupIndex) => {
223
283
  const best = new Map();
224
- const candidates = [...postings].filter(([term]) => group.some((word) => term === word ||
225
- (groupIndex === groups.length - 1 && term.startsWith(word))))
226
- .sort((a, b) => Number(group.includes(b[0])) - Number(group.includes(a[0])) || a[1].length - b[1].length || compare(a[0], b[0])).slice(0, 32);
284
+ // Matching terms by name and document frequency; postings are decoded only for the
285
+ // 32 kept.
286
+ const matched = new Map();
287
+ for (const shard of shards) for (const term of shard.terms()) {
288
+ if (!matched.has(term) && group.some((word) => term === word || (groupIndex === groups.length - 1 && term.startsWith(word)))) {
289
+ matched.set(term, shard);
290
+ }
291
+ }
292
+ const candidates = [...matched].sort(([a, sa], [b, sb]) => Number(group.includes(b)) - Number(group.includes(a)) ||
293
+ sa.df(a) - sb.df(b) || compare(a, b)).slice(0, 32).map(([term, shard]) => [term, shard.get(term)]);
227
294
  for (const [term, list] of candidates) {
228
295
  const idf = Math.log(1 + (totalDocs - list.length + 0.5) / (list.length + 0.5));
229
296
  for (const [doc, tf, positions] of list) {
230
297
  if (doc >= totalDocs || !tf) throw new Error("Invalid search posting");
231
- const weight = Math.max(...positions.map(([, field]) => fieldWeights[field]));
298
+ let weight = 0;
299
+ for (const [, field] of positions) if (fieldWeights[field] > weight) weight = fieldWeights[field];
232
300
  const exact = term === group[0] ? 4 : group.includes(term) ? 0.75 : 0.5;
233
301
  const score = exact * weight * idf * (tf * 2.2) / (tf + 1.2 * (0.25 + 0.75 * state.lengths[doc] / avgdl));
234
302
  const previous = best.get(doc);
@@ -263,7 +331,13 @@ export function createSearch({ base = "/_search/" } = {}) {
263
331
  const top = ranked.sort((a, b) => b[1] - a[1] || a[0] - b[0]).slice(0, resultLimit);
264
332
  throwIfAborted(signal);
265
333
  const pages = await Promise.all(top.map(async ([doc, score]) => {
266
- const fragment = await (await fetchIndex(`${state.manifest.fragmentsDir || "f"}/${doc}.json`, { signal })).json();
334
+ const path = `${state.manifest.fragmentsDir || "f"}/${doc}.json`;
335
+ if (!fragmentCache.has(path)) {
336
+ // Shared by every query that needs the page, so no one query's signal aborts it.
337
+ fragmentCache.set(path, fetchIndex(path).then((response) => response.json())
338
+ .catch((error) => { fragmentCache.delete(path); throw error; }));
339
+ }
340
+ const fragment = await fragmentCache.get(path);
267
341
  return sectionMatches(fragment, matchedPositions.get(doc) || [], fieldWeights).slice(0, sectionLimit).map(match => {
268
342
  const url = match.anchor ? `${fragment.url.split("#")[0]}#${encodeURIComponent(match.anchor.id)}` : fragment.url;
269
343
  return { ...fragment, url, section: match.anchor?.text || "", ...excerptFor(fragment, groups, match), score };
package/theme/index.css CHANGED
@@ -1039,12 +1039,12 @@
1039
1039
  .afwd-sidebar-link:hover .afwd-sidebar-dot {
1040
1040
  opacity: 0.6;
1041
1041
  }
1042
- .afwd-sidebar-link.afwd-active {
1042
+ .afwd-sidebar-link[aria-current="page"] {
1043
1043
  color: var(--afw-accent-text);
1044
1044
  background: var(--afw-accent-soft);
1045
1045
  font-weight: 600;
1046
1046
  }
1047
- .afwd-sidebar-link.afwd-active .afwd-sidebar-dot {
1047
+ .afwd-sidebar-link[aria-current="page"] .afwd-sidebar-dot {
1048
1048
  opacity: 1;
1049
1049
  }
1050
1050