shelving 1.236.2 → 1.237.0

package/ui/transition/HorizontalTransition.md

@@ -0,0 +1,44 @@
+# HorizontalTransition
+
+A direction-aware [`Transition`](/ui/Transition) preset that slides its children horizontally — right when moving forward, left when moving back. It reads the active transition type so the slide direction matches the navigation direction.
+
+**Things to know:**
+
+- Defaults to `slideRight`; with the type set to `"forward"` it slides right (`slideRight`), and to `"back"` it slides left (`slideLeft`).
+- Set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback before navigating — see [`Transition`](/ui/Transition).
+- Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
+
+## Usage
+
+```tsx
+import { HorizontalTransition, setTransitionType, requireNavigation } from "shelving/ui";
+import { startTransition } from "react";
+
+function navigate(direction: "forward" | "back", url: string) {
+  const nav = requireNavigation();
+  startTransition(() => {
+    setTransitionType(direction);
+    nav.forward(url);
+  });
+}
+
+// In the layout:
+<HorizontalTransition>
+  <Router routes={ROUTES}/>
+</HorizontalTransition>
+```
+
+## Styling
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--horizontal-transition-size` | Slide distance for the enter/leave keyframes | `25vw` |
+| `--horizontal-transition-duration` | Duration of the slide keyframes | `var(--duration-normal)` |
+
+**Global tokens it reads** — `--duration-normal`.
+
+## See also
+
+- [`VerticalTransition`](/ui/VerticalTransition) — the vertical counterpart
+- [`Transition`](/ui/Transition) — the base wrapper, `overlay`, and `setTransitionType`
+- [`Navigation`](/ui/Navigation) — triggers the route changes this animates

package/ui/transition/HorizontalTransition.tsx

@@ -12,6 +12,7 @@ export interface HorizontalTransitionProps extends TransitionProps {}
 /**
  * Transition that slides its children horizontally — right when moving forward, left when moving back.
  *
+ * @kind component
  * @param props Shared transition variant props plus `children`.
  * @returns A `<Transition>` element configured with the horizontal slide classes.
  * @example <HorizontalTransition>{currentStep}</HorizontalTransition>

package/ui/transition/Transition.d.ts

@@ -18,6 +18,7 @@ export interface TransitionProps extends ChildProps {
  *   - These must correspond to a `::view-transition(.className)` that is set in CSS.
  * - Supports variant classes, e.g. `<Transition overlay>` applies `::view-transition(.overlay)` from `Transition.css`.
  *
+ * @kind component
  * @param props Transition class overrides (`default`/`forward`/`back`) plus `children` and variant props.
  * @returns A `<ViewTransition>` element wrapping the children.
  * @example <Transition default="fade">{content}</Transition>

package/ui/transition/Transition.js

@@ -10,6 +10,7 @@ import "./Transition.css";
  *   - These must correspond to a `::view-transition(.className)` that is set in CSS.
  * - Supports variant classes, e.g. `<Transition overlay>` applies `::view-transition(.overlay)` from `Transition.css`.
  *
+ * @kind component
  * @param props Transition class overrides (`default`/`forward`/`back`) plus `children` and variant props.
  * @returns A `<ViewTransition>` element wrapping the children.
  * @example <Transition default="fade">{content}</Transition>

package/ui/transition/Transition.md

@@ -0,0 +1,70 @@
+# Transition
+
+The base View Transition wrapper. It wraps its children in React 19's `<ViewTransition>` and applies named CSS transition classes, so swapping content between renders produces a smooth animation. Use it directly to specify any transition class names, or reach for a preset variant — [`FadeTransition`](/ui/FadeTransition), [`CollapseTransition`](/ui/CollapseTransition), [`VerticalTransition`](/ui/VerticalTransition), [`HorizontalTransition`](/ui/HorizontalTransition).
+
+**Things to know:**
+
+- Set `default` for the base transition; `forward` and `back` default to it and let you pick a direction-aware variant. The class names must correspond to `::view-transition-old(.className)` / `::view-transition-new(.className)` rules in your CSS.
+- Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`, from `Transition.css`).
+- Direction is driven by the active view-transition type. Call `setTransitionType("forward")` (or `"back"`) inside a `startTransition()` callback before navigating; the variants read that type to choose the correct slide.
+
+## Usage
+
+### Custom transition
+
+```tsx
+import { Transition } from "shelving/ui";
+
+<Transition default="zoom" forward="zoomIn" back="zoomOut">
+  {children}
+</Transition>
+```
+
+### Overlay
+
+```tsx
+import { Transition } from "shelving/ui";
+
+<Transition default="fade" overlay>
+  <Notification/>
+</Transition>
+```
+
+### Setting the direction with `setTransitionType`
+
+```tsx
+import { HorizontalTransition, setTransitionType, requireNavigation } from "shelving/ui";
+import { startTransition } from "react";
+
+function go(direction: "forward" | "back", url: string) {
+  const nav = requireNavigation();
+  startTransition(() => {
+    setTransitionType(direction);
+    nav.forward(url);
+  });
+}
+
+// In the layout — slides right on forward, left on back:
+<HorizontalTransition>
+  <Router routes={ROUTES}/>
+</HorizontalTransition>
+```
+
+## Styling
+
+Transitions are driven by CSS `::view-transition-*` pseudo-element rules keyed on the transition class names, not by per-component `--variable` hooks. `<Transition>` itself only ships the `overlay` rule:
+
+| Variable | Styles | Default |
+|---|---|---|
+| _(none)_ | `<Transition>` exposes no own custom properties | — |
+
+The `overlay` variant sets `z-index: 100` on `::view-transition-group(.overlay)`. The preset variants document their own timing/distance hooks (`--fade-transition-duration`, `--vertical-transition-size` / `-duration`, `--horizontal-transition-size` / `-duration`) on their pages.
+
+**Global tokens it reads** — none directly; the preset variants fall back to `--duration-fast` / `--duration-normal`.
+
+## See also
+
+- [`FadeTransition`](/ui/FadeTransition) — opacity fade preset
+- [`CollapseTransition`](/ui/CollapseTransition) — size collapse preset
+- [`VerticalTransition`](/ui/VerticalTransition) / [`HorizontalTransition`](/ui/HorizontalTransition) — direction-aware slide presets
+- [`Navigation`](/ui/Navigation) — triggers the route changes transitions animate

package/ui/transition/Transition.tsx

@@ -22,6 +22,7 @@ export interface TransitionProps extends ChildProps {
  *   - These must correspond to a `::view-transition(.className)` that is set in CSS.
  * - Supports variant classes, e.g. `<Transition overlay>` applies `::view-transition(.overlay)` from `Transition.css`.
  *
+ * @kind component
  * @param props Transition class overrides (`default`/`forward`/`back`) plus `children` and variant props.
  * @returns A `<ViewTransition>` element wrapping the children.
  * @example <Transition default="fade">{content}</Transition>

package/ui/transition/VerticalTransition.d.ts

@@ -11,6 +11,7 @@ export interface VerticalTransitionProps extends TransitionProps {
 /**
  * Transition that slides its children vertically — down when moving forward, up when moving back.
  *
+ * @kind component
  * @param props Shared transition variant props plus `children`.
  * @returns A `<Transition>` element configured with the vertical slide classes.
  * @example <VerticalTransition>{currentStep}</VerticalTransition>

package/ui/transition/VerticalTransition.js

@@ -4,6 +4,7 @@ import { Transition } from "./Transition.js";
 /**
  * Transition that slides its children vertically — down when moving forward, up when moving back.
  *
+ * @kind component
  * @param props Shared transition variant props plus `children`.
  * @returns A `<Transition>` element configured with the vertical slide classes.
  * @example <VerticalTransition>{currentStep}</VerticalTransition>

package/ui/transition/VerticalTransition.md

@@ -0,0 +1,34 @@
+# VerticalTransition
+
+A direction-aware [`Transition`](/ui/Transition) preset that slides its children vertically — down when moving forward, up when moving back. It reads the active transition type so the slide direction matches the navigation direction.
+
+**Things to know:**
+
+- Defaults to `slideDown`; with the type set to `"forward"` it slides down (`slideDown`), and to `"back"` it slides up (`slideUp`).
+- Set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback before navigating — see [`Transition`](/ui/Transition).
+- Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
+
+## Usage
+
+```tsx
+import { VerticalTransition } from "shelving/ui";
+
+<VerticalTransition>
+  <Router routes={ROUTES}/>
+</VerticalTransition>
+```
+
+## Styling
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--vertical-transition-size` | Slide distance for the enter/leave keyframes | `25vh` |
+| `--vertical-transition-duration` | Duration of the slide keyframes | `var(--duration-normal)` |
+
+**Global tokens it reads** — `--duration-normal`.
+
+## See also
+
+- [`HorizontalTransition`](/ui/HorizontalTransition) — the horizontal counterpart
+- [`Transition`](/ui/Transition) — the base wrapper, `overlay`, and `setTransitionType`
+- [`Navigation`](/ui/Navigation) — triggers the route changes this animates

package/ui/transition/VerticalTransition.tsx

@@ -12,6 +12,7 @@ export interface VerticalTransitionProps extends TransitionProps {}
 /**
  * Transition that slides its children vertically — down when moving forward, up when moving back.
  *
+ * @kind component
  * @param props Shared transition variant props plus `children`.
  * @returns A `<Transition>` element configured with the vertical slide classes.
  * @example <VerticalTransition>{currentStep}</VerticalTransition>

package/ui/tree/TreeApp.d.ts

@@ -24,6 +24,7 @@ export interface TreeAppProps extends PossibleMeta {
  * - Element rendering uses the default mappings on `<TreePage>`, `<TreeMenu>`, `<TreeCards>`.
  *   Override by wrapping with `<TreePageMapping>`, `<TreeMenuMapping>`, or `<TreeCardMapping>`.
  *
+ * @kind component
  * @param props The `tree` to render, optional extra `routes`, and app meta.
  * @returns The configured `<App>` element with sidebar layout and tree routing.
  * @example <TreeApp tree={tree} title="Docs" />

package/ui/tree/TreeApp.js

@@ -13,6 +13,7 @@ import { TreeSidebar } from "./TreeSidebar.js";
  * - Element rendering uses the default mappings on `<TreePage>`, `<TreeMenu>`, `<TreeCards>`.
  *   Override by wrapping with `<TreePageMapping>`, `<TreeMenuMapping>`, or `<TreeCardMapping>`.
  *
+ * @kind component
  * @param props The `tree` to render, optional extra `routes`, and app meta.
  * @returns The configured `<App>` element with sidebar layout and tree routing.
  * @example <TreeApp tree={tree} title="Docs" />

package/ui/tree/TreeApp.md

@@ -0,0 +1,59 @@
+# TreeApp
+
+The entry point for a tree-based documentation site. Given a `TreeElement` from [extract](/extract), `TreeApp` produces a complete site in one line: a sidebar menu, client-side routing, and a rendered page for every element in the tree.
+
+**Things to know:**
+
+- It wraps `<App>` with error catching and a sidebar layout, then wires a [`TreeRouter`](/ui/TreeRouter) inside. The sidebar is always a [`TreeSidebar`](/ui/TreeSidebar) built from the root.
+- The router covers the whole tree: `/` renders the root, and every deeper path resolves the matching descendant — both rendered via the default page renderers ([`TreePage`](/ui/TreePage) for directories/files, [`DocumentationPage`](/ui/DocumentationPage) for symbols).
+- Only directories and files (plus `kind: "module"` symbols) appear in the navigation — code symbols are kept off the sidebar but still get their own pages.
+- Every renderer is overridable. Each dispatch layer is a `[Mapping, Mapper]` pair built by `createMapper()`; wrap the app (or any subtree) in the matching `*Mapping` component to swap a renderer for one element type without touching anything else:
+
+  | Mapping pair | Overrides |
+  |---|---|
+  | [`TreePageMapping`](/ui/TreeRouter) / `TreeRouterMapper` | Full-page renderer (dispatched by [`TreeRouter`](/ui/TreeRouter)) |
+  | [`TreeMenuMapping`](/ui/TreeMenu) / `TreeMenuMapper` | Sidebar menu item |
+  | [`TreeCardMapping`](/ui/TreeCards) / `TreeCardMapper` | Card in a listing |
+
+## Usage
+
+### Basic
+
+```tsx
+import { TreeApp } from "shelving/ui";
+
+// `tree` is a TreeElement returned by DirectoryExtractor (see /extract).
+<TreeApp tree={tree} />
+```
+
+That single line produces a complete documentation site.
+
+### Adding custom routes
+
+Extra `routes` are merged before the tree routes, so they take precedence on conflicts.
+
+```tsx
+<TreeApp tree={tree} routes={{ "/changelog": ChangelogPage }} />
+```
+
+### Overriding a renderer
+
+Wrap the app (or any subtree) in a `*Mapping` component to replace the renderer for one element type.
+
+```tsx
+import { TreeApp, TreePageMapping } from "shelving/ui";
+
+<TreePageMapping mapping={{ "tree-element": MyTreePage }}>
+  <TreeApp tree={tree} />
+</TreePageMapping>
+```
+
+The same pattern works for [`TreeMenuMapping`](/ui/TreeMenu) (sidebar items) and [`TreeCardMapping`](/ui/TreeCards) (cards inside directory listings).
+
+## See also
+
+- [extract](/extract) — builds the `TreeElement` tree that `TreeApp` consumes.
+- [`TreeRouter`](/ui/TreeRouter) — resolves the URL to an element and dispatches it to a page renderer.
+- [`TreeSidebar`](/ui/TreeSidebar) / [`TreeMenu`](/ui/TreeMenu) — the navigation built into the sidebar.
+- [`TreePage`](/ui/TreePage) / [`TreeCards`](/ui/TreeCards) — the default directory/file page and card listing.
+- [`DocumentationPage`](/ui/DocumentationPage) — the default renderer for documented symbols.

package/ui/tree/TreeApp.tsx

@@ -31,6 +31,7 @@ export interface TreeAppProps extends PossibleMeta {
  * - Element rendering uses the default mappings on `<TreePage>`, `<TreeMenu>`, `<TreeCards>`.
  *   Override by wrapping with `<TreePageMapping>`, `<TreeMenuMapping>`, or `<TreeCardMapping>`.
  *
+ * @kind component
  * @param props The `tree` to render, optional extra `routes`, and app meta.
  * @returns The configured `<App>` element with sidebar layout and tree routing.
  * @example <TreeApp tree={tree} title="Docs" />

package/ui/tree/TreeMenu.d.ts

@@ -55,6 +55,7 @@ export interface TreeMenuProps {
  * - To customise renderers for specific types, wrap in `<TreeMenuMapping mapping={…}>`.
  * - Only directories and files appear — code symbols are kept off the navigation.
  *
+ * @kind component
  * @param props The root `tree` element and optional root `path`.
  * @returns A `<Menu>` of navigation links to the root's children.
  * @example <TreeMenu tree={tree} />

package/ui/tree/TreeMenu.js

@@ -54,6 +54,7 @@ export const [TreeMenuMapping, TreeMenuMapper] = createMapper({
  * - To customise renderers for specific types, wrap in `<TreeMenuMapping mapping={…}>`.
  * - Only directories and files appear — code symbols are kept off the navigation.
  *
+ * @kind component
  * @param props The root `tree` element and optional root `path`.
  * @returns A `<Menu>` of navigation links to the root's children.
  * @example <TreeMenu tree={tree} />

package/ui/tree/TreeMenu.md

@@ -0,0 +1,35 @@
+# TreeMenu
+
+A sidebar navigation menu built from the children of a root tree element. Each child renders as a menu item; items with menu-eligible children of their own reveal a nested submenu based on the current URL.
+
+**Things to know:**
+
+- Only directories and files appear, plus documentation symbols of `kind: "module"` — functions, classes, methods, properties, etc. are kept off the navigation (they still get their own pages via [`TreeApp`](/ui/TreeApp)).
+- Each item computes its own href by appending its `name` to the parent `path` (defaulting to `/`).
+- It is a `[Mapping, Mapper]` pair: wrap any subtree in `<TreeMenuMapping mapping={…}>` to swap the per-type menu-item renderer without touching the rest of the site. [`TreeSidebar`](/ui/TreeSidebar) shares this same mapper.
+- Use it directly for finer layout control; otherwise [`TreeApp`](/ui/TreeApp) wires a [`TreeSidebar`](/ui/TreeSidebar) (a home link plus this menu) for you.
+
+## Usage
+
+```tsx
+import { TreeMenu } from "shelving/ui";
+
+// Just the navigation menu from a subtree's children.
+<TreeMenu tree={section} path="/docs" />
+```
+
+Override the menu-item renderer for one element type:
+
+```tsx
+import { TreeApp, TreeMenuMapping } from "shelving/ui";
+
+<TreeMenuMapping mapping={{ "tree-element": MyMenuItem }}>
+  <TreeApp tree={tree} />
+</TreeMenuMapping>
+```
+
+## See also
+
+- [`TreeSidebar`](/ui/TreeSidebar) — a home link plus this menu; the default sidebar.
+- [`TreeApp`](/ui/TreeApp) — wires the sidebar and routing into a complete site.
+- [`TreeCards`](/ui/TreeCards) — the card-listing equivalent for page bodies.

package/ui/tree/TreeMenu.tsx

@@ -84,6 +84,7 @@ export interface TreeMenuProps {
  * - To customise renderers for specific types, wrap in `<TreeMenuMapping mapping={…}>`.
  * - Only directories and files appear — code symbols are kept off the navigation.
  *
+ * @kind component
  * @param props The root `tree` element and optional root `path`.
  * @returns A `<Menu>` of navigation links to the root's children.
  * @example <TreeMenu tree={tree} />

package/ui/tree/TreeSidebar.d.ts

@@ -19,6 +19,7 @@ export interface TreeSidebarProps {
  * - The home link uses `path` as its href (defaulting to `/`). The children's hrefs are computed by appending their `name` to the root's path.
  * - To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
  *
+ * @kind component
  * @param props The root `tree` element and optional root `path`.
  * @returns A `<Menu>` with a home link plus the root's children as navigation items.
  * @example <TreeSidebar tree={tree} />

package/ui/tree/TreeSidebar.js

@@ -9,6 +9,7 @@ import { matchMenuElement, TreeMenuMapper } from "./TreeMenu.js";
  * - The home link uses `path` as its href (defaulting to `/`). The children's hrefs are computed by appending their `name` to the root's path.
  * - To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
  *
+ * @kind component
  * @param props The root `tree` element and optional root `path`.
  * @returns A `<Menu>` with a home link plus the root's children as navigation items.
  * @example <TreeSidebar tree={tree} />

package/ui/tree/TreeSidebar.md

@@ -0,0 +1,24 @@
+# TreeSidebar
+
+The default sidebar for a tree-based site: a single "home" link for the root element, followed by the root's children as a navigation menu. [`TreeApp`](/ui/TreeApp) mounts one of these automatically.
+
+**Things to know:**
+
+- The home link uses `path` as its href (defaulting to `/`); children's hrefs are computed by appending their `name` to the root path.
+- The children render through the same mapper as [`TreeMenu`](/ui/TreeMenu), so customise them by wrapping in `<TreeMenuMapping mapping={…}>`.
+- Only directories, files, and `kind: "module"` symbols appear — code symbols are kept off the navigation.
+- Use it directly for finer layout control outside [`TreeApp`](/ui/TreeApp).
+
+## Usage
+
+```tsx
+import { TreeSidebar } from "shelving/ui";
+
+// A home link + children menu combined — the default sidebar.
+<TreeSidebar tree={root} />
+```
+
+## See also
+
+- [`TreeMenu`](/ui/TreeMenu) — the children menu, usable on its own; shares the override mapper.
+- [`TreeApp`](/ui/TreeApp) — wires this sidebar into the page layout.

package/ui/tree/TreeSidebar.tsx

@@ -24,6 +24,7 @@ export interface TreeSidebarProps {
  * - The home link uses `path` as its href (defaulting to `/`). The children's hrefs are computed by appending their `name` to the root's path.
  * - To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
  *
+ * @kind component
  * @param props The root `tree` element and optional root `path`.
  * @returns A `<Menu>` with a home link plus the root's children as navigation items.
  * @example <TreeSidebar tree={tree} />

package/ui/util/getClass.md

@@ -0,0 +1,55 @@
+# getClass
+
+Joins any mix of class inputs into a single `className` string. These two helpers (`getClass` and `getModuleClass`) appear in almost every component in the library — every component that accepts variant props (`small`, `primary`, `plain`, etc.) uses them to build its `className`.
+
+**Things to know:**
+
+- `getClass(...classes)` accepts strings, `null` / `undefined` (ignored), nested arrays, and `Variants` objects. A `Variants` object is a plain boolean dictionary: keys whose value is strictly `true` are included, all others ignored — so you can pass component `props` straight through and boolean variant flags are picked up automatically.
+- `getModuleClass(module, ...classes)` does the same but maps each resolved class through a CSS module dictionary, yielding only the hashed names that exist in the module. If `module` is a string (the environment doesn't process `.module.css` files) it returns `undefined` silently, so components degrade gracefully.
+- The `Classes` type describes every accepted input form: `string | null | undefined | Classes[] | Variants`.
+
+## Usage
+
+```ts
+import { getClass } from "shelving/ui";
+
+getClass("button", null, { primary: true, small: false });
+// → "button primary"
+
+getClass("box", ["a", "b"]);
+// → "box a b"
+```
+
+```ts
+import { getModuleClass } from "shelving/ui";
+import BUTTON_CSS from "./Button.module.css";
+
+// Pass the base class name then the whole props object.
+getModuleClass(BUTTON_CSS, "button", variants);
+// → hashed class string containing "button" plus any matching true-valued variant keys
+```
+
+The canonical component pattern combines both:
+
+```tsx
+import { getClass, getModuleClass } from "shelving/ui";
+import BUTTON_CSS from "./Button.module.css";
+
+export function Button({ children, ...variants }: ButtonProps): ReactElement {
+  return (
+    <button
+      className={getClass(
+        BLOCK_CLASS, //
+        getModuleClass(BUTTON_CSS, "button", variants),
+      )}
+    >
+      {children}
+    </button>
+  );
+}
+```
+
+## See also
+
+- [`requireContext`](/ui/requireContext) — the other helper at the heart of the component layer.
+- [`ui`](/ui) — the styling system: tint ladder, cascade layers, and theming.

package/ui/util/notify.md

@@ -0,0 +1,50 @@
+# notify
+
+Dispatches a `notice` event so the global `<Notices>` list can display it. This is a thin event bus for toast-style notifications: components dispatch custom events on the DOM and `<Notices>` listens and renders them — no context required.
+
+**Things to know:**
+
+- The event bubbles, so any ancestor subscribed with `subscribeNotices()` receives it; it defaults to dispatching on `window`.
+- A family of helpers builds on `notify`:
+
+| Function | What it does |
+|---|---|
+| `notify(message, status?, el?)` | Dispatch a notice event (defaults to `window`) |
+| `notifySuccess(message, el?)` | Shorthand for a `"success"` notice |
+| `notifyError(message, el?)` | Shorthand for an `"error"` notice |
+| `notifyThrown(thrown, el?)` | Extract a message from a caught value and dispatch an error |
+| `callNotified(callback, ...args)` | Run a callback; dispatch success or error automatically |
+| `awaitNotified(promise)` | Same for an already-pending promise |
+| `subscribeNotices(callback, el?)` | Listen for notice events; returns an unsubscribe function |
+
+## Usage
+
+```ts
+import { notifySuccess, notifyError } from "shelving/ui";
+
+notifySuccess("Profile updated.");
+notifyError("Could not connect.");
+```
+
+```ts
+import { callNotified } from "shelving/ui";
+
+// Return a string for success; throw for error.
+callNotified(async () => {
+  await saveData();
+  return "Saved!";
+});
+```
+
+```ts
+import { subscribeNotices } from "shelving/ui";
+
+const stop = subscribeNotices((message, status) => show(message, status));
+// Call stop() to remove the listener.
+```
+
+## See also
+
+- [`Notices`](/ui/Notices) — the global list that listens for these events and renders them.
+- [`Notice`](/ui/Notice) — the callout each notice is rendered as.
+- [`store`](/store) — the `ArrayStore` / `DataStore` layer behind the global notices.

package/ui/util/requireContext.md

@@ -0,0 +1,24 @@
+# requireContext
+
+Reads a React context and throws `RequiredError` if the value is `null` or `undefined`. Use it instead of `use(context)` when a context must be provided by an ancestor — every `require*()` hook in the library follows this pattern.
+
+**Things to know:**
+
+- Reads the context with React's `use()`, so it must be called inside a component or hook.
+- Treats both `null` and `undefined` as "unset" and throws, naming the context's `displayName` in the message.
+- Pass the calling function as `caller` so the thrown `RequiredError` is attributed to it (defaults to `requireContext` itself).
+
+## Usage
+
+```ts
+import { requireContext } from "shelving/ui";
+
+function requireNavigation(): NavigationStore {
+  return requireContext(NavigationContext, requireNavigation);
+}
+```
+
+## See also
+
+- [`getClass`](/ui/getClass) — the other helper at the heart of the component layer.
+- [`ui/router`](/ui) — uses `requireContext` to read the navigation and meta contexts.

package/ui/app/README.md

@@ -1,32 +0,0 @@
-# App
-
-Root component for a client-side Shelving app. `<App>` applies the theme CSS class to `document.body` and provides a `Meta` context so every descendant can read or update page metadata.
-
-Use `<App>` when mounting into an existing HTML page on the client. For server-side rendering where you need the full `<html>` document shell, use [`<HTML>`](/ui/page) instead.
-
-## Usage
-
-```tsx
-import { App, Navigation, Router } from "shelving/ui";
-
-export function MyApp() {
-  return (
-    <App app="My App" root="https://example.com/" url="/">
-      <Navigation>
-        <Router routes={{
-          "/": HomePage,
-          "/about": AboutPage,
-        }} />
-      </Navigation>
-    </App>
-  );
-}
-```
-
-`<App>` accepts all `PossibleMeta` props (`app`, `root`, `url`, `title`, `language`, `tags`, etc.) and merges them into the context it provides to children. On mount it adds the theme class to `document.body`, which activates the CSS custom property tokens defined in `App.module.css`; on unmount it removes it.
-
-## See also
-
-- [`ui/page`](/ui/page) — `<HTML>` and `<Page>` for the document shell and per-page metadata
-- [`ui/layout`](/ui/layout) — `SidebarLayout` and `CenteredLayout`
-- [`ui/router`](/ui/router) — `<Navigation>` and `<Router>` for client-side routing