@waveso/docs 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # @waveso/docs
 
+## 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

@@ -2823,14 +2823,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 +2887,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 +2919,61 @@
     }
   }
 
-  .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 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 at 12px: `⌘` has 6.39px of ink against
+   * `K`'s 8.75px, so at a shared size it sits a third short of the letter next
+   * to it. `1.35em` is that ratio, and it makes the two read as one mark.
+   *
+   * `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.45em;
+    line-height: 1;
+    /*
+     * ⚠️ 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 +3062,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.0",
   "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": [