shelving 1.236.2 → 1.237.0

package/ui/form/SchemaInput.md

@@ -0,0 +1,64 @@
+# SchemaInput
+
+Schema-driven input dispatch. `SchemaInput` inspects a `Schema` instance and renders the right control automatically — the same mechanism [`Form`](/ui/Form) uses to turn a `DataSchema` into a complete set of inputs.
+
+**Things to know:**
+
+- `required` defaults to whether the schema is required (i.e. not wrapped in an `OptionalSchema` or `NullableSchema`); override it explicitly when needed.
+- It throws an `UnexpectedError` if no input matches the schema type.
+- `SchemaField` wraps the chosen input in a [`Field`](/ui/Field) with its label and message; pass `children` to override the input while keeping the field chrome.
+- Every input it dispatches to is a standalone, controlled component extending `ValueInputProps<O>` — see the prop contract below.
+
+The schema-to-input mapping:
+
+| Schema type | Rendered as |
+|---|---|
+| `StringSchema` | [`TextInput`](/ui/TextInput) |
+| `NumberSchema` | [`NumberInput`](/ui/NumberInput) (formatted on blur) |
+| `DateSchema` | [`DateInput`](/ui/DateInput) |
+| `BooleanSchema` | [`CheckboxInput`](/ui/CheckboxInput) |
+| `ChoiceSchema` (≤ 8 options) | [`ChoiceRadioInputs`](/ui/ChoiceRadioInputs) |
+| `ChoiceSchema` (> 8 options) | [`SelectInput`](/ui/SelectInput) |
+| `ArraySchema` | [`ArrayInput`](/ui/ArrayInput) |
+| `DictionarySchema` | [`DictionaryInput`](/ui/DictionaryInput) |
+| `DataSchema` | [`DataInput`](/ui/DataInput) |
+
+The shared value-input prop contract (`ValueInputProps<O>`):
+
+| Prop | Contract |
+|---|---|
+| `name` | HTML field name |
+| `value` | Current value |
+| `onValue(v)` | Called on every change |
+| `required` | Marks the field as required |
+| `disabled` | Disables the control |
+| `message` | Inline error string |
+
+[`DataInput`](/ui/DataInput) renders a row of `SchemaInput` elements for each property of a nested data object, and propagates sub-field errors from a `"key: message\n…"` formatted `message` string. `ArrayInput` and `DictionaryInput` both accept an `items` schema to render a repeatable list of sub-inputs with add/remove buttons.
+
+## Usage
+
+### Dispatch on a single schema
+
+```tsx
+import { SchemaInput } from "shelving/ui";
+import { StringSchema, NumberSchema } from "shelving/schema";
+
+<SchemaInput name="email" schema={new StringSchema({ title: "Email" })} /> // -> <TextInput>
+<SchemaInput name="age" schema={new NumberSchema({ title: "Age" })} /> // -> <NumberInput>
+```
+
+### Wrapped in a field
+
+```tsx
+import { SchemaField } from "shelving/ui";
+
+<SchemaField name="email" schema={EMAIL_SCHEMA} /> // <Field> wrapping a <TextInput>
+```
+
+## See also
+
+- [`Form`](/ui/Form) — drives `SchemaInput` for every property of its schema.
+- [`Field`](/ui/Field) — the label + input + error wrapper `SchemaField` composes.
+- [schema](/schema) — the `Schema` types `SchemaInput` dispatches on.
+- [ui](/ui) — top-level UI module index.

package/ui/form/SchemaInput.tsx

@@ -61,6 +61,7 @@ export interface SchemaInputProps<T extends Schema, I = never> extends ValueInpu
  * @param props Props including the `schema` plus value input props.
  * @returns The matching input element for the schema.
  * @throws `UnexpectedError` if no input matches the schema type.
+ * @kind component
  * @example <SchemaInput name="email" schema={EMAIL} /> // Outputs a `<TextInput>` for the "email" property.
  * @example <SchemaInput name="age" schema={AGE} /> // Outputs a `<NumberInput>` for the "age" property.
  * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/SchemaInput

package/ui/inline/Code.d.ts

@@ -32,6 +32,7 @@ export interface CodeProps extends ColorVariants, TypographyVariants, OptionalCh
  * Inline code span — renders a `<code>` element.
  * - Pass `plain` to drop the default background and padding.
  *
+ * @kind component
  * @param props Colour and typography variants, `children`, plus an optional `plain` toggle.
  * @returns Rendered `<code>` element.
  * @example <Code>npm install</Code>

package/ui/inline/Code.js

@@ -24,6 +24,7 @@ export const CODE_PROSE_CLASS = getModuleClass(CODE_CSS, "prose");
  * Inline code span — renders a `<code>` element.
  * - Pass `plain` to drop the default background and padding.
  *
+ * @kind component
  * @param props Colour and typography variants, `children`, plus an optional `plain` toggle.
  * @returns Rendered `<code>` element.
  * @example <Code>npm install</Code>

package/ui/inline/Code.md

@@ -0,0 +1,58 @@
+# Code
+
+An inline code span — renders a `<code>` element with monospace type and a subtle tinted background. `Code.tsx` exports four siblings that share the same monospace styling but carry different HTML semantics:
+
+| Component  | HTML element | Use for                         |
+| ---------- | ------------ | ------------------------------- |
+| `Code`     | `<code>`     | Inline code fragments           |
+| `Keyboard` | `<kbd>`      | Keyboard input, e.g. `Ctrl+S`   |
+| `Sample`   | `<samp>`     | Program output                  |
+| `Variable` | `<var>`      | Variable names in documentation |
+
+**Things to know:**
+
+- Pick the sibling whose semantics match — they all look the same but mean different things to assistive tech and search.
+- Pass `plain` to drop the default background and inline padding (useful when the code already sits inside a tinted container).
+- Painted from the [tint ladder](/ui/TINT_CLASS): the background is `--tint-90` and the text `--tint-00`, so it re-tints with its surrounding scope.
+- Inside [`Prose`](/ui/Prose) raw `<code>` / `<kbd>` / `<samp>` / `<var>` pick up the same styling, and code inside a `<pre>` drops the inline box automatically.
+
+## Usage
+
+### Inline code and keyboard input
+
+```tsx
+import { Code, Keyboard, Sample } from "shelving/ui";
+
+<p>Run <Code>npm install</Code>, then press <Keyboard>Enter</Keyboard>.</p>
+<p>It prints <Sample>Done.</Sample></p>
+```
+
+### Plain (no background)
+
+```tsx
+import { Code } from "shelving/ui";
+
+<Code plain>const x = 1;</Code>
+```
+
+## Styling
+
+`Code` paints from the [tint ladder](/ui/TINT_CLASS); the box (`background` / `color`) reads ladder steps directly, while type, padding, and radius have per-property hooks.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--code-font` | Font family | `var(--font-code)` |
+| `--code-weight` | Font weight | `var(--weight-code)` |
+| `--code-size` | Font size | `var(--size-smaller)` |
+| `--code-leading` | Line height | `var(--leading)` |
+| `--code-padding` | Inline padding (non-`plain`) | `var(--space-xxsmall)` |
+| `--code-radius` | Corner radius (non-`plain`) | `var(--radius-xxsmall)` |
+
+**Global tokens it reads:** `--font-code`, `--weight-code`, `--size-smaller`, `--leading`, `--space-xxsmall`, `--radius-xxsmall`, and the tint-ladder steps `--tint-00` / `--tint-90` for the box fill and text.
+
+## See also
+
+- [`Preformatted`](/ui/Preformatted) — block-level `<pre>` for multi-line code.
+- [`Mark`](/ui/Mark) — highlight a run of text rather than mark it as code.
+- [`Prose`](/ui/Prose) — styles raw `<code>` and friends inside longform content.
+- [`ui`](/ui) — the styling system: tint ladder and theming.

package/ui/inline/Code.tsx

@@ -39,6 +39,7 @@ export interface CodeProps extends ColorVariants, TypographyVariants, OptionalCh
  * Inline code span — renders a `<code>` element.
  * - Pass `plain` to drop the default background and padding.
  *
+ * @kind component
  * @param props Colour and typography variants, `children`, plus an optional `plain` toggle.
  * @returns Rendered `<code>` element.
  * @example <Code>npm install</Code>

package/ui/inline/Link.d.ts

@@ -22,6 +22,7 @@ export interface LinkProps extends ClickableProps {
 /**
  * Inline link — delegates to `Clickable`, rendering an `<a>` (when `href` is set) or `<button>` (when `onClick` is set).
  *
+ * @kind component
  * @param props Clickable props such as `href`, `onClick`, `title`, and `children`.
  * @returns Rendered inline `<a>` or `<button>` element.
  * @example <Link href="/about">About us</Link>

package/ui/inline/Link.js

@@ -17,6 +17,7 @@ export const LINK_PROSE_CLASS = getModuleClass(LINK_CSS, "prose");
 /**
  * Inline link — delegates to `Clickable`, rendering an `<a>` (when `href` is set) or `<button>` (when `onClick` is set).
  *
+ * @kind component
  * @param props Clickable props such as `href`, `onClick`, `title`, and `children`.
  * @returns Rendered inline `<a>` or `<button>` element.
  * @example <Link href="/about">About us</Link>

package/ui/inline/Link.md

@@ -0,0 +1,47 @@
+# Link
+
+An inline link or action. Delegates to [`Clickable`](/ui/Clickable), rendering an `<a>` when `href` is provided or a `<button>` when `onClick` is provided — so the same component covers both navigation and in-page actions. Prefer it over a raw `<a>` inside React components.
+
+**Things to know:**
+
+- It handles busy state, URL resolution, and active-page highlighting automatically via the shared `Clickable` helper.
+- An `<a>` (any actual link) shows an underline that disappears on hover; a `<button>` variant carries no underline.
+- Reach for `Link` for inline text links; for standalone calls to action use a button-styled component instead.
+- Inside [`Prose`](/ui/Prose) a raw `<a>` picks up the same styling, so Markdown-rendered links match component ones.
+
+## Usage
+
+### Link inside body copy
+
+```tsx
+import { Paragraph, Link } from "shelving/ui";
+
+<Paragraph>
+  Read our <Link href="/privacy">privacy policy</Link> for details.
+</Paragraph>
+```
+
+### Action button
+
+```tsx
+import { Link } from "shelving/ui";
+
+<Link onClick={() => save()}>Save now</Link>
+```
+
+## Styling
+
+`Link` exposes a couple of inline hooks; the link colour comes from the global `--color-link` token.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--link-weight` | Text colour and font weight | `var(--color-link)` colour / `var(--weight-strong)` weight |
+
+**Global tokens it reads:** `--color-link`, `--weight-strong`, and `--stroke-normal` (the underline thickness).
+
+## See also
+
+- [`Clickable`](/ui/Clickable) — the underlying primitive that renders `<a>` vs `<button>`.
+- [`Strong`](/ui/Strong) — emphasis for runs of text that are not links.
+- [`Prose`](/ui/Prose) — styles raw `<a>` inside longform content.
+- [`ui`](/ui) — the styling system and theming tokens.

package/ui/inline/Link.tsx

@@ -27,6 +27,7 @@ export interface LinkProps extends ClickableProps {}
 /**
  * Inline link — delegates to `Clickable`, rendering an `<a>` (when `href` is set) or `<button>` (when `onClick` is set).
  *
+ * @kind component
  * @param props Clickable props such as `href`, `onClick`, `title`, and `children`.
  * @returns Rendered inline `<a>` or `<button>` element.
  * @example <Link href="/about">About us</Link>

package/ui/inline/Mark.d.ts

@@ -22,6 +22,7 @@ export interface MarkProps extends OptionalChildProps {
 /**
  * Highlighted text — renders a `<mark>` element to call attention to a run of text.
  *
+ * @kind component
  * @param props The `children` to highlight.
  * @returns Rendered `<mark>` element.
  * @example <Mark>search term</Mark>

package/ui/inline/Mark.js

@@ -16,6 +16,7 @@ export const MARK_PROSE_CLASS = getModuleClass(MARK_CSS, "prose");
 /**
  * Highlighted text — renders a `<mark>` element to call attention to a run of text.
  *
+ * @kind component
  * @param props The `children` to highlight.
  * @returns Rendered `<mark>` element.
  * @example <Mark>search term</Mark>

package/ui/inline/Mark.md

@@ -0,0 +1,40 @@
+# Mark
+
+Highlighted text — renders a `<mark>` element to call attention to a run of text, such as a matched search term. Painted as a small inline pill with a yellow background by default.
+
+**Things to know:**
+
+- Use it for relevance highlighting (search hits, the current match), not for general emphasis — reach for [`Strong`](/ui/Strong) or [`Emphasis`](/ui/Emphasis) for that.
+- It is a self-contained inline pill: it adds its own inline padding and rounded corners.
+- Inside [`Prose`](/ui/Prose) a raw `<mark>` picks up the same styling, so Markdown-rendered highlights match component ones.
+
+## Usage
+
+### Highlighted search term
+
+```tsx
+import { Mark } from "shelving/ui";
+
+<p>Files are stored in <Mark>UTF-8</Mark> encoding.</p>
+```
+
+## Styling
+
+`Mark` is a fixed-palette highlight: it paints from dedicated colour hooks rather than the tint ladder.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--mark-color-bg` | Background fill | `var(--light-yellow)` |
+| `--mark-color-text` | Text colour | `var(--dark-yellow)` |
+| `--mark-padding` | Inline padding | `0.375em` |
+| `--mark-radius` | Corner radius | `var(--radius-xxsmall)` |
+| `--mark-weight` | Font weight | `var(--weight-strong)` |
+
+**Global tokens it reads:** `--light-yellow`, `--dark-yellow`, `--radius-xxsmall`, and `--weight-strong`.
+
+## See also
+
+- [`Strong`](/ui/Strong) — strong importance rather than relevance highlighting.
+- [`Emphasis`](/ui/Emphasis) — stress emphasis (italic) for a run of text.
+- [`Code`](/ui/Code) — inline code rather than a highlight.
+- [`ui`](/ui) — the styling system and theming tokens.

package/ui/inline/Mark.tsx

@@ -27,6 +27,7 @@ export interface MarkProps extends OptionalChildProps {}
 /**
  * Highlighted text — renders a `<mark>` element to call attention to a run of text.
  *
+ * @kind component
  * @param props The `children` to highlight.
  * @returns Rendered `<mark>` element.
  * @example <Mark>search term</Mark>

package/ui/inline/Strong.d.ts

@@ -22,6 +22,7 @@ export interface StrongProps extends OptionalChildProps {
 /**
  * Strong importance — renders a `<strong>` element for text of strong importance (typically bold).
  *
+ * @kind component
  * @param props The `children` to render with strong importance.
  * @returns Rendered `<strong>` element.
  * @example <Strong>Warning</Strong>

package/ui/inline/Strong.js

@@ -16,6 +16,7 @@ export const STRONG_PROSE_CLASS = getModuleClass(STRONG_CSS, "prose");
 /**
  * Strong importance — renders a `<strong>` element for text of strong importance (typically bold).
  *
+ * @kind component
  * @param props The `children` to render with strong importance.
  * @returns Rendered `<strong>` element.
  * @example <Strong>Warning</Strong>

package/ui/inline/Strong.md

@@ -0,0 +1,34 @@
+# Strong
+
+Strong importance — renders a `<strong>` element for text that carries strong importance, seriousness, or urgency (typically shown bold). Prefer it over a raw `<strong>` or `<b>` inside React components so the semantics and class names stay consistent.
+
+**Things to know:**
+
+- Use `Strong` for importance, [`Emphasis`](/ui/Emphasis) for stress emphasis (italic), and [`Mark`](/ui/Mark) for relevance highlighting — they are not interchangeable.
+- It only sets the font weight; it inherits colour and size from the surrounding text.
+- Inside [`Prose`](/ui/Prose) raw `<strong>` / `<b>` pick up the same styling, so Markdown-rendered bold text matches component ones.
+
+## Usage
+
+### Strong importance in body copy
+
+```tsx
+import { Paragraph, Strong } from "shelving/ui";
+
+<Paragraph>
+  Press save before leaving. <Strong>Unsaved changes will be lost.</Strong>
+</Paragraph>
+```
+
+## Styling
+
+`Strong` has no own theming hooks — it sets `font-weight: var(--weight-strong)` and inherits everything else from its surroundings.
+
+**Global tokens it reads:** `--weight-strong`.
+
+## See also
+
+- [`Emphasis`](/ui/Emphasis) — stress emphasis (italic `<em>`) rather than importance.
+- [`Mark`](/ui/Mark) — highlight a run of text by relevance.
+- [`Small`](/ui/Small) — de-emphasised fine print.
+- [`ui`](/ui) — the styling system and theming tokens.

package/ui/inline/Strong.tsx

@@ -27,6 +27,7 @@ export interface StrongProps extends OptionalChildProps {}
 /**
  * Strong importance — renders a `<strong>` element for text of strong importance (typically bold).
  *
+ * @kind component
  * @param props The `children` to render with strong importance.
  * @returns Rendered `<strong>` element.
  * @example <Strong>Warning</Strong>

package/ui/layout/CenteredLayout.d.ts

@@ -12,6 +12,7 @@ export interface CenteredLayoutProps extends OptionalChildProps {
  * Layout that centres its content with no header/footer and a narrow max-width.
  * - Used for e.g. login/register/error/form pages where the content is the only focus.
  *
+ * @kind component
  * @param children The content to centre.
  * @param fullWidth Drop the narrow max-width and let content fill the width (defaults to `false`).
  * @returns The centred layout element.

package/ui/layout/CenteredLayout.js

@@ -7,6 +7,7 @@ import { LAYOUT_CLASS } from "./Layout.js";
  * Layout that centres its content with no header/footer and a narrow max-width.
  * - Used for e.g. login/register/error/form pages where the content is the only focus.
  *
+ * @kind component
  * @param children The content to centre.
  * @param fullWidth Drop the narrow max-width and let content fill the width (defaults to `false`).
  * @returns The centred layout element.

package/ui/layout/CenteredLayout.md

@@ -0,0 +1,38 @@
+# CenteredLayout
+
+A full-viewport layout that centres its content horizontally inside a narrow max-width column. Good for login, registration, error, and other focused single-purpose pages where the content is the only thing on screen.
+
+**Things to know:**
+
+- Pass `fullWidth` to drop the max-width constraint while keeping the centred positioning — use it when the content itself needs to fill the width.
+- Like the other full-viewport layouts it owns scroll, padding, and safe-area insets so individual pages don't have to.
+
+## Usage
+
+```tsx
+import { CenteredLayout, Section } from "shelving/ui";
+
+function LoginPage() {
+  return (
+    <CenteredLayout>
+      <Section narrow>
+        <LoginForm/>
+      </Section>
+    </CenteredLayout>
+  );
+}
+```
+
+Layouts compose naturally as [`Router`](/ui/Router) route values — wrap a group of routes in a shared layout, then route further inside it.
+
+## Styling
+
+This layout exposes no own `--centered-layout-*` hooks. The inner column is capped at the global `--width-wide` token (dropped when `fullWidth` is set), and the outer element composes the shared `.layout` behaviour, so it reads the layout hooks `--layout-space`, `--layout-padding`, and `--layout-inset-top` / `-bottom` / `-left` / `-right`.
+
+**Global tokens it reads** — `--width-wide`.
+
+## See also
+
+- [`SidebarLayout`](/ui/SidebarLayout) — the other full-viewport layout, with a fixed side column
+- [`Page`](/ui/Page) — sits above layouts in the tree
+- [`Router`](/ui/Router) — wrap route groups in a shared layout

package/ui/layout/CenteredLayout.tsx

@@ -18,6 +18,7 @@ export interface CenteredLayoutProps extends OptionalChildProps {
  * Layout that centres its content with no header/footer and a narrow max-width.
  * - Used for e.g. login/register/error/form pages where the content is the only focus.
  *
+ * @kind component
  * @param children The content to centre.
  * @param fullWidth Drop the narrow max-width and let content fill the width (defaults to `false`).
  * @returns The centred layout element.

package/ui/layout/SidebarLayout.d.ts

@@ -19,6 +19,7 @@ export interface SidebarLayoutProps extends OptionalChildProps {
  * - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
  * - Use the `--sidebar-layout-width`, `--sidebar-layout-bg`, `--sidebar-layout-border`, and `--sidebar-layout-color-border` custom properties to override defaults.
  *
+ * @kind component
  * @param sidebar The side-column content, rendered inside a `<nav>`.
  * @param children The main scrollable content.
  * @param right Render the sidebar on the right rather than the left (defaults to `false`).

package/ui/layout/SidebarLayout.js

@@ -14,6 +14,7 @@ import SIDEBAR_LAYOUT_CSS from "./SidebarLayout.module.css";
  * - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
  * - Use the `--sidebar-layout-width`, `--sidebar-layout-bg`, `--sidebar-layout-border`, and `--sidebar-layout-color-border` custom properties to override defaults.
  *
+ * @kind component
  * @param sidebar The side-column content, rendered inside a `<nav>`.
  * @param children The main scrollable content.
  * @param right Render the sidebar on the right rather than the left (defaults to `false`).

package/ui/layout/SidebarLayout.md

@@ -0,0 +1,65 @@
+# SidebarLayout
+
+A full-viewport layout with a fixed-width side column next to a scrollable main content column. The sidebar renders as a `<nav>` landmark — it almost always holds the primary navigation. On narrow viewports it collapses to an off-canvas drawer toggled by a single burger/close button.
+
+**Things to know:**
+
+- Pass `right` to place the sidebar on the right rather than the left.
+- The sidebar renders as `<nav>`, so it is a navigation landmark without extra markup — drop a [`Menu`](/ui/Menu) inside it.
+- While the drawer is open an overlay dims the page; clicking the overlay closes it.
+- Inside a [`Navigation`](/ui/Navigation) context the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
+- The layout owns scroll, padding, and safe-area insets so individual pages don't have to.
+
+## Usage
+
+```tsx
+import { SidebarLayout, Menu, MenuItem, Router } from "shelving/ui";
+
+function AppShell() {
+  const nav = (
+    <Menu>
+      <MenuItem href="/dashboard">Dashboard</MenuItem>
+      <MenuItem href="/users">Users</MenuItem>
+      <MenuItem href="/settings">Settings</MenuItem>
+    </Menu>
+  );
+  return (
+    <SidebarLayout sidebar={nav}>
+      <Router routes={ROUTES}/>
+    </SidebarLayout>
+  );
+}
+```
+
+Layouts compose naturally as [`Router`](/ui/Router) route values — wrap a group of routes in a shared layout, then route further inside it.
+
+### Keyboard-aware safe area
+
+`useSafeKeyboardArea()` (exported alongside the layouts) tracks the dynamic viewport and writes a `--layout-inset-bottom` custom property reflecting the space hidden behind the on-screen keyboard. This is an iOS Safari workaround until `interactive-widget` viewport support lands.
+
+```tsx
+import { useSafeKeyboardArea } from "shelving/ui";
+
+useEffect(useSafeKeyboardArea, []);
+```
+
+## Styling
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--sidebar-layout-width` | Width of the side column (and drawer) | `17.5rem` |
+| `--sidebar-layout-background` | Page background while the layout is mounted | `var(--tint-100)` |
+| `--sidebar-layout-sidebar-background` | Sidebar column fill | `var(--tint-90)` |
+| `--sidebar-layout-content-background` | Main content column fill | `var(--tint-100)` |
+| `--sidebar-layout-border` | Divider between sidebar and content | `var(--stroke-normal) solid var(--tint-80)` |
+
+The content column composes the shared `.layout` behaviour, so it also reads the layout hooks `--layout-space`, `--layout-padding`, `--layout-inset-top` / `-bottom` / `-left` / `-right`, and `--layout-body-bg`.
+
+**Global tokens it reads** — the tint ladder `--tint-80` / `--tint-90` / `--tint-100`, plus `--space-normal`, `--stroke-normal`, `--duration-normal`, and `--color-shadow`.
+
+## See also
+
+- [`CenteredLayout`](/ui/CenteredLayout) — the other full-viewport layout, for focused single-column pages
+- [`Menu`](/ui/Menu) / [`MenuItem`](/ui/MenuItem) — navigation links for the sidebar
+- [`Router`](/ui/Router) — wrap route groups in a shared layout
+- [`Page`](/ui/Page) — sits above layouts in the tree

package/ui/layout/SidebarLayout.tsx

@@ -27,6 +27,7 @@ export interface SidebarLayoutProps extends OptionalChildProps {
  * - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
  * - Use the `--sidebar-layout-width`, `--sidebar-layout-bg`, `--sidebar-layout-border`, and `--sidebar-layout-color-border` custom properties to override defaults.
  *
+ * @kind component
  * @param sidebar The side-column content, rendered inside a `<nav>`.
  * @param children The main scrollable content.
  * @param right Render the sidebar on the right rather than the left (defaults to `false`).

package/ui/menu/Menu.d.ts

@@ -13,6 +13,7 @@ export interface MenuProps extends OptionalChildProps {
  * - Renders as a bare `<menu>` element — semantically equivalent to `<ul>` per HTML spec but more meaningful for menu contexts. Place inside a `<nav>` (or use the sidebar-style nav at the layout level) if a navigation landmark is needed.
  * - Nested `<Menu>` instances (typically inside a `<MenuItem>`) get indented via the `.menu .menu` CSS rule.
  *
+ * @kind component
  * @param children The `<MenuItem>` entries to list.
  * @returns The menu element.
  * @example <Menu><MenuItem href="/home">Home</MenuItem></Menu>
@@ -36,6 +37,7 @@ export interface MenuItemProps extends ClickableProps {
  * - Reads the current page URL from `<Meta>` and computes `active` / `proud` against its own `href`.
  * - Splits `children` into `[label, ...after]`: label goes inside the `<a>`; `after` is rendered as siblings below it, only when proud.
  *
+ * @kind component
  * @param href The link target, used to compute `active`/`proud` against the current URL.
  * @param children The label (first node) and optional submenu (remaining nodes).
  * @param props Additional `<Clickable>` props.

package/ui/menu/Menu.js

@@ -15,6 +15,7 @@ const MENU_ACTIVE_CLASS = getModuleClass(MENU_CSS, "active");
  * - Renders as a bare `<menu>` element — semantically equivalent to `<ul>` per HTML spec but more meaningful for menu contexts. Place inside a `<nav>` (or use the sidebar-style nav at the layout level) if a navigation landmark is needed.
  * - Nested `<Menu>` instances (typically inside a `<MenuItem>`) get indented via the `.menu .menu` CSS rule.
  *
+ * @kind component
  * @param children The `<MenuItem>` entries to list.
  * @returns The menu element.
  * @example <Menu><MenuItem href="/home">Home</MenuItem></Menu>
@@ -28,6 +29,7 @@ export function Menu({ children }) {
  * - Reads the current page URL from `<Meta>` and computes `active` / `proud` against its own `href`.
  * - Splits `children` into `[label, ...after]`: label goes inside the `<a>`; `after` is rendered as siblings below it, only when proud.
  *
+ * @kind component
  * @param href The link target, used to compute `active`/`proud` against the current URL.
  * @param children The label (first node) and optional submenu (remaining nodes).
  * @param props Additional `<Clickable>` props.

package/ui/menu/Menu.md

@@ -0,0 +1,51 @@
+# Menu
+
+A `<menu>` list of [`MenuItem`](/ui/MenuItem) children — the container for URL-aware navigation in sidebars, dropdowns, and any other list of links.
+
+**Things to know:**
+
+- Renders as a bare `<menu>` element (semantically equivalent to `<ul>` but more meaningful for menus). Place it inside a `<nav>` — or a [`SidebarLayout`](/ui/SidebarLayout) sidebar, which is already a `<nav>` landmark — if a navigation landmark is needed.
+- Nesting a `<Menu>` inside a [`MenuItem`](/ui/MenuItem) gets indented automatically via the `.menu .menu` descendant rule.
+
+## Usage
+
+```tsx
+import { Menu, MenuItem } from "shelving/ui";
+
+<Menu>
+  <MenuItem href="/dashboard">Dashboard</MenuItem>
+  <MenuItem href="/users">
+    Users
+    <Menu>
+      <MenuItem href="/users/active">Active</MenuItem>
+      <MenuItem href="/users/archived">Archived</MenuItem>
+    </Menu>
+  </MenuItem>
+  <MenuItem href="/settings">Settings</MenuItem>
+</Menu>
+```
+
+## Styling
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--menu-gap` | Vertical gap between items | `var(--space-xxsmall)` |
+| `--menu-font` | Font family | `var(--font-body)` |
+| `--menu-size` | Font size | `var(--size-normal)` |
+| `--menu-leading` | Line height | `var(--leading)` |
+| `--menu-color` | Text colour | `var(--tint-00)` |
+| `--menu-nested-space` | Block margin around a nested submenu | `var(--space-xxsmall)` |
+| `--menu-padding` | Item link padding (also insets the nested border) | `var(--space-xxsmall)` |
+| `--menu-nested-border` | Nested submenu left-border width | `var(--stroke-focus)` |
+| `--menu-nested-color-border` | Nested submenu left-border colour | `var(--tint-50)` |
+| `--menu-nested-indent` | Nested submenu left padding | `var(--space-xsmall)` |
+
+Item-state hooks (`--menu-hover-*`, `--menu-proud-*`, `--menu-active-*`, `--menu-radius`, `--menu-focus-border`) are documented on [`MenuItem`](/ui/MenuItem).
+
+**Global tokens it reads** — the tint ladder `--tint-00` / `--tint-50`, plus `--space-xxsmall` / `--space-xsmall`, `--font-body`, `--size-normal`, `--leading`, and `--stroke-focus`.
+
+## See also
+
+- [`MenuItem`](/ui/MenuItem) — the individual link entries
+- [`SidebarLayout`](/ui/SidebarLayout) — renders a `<nav>` that typically contains a `<Menu>`
+- [`Router`](/ui/Router) — provides the URL context items read

package/ui/menu/Menu.tsx

@@ -25,6 +25,7 @@ export interface MenuProps extends OptionalChildProps {}
  * - Renders as a bare `<menu>` element — semantically equivalent to `<ul>` per HTML spec but more meaningful for menu contexts. Place inside a `<nav>` (or use the sidebar-style nav at the layout level) if a navigation landmark is needed.
  * - Nested `<Menu>` instances (typically inside a `<MenuItem>`) get indented via the `.menu .menu` CSS rule.
  *
+ * @kind component
  * @param children The `<MenuItem>` entries to list.
  * @returns The menu element.
  * @example <Menu><MenuItem href="/home">Home</MenuItem></Menu>
@@ -52,6 +53,7 @@ export interface MenuItemProps extends ClickableProps {
  * - Reads the current page URL from `<Meta>` and computes `active` / `proud` against its own `href`.
  * - Splits `children` into `[label, ...after]`: label goes inside the `<a>`; `after` is rendered as siblings below it, only when proud.
  *
+ * @kind component
  * @param href The link target, used to compute `active`/`proud` against the current URL.
  * @param children The label (first node) and optional submenu (remaining nodes).
  * @param props Additional `<Clickable>` props.