@waveso/docs 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,186 @@
 # @waveso/docs
 
+## 0.9.1
+
+### Patch Changes
+
+- 80d3db4: The sidebar's handle and the search shortcut stop competing with the page.
+
+  **The handle is 16 × 56 and faded.** It was 20 × 80 at full strength — a solid
+  slab beside the reading column, for a control nobody looks at while reading. It
+  now sits at 40% until a pointer or a caret reaches it, the same treatment as the
+  tree's markers.
+
+  ⚠️ BOTH MARKS FADE, NOT THE PILL ALONE. Fading `::before` by itself leaves crisp
+  dots on a washed-out slab, which reads louder than the solid grip it replaced.
+
+  ⚠️ AND NOT ON THE `<button>`, which would take the focus ring down with it —
+  `opacity` applies to the whole element, outline included, so a keyboard reader
+  would get a 40% indicator on the control they had just moved to. It is on the
+  two pseudo-elements, and `:focus-visible` restores both.
+
+  ⚠️ THE TAP TARGET IS UNCHANGED BY ANY OF IT. The button is the whole strip and
+  runs the height of the column; the pill is paint. At 16px plus 4px of padding a
+  side the strip is 24px wide — WCAG 2.5.8's minimum to the pixel, and a test now
+  says so, because the next narrowing is the one that fails it.
+
+  ⚠️ THE DOTS DO NOT SCALE WITH THE PILL. They are `box-shadow` offsets on one
+  element, so they span 18px whatever the pill does. Found by shortening it to
+  16px tall and watching the outer two render outside it.
+
+  **`⌘K` is levelled with `Search`.** Equal `font-size` in two families is not
+  equal type: the label is `ui-sans-serif` and the badge `ui-monospace`, which
+  draws 0.7292px of cap per px. `1.012em` is what puts the `K`'s cap on the `S`'s.
+
+  ⚠️ AND THE SYMBOL IS `1.369em`, THE MEASURED INK RATIO — NOT A HAIR MORE. At
+  `1.45em` the `⌘` stood 6% above the cap line, and the badge read as _bigger
+  type_ than the label: 88 device px of ink against the word's 85, its top three
+  higher, its centre 1.5 out. Same letter height, louder cluster. At the ratio,
+  `Search` and `⌘K` measure 85 and 85 and share a centre to the device pixel.
+
+  ⚠️ AND `line-height: 0` ON THE SYMBOL, WHICH IS WHAT MADE THE TWO CENTRE. A line
+  box is as tall as the tallest inline box in it, so the 20.5px glyph made the
+  `<kbd>` 20.55px against the label's 17 — and flex centres them by their _boxes_,
+  so the `K` rode 1.9px high inside a box the symbol had stretched.
+
+  Also fixed: the focus-indicator test looked its selectors up with `indexOf`, so
+  `…:focus-visible` matched inside `…:focus-visible::before` — a different rule,
+  about pseudo-elements, with no business declaring an outline. It reported the
+  trigger as having no focus indicator while the trigger's own rule sat further
+  down the file declaring one.
+
+- 27f63ec: Sidebar separators keep the case their author wrote them in.
+
+  ⚠️ `text-transform: uppercase` ON A STRING THIS PACKAGE DOES NOT OWN. A
+  separator's text comes from a consumer's `meta.json` — `"---Reference---"` —
+  and restyling it is this package rewriting words in a language it cannot read.
+  Portuguese `Referência` shipped as `REFERÊNCIA`. Turkish trades its dotted and
+  dotless `i` for each other under a naive uppercase. No CJK script has a case to
+  transform at all, so those authors got the `letter-spacing` and none of the
+  effect it existed to rescue.
+
+  The string was already a prop. Its shape was not, and there was no way to turn
+  this off short of overriding the rule.
+
+  Reading as a divider rather than as another row is done by size, weight and a
+  subtle colour — none of which touch a character. `letter-spacing` goes with the
+  caps: it is there to make uppercase legible, and on sentence case it only reads
+  as loose.
+
+## 0.9.0
+
+### Minor Changes
+
+- 216f2df: **The search dialog says how to drive it.** A magnifier on the trigger and in
+  the input, and a footer carrying `↑` `↓` Select · `↵` Open · `Esc` Close.
+
+  ⚠️ AND IT DELETES A BUTTON THAT SAID `Close` IN HARDCODED ENGLISH. Every other
+  user-facing string in this package had been lifted to a prop; that one was
+  missed, in the one dialog a reader cannot leave without it — so a Portuguese
+  site rendered a Portuguese dialog with an English way out. It is `closeLabel`
+  now, alongside `selectLabel` and `openLabel`.
+
+  The key-caps beside them are glyphs and stay untranslated: an arrow is an
+  arrow, and `Esc` is `Esc` on a Portuguese keyboard. The props are the verbs,
+  which are not.
+
+  ⚠️ THE DISMISS CONTROL IS A BUTTON, NOT A THIRD HINT. Under `(hover: none) and
+(pointer: coarse)` the two hints are hidden — on the same reasoning as the
+  trigger's `⌘K`, that an instruction to press a key is one a reader on a phone
+  cannot follow — and that leaves this as the only pointer route out of the
+  dialog. It is not hidden with them.
+
+  ⚠️ IT ALSO MOVED PAST THE RESULTS. The button it replaces sat in the input row,
+  so one Tab from the query landed on _Close_ rather than on the first result —
+  past every answer the reader had just asked for. Document order is tab order
+  here, and a test now holds it.
+
+  The hints are `aria-hidden`: they describe the pointer-free path through a
+  listbox that a screen reader already exposes through `role`,
+  `aria-activedescendant` and `aria-posinset`, so announcing them adds two lines
+  of symbols and no information. The magnifiers are hidden for the reason the
+  trigger's own label is pinned — named from content, that button once announced
+  as "Search Ctrl K".
+
+  Published sizes rise with it: the quick start's total 14 → 14.3 KB, the search
+  dialog 9.3 → 9.5 KB. Budgets raised in `size-budget.json` with the reason.
+
+  ⚠️ AND THE TRIGGER NOW SHARES A COLUMN WITH THE TREE. It sits directly above
+  the navigation, so its magnifier is the first thing in the same column as every
+  folder and page marker below it and its label starts the same column as every
+  title — and both were out, measured at 1280px by 3px and 11px. The trigger was
+  spaced as a standalone control: 10px of inline padding against the rows' 8px,
+  and a 16px gap against their 8px. It carries a 1px border the rows do not, so
+  the fix is `calc(0.5rem - 1px)` rather than `0.5rem` — matching the number
+  instead of the content edge leaves it 1px out and looks fixed in a screenshot.
+  A browser test measures both columns against the tree's.
+
+  ## The trigger's shortcut is plain text again
+
+  `⌘K` was a bordered chip inside a bordered, filled control — a chip on a chip,
+  sharing its fill, for a hint nobody clicks. It kept that border only because
+  the footer's key-caps were added to the same rule; the two are separate now,
+  and a test holds them apart. There was never a `background` on either: the
+  trigger's own `--wave-docs-bg-subtle` showed through, which is what made the
+  border read as a filled shape.
+
+  ⚠️ AND THE `⌘` IS ITS OWN ELEMENT, BECAUSE CSS CANNOT SELECT A CHARACTER.
+  Measured in the shipped mono stack at 12px, the glyph carries 6.39px of ink
+  against the `K`'s 8.75px — a third short of the letter beside it, in one string
+  at one size. `1.45em` on the symbol brings it to 9.26px — a hair
+  taller than the letter, which is what makes the two read as one mark. `Ctrl` is
+  gated out of that rule by an attribute: it is a word set in the same face as
+  the `K`, and scaling it makes the hint shout.
+
+  ⚠️ AND SIZE ALONE LEAVES IT FLOATING. `⌘` is drawn around the font's
+  mathematical axis rather than standing on the baseline like a capital, so at
+  that size its ink centre sits 2.24px above the `K`'s while inline layout aligns
+  the two by baseline. `vertical-align: -0.13em` drops it. Measured off a render
+  at 8x: both ink boxes centre on the same pixel, with the symbol 5% the taller.
+
+  New public class names: `.wave-docs-search-glyph`, `.wave-docs-search-footer`,
+  `.wave-docs-search-hint`, `.wave-docs-search-kbd`, `.wave-docs-search-trigger-mod`.
+  `.wave-docs-search-close` survives, restyled — it is a footer control now, not
+  a bordered button in the input row.
+
+### Patch Changes
+
+- 5647418: Sidebar groups stop collapsing behind the reader.
+
+  Expand three sections, click a page, and two of them shut. Or: open a section,
+  read a page in it, open another section, read a page in _that_ — and the first
+  one closes. Both reported from real use, and both the same defect.
+
+  ⚠️ THE CAUSE WAS `setToggled({})` ON EVERY NAVIGATION. The reader's own state
+  and the route's default share one map — `toggled[key] ?? hasActive` — so
+  clearing it does not "reset the tree to its default" in any useful sense. The
+  default is _open only what holds the current page_, so wiping the map collapses
+  everything the reader had deliberately opened.
+
+  Navigation now opens whatever holds the page just arrived at, and closes
+  nothing. A group closes when the reader closes it.
+
+  ⚠️ AND IT RECORDS `true` RATHER THAN DELETING THE KEY, WHICH IS THE HALF THAT
+  IS EASY TO GET WRONG. Deleting also reopens the group — it falls back to
+  `hasActive` — and looks correct for exactly one navigation. Read a page in one
+  section, then a page in another, and the first section has no entry left and no
+  longer holds the route, so it shuts. That is the second report, reproduced by
+  the obvious fix.
+
+  The state is also seeded from the first route rather than starting empty, so a
+  group open at first paint is open by _record_ rather than by inference. Without
+  it, landing on a deep page from a search result and clicking away collapses the
+  section you arrived in, while one you had opened by hand would have stayed.
+
+  Kept from the old reset: a group collapsed an hour ago must not hide the page
+  just navigated to. It is reopened explicitly.
+
+  It costs 60 gzipped bytes on the sidebar bundle — a walk that names the groups
+  holding the current route. The line it replaces cost nothing, which is the
+  point: the cheapest possible reset was also the one that threw away everything
+  the reader had opened. Published sizes rise with it: the quick start's total
+  14.3 → 14.5 KB, the navigation 3 → 3.1 KB.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -69,16 +69,16 @@ Every figure below is a **ceiling**, and `pnpm size` fails the build if the meas
 
 | | At most |
 | --- | --- |
-| Everything the quick start ships, gzipped | 14 KB |
-| Search dialog and router wiring | 9.3 KB |
-| Navigation: one sidebar, open and closed | 3 KB |
+| Everything the quick start ships, gzipped | 14.5 KB |
+| Search dialog and router wiring | 9.5 KB |
+| Navigation: one sidebar, open and closed | 3.1 KB |
 | Table of contents | 0.9 KB |
 | Copy-button runtime | 1.1 KB |
 | hast over the wire vs HTML, prose page | 1.20× |
 | hast over the wire vs HTML, code and tables | 1.12× |
 | Highlighting vs no highlighting | 2.00× |
 
-The first row is the honest total: a reader who lands on a page of your documentation downloads under 14 KB gzipped of JavaScript from this package, and that is the whole of it. No markdown parser and no syntax highlighter reach the browser at all — those run in Node at build time. Drop the search dialog and it is under 4 KB.
+The first row is the honest total: a reader who lands on a page of your documentation downloads under 14.5 KB gzipped of JavaScript from this package, and that is the whole of it. No markdown parser and no syntax highlighter reach the browser at all — those run in Node at build time. Drop the search dialog and it is under 4 KB.
 
 The one real cost is the middle pair: shipping a tree instead of a string is about 20% more brotli on a prose page, and about 12% on a page with code and tables, where Shiki's token spans dominate both representations equally. That is the price of never handing markup to `dangerouslySetInnerHTML`, and it is the first number a skeptical reviewer should ask for.
 
@@ -755,10 +755,17 @@ If your site sets Next's own `basePath` config, prefix `indexUrl` yourself: Next
 | `loadingLabel` | `string` | `'Loading the search index…'` | While the index is fetched |
 | `errorLabel` | `string` | `'Search is unavailable right now. Try reloading the page.'` | When it cannot be |
 | `emptyLabel` | `string` | `'No results for “{query}”.'` | No matches. `{query}` is what was typed |
+| `selectLabel` | `string` | `'Select'` | Footer hint beside `↑` `↓` |
+| `openLabel` | `string` | `'Open'` | Footer hint beside `↵` |
+| `closeLabel` | `string` | `'Close'` | The footer's dismiss button, beside `Esc` |
 | `resultCountLabels` | `Partial<Record<Intl.LDMLPluralRule, string>>` | `{ one: '{count} result', other: '{count} results' }` | The live region, by plural category |
 | `locale` | `string` | `<html lang>`, then `'en'` | Language tag for those plural rules |
 | `miniSearchOptions` | `Partial<Options<SearchRecord>>` | — | See [Tuning](#tuning) |
 
+The dialog's footer carries the three keyboard hints and the dismiss control. The key-caps beside them — `↑` `↓` `↵` `Esc` — are glyphs and are not translatable; the three props above are the verbs, which are.
+
+Under `(hover: none) and (pointer: coarse)` the two hints are hidden, on the same reasoning as the trigger's `⌘K`: an instruction to press a key is one a reader on a phone cannot follow. `closeLabel`'s button is deliberately not hidden with them — on exactly those devices it is the only pointer route out of the dialog.
+
 **`pageSize` replaced `maxResults` in 0.4.0**, and the meaning changed with the name: `maxResults` was a hard ceiling of 8 that made results unreachable on a six-page site, and the live region announced the slice as though it were the total. `pageSize` is a window — every match is reachable by scrolling, and the count announced is the real one.
 
 `resultCountLabels` is keyed by plural category rather than being a singular and a plural, because most languages are not English: Polish takes four forms and Arabic six. `Intl.PluralRules` picks, and a category you do not list falls back to `other`.

package/dist/react/search-dialog.d.ts

@@ -95,6 +95,29 @@ interface SearchDialogProps {
    * `{query}` is replaced with what the reader typed.
    */
   emptyLabel?: string | undefined;
+  /**
+   * The arrow-keys hint in the footer. Defaults to `'Select'`.
+   *
+   * The key-caps beside it are glyphs and are not translatable — an arrow is an
+   * arrow, and `Esc` is `Esc` on a Portuguese keyboard. These props are the
+   * verbs, which are not.
+   */
+  selectLabel?: string | undefined;
+  /** The Enter hint in the footer. Defaults to `'Open'`. */
+  openLabel?: string | undefined;
+  /**
+   * The footer's dismiss control. Defaults to `'Close'`.
+   *
+   * ⚠️ THIS REPLACES A BUTTON THAT SAID `Close` IN HARDCODED ENGLISH — the one
+   * string in this package that was never lifted to a prop, in the one dialog a
+   * reader cannot leave without it.
+   *
+   * It names a real button rather than a third hint: under `pointer: coarse`
+   * the two hints beside it are hidden, because an instruction to press Esc is
+   * one a reader on a phone cannot follow — and that leaves this as the only
+   * pointer route out of the dialog.
+   */
+  closeLabel?: string | undefined;
   /**
    * The live region's announcement, by plural category. `{count}` is the total.
    *
@@ -151,6 +174,6 @@ interface SearchDialogProps {
  * portalled to `document.body`, so a navbar's stacking context cannot trap
  * it behind the page.
  */
-declare function SearchDialog({ indexUrl, navigate, Link, triggerLabel, placeholder, dialogLabel, pageSize, minQueryLength, debounceMs, className, miniSearchOptions, hintLabel, shortQueryLabel, loadingLabel, errorLabel, emptyLabel, resultCountLabels, locale }: SearchDialogProps): ReactNode;
+declare function SearchDialog({ indexUrl, navigate, Link, triggerLabel, placeholder, dialogLabel, pageSize, minQueryLength, debounceMs, className, miniSearchOptions, hintLabel, shortQueryLabel, loadingLabel, errorLabel, emptyLabel, selectLabel, openLabel, closeLabel, resultCountLabels, locale }: SearchDialogProps): ReactNode;
 //#endregion
 export { SearchDialog, SearchDialogProps };

package/dist/react/search-dialog.js

@@ -26,7 +26,7 @@ const FOCUSABLE_SELECTOR = [
 * portalled to `document.body`, so a navbar's stacking context cannot trap
 * it behind the page.
 */
-function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", placeholder = "Search documentation", dialogLabel = "Search documentation", pageSize = 20, minQueryLength = 2, debounceMs = 120, className, miniSearchOptions, hintLabel, shortQueryLabel, loadingLabel, errorLabel, emptyLabel, resultCountLabels, locale }) {
+function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", placeholder = "Search documentation", dialogLabel = "Search documentation", pageSize = 20, minQueryLength = 2, debounceMs = 120, className, miniSearchOptions, hintLabel, shortQueryLabel, loadingLabel, errorLabel, emptyLabel, selectLabel = "Select", openLabel = "Open", closeLabel = "Close", resultCountLabels, locale }) {
 	const [isOpen, setIsOpen] = useState(false);
 	const [query, setQuery] = useState("");
 	const [hits, setHits] = useState([]);
@@ -53,7 +53,18 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 	const movedByKeyboard = useRef(false);
 	const [activeIndex, setActiveIndex] = useState(0);
 	const [status, setStatus] = useState("idle");
-	const [shortcutHint, setShortcutHint] = useState("");
+	/**
+	* The trigger's shortcut, split rather than held as one string.
+	*
+	* ⚠️ THE `⌘` NEEDS ITS OWN `font-size` AND CSS CANNOT SELECT A CHARACTER.
+	* Measured in the shipped mono stack at 12px, its ink is 6.39px tall against
+	* the `K`'s 8.75px — so as one string the symbol sits visibly short of the
+	* letter beside it. Two nodes is the only way to scale one and not the other.
+	*
+	* `null` until the effect below resolves the platform: reading it during
+	* render would disagree with the server's markup and break hydration.
+	*/
+	const [shortcut, setShortcut] = useState(null);
 	const dialogRef = useRef(null);
 	const triggerRef = useRef(null);
 	const inputRef = useRef(null);
@@ -126,7 +137,10 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 	}, [isOpen, closeDialog]);
 	useEffect(() => {
 		const isApple = /mac|iphone|ipad|ipod/i.test(navigator.userAgent);
-		setShortcutHint(isApple ? "⌘K" : "Ctrl K");
+		setShortcut({
+			modifier: isApple ? "⌘" : "Ctrl",
+			isSymbol: isApple
+		});
 	}, []);
 	useEffect(() => {
 		if (isOpen) {
@@ -267,13 +281,21 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 		onClick: openDialog,
 		onPointerEnter: warmIndex,
 		onFocus: warmIndex,
-		children: [/* @__PURE__ */ jsx("span", {
-			className: "wave-docs-search-trigger-label",
-			children: triggerLabel
-		}), shortcutHint === "" ? null : /* @__PURE__ */ jsx("kbd", {
-			className: "wave-docs-search-trigger-kbd",
-			children: shortcutHint
-		})]
+		children: [
+			/* @__PURE__ */ jsx(SearchGlyph, {}),
+			/* @__PURE__ */ jsx("span", {
+				className: "wave-docs-search-trigger-label",
+				children: triggerLabel
+			}),
+			shortcut === null ? null : /* @__PURE__ */ jsxs("kbd", {
+				className: "wave-docs-search-trigger-kbd",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "wave-docs-search-trigger-mod",
+					"data-symbol": shortcut.isSymbol ? "" : void 0,
+					children: shortcut.modifier
+				}), shortcut.isSymbol ? "K" : " K"]
+			})
+		]
 	}), isOpen ? createPortal(/* @__PURE__ */ jsx("div", {
 		className: "wave-docs-search-backdrop",
 		onMouseDown: (event) => {
@@ -288,7 +310,7 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 			children: [
 				/* @__PURE__ */ jsxs("div", {
 					className: "wave-docs-search-input-row",
-					children: [/* @__PURE__ */ jsx("input", {
+					children: [/* @__PURE__ */ jsx(SearchGlyph, {}), /* @__PURE__ */ jsx("input", {
 						ref: inputRef,
 						className: "wave-docs-search-input",
 						type: "text",
@@ -305,11 +327,6 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 						autoComplete: "off",
 						autoCorrect: "off",
 						spellCheck: false
-					}), /* @__PURE__ */ jsx("button", {
-						type: "button",
-						className: "wave-docs-search-close",
-						onClick: closeDialog,
-						children: "Close"
 					})]
 				}),
 				/* @__PURE__ */ jsx("div", {
@@ -346,11 +363,82 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 					},
 					resultCountLabels,
 					locale
+				}),
+				/* @__PURE__ */ jsxs("div", {
+					className: "wave-docs-search-footer",
+					children: [
+						/* @__PURE__ */ jsxs("span", {
+							className: "wave-docs-search-hint",
+							"aria-hidden": "true",
+							children: [
+								/* @__PURE__ */ jsx("kbd", {
+									className: "wave-docs-search-kbd",
+									children: "↑"
+								}),
+								/* @__PURE__ */ jsx("kbd", {
+									className: "wave-docs-search-kbd",
+									children: "↓"
+								}),
+								selectLabel
+							]
+						}),
+						/* @__PURE__ */ jsxs("span", {
+							className: "wave-docs-search-hint",
+							"aria-hidden": "true",
+							children: [/* @__PURE__ */ jsx("kbd", {
+								className: "wave-docs-search-kbd",
+								children: "↵"
+							}), openLabel]
+						}),
+						/* @__PURE__ */ jsxs("button", {
+							type: "button",
+							className: "wave-docs-search-close",
+							"aria-label": closeLabel,
+							"aria-keyshortcuts": "Escape",
+							onClick: closeDialog,
+							children: [/* @__PURE__ */ jsx("kbd", {
+								className: "wave-docs-search-kbd",
+								children: "Esc"
+							}), /* @__PURE__ */ jsx("span", { children: closeLabel })]
+						})
+					]
 				})
 			]
 		})
 	}), document.body) : null] });
 }
+/**
+* The magnifier, on the trigger and in the dialog's input row.
+*
+* Decorative in both places: the trigger carries its name in `aria-label` and
+* the input carries its own, so this glyph would only ever repeat a word that
+* is already there — announced as "search Search" and, on some engines, as the
+* name of the character.
+*
+* Inline SVG rather than a `::before` glyph, matching every other icon in this
+* package: generated content is announced by some screen-reader and browser
+* pairs, which is the one thing `aria-hidden` cannot take back.
+*/
+function SearchGlyph() {
+	return /* @__PURE__ */ jsxs("svg", {
+		className: "wave-docs-search-glyph",
+		"aria-hidden": "true",
+		focusable: "false",
+		viewBox: "0 0 24 24",
+		width: "16",
+		height: "16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		children: [/* @__PURE__ */ jsx("circle", {
+			cx: "11",
+			cy: "11",
+			r: "7"
+		}), /* @__PURE__ */ jsx("path", { d: "m20 20-3.5-3.5" })]
+	});
+}
 /** One result row: a real link, so middle-click and "open in new tab" work. */
 function SearchResultOption({ hit, id, isActive, setSize, posInSet, onActivate, onSelect, Link }) {
 	function handleClick(event) {

package/dist/react/sidebar.js

@@ -15,6 +15,24 @@ function normalizeHref(href) {
 function isActiveHref(pathname, href) {
 	return normalizeHref(pathname) === normalizeHref(href);
 }
+/**
+* `{ [key]: true }` for every group the active page lives inside, keyed the way
+* the tree renders — `${prefix}-${index}`, index counted over *all* siblings
+* because that is what `NavList` does.
+*
+* Shaped as the state itself rather than as a list of keys so both callers can
+* spread it: it seeds the map on mount and merges into it on every navigation,
+* and neither needs a loop of its own.
+*/
+function openAlong(nodes, pathname, prefix, into = {}) {
+	nodes.forEach((node, index) => {
+		if (node.type !== "group" || !containsActive(node, pathname)) return;
+		const key = `${prefix}-${index}`;
+		into[key] = true;
+		openAlong(node.children, pathname, key, into);
+	});
+	return into;
+}
 /** Whether the active page lives anywhere under this node. */
 function containsActive(node, pathname) {
 	switch (node.type) {
@@ -74,11 +92,14 @@ function DocsSidebar({ nav, pathname, Link, label = "Docs", expandGroup, collaps
 		externalLink: externalLink ?? DEFAULT_SIDEBAR_LABELS.externalLink
 	};
 	const baseId = useId();
-	const [toggled, setToggled] = useState({});
+	const [toggled, setToggled] = useState(() => openAlong(nav, pathname, baseId));
 	const lastPathname = useRef(pathname);
 	if (lastPathname.current !== pathname) {
 		lastPathname.current = pathname;
-		setToggled({});
+		setToggled((previous) => ({
+			...previous,
+			...openAlong(nav, pathname, baseId)
+		}));
 	}
 	const handleToggle = (key, isOpen) => {
 		setToggled((previous) => ({

package/dist/styles.css

@@ -153,7 +153,7 @@
      * of padding on every side — so setting this is the whole of resizing the
      * control, and the hit area grows with it rather than being a second number
      * to keep in step. */
-    --wave-docs-trigger-width: 1.25rem;
+    --wave-docs-trigger-width: 1rem;
     --wave-docs-toc-width: 15rem;
 
     /*
@@ -1768,14 +1768,28 @@
     margin-block: 1rem 0.25rem;
   }
 
+  /*
+   * ⚠️ NO `text-transform: uppercase`, AND IT USED TO HAVE ONE.
+   *
+   * A separator's text is authored — `"---Reference---"` in someone's
+   * `meta.json` — so uppercasing it is this package rewriting words it does not
+   * own, in a language it cannot read. Portuguese `Referência` came out as
+   * `REFERÊNCIA`; Turkish loses the dotted and dotless `i` to each other, and
+   * no CJK script has a case to transform at all, so those authors got the
+   * `letter-spacing` and none of the effect it was there to rescue. And it
+   * could not be turned off — the string is a prop, but its shape was ours.
+   *
+   * The job the caps were doing — read as a divider, not as a row — is already
+   * done by the size, the weight and the subtle colour, none of which touch a
+   * single character. `letter-spacing` went with them: it exists to make caps
+   * legible, and on sentence case it only reads as loose.
+   */
   .wave-docs-sidebar__separator {
     display: block;
     padding-inline: 0.5rem;
     color: var(--wave-docs-fg-subtle);
     font-size: 0.75rem;
     font-weight: 650;
-    letter-spacing: 0.06em;
-    text-transform: uppercase;
   }
 
   @media (prefers-reduced-motion: no-preference) {
@@ -2607,7 +2621,12 @@
   .wave-docs-layout__sidebar-trigger::before {
     content: '';
     width: var(--wave-docs-trigger-width);
-    height: 5rem;
+    /*
+     * 16 x 56 — a 3.5:1 grip. It was 20 x 80, which at the old width read as a
+     * slab; narrowing it made the length obvious. The floor is 18px, the span
+     * of the three dots, and nothing here scales with the pill: see `::after`.
+     */
+    height: 3.5rem;
     border-radius: var(--wave-docs-radius-sm);
     background-color: var(--wave-docs-border-strong);
   }
@@ -2631,11 +2650,46 @@
     translate: -50% -50%;
     border-radius: 50%;
     background: currentcolor;
+    /*
+     * ⚠️ THE DOTS DO NOT SCALE WITH THE PILL. They are `box-shadow` offsets on
+     * one element, so ±7px is 18px of ink whatever `--wave-docs-trigger-width`
+     * or the pill's height happen to be. Shorten the pill below 18px and the
+     * outer two sit outside it, top and bottom — measured, not guessed.
+     */
     box-shadow:
       0 -7px 0 currentcolor,
       0 7px 0 currentcolor;
   }
 
+  /*
+   * Faded at rest, full strength under a pointer or a caret — the same
+   * treatment as the tree's markers, and for the same reason: this is a handle,
+   * not a thing to look at while reading.
+   *
+   * ⚠️ BOTH MARKS, NOT THE PILL ALONE. Fading `::before` by itself leaves the
+   * dots at full strength on a washed-out slab, which reads louder than the
+   * solid grip it replaced — the opposite of the point.
+   *
+   * ⚠️ AND NOT ON THE BUTTON ITSELF, which would take the focus ring down with
+   * it: `opacity` applies to the whole element, outline included, so a keyboard
+   * reader would get a 40% indicator on a control they had just moved to.
+   *
+   * ⚠️ THE TAP TARGET IS UNTOUCHED BY ANY OF THIS. The `<button>` is the entire
+   * strip and runs the height of the column; the pill is paint. Its 80px was
+   * only ever ink, which is why 32px costs nothing a finger can feel.
+   */
+  .wave-docs-layout__sidebar-trigger::before,
+  .wave-docs-layout__sidebar-trigger::after {
+    opacity: 0.4;
+  }
+
+  .wave-docs-layout__sidebar-trigger:hover::before,
+  .wave-docs-layout__sidebar-trigger:hover::after,
+  .wave-docs-layout__sidebar-trigger:focus-visible::before,
+  .wave-docs-layout__sidebar-trigger:focus-visible::after {
+    opacity: 1;
+  }
+
   /*
    * ⚠️ THE STRIP'S HOVER LIGHTS THE BUTTON TOO, AND THAT IS WHAT MAKES IT ONE
    * CONTROL. Hovering 44px of strip while the button inside it stays grey reads
@@ -2667,7 +2721,8 @@
        */
       transition:
         background-color 120ms ease-out,
-        color 120ms ease-out;
+        color 120ms ease-out,
+        opacity 120ms ease-out;
     }
   }
 
@@ -2823,14 +2878,30 @@
  * ------------------------------------------------------------------------ */
 
 @layer components {
+  /*
+   * ⚠️ THE INLINE PADDING AND THE GAP ARE THE NAVIGATION'S, NOT THIS BUTTON'S,
+   * AND THE `- 1px` IS THE WHOLE REASON THEY LOOK THE SAME.
+   *
+   * The trigger sits directly above the tree, so its magnifier is the first
+   * thing in the same column as every folder and page marker below it, and its
+   * label starts the same column as every title. Both were off — measured at
+   * 1280px, the glyph by 3px and the label by 11px — because this button was
+   * spaced as a standalone control: 10px of padding against the rows' 8px, and
+   * a 16px gap against their 8px.
+   *
+   * The rows carry no border and this does, so matching `0.5rem` outright would
+   * leave the glyph 1px out. `calc(0.5rem - 1px)` puts the *content* edge where
+   * theirs is, which is the edge a reader sees. Block padding is untouched: it
+   * sets this control's height, and nothing below it is the same height.
+   */
   .wave-docs-search-trigger {
     display: flex;
     align-items: center;
     justify-content: space-between;
-    gap: 1rem;
+    gap: 0.5rem;
     width: 100%;
     max-width: 20rem;
-    padding: 0.4375rem 0.625rem;
+    padding: 0.4375rem calc(0.5rem - 1px);
     border: 1px solid var(--wave-docs-border);
     border-radius: var(--wave-docs-radius);
     background: var(--wave-docs-bg-subtle);
@@ -2871,14 +2942,26 @@
     outline-offset: 2px;
   }
 
-  /* The label is the flexible half of the trigger; the shortcut hint beside it
-   * must never be the thing that gets squeezed out at narrow widths. */
+  /* The label is the flexible half of the trigger; neither the magnifier before
+   * it nor the shortcut hint after it may be the thing squeezed out at narrow
+   * widths. `flex: 1 1 auto` because the row is `space-between` and three
+   * items would otherwise centre the middle one, leaving a gap on both sides of
+   * a short label. */
   .wave-docs-search-trigger-label {
+    flex: 1 1 auto;
+    min-width: 0;
     overflow: hidden;
     text-overflow: ellipsis;
     white-space: nowrap;
   }
 
+  /* Quieter than the words either side of it, in the trigger and in the dialog
+   * alike — it is a category marker, not a control. */
+  .wave-docs-search-glyph {
+    flex: none;
+    color: var(--wave-docs-fg-subtle);
+  }
+
   /*
    * ⚠️ HIDDEN WHERE THE SHORTCUT CANNOT BE PRESSED, WHICH IS NOT A WIDTH
    * QUESTION. `⌘K` is an instruction, and on a phone or a tablet it is one the
@@ -2891,16 +2974,105 @@
     }
   }
 
-  .wave-docs-search-trigger-kbd {
+  .wave-docs-search-trigger-kbd,
+  .wave-docs-search-kbd {
     flex: none;
-    padding: 0.05rem 0.35rem;
-    border: 1px solid var(--wave-docs-border-strong);
-    border-radius: var(--wave-docs-radius-sm);
     color: var(--wave-docs-fg-subtle);
     font-family: var(--wave-docs-font-mono);
     font-size: 0.75rem;
   }
 
+  /*
+   * The footer's caps are drawn as keys; the trigger's shortcut is not.
+   *
+   * They were one rule, and the trigger's read as a chip on a surface that is
+   * already a chip — a bordered box inside a bordered box, sharing its fill,
+   * for a hint nobody clicks. The footer's caps sit on the flat bottom of the
+   * dialog and are the only thing there that has to look pressable.
+   *
+   * No `background` was ever set on either: the trigger's own
+   * `--wave-docs-bg-subtle` showed through, which is what made the border read
+   * as a filled shape. Removing the border is what removes the shape.
+   */
+  .wave-docs-search-kbd {
+    padding: 0.05rem 0.35rem;
+    border: 1px solid var(--wave-docs-border-strong);
+    border-radius: var(--wave-docs-radius-sm);
+  }
+
+  /*
+   * ⚠️ THE LABEL'S SIZE, AND IT IS THE CAPS THAT HAD TO MATCH — NOT THE NUMBER.
+   *
+   * `Search` is `ui-sans-serif` and this is `ui-monospace`, and the same
+   * `font-size` in two families does not give you the same letter. Measured at
+   * 14px: the label's `S` carries 10.33px of ink and the mono `K` carries
+   * 10.21px. A tenth of a pixel — invisible until you look, and then it is the
+   * only thing you can see.
+   *
+   * `1.012em` is that tenth. Mono here draws 0.7292px of cap per px of
+   * `font-size`, so 10.33px of cap needs 14.17px, which is 1.012 x the 14px it
+   * sits beside. `em` rather than a `rem` constant so it tracks the label if
+   * the trigger's size ever moves.
+   *
+   * ⚠️ IT IS A MEASURED CONSTANT AND IT BELONGS TO THESE TWO FAMILIES. Change
+   * `--wave-docs-font-mono` or `--wave-docs-font-sans` and it is wrong — not
+   * broken, just quietly a tenth of a pixel out again. Re-measure the caps, do
+   * not re-derive from the declaration.
+   *
+   * Not in the shared rule above: the footer's caps sit in a 12px footer and
+   * belong at 12px. This is the only `<kbd>` standing beside body-sized text.
+   */
+  .wave-docs-search-trigger-kbd {
+    font-size: 1.012em;
+  }
+
+  /*
+   * ⚠️ THE SYMBOL IS SCALED AND THE WORD IS NOT — which is why this is a
+   * separate element rather than one string in the `<kbd>`.
+   *
+   * Measured in the shipped mono stack: `⌘` carries 6.39px of ink per 8.75px of
+   * `K`, so at a shared `font-size` it sits a third short of the letter next to
+   * it. `1.369em` is exactly that ratio, and it makes the two the same height.
+   *
+   * ⚠️ NOT A HAIR TALLER, WHICH IS WHERE THIS FIRST LANDED. `1.45em` gave the
+   * symbol 6% on the `K` — invisible at 12px, and at this size 0.6px of ink
+   * standing above the cap line. It made the whole badge read as *bigger type*
+   * than the label beside it: measured against the word `Search`, 88 device px
+   * of ink against 85, its top three device px higher and its centre 1.5 out.
+   * Same letter height, louder cluster. The eye compares the clusters.
+   *
+   * `Ctrl` gets none of it: it is a word set in the same face as the `K`, and
+   * scaling it would make the hint shout.
+   */
+  .wave-docs-search-trigger-mod[data-symbol] {
+    font-size: 1.369em;
+    /*
+     * ⚠️ `0`, NOT `1` — THIS GLYPH MUST NOT SIZE THE LINE IT SITS ON. A line
+     * box is as tall as the tallest inline box in it, so at `line-height: 1`
+     * this 20.5px symbol made the `<kbd>` 20.55px tall against the label's 17,
+     * and the two were centred as flex items by their *boxes*. Same cap height,
+     * 1.9px apart on screen — measured off an 8x render, invisible in the CSS.
+     *
+     * At `0` the symbol contributes no height, the `<kbd>` keeps the line box
+     * its own font gives it, and the `K` centres with the `S` beside it. The
+     * glyph still paints in full: `line-height` bounds the line, not the ink.
+     */
+    line-height: 0;
+    /*
+     * ⚠️ AND IT HAS TO BE MOVED DOWN, WHICH `font-size` ALONE WILL NEVER DO.
+     *
+     * `⌘` is drawn around the font's mathematical axis, not standing on the
+     * baseline like a capital. Measured at this size: its ink runs from 11.24px
+     * above the baseline to 1.98px *above* it — a centre 6.61px up — while the
+     * `K` beside it runs 8.75px to 0, centred 4.38px up. Aligned by baseline,
+     * as inline text is, the symbol therefore floats 2.24px high.
+     *
+     * `-0.13em` of this element's own 17.4px is 2.26px, which puts the two ink
+     * centres within a rounding error of each other.
+     */
+    vertical-align: -0.13em;
+  }
+
   .wave-docs-search-backdrop {
     position: fixed;
     inset: 0;
@@ -2989,21 +3161,94 @@
     color: var(--wave-docs-fg-subtle);
   }
 
-  .wave-docs-search-close {
+  /*
+   * The keyboard footer.
+   *
+   * ⚠️ `flex: none`, BECAUSE THE LIST ABOVE IT IS `flex: 1 1 auto`. The dialog
+   * is a column with a ceiling, and the results are what takes the slack and
+   * scrolls; without this the footer is a second growable item and the two
+   * share the overflow — a footer that drifts down the dialog as results
+   * arrive, and a list that never quite reaches it.
+   */
+  .wave-docs-search-footer {
     flex: none;
-    padding: 0.3125rem 0.625rem;
-    border: 1px solid var(--wave-docs-border);
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    padding: 0.5rem 0.75rem;
+    border-block-start: 1px solid var(--wave-docs-border);
+    color: var(--wave-docs-fg-subtle);
+    font-size: 0.75rem;
+  }
+
+  .wave-docs-search-hint,
+  .wave-docs-search-close {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.375rem;
+  }
+
+  /*
+   * ⚠️ A NEGATIVE MARGIN, BECAUSE `gap` CANNOT VARY PER PAIR. `↑` and `↓` are
+   * one instruction and read as one object; the gap that separates a cap from
+   * the word beside it is too wide between two caps that belong together. A
+   * flex container has a single gap, so the only ways to tighten one pair are
+   * an extra wrapper element or this — and a wrapper on every hint is markup
+   * bought for spacing.
+   *
+   * `-0.25rem` against the `0.375rem` above leaves `0.125rem` between them.
+   */
+  .wave-docs-search-kbd + .wave-docs-search-kbd {
+    margin-inline-start: -0.25rem;
+  }
+
+  /*
+   * The only cap holding a word rather than a glyph, and three letters at the
+   * arrows' size made it the loudest thing in the footer. `line-height` pins
+   * the box so it still sits at the same height as the caps beside it —
+   * without it the smaller text shrinks the content box and the cap rides
+   * high in a row of taller ones.
+   */
+  .wave-docs-search-close .wave-docs-search-kbd {
+    font-size: 0.625rem;
+    /* Solved, not guessed: the cap is 3.6px of border and padding plus its own
+     * line box, and the 12px caps beside it measure 17.6px. 10px x 1.4 = 14,
+     * and 14 + 3.6 is 17.6 — all four exactly the same height. */
+    line-height: 1.4;
+  }
+
+  /*
+   * ⚠️ HIDDEN WHERE THE KEY CANNOT BE PRESSED — the same query, and the same
+   * reason, as the trigger's `⌘K`. An instruction to press an arrow key is one
+   * a reader on a phone cannot follow, and a 10-inch tablet at 1024px would
+   * keep it under any width rule.
+   *
+   * The Close button beside them is deliberately NOT in here. It is the only
+   * pointer dismiss affordance in the dialog, and on exactly the devices this
+   * query names there is no Esc to fall back to.
+   */
+  @media (hover: none) and (pointer: coarse) {
+    .wave-docs-search-hint {
+      display: none;
+    }
+  }
+
+  /* Pushed to the far end, away from the two hints — the difference between a
+   * control and a caption, said with position. */
+  .wave-docs-search-close {
+    margin-inline-start: auto;
+    padding: 0.125rem 0.25rem;
+    border: 0;
     border-radius: var(--wave-docs-radius-sm);
     background: none;
     color: var(--wave-docs-fg-muted);
     font: inherit;
-    font-size: 0.8125rem;
+    font-size: 0.75rem;
     cursor: pointer;
   }
 
   .wave-docs-search-close:hover {
     color: var(--wave-docs-fg);
-    border-color: var(--wave-docs-border-strong);
   }
 
   /*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waveso/docs",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Zero parser bytes in the browser: markdown docs for Next.js, built to hast in Node and rendered as your components",
   "type": "module",
   "sideEffects": [