@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.
- package/build/last-updated-plugin.js +6 -2
- package/build/last-updated.js +28 -3
- package/components/Breadcrumbs.jsx +3 -1
- package/components/DocsLayout.jsx +10 -25
- package/components/Pagination.jsx +3 -1
- package/components/Sidebar.jsx +39 -5
- package/components/SidebarNode.jsx +30 -17
- package/components/Tabs.jsx +7 -2
- package/components/nav-source.js +67 -0
- package/package.json +6 -6
- package/search.js +111 -37
- package/theme/index.css +2 -2
|
@@ -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("/");
|
package/build/last-updated.js
CHANGED
|
@@ -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
|
|
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`,
|
|
11
|
-
//
|
|
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.
|
|
40
|
-
//
|
|
41
|
-
//
|
|
42
|
-
// its
|
|
43
|
-
|
|
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) => {
|
package/components/Sidebar.jsx
CHANGED
|
@@ -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
|
|
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
|
|
4
|
-
//
|
|
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 {
|
|
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
|
-
<
|
|
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
|
-
</
|
|
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
|
-
<
|
|
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
|
-
</
|
|
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
|
|
150
|
+
<SidebarNode item={given ? child : undefined} nodeId={`${nodeId}-${i}`} />
|
|
138
151
|
))}
|
|
139
152
|
</ul>
|
|
140
153
|
) : null}
|
package/components/Tabs.jsx
CHANGED
|
@@ -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=
|
|
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.
|
|
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.
|
|
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.
|
|
78
|
+
"@opentf/afw-compiler": "0.28.0",
|
|
79
79
|
"@opentf/syntax-highlighter": "0.5.0"
|
|
80
80
|
},
|
|
81
81
|
"devDependencies": {
|
|
82
|
-
"@opentf/afw": "0.
|
|
83
|
-
"@opentf/afw-test": "1.
|
|
84
|
-
"@opentf/vite-plugin-afw": "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
|
-
|
|
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
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
-
|
|
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
|
-
|
|
120
|
+
flush();
|
|
121
|
+
return groups;
|
|
60
122
|
}
|
|
61
123
|
function wordGroups(text) {
|
|
62
|
-
return (text.match(
|
|
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])
|
|
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].
|
|
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].
|
|
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
|
|
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
|
-
|
|
225
|
-
|
|
226
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
1047
|
+
.afwd-sidebar-link[aria-current="page"] .afwd-sidebar-dot {
|
|
1048
1048
|
opacity: 1;
|
|
1049
1049
|
}
|
|
1050
1050
|
|