@waveso/docs 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,231 @@
 # @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
+
+- 98f8041: **The sidebar tells a category from a page at a glance.** A folder on every
+  group, a page on every page.
+
+  Weight and a chevron were the only difference, and that is not enough to scan:
+  a `Reference` group sitting directly above an `Internals` page read as one
+  undifferentiated column, and a real tree interleaves the two a dozen times. A
+  silhouette is read before any word is.
+
+  Two inline SVG paths, in the same style as the disclosure chevron and the
+  external-link mark that were already there. The package still ships no icon
+  set and takes no icon dependency — a folder and a page are as generic as the
+  chevron beside them.
+
+  `icons={false}` on `DocsSidebar` turns them off, for a host whose own
+  navigation has a different vocabulary and does not want a second one.
+
+  ⚠️ AN EXTERNAL LINK'S MARK MOVED TO THE HEAD OF ITS ROW. It used to sit at the
+  far end, which cost twice: the leading slot had to be an empty box to stop the
+  column going ragged, and the trailing edge carried two unrelated meanings —
+  "opens elsewhere" on one row, "expands" on the next. Leading is what a row _is_;
+  trailing is what it _does_. With the mark moved, the only thing at the far end
+  of any row is a chevron, which is what makes a group legible from across the
+  column, and it leaves that edge free for a status dot or an overflow control
+  later. A browser test measures the alignment, because the claim is about a
+  column and a column is geometry.
+
+  The sr-only "(opens in a new tab)" did **not** move with it — the name is still
+  read as "GitHub, opens in a new tab" rather than the other way round.
+
+  ⚠️ AND `icons={false}` PUTS THE MARK BACK ON THE TRAILING EDGE. With no column
+  to lead, rendering nothing would leave a link that leaves your site looking
+  exactly like one that does not. Turning off a decorative column is not consent
+  to drop a warning.
+
+  The markers sit at `opacity: 0.4` and inherit their row's colour rather than
+  carrying a grey of their own, so the relationship holds at every weight — a
+  bold group title and a muted page title each get a marker a fixed step lighter
+  than themselves. Full strength on hover and on the current page.
+
+  New public class names: `.wave-docs-sidebar__icon` and
+  `.wave-docs-sidebar__label`. The label wrapper is the flex hook that lets a row
+  put a chevron at its far end, and it is present whether or not there is a
+  marker beside it.
+
+  ## Your own icons, by name
+
+  The three built-ins are defaults, not a set. Content names an icon; the host
+  maps the name to a component:
+
+  ```yaml
+  # content/internals.md
+  icon: wrench
+  ```
+
+  ```json
+  // content/reference/meta.json
+  { "title": "Reference", "icon": "book" }
+  ```
+
+  ```tsx
+  <docs.Layout icons={{ wrench: Wrench, book: Book }}>{children}</docs.Layout>
+  ```
+
+  Also on `DocsSidebar` and `DocsNav` for a hand-assembled shell.
+
+  ⚠️ A NAME, NEVER ART THIS PACKAGE SHIPS. Content is authored in YAML and JSON
+  and cannot carry a React element, and a docs package mounted inside someone
+  else's application must not stand its iconography next to theirs. The bundle
+  grows by a lookup, not by an icon set — and never will by one.
+
+  ⚠️ EVERY COMPONENT IN THE MAP MUST BE A CLIENT COMPONENT. `docs.Layout` is a
+  Server Component and the tree it hands the map to is not, so React serialises a
+  _reference_ to each icon; a server component cannot be one. Icons imported from
+  a library already satisfy this. The same boundary `search` documents.
+
+  A name with no entry in the map falls back to the built-in marker for that
+  node's type — a typo in one file leaves a folder where a book should be, not a
+  hole in the column.
+
+### Patch Changes
+
+- 72ad371: The sidebar's disclosure chevron points at the group it belongs to.
+
+  `.wave-docs-sidebar__group-header` is `justify-content: space-between`, so the
+  chevron sits flush against the navigation's inline end with the label at the
+  other side of the row — and unrotated it aimed at the panel's border. Worse
+  than at nothing: a chevron at the _trailing_ edge of a row is the platform
+  idiom for "this takes you somewhere else", so it read as navigation on a
+  control that only opens a list in place. A collapsed group now points back at
+  its own label; an open one still points down at its children.
+
+  ⚠️ AND IT MIRRORS, WHICH A ROTATION DOES NOT DO ON ITS OWN. `rotate` is
+  physical — 180deg is left in every writing mode — while every other property
+  placing that row is logical. Under `dir="rtl"` the header mirrors, the chevron
+  moves to the inline start and the label lands to its right, so a single
+  unmirrored rotation would point it out of the panel on the other side: the same
+  defect, reflected.
+
+  ⚠️ THE MIRROR IS `[dir='rtl']`, NOT `:dir(rtl)`, AND THAT IS NOT A STYLE
+  PREFERENCE. Next compiles this stylesheet with lightningcss, which downlevels
+  `:dir(rtl)` into a hardcoded list of right-to-left _languages_ —
+  `:is(:lang(ae), :lang(ar), … :lang(yi))`. Direction is not language, and the
+  substitution is wrong in both directions: `<html dir="rtl" lang="en">` gets no
+  mirror, `lang="ar" dir="ltr"` gets one it never asked for. It is invisible from
+  inside this repo, because the tests inject the source text into a `<style>`
+  element where `:dir()` behaves perfectly — it was caught by measuring the built
+  site. The stylesheet now uses `:dir()` nowhere, and a test enforces that.
+
 ## 0.7.1
 
 ### Patch 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 | 13.9 KB |
-| Search dialog and router wiring | 9.3 KB |
-| Navigation: one sidebar, open and closed | 2.9 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 13.9 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.
 
@@ -202,7 +202,7 @@ Every component takes data as props, and every module that imports from `next/*`
 | --- | --- | --- |
 | `DocContent` | `react/doc-content` | Renders a hast tree, inside `.wave-docs-prose`. Server Component |
 | `DocsHero` | `react/hero` | A landing page's header. `title`, `description`, `actions`, `Link`, `externalLabel`. Server Component |
-| `DocsSidebar` | `react/sidebar` | Takes `pathname` as a prop, not from `next/navigation` |
+| `DocsSidebar` | `react/sidebar` | Takes `pathname` as a prop, not from `next/navigation`. `icons` controls the marker column — see [Sidebar icons](#sidebar-icons) |
 | `DocsToc` | `react/toc` | Scrollspy via `IntersectionObserver`. `label`, `topLabel`, `rootMargin`, `className` |
 | `DocsSearch` | `react/next-search` | `SearchDialog`, wired to Next's router. What you want |
 | `DocsLink` | `react/next-link` | `next/link`, adapted — pass it as `Link` when composing by hand |
@@ -214,6 +214,48 @@ Every component takes data as props, and every module that imports from `next/*`
 
 `DocsToc`'s `rootMargin` is the `IntersectionObserver` margin that decides how far above the viewport a heading counts as current; the default keeps the highlight on the section you are reading rather than the one about to arrive. `topLabel` is the back-to-top link at the end — it fades in once the reader is about a third of a screen down and fades out again on the way back, on a scroll timeline rather than a scroll listener, so the component ships no extra bytes to do it. Where that timeline cannot run — an engine without scroll-driven animations, a page too short to scroll, or a host that scrolls an inner pane rather than the document — the link is simply always there.
 
+### Sidebar icons
+
+Every row in the sidebar carries a marker at its head: a folder on a group, a page on a page, an arrow on a link that leaves your site. Weight and a chevron were the only difference before, and where categories and pages interleave that is not enough to scan.
+
+Three glyphs ship. **No icon set does**, and none ever will — this package is mounted inside applications that already have one, and a second vocabulary beside theirs is worse than none. Your own icons come in by name:
+
+```yaml
+# content/reference/index.md
+---
+title: Reference
+icon: book
+---
+```
+
+```json
+// content/reference/meta.json — for a directory with no index page,
+// and for hand-written links
+{ "title": "Reference", "icon": "book", "pages": [{ "title": "npm", "href": "https://npmjs.com", "icon": "package" }] }
+```
+
+```tsx
+import { DocsSidebar } from '@waveso/docs/react/sidebar';
+import type { DocNavNode } from '@waveso/docs/types';
+
+// Yours: `lucide-react`, your design system, or hand-written. Rendered with no
+// props, in a 1rem box — `currentColor` and `100%` keep it in line with the
+// built-ins and with the row it sits on.
+const Book = () => (
+  <svg viewBox="0 0 24 24" width="100%" height="100%" fill="none" stroke="currentColor">
+    <path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20V2H6.5A2.5 2.5 0 0 0 4 4.5v15Z" />
+  </svg>
+);
+
+export function Nav({ nav, pathname }: { nav: DocNavNode[]; pathname: string }) {
+  return <DocsSidebar nav={nav} pathname={pathname} icons={{ book: Book }} />;
+}
+```
+
+A name with no entry in the map falls back to the built-in marker for that node's type — a typo in one file leaves a folder where a book should be, not a hole in the column. The component is rendered with no props, in a `1rem` box, and the built-ins use `currentColor`, so anything following those two conventions sits in line with them.
+
+`icons={false}` removes the column entirely. The external-link mark moves back to the trailing edge there: turning off a decorative column is not consent to drop a warning that a link leaves your site.
+
 The two components the adapter injects take a little more than an `<a>` and an `<img>`. `DocsLinkProps` adds `prefetch` — passed straight to `next/link`, where `false` disables the hover and viewport paths both, so it is a stronger switch in the App Router than the name suggests. `DocsImageProps` carries `src`, `alt`, `width` and `height` — the four `next/image` refuses to render without — and adds `sizes`, `loading`, `decoding` and `fetchPriority`, forwarded to it; markdown carries none of them, so they come from your `imageResolver` or from a `components` override. `decoding` defaults to `async`, and `loading` to `lazy` — except on an image the author marked `eager`, which is usually the page's largest element.
 
 ### Layout
@@ -713,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/frontmatter.d.ts

@@ -32,6 +32,7 @@ declare const docFrontmatterSchema: z.ZodObject<{
   draft: z.ZodExactOptional<z.ZodBoolean>;
   aliases: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
   order: z.ZodExactOptional<z.ZodNumber>;
+  icon: z.ZodExactOptional<z.ZodString>;
   actions: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
     label: z.ZodString;
     href: z.ZodString;

package/dist/frontmatter.js

@@ -32,6 +32,7 @@ const docFrontmatterSchema = z.object({
 	draft: z.boolean().exactOptional(),
 	aliases: z.array(z.string()).exactOptional(),
 	order: z.number().exactOptional(),
+	icon: z.string().min(1).exactOptional(),
 	actions: z.array(z.object({
 		label: z.string().min(1),
 		href: z.string().min(1).refine(isSafeHref, "must be a safe URL (no javascript: or data:)"),

package/dist/meta.d.ts

@@ -10,9 +10,11 @@ import { z } from "zod";
  */
 declare const docsMetaSchema: z.ZodObject<{
   title: z.ZodExactOptional<z.ZodString>;
+  icon: z.ZodExactOptional<z.ZodString>;
   pages: z.ZodExactOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
     title: z.ZodString;
     href: z.ZodString;
+    icon: z.ZodExactOptional<z.ZodString>;
   }, z.core.$strict>]>>>;
 }, z.core.$strict>;
 /**

package/dist/meta.js

@@ -25,9 +25,11 @@ const REST = "...";
 */
 const docsMetaSchema = z.strictObject({
 	title: z.string().exactOptional(),
+	icon: z.string().min(1).exactOptional(),
 	pages: z.array(z.union([z.string(), z.strictObject({
 		title: z.string(),
-		href: z.string().refine(isSafeHref, { message: "that is not a scheme this package will put in a link. Use http(s), mailto, tel, sms, ftp, irc, xmpp, news, feed, git or matrix — or a path, which needs no scheme at all." })
+		href: z.string().refine(isSafeHref, { message: "that is not a scheme this package will put in a link. Use http(s), mailto, tel, sms, ftp, irc, xmpp, news, feed, git or matrix — or a path, which needs no scheme at all." }),
+		icon: z.string().min(1).exactOptional()
 	})])).exactOptional()
 });
 /**
@@ -93,7 +95,8 @@ function orderNavEntries(entries, meta, metaPath, depth) {
 				type: "link",
 				title: page.title,
 				href: page.href,
-				external: opensInNewTab(page.href)
+				external: opensInNewTab(page.href),
+				...page.icon !== void 0 ? { icon: page.icon } : {}
 			});
 			continue;
 		}

package/dist/next.d.ts

@@ -3,6 +3,7 @@ import { DocsHighlighter, DocsLang, DocsTheme, DocsThemes } from "./highlighter.
 import { SerializableSearchOptions } from "./search-options.js";
 import { DocsLabels } from "./react/shell-labels.js";
 import { MarkdownComponents } from "./react/markdown-components.js";
+import { DocsIconMap } from "./react/sidebar.js";
 import { DocsLayoutSearchProps } from "./react/layout.js";
 import { DocsSource } from "./source.js";
 import { ReactNode } from "react";
@@ -154,6 +155,19 @@ interface DocsLayoutProps {
    * mean naming one string cost you the other twenty-one.
    */
   labels?: DocsLabels | undefined;
+  /**
+   * The sidebar's marker column: `true` (default), `false`, or your own icons
+   * keyed by the `icon` names your content authors in frontmatter and
+   * `meta.json`. See `DocsSidebarProps.icons`.
+   *
+   * ⚠️ EVERY COMPONENT IN THE MAP MUST BE A CLIENT COMPONENT — the same
+   * boundary `search` documents at length. This is a Server Component handing
+   * props to a Client one, so React serialises a *reference* to a client
+   * component and cannot serialise a server one. Icons imported from a library
+   * already satisfy this; one defined inline in a server file fails the build
+   * at the boundary.
+   */
+  icons?: boolean | DocsIconMap | undefined;
 }
 /** Props Next hands a page in the App Router. */
 interface DocsPageProps {

package/dist/next.js

@@ -468,7 +468,7 @@ function createDocsRoute(options) {
 		async IndexPage() {
 			return renderRoute([]);
 		},
-		async Layout({ children, search, labels }) {
+		async Layout({ children, search, labels, icons }) {
 			const { DocsLayoutShell } = await import("./react/layout.js");
 			const host = search === true || search === void 0 || search === false ? void 0 : search;
 			const requestedOptions = host?.miniSearchOptions ?? options.miniSearchOptions;
@@ -485,7 +485,8 @@ function createDocsRoute(options) {
 				nav: await requestScopedSource.nav(),
 				searchIndexUrl,
 				search: searchProps,
-				...shellLabels === void 0 ? {} : { labels: shellLabels }
+				...shellLabels === void 0 ? {} : { labels: shellLabels },
+				...icons === void 0 ? {} : { icons }
 			});
 		},
 		async generateStaticParams() {

package/dist/react/layout.d.ts

@@ -2,6 +2,7 @@ import { DocNavNode } from "../types.js";
 import { SerializableSearchOptions } from "../search-options.js";
 import { DocsLabels } from "./shell-labels.js";
 import { DocsSearchProps } from "./next-search.js";
+import { DocsIconMap } from "./sidebar.js";
 import { ReactNode } from "react";
 //#region src/react/layout.d.ts
 /**
@@ -53,7 +54,21 @@ interface DocsLayoutShellProps {
    * passed either. Configuration that could not be configured.
    */
   labels?: DocsLabels | undefined;
+  /**
+   * The sidebar's marker column: `true` (default), `false`, or your own icons
+   * keyed by the `icon` names your content authors. See
+   * {@link DocsSidebarProps.icons}.
+   *
+   * ⚠️ EVERY COMPONENT IN THE MAP MUST BE A CLIENT COMPONENT. This shell is a
+   * Server Component and the tree it hands them to is not, so the map crosses
+   * that boundary — React can serialise a *reference* to a client component and
+   * cannot serialise a server one. Import your icons from a module carrying
+   * `'use client'` (every icon library does) and this is invisible; define one
+   * inline in a server file and the build fails at the boundary rather than
+   * here.
+   */
+  icons?: boolean | DocsIconMap | undefined;
 }
-declare function DocsLayoutShell({ children, nav, searchIndexUrl, search, labels }: DocsLayoutShellProps): ReactNode;
+declare function DocsLayoutShell({ children, nav, searchIndexUrl, search, labels, icons }: DocsLayoutShellProps): ReactNode;
 //#endregion
 export { DocsLayoutSearchProps, DocsLayoutShell, DocsLayoutShellProps };

package/dist/react/layout.js

@@ -4,7 +4,7 @@ import { DocsNextNav } from "./next-nav.js";
 import { SkipLink } from "./skip-link.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/layout.tsx
-function DocsLayoutShell({ children, nav, searchIndexUrl, search = true, labels }) {
+function DocsLayoutShell({ children, nav, searchIndexUrl, search = true, labels, icons }) {
 	const text = resolveLabels(labels);
 	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(SkipLink, { children: text.skipToContent }), /* @__PURE__ */ jsx("div", {
 		className: "wave-docs-shell",
@@ -18,6 +18,7 @@ function DocsLayoutShell({ children, nav, searchIndexUrl, search = true, labels
 				...labels?.expandGroup === void 0 ? {} : { expandGroup: labels.expandGroup },
 				...labels?.collapseGroup === void 0 ? {} : { collapseGroup: labels.collapseGroup },
 				...labels?.externalLink === void 0 ? {} : { externalLink: labels.externalLink },
+				...icons === void 0 ? {} : { icons },
 				children: search === false ? null : /* @__PURE__ */ jsx(DocsSearch, {
 					indexUrl: searchIndexUrl,
 					...search === true ? {} : search,

package/dist/react/nav.d.ts

@@ -1,5 +1,6 @@
 import { DocNavNode } from "../types.js";
 import { DocsLinkComponent } from "./markdown-components.js";
+import { DocsIconMap } from "./sidebar.js";
 import { ReactNode } from "react";
 //#region src/react/nav.d.ts
 /** The navigation's `id`, and the trigger's `aria-controls`. */
@@ -26,7 +27,9 @@ interface DocsNavProps {
   expandGroup?: string | undefined;
   collapseGroup?: string | undefined;
   externalLink?: string | undefined;
+  /** The marker column. See `DocsSidebarProps.icons`. */
+  icons?: boolean | DocsIconMap | undefined;
 }
-declare function DocsNav({ nav, pathname, Link, label, children, closeLabel, openLabel, expandGroup, collapseGroup, externalLink }: DocsNavProps): ReactNode;
+declare function DocsNav({ nav, pathname, Link, label, children, closeLabel, openLabel, expandGroup, collapseGroup, externalLink, icons }: DocsNavProps): ReactNode;
 //#endregion
 export { DOCS_NAV_ID, DocsNav, DocsNavProps };

package/dist/react/nav.js

@@ -5,7 +5,7 @@ import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/nav.tsx
 /** The navigation's `id`, and the trigger's `aria-controls`. */
 const DOCS_NAV_ID = "wave-docs-nav";
-function DocsNav({ nav, pathname, Link, label = "Documentation", children, closeLabel = "Close navigation", openLabel = "Open navigation", expandGroup, collapseGroup, externalLink }) {
+function DocsNav({ nav, pathname, Link, label = "Documentation", children, closeLabel = "Close navigation", openLabel = "Open navigation", expandGroup, collapseGroup, externalLink, icons }) {
 	const shellRef = useRef(null);
 	const navRef = useRef(null);
 	const returnFocusRef = useRef(null);
@@ -98,7 +98,8 @@ function DocsNav({ nav, pathname, Link, label = "Documentation", children, close
 				Link,
 				...expandGroup === void 0 ? {} : { expandGroup },
 				...collapseGroup === void 0 ? {} : { collapseGroup },
-				...externalLink === void 0 ? {} : { externalLink }
+				...externalLink === void 0 ? {} : { externalLink },
+				...icons === void 0 ? {} : { icons }
 			})]
 		}), /* @__PURE__ */ jsx("button", {
 			type: "button",

package/dist/react/next-nav.d.ts

@@ -1,4 +1,5 @@
 import { DocNavNode } from "../types.js";
+import { DocsIconMap } from "./sidebar.js";
 import { ReactNode } from "react";
 //#region src/react/next-nav.d.ts
 interface DocsNextNavProps {
@@ -13,7 +14,9 @@ interface DocsNextNavProps {
   expandGroup?: string | undefined;
   collapseGroup?: string | undefined;
   externalLink?: string | undefined;
+  /** The marker column. See `DocsSidebarProps.icons`. */
+  icons?: boolean | DocsIconMap | undefined;
 }
-declare function DocsNextNav({ nav, label, closeLabel, openLabel, children, expandGroup, collapseGroup, externalLink }: DocsNextNavProps): ReactNode;
+declare function DocsNextNav({ nav, label, closeLabel, openLabel, children, expandGroup, collapseGroup, externalLink, icons }: DocsNextNavProps): ReactNode;
 //#endregion
 export { DocsNextNav, DocsNextNavProps };

package/dist/react/next-nav.js

@@ -19,7 +19,7 @@ import { usePathname } from "next/navigation";
 */
 /** Module scope: a fresh identity here remounts every nav link on every render. */
 const Link = wrapNextLink(NextLink);
-function DocsNextNav({ nav, label, closeLabel, openLabel, children, expandGroup, collapseGroup, externalLink }) {
+function DocsNextNav({ nav, label, closeLabel, openLabel, children, expandGroup, collapseGroup, externalLink, icons }) {
 	return /* @__PURE__ */ jsx(DocsNav, {
 		nav,
 		pathname: usePathname(),
@@ -30,6 +30,7 @@ function DocsNextNav({ nav, label, closeLabel, openLabel, children, expandGroup,
 		...expandGroup === void 0 ? {} : { expandGroup },
 		...collapseGroup === void 0 ? {} : { collapseGroup },
 		...externalLink === void 0 ? {} : { externalLink },
+		...icons === void 0 ? {} : { icons },
 		children
 	});
 }

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 };