shelving 1.236.2 → 1.237.0

package/ui/menu/MenuItem.md

@@ -0,0 +1,54 @@
+# MenuItem
+
+A single `<li>` link entry inside a [`Menu`](/ui/Menu). It reads the current page URL from the `Meta` context and automatically marks itself `active` (exact match) or `proud` (an ancestor of the current page) — and when proud, reveals its submenu children.
+
+**Things to know:**
+
+- The first child is the link label (rendered inside the `<a>`). Any additional children form the submenu and are rendered only when the item is proud (the current URL starts with the item's `href`). Wrap that submenu in a nested [`Menu`](/ui/Menu) to get the `.menu .menu` indentation.
+- It forwards all `ClickableProps` — `href`, `onClick`, `disabled`, and so on — to the underlying [`Clickable`](/ui/Clickable).
+- `active` and `proud` are computed against the URL from [`Router`](/ui/Router) / [`Navigation`](/ui/Navigation) context.
+
+## Usage
+
+```tsx
+import { Menu, MenuItem } from "shelving/ui";
+
+<Menu>
+  <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
+
+The item link's hooks (defined in `Menu.module.css`):
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--menu-padding` | Link inner padding | `var(--space-xxsmall)` |
+| `--menu-radius` | Link corner radius | `var(--radius-xxsmall)` |
+| `--menu-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
+| `--menu-hover-background` | Link fill on hover/focus | `var(--tint-90)` |
+| `--menu-hover-color` | Link text colour on hover/focus | `var(--tint-00)` |
+| `--menu-proud-background` | Fill when proud (ancestor of current page) | `transparent` |
+| `--menu-proud` | Text colour when proud | `var(--tint-00)` |
+| `--menu-proud-weight` | Font weight when proud | `var(--weight-strong)` |
+| `--menu-active-background` | Fill when active (current page) | `var(--tint-100)` |
+| `--menu-active-color` | Text colour when active | `var(--tint-00)` |
+| `--menu-active-weight` | Font weight when active | `var(--weight-strong)` |
+
+List-level hooks (`--menu-gap`, `--menu-color`, the nested-submenu hooks, etc.) are documented on [`Menu`](/ui/Menu).
+
+**Global tokens it reads** — the tint ladder `--tint-00` / `--tint-90` / `--tint-100`, plus `--space-xxsmall`, `--radius-xxsmall`, `--stroke-focus`, `--stroke-normal`, `--color-focus`, and `--weight-strong`.
+
+## See also
+
+- [`Menu`](/ui/Menu) — the `<menu>` container these go inside
+- [`Clickable`](/ui/Clickable) — the link primitive `MenuItem` forwards its props to
+- [`Router`](/ui/Router) — provides the URL context used to compute `active`/`proud`

package/ui/misc/Catcher.d.ts

@@ -48,6 +48,7 @@ type CatcherState = {
  * - Catches render-time errors below it and shows the `as` component (defaults to `<ErrorNotice>`) with the caught `reason`.
  * - Provides a retry callback to descendant `<RetryButton>`s that clears the error and re-renders `children`.
  *
+ * @kind component
  * @example <Catcher><RiskyComponent /></Catcher>
  * @example <Catcher as={ErrorPage}><RiskyComponent /></Catcher>
  * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/Catcher

package/ui/misc/Catcher.js

@@ -36,6 +36,7 @@ export function RetryButton({ children = RETRY_CHILDREN, ...props }) {
  * - Catches render-time errors below it and shows the `as` component (defaults to `<ErrorNotice>`) with the caught `reason`.
  * - Provides a retry callback to descendant `<RetryButton>`s that clears the error and re-renders `children`.
  *
+ * @kind component
  * @example <Catcher><RiskyComponent /></Catcher>
  * @example <Catcher as={ErrorPage}><RiskyComponent /></Catcher>
  * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/Catcher

package/ui/misc/Catcher.md

@@ -0,0 +1,41 @@
+# Catcher
+
+A React error boundary that catches errors thrown anywhere in its subtree and replaces the failed region with a fallback component. Pass `as` to supply a custom error renderer; it defaults to `ErrorNotice` (an inline error notice with a retry button).
+
+**Things to know:**
+
+- `PageCatcher` is a convenience wrapper that renders `ErrorPage` instead — a full-page error display inside a `<CenteredLayout>`.
+- `RetryButton` reads the retry callback from the nearest `Catcher` via context and renders a `<Button>`. It returns `null` when there is no parent catcher to retry.
+- `ErrorNotice` and `ErrorPage` can be used standalone when you need to display a known error without a boundary. Both use `getMessage()` to extract a human-readable message, falling back to `"Unknown error"`.
+
+## Usage
+
+```tsx
+import { PageCatcher, Catcher, ErrorNotice } from "shelving/ui";
+
+// Catch and display errors for a whole page.
+<PageCatcher>
+  <MyPage />
+</PageCatcher>
+
+// Localised error boundary inside a panel.
+<Catcher as={ErrorNotice}>
+  <LiveFeed />
+</Catcher>
+```
+
+```tsx
+import { Catcher, ErrorPage, RetryButton } from "shelving/ui";
+
+// Custom error renderer plus a retry button anywhere in the subtree.
+<Catcher as={ErrorPage}>
+  <RiskyComponent />
+  <RetryButton small />
+</Catcher>
+```
+
+## See also
+
+- [`Notice`](/ui/Notice) — the callout `ErrorNotice` renders inside.
+- [`Button`](/ui/Button) — the element `RetryButton` renders.
+- [`Page`](/ui/Page) — the full-page shell `ErrorPage` renders inside.

package/ui/misc/Catcher.tsx

@@ -80,6 +80,7 @@ type CatcherState = {
  * - Catches render-time errors below it and shows the `as` component (defaults to `<ErrorNotice>`) with the caught `reason`.
  * - Provides a retry callback to descendant `<RetryButton>`s that clears the error and re-renders `children`.
  *
+ * @kind component
  * @example <Catcher><RiskyComponent /></Catcher>
  * @example <Catcher as={ErrorPage}><RiskyComponent /></Catcher>
  * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/Catcher

package/ui/misc/Loading.d.ts

@@ -14,6 +14,7 @@ export interface LoadingProps {
  * - Self-contained inline SVG with a rotating indicator arc; inherits its colour and size from the surrounding text.
  *
  * @returns The spinner element.
+ * @kind component
  * @example <Loading />
  * @see https://dhoulb.github.io/shelving/ui/misc/Loading/Loading
  */

package/ui/misc/Loading.js

@@ -6,6 +6,7 @@ import styles from "./Loading.module.css";
  * - Self-contained inline SVG with a rotating indicator arc; inherits its colour and size from the surrounding text.
  *
  * @returns The spinner element.
+ * @kind component
  * @example <Loading />
  * @see https://dhoulb.github.io/shelving/ui/misc/Loading/Loading
  */

package/ui/misc/Loading.md

@@ -0,0 +1,28 @@
+# Loading
+
+An animated SVG spinner used as a loading indicator. Self-contained inline SVG with a rotating indicator arc that inherits its colour and size from the surrounding text.
+
+**Things to know:**
+
+- Takes no props.
+- `LOADING` is a pre-keyed `<Loading />` element with a stable `key` — drop it straight into `Suspense` fallbacks and lists to avoid unnecessary reconciliation overhead.
+
+## Usage
+
+```tsx
+import { Loading, LOADING } from "shelving/ui";
+
+<Loading />
+
+// Pre-keyed constant for fallbacks and lists.
+<Suspense fallback={LOADING}>
+  <SlowComponent />
+</Suspense>
+
+{busy ? LOADING : children}
+```
+
+## See also
+
+- [`StatusIcon`](/ui/StatusIcon) — uses `<Loading>` for the `"loading"` status.
+- [`Notice`](/ui/Notice) — shows `<Loading>` for a loading notice.

package/ui/misc/Loading.tsx

@@ -18,6 +18,7 @@ export interface LoadingProps {
  * - Self-contained inline SVG with a rotating indicator arc; inherits its colour and size from the surrounding text.
  *
  * @returns The spinner element.
+ * @kind component
  * @example <Loading />
  * @see https://dhoulb.github.io/shelving/ui/misc/Loading/Loading
  */

package/ui/misc/Mapper.md

@@ -0,0 +1,40 @@
+# createMapper
+
+Creates a `[Mapping, Mapper]` component pair backed by a private React context. `Mapper` walks a pre-walked element tree and replaces each matching element type with the registered component; `Mapping` lets a subtree override or extend the dispatch table. This is the right tool when a component renders a tree of typed elements and callers need to swap in their own renderers for specific types.
+
+**Things to know:**
+
+- Each call to `createMapper()` creates its own context — independent mappers don't interfere with each other.
+- Unmapped element types fall through and render as themselves (e.g. an unmapped `<tree-foo>` appears as a raw `<tree-foo>` element).
+- Any extra props passed to `Mapper` (the type parameter `E`) are spread onto every dispatched child, so you can thread shared context like a `path` into each renderer.
+
+## Usage
+
+```tsx
+import { createMapper } from "shelving/ui";
+
+const [TreeMapping, TreeMapper] = createMapper({
+  "tree-element": TreeRow,
+});
+
+// In a consumer — dispatch a pre-walked element tree.
+<TreeMapper>{walkElements(children)}</TreeMapper>
+
+// Override one entry inside a subtree.
+<TreeMapping mapping={{ "tree-element": SpecialTreeRow }}>
+  <TreeMapper>{walkElements(children)}</TreeMapper>
+</TreeMapping>
+```
+
+```tsx
+// With extra props threaded into every dispatched child.
+const [TreeMenuMapping, TreeMenuMapper] = createMapper<{ path?: AbsolutePath }>({
+  "tree-element": TreeMenuItem,
+});
+
+<TreeMenuMapper path="/foo">{queryElements(children, query)}</TreeMenuMapper>
+```
+
+## See also
+
+- [`ui`](/ui) — the component library these element trees are rendered with.

package/ui/misc/Markup.d.ts

@@ -18,6 +18,7 @@ export interface MarkupProps extends Partial<MarkupOptions> {
  * @param children The source markup string to parse and render (renders `null` when empty).
  * @param options Optional `MarkupOptions` overrides (`rules`, `rel`, `url`, `root`, `schemes`).
  * @returns The parsed markup as React nodes, or `null` when `children` is empty.
+ * @kind component
  * @example <Prose><Markup>{`A *bold* word with \`code\`.`}</Markup></Prose>
  * @see https://dhoulb.github.io/shelving/ui/misc/Markup/Markup
  */

package/ui/misc/Markup.js

@@ -9,6 +9,7 @@ import { requireMeta } from "./MetaContext.js";
  * @param children The source markup string to parse and render (renders `null` when empty).
  * @param options Optional `MarkupOptions` overrides (`rules`, `rel`, `url`, `root`, `schemes`).
  * @returns The parsed markup as React nodes, or `null` when `children` is empty.
+ * @kind component
  * @example <Prose><Markup>{`A *bold* word with \`code\`.`}</Markup></Prose>
  * @see https://dhoulb.github.io/shelving/ui/misc/Markup/Markup
  */

package/ui/misc/Markup.md

@@ -0,0 +1,34 @@
+# Markup
+
+Parses a markup string and renders the resulting React nodes inline. Defaults to the full block + inline rule set and resolves links against the current `<Meta>` context, so it's the standard way to render user- or content-authored markup in the UI.
+
+**Things to know:**
+
+- `url` and `root` default to the current `<Meta>` context, so link rules resolve site-absolute and relative hrefs correctly. Override any `MarkupOptions` prop (`rules`, `rel`, `url`, `root`, `schemes`) directly on `<Markup>` for a custom rule set or base URL.
+- Renders `null` when `children` is empty.
+- Wrap in `<Prose>` to give the produced `<p>` / `<ul>` / `<pre>` / etc. the standard prose typography.
+
+## Usage
+
+```tsx
+import { Prose, Markup } from "shelving/ui";
+
+<Prose>
+  <Markup>{article.body}</Markup>
+</Prose>
+```
+
+```tsx
+import { Markup } from "shelving/ui";
+
+// Custom rule set or base URL via MarkupOptions props.
+<Markup rules={INLINE_ONLY} root="https://example.com">
+  {comment.body}
+</Markup>
+```
+
+## See also
+
+- [`Prose`](/ui/Prose) — longform typography wrapper for the rendered markup.
+- [`markup`](/markup) — the markup parser and rule set underlying `<Markup>`.
+- [`Meta`](/ui/Meta) — the page metadata `<Markup>` reads to resolve links.

package/ui/misc/Markup.tsx

@@ -21,6 +21,7 @@ export interface MarkupProps extends Partial<MarkupOptions> {
  * @param children The source markup string to parse and render (renders `null` when empty).
  * @param options Optional `MarkupOptions` overrides (`rules`, `rel`, `url`, `root`, `schemes`).
  * @returns The parsed markup as React nodes, or `null` when `children` is empty.
+ * @kind component
  * @example <Prose><Markup>{`A *bold* word with \`code\`.`}</Markup></Prose>
  * @see https://dhoulb.github.io/shelving/ui/misc/Markup/Markup
  */

package/ui/misc/StatusIcon.d.ts

@@ -18,6 +18,7 @@ export interface StatusIconProps {
  * @param status The status to represent (defaults to `"info"`).
  * @param size Optional icon size (defaults to the current line height).
  * @returns The status icon element.
+ * @kind component
  * @example <StatusIcon status="error" size="large" />
  * @see https://dhoulb.github.io/shelving/ui/misc/StatusIcon/StatusIcon
  */

package/ui/misc/StatusIcon.js

@@ -19,6 +19,7 @@ const STATUS_ICONS = {
  * @param status The status to represent (defaults to `"info"`).
  * @param size Optional icon size (defaults to the current line height).
  * @returns The status icon element.
+ * @kind component
  * @example <StatusIcon status="error" size="large" />
  * @see https://dhoulb.github.io/shelving/ui/misc/StatusIcon/StatusIcon
  */

package/ui/misc/StatusIcon.md

@@ -0,0 +1,25 @@
+# StatusIcon
+
+Renders the icon for a given status, coloured to match. Picks a heroicon per status (`success`, `error`, `warning`, etc.) and uses the animated `<Loading>` spinner for `"loading"`.
+
+**Things to know:**
+
+- `status` defaults to `"info"` (an info icon) when unset.
+- Size it via the `size` prop (`"small"`, `"normal"`, `"large"`, `"xlarge"`, or `"xxlarge"`); defaults to the current line height.
+- Has no own styling hooks — it paints from the shared status colours and inherits its size from the surrounding text.
+
+## Usage
+
+```tsx
+import { StatusIcon } from "shelving/ui";
+
+<StatusIcon status="success" size="large" />
+<StatusIcon status="error" />
+<StatusIcon status="loading" size="small" />
+```
+
+## See also
+
+- [`Loading`](/ui/Loading) — the spinner used for the `"loading"` status.
+- [`Notice`](/ui/Notice) — uses `<StatusIcon>` as its default icon.
+- [`Tag`](/ui/Tag) — inline label sharing the same status vocabulary.

package/ui/misc/StatusIcon.tsx

@@ -35,6 +35,7 @@ export interface StatusIconProps {
  * @param status The status to represent (defaults to `"info"`).
  * @param size Optional icon size (defaults to the current line height).
  * @returns The status icon element.
+ * @kind component
  * @example <StatusIcon status="error" size="large" />
  * @see https://dhoulb.github.io/shelving/ui/misc/StatusIcon/StatusIcon
  */

package/ui/misc/Tag.d.ts

@@ -33,6 +33,7 @@ export interface TagProps extends TagVariants, ClickableProps {
  *
  * @param props Tag styling variants and clickable props.
  * @returns The tag element.
+ * @kind component
  * @example <Tag success>Active</Tag>
  * @example <Tag color="purple" href="/beta">Beta</Tag>
  * @see https://dhoulb.github.io/shelving/ui/misc/Tag/Tag

package/ui/misc/Tag.js

@@ -25,6 +25,7 @@ export function getTagClass(variants) {
  *
  * @param props Tag styling variants and clickable props.
  * @returns The tag element.
+ * @kind component
  * @example <Tag success>Active</Tag>
  * @example <Tag color="purple" href="/beta">Beta</Tag>
  * @see https://dhoulb.github.io/shelving/ui/misc/Tag/Tag

package/ui/misc/Tag.md

@@ -0,0 +1,47 @@
+# Tag
+
+A small inline label used to annotate other content. Accepts a status variant or a raw colour, and can be static or interactive depending on whether `href` / `onClick` is set.
+
+**Things to know:**
+
+- Delegates to `<Clickable>` — renders as `<a>` when `href` is set, otherwise `<button>`.
+- Accepts a status variant (`success`, `info`, `error`, etc.) _or_ a raw colour (`color="red"`, `color="purple"`, etc.). Use `status` for semantic meaning and `color` for purely decorative differentiation.
+- Composes status, colour, and typography styling variants.
+
+## Usage
+
+```tsx
+import { Tag } from "shelving/ui";
+
+<Tag success>Active</Tag>
+<Tag warning href="/billing">Overdue</Tag>
+<Tag color="purple" size="small">Beta</Tag>
+```
+
+## Styling
+
+`Tag` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Move `--tag-tint` to recolour the whole tag at once.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--tag-tint` | Tint anchor for the tag scope | `inherit` (flows from `color=` / `status=` / parent) |
+| `--tag-background` | Surface fill | `var(--tint-50)` |
+| `--tag-hover-background` | Surface fill when an interactive tag is hovered | `var(--tint-55)` |
+| `--tag-color` | Text colour | `var(--tint-100)` |
+| `--tag-padding` | Inner padding | `0 var(--space-xxsmall)` |
+| `--tag-border` | Border shorthand | `0` |
+| `--tag-radius` | Corner radius | `var(--radius-xxsmall)` |
+| `--tag-font` | Font family | `var(--font-body)` |
+| `--tag-size` | Font size | `var(--size-small)` |
+| `--tag-weight` | Font weight | `var(--weight-strong)` |
+| `--tag-leading` | Line height | `var(--leading)` |
+| `--tag-case` | Text transform | `var(--case-label)` |
+| `--tag-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
+
+**Global tokens it reads** — the tint ladder `--tint-50` / `--tint-55` / `--tint-100`, plus `--space-xxsmall`, `--radius-xxsmall`, `--font-body`, `--size-small`, `--weight-strong`, `--leading`, `--case-label`, `--stroke-normal`, `--stroke-focus`, and `--color-focus`.
+
+## See also
+
+- [`StatusIcon`](/ui/StatusIcon) — pairs a status with its matching icon.
+- [`Notice`](/ui/Notice) — block-level status callout sharing the same status vocabulary.
+- [`ui`](/ui) — the styling system: tint ladder, cascade layers, and theming.

package/ui/misc/Tag.tsx

@@ -46,6 +46,7 @@ export interface TagProps extends TagVariants, ClickableProps {}
  *
  * @param props Tag styling variants and clickable props.
  * @returns The tag element.
+ * @kind component
  * @example <Tag success>Active</Tag>
  * @example <Tag color="purple" href="/beta">Beta</Tag>
  * @see https://dhoulb.github.io/shelving/ui/misc/Tag/Tag

package/ui/notice/Notice.d.ts

@@ -22,6 +22,7 @@ export interface NoticeProps extends FlexVariants, ColorVariants, StatusVariants
  * @param icon Optional icon override (`false`/`null` hides it; defaults to the matching `<StatusIcon>`).
  * @param props Flex, colour, and status styling variants.
  * @returns The notice callout element.
+ * @kind component
  * @example <Notice status="success">Saved your changes</Notice>
  * @see https://dhoulb.github.io/shelving/ui/notice/Notice/Notice
  */

package/ui/notice/Notice.js

@@ -16,6 +16,7 @@ import NOTICE_CSS from "./Notice.module.css";
  * @param icon Optional icon override (`false`/`null` hides it; defaults to the matching `<StatusIcon>`).
  * @param props Flex, colour, and status styling variants.
  * @returns The notice callout element.
+ * @kind component
  * @example <Notice status="success">Saved your changes</Notice>
  * @see https://dhoulb.github.io/shelving/ui/notice/Notice/Notice
  */

package/ui/notice/Notice.md

@@ -0,0 +1,53 @@
+# Notice
+
+A block-level status callout with an icon and message, used to highlight feedback. Rendered as an `<aside>` with a status icon and a message, mapping its `status` to the appropriate colour and ARIA role.
+
+**Things to know:**
+
+- Shows a `<StatusIcon>` for the current `status` by default; pass `icon` to override, or `false` / `null` to hide it.
+- Sets an ARIA `role` of `"alert"` for `error` / `danger` statuses, otherwise `"status"`.
+- `LOADING_NOTICE` is a shared `<Notice status="loading" />` element ready to drop into `Suspense` fallbacks.
+
+## Usage
+
+```tsx
+import { Notice } from "shelving/ui";
+
+<Notice status="success">Your changes have been saved.</Notice>
+<Notice status="error">Something went wrong.</Notice>
+<Notice status="loading" />
+```
+
+```tsx
+import { LOADING_NOTICE } from "shelving/ui";
+
+<Suspense fallback={LOADING_NOTICE}>
+  <SlowPanel />
+</Suspense>
+```
+
+## Styling
+
+`Notice` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Move `--notice-tint` to recolour everything at once.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--notice-tint` | Tint anchor for the notice scope | `inherit` (flows from `color=` / `status=` / parent) |
+| `--notice-background` | Surface fill | `var(--tint-90)` |
+| `--notice-color` | Text colour | `var(--tint-50)` |
+| `--notice-border` | Border shorthand | `var(--notice-stroke) solid var(--tint-80)` |
+| `--notice-stroke` | Border thickness | `var(--stroke-normal)` (2px) |
+| `--notice-radius` | Corner radius | `var(--radius-xsmall)` |
+| `--notice-padding` | Inner padding | `var(--space-small)` |
+| `--notice-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` |
+| `--notice-size` | Font size | `var(--size-normal)` |
+| `--notice-weight` | Font weight | `var(--weight-strong)` |
+
+**Global tokens it reads** — the tint ladder `--tint-50` / `--tint-80` / `--tint-90`, plus `--space-paragraph`, `--space-small`, `--radius-xsmall`, `--stroke-normal`, `--size-normal`, and `--weight-strong`.
+
+## See also
+
+- [`Notices`](/ui/Notices) — the global list that renders incoming notices as `<Notice>` elements.
+- [`StatusIcon`](/ui/StatusIcon) — the default icon shown for the notice's status.
+- [`notify`](/ui/notify) — dispatch notices into the global `<Notices>` list.
+- [`ui`](/ui) — the styling system: tint ladder, cascade layers, and theming.

package/ui/notice/Notice.tsx

@@ -28,6 +28,7 @@ export interface NoticeProps extends FlexVariants, ColorVariants, StatusVariants
  * @param icon Optional icon override (`false`/`null` hides it; defaults to the matching `<StatusIcon>`).
  * @param props Flex, colour, and status styling variants.
  * @returns The notice callout element.
+ * @kind component
  * @example <Notice status="success">Saved your changes</Notice>
  * @see https://dhoulb.github.io/shelving/ui/notice/Notice/Notice
  */

package/ui/notice/Notices.d.ts

@@ -14,6 +14,7 @@ export interface NoticesProps extends FlexVariants {
  *
  * @param props Flex styling variants for the container.
  * @returns The notices container element.
+ * @kind component
  * @example <Notices column />
  * @see https://dhoulb.github.io/shelving/ui/notice/Notices/Notices
  */

package/ui/notice/Notices.js

@@ -15,6 +15,7 @@ const NOTICES_CLASS = getModuleClass(NOTICES_CSS, "notices");
  *
  * @param props Flex styling variants for the container.
  * @returns The notices container element.
+ * @kind component
  * @example <Notices column />
  * @see https://dhoulb.github.io/shelving/ui/notice/Notices/Notices
  */

package/ui/notice/Notices.md

@@ -0,0 +1,59 @@
+# Notices
+
+Renders the global list of active notices and subscribes to incoming `"notice"` events. It listens for `"notice"` events on `window` (dispatched by the `notify` helpers) and shows each one as a `<Notice>` — this is how components like `<Button>` and `<FormNotify>` send notices into the global list.
+
+**Things to know:**
+
+- Mount `<Notices>` once near the root of your app. It renders at that point in the DOM and listens automatically — no context required.
+- Notices auto-dismiss after a short delay unless they carry a `"loading"` status.
+- Backed by the `NOTICES` store singleton; for advanced use you can keep a reference to a notice to update or close it manually.
+
+## Usage
+
+Mount once near the root of your app:
+
+```tsx
+import { Notices } from "shelving/ui";
+
+export function AppLayout({ children }) {
+  return (
+    <>
+      {children}
+      <Notices />
+    </>
+  );
+}
+```
+
+Dispatch notices from anywhere — no context required:
+
+```tsx
+import { notifySuccess, notifyError, callNotified } from "shelving/ui";
+
+notifySuccess("Profile updated.");
+notifyError("Could not connect.");
+
+// Wrap an async callback — dispatches success or error automatically.
+callNotified(async () => {
+  await saveProfile(data);
+  return "Profile updated.";
+});
+```
+
+Programmatic control via the `NOTICES` singleton:
+
+```tsx
+import { NOTICES } from "shelving/ui";
+
+// Show a loading notice and hold a reference to it.
+const notice = NOTICES.show(undefined, "loading");
+await uploadFile(file);
+notice.show("Upload complete.", "success"); // Update in place.
+notice.close(); // Or close it immediately.
+```
+
+## See also
+
+- [`Notice`](/ui/Notice) — the callout each entry in the list is rendered as.
+- [`notify`](/ui/notify) — `notify`, `notifySuccess`, `notifyError`, `callNotified`, and `subscribeNotices`.
+- [`store`](/store) — `ArrayStore` and `DataStore` that the notices store layer extends.

package/ui/notice/Notices.tsx

@@ -23,6 +23,7 @@ export interface NoticesProps extends FlexVariants {}
  *
  * @param props Flex styling variants for the container.
  * @returns The notices container element.
+ * @kind component
  * @example <Notices column />
  * @see https://dhoulb.github.io/shelving/ui/notice/Notices/Notices
  */

package/ui/page/HTML.d.ts

@@ -12,6 +12,7 @@ export interface HTMLProps extends PossibleMeta, ChildProps {
  * Render the full `<html>` document shell wrapping `<head>` and `<body>`.
  * - Emits the literal `<head>` with `<base>` and other shell-level metadata; per-page hoistable elements (title, meta, links, stylesheets, scripts) come from `<Head>` inside `<Page>` and are hoisted into this `<head>` by React 19.
  *
+ * @kind component
  * @param children The document body content.
  * @param meta Initial meta (language/root/app) merged with the surrounding `<Meta>` context.
  * @returns The `<html>` document element.

package/ui/page/HTML.js

@@ -4,6 +4,7 @@ import { MetaContext, requireMeta } from "../misc/MetaContext.js";
  * Render the full `<html>` document shell wrapping `<head>` and `<body>`.
  * - Emits the literal `<head>` with `<base>` and other shell-level metadata; per-page hoistable elements (title, meta, links, stylesheets, scripts) come from `<Head>` inside `<Page>` and are hoisted into this `<head>` by React 19.
  *
+ * @kind component
  * @param children The document body content.
  * @param meta Initial meta (language/root/app) merged with the surrounding `<Meta>` context.
  * @returns The `<html>` document element.

package/ui/page/HTML.md

@@ -0,0 +1,36 @@
+# HTML
+
+The full `<html>` document shell, wrapping `<head>` and `<body>`. Use it as the outermost wrapper for server-side rendering — it owns the literal `<head>` (charset, `<base>`, app `<title>`) while per-page hoistable tags come from [`Page`](/ui/Page).
+
+**Things to know:**
+
+- Accepts `PossibleMeta` props (`app`, `root`, `url`, `title`, `description`, `language`, `tags`, `links`, `stylesheets`, `modules`, `scripts`) and merges them into the `Meta` context it provides to children.
+- `<base>` lives only here — it is not a hoistable element, unlike the title/meta/link/script tags that [`Page`](/ui/Page) emits and React 19 lifts into this `<head>`.
+- Pass the request URL so the tree can match routes during SSR.
+
+## Usage
+
+```tsx
+import { HTML, Page } from "shelving/ui";
+import { Navigation, Router } from "shelving/ui";
+
+// Server-side render — pass the request URL to <HTML>.
+renderToString(
+  <HTML app="My App" root="https://example.com/" url={requestUrl} language="en">
+    <Navigation>
+      <Router routes={{
+        "/": HomePage,
+        "/about": AboutPage,
+      }}/>
+    </Navigation>
+  </HTML>
+);
+```
+
+For client-side-only roots that don't need an `<html>` shell, use `<App>` from [`ui`](/ui) instead.
+
+## See also
+
+- [`Page`](/ui/Page) — wraps a single page and emits its hoistable head tags
+- [`Head`](/ui/Head) — the low-level emitter `Page` renders for you
+- [`Navigation`](/ui/Navigation) / [`Router`](/ui/Router) — URL-driven rendering inside the shell