shelving 1.236.2 → 1.237.0

package/ui/misc/README.md

@@ -1,121 +0,0 @@
-# Misc
-
-Cross-cutting utilities and components that don't belong to a single content category. These are the primitives other components in [ui](/ui) are built from — error handling, status colouring, markdown rendering, element dispatch, and page metadata.
-
-## Error boundaries
-
-`Catcher` is a React class component that catches errors thrown anywhere in its subtree and replaces the failed region with a fallback UI. Pass `as` to supply a custom error renderer; it defaults to `ErrorNotice` (an inline error notice with a retry button). `PageCatcher` is a convenience wrapper that uses `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>`. Returns `null` when there is no parent catcher.
-
-`ErrorNotice` and `ErrorPage` can be used standalone when you need to display a known error without a boundary.
-
-```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>
-```
-
-## Status and colour
-
-`Status` is the type (`"loading" | "info" | "success" | "warning" | "danger" | "error"`) and `StatusProps` is the matching props interface — a `status="error"` prop plus boolean aliases (`<Notice error>`). Use these as the canonical vocabulary for component state everywhere in the UI.
-
-`getStatusClass` maps a `Status` string or `StatusProps` object to a CSS module class. Compose it with other class helpers when building components that need status colouring.
-
-`Color` (from [ui/style](../style/)) exports `ColorProps` — a `color` prop taking a raw hue (`"red"`, `"blue"`, `"purple"`, `"green"`, etc.) — and `getColorClass`. Use `status` for semantic meaning and `color` for purely decorative differentiation.
-
-`getTypographyClass` (from `Typography`) returns a class for the `size` prop (`size="small"` … `size="xxlarge"`), the `tint` prop, and the font-family (`code`, `sans`, `serif`, …) and alignment variants. Compose into components that need typography overrides without wrapping in an extra element.
-
-## Loading spinner
-
-`Loading` renders an animated SVG spinner. `LOADING` is a pre-keyed `<Loading />` constant — use it directly to avoid unnecessary reconciliation overhead.
-
-```tsx
-import { LOADING } from "shelving/ui";
-
-{busy ? LOADING : children}
-```
-
-## Status icon
-
-`StatusIcon` picks the right icon for a given status and sizes it via the `size` prop (`"small"`, `"normal"`, `"large"`, `"xlarge"`, or `"xxlarge"`; defaults to the current line height). `info` is the default when no `status` prop is set.
-
-```tsx
-import { StatusIcon } from "shelving/ui";
-
-<StatusIcon status="success" size="large" />
-<StatusIcon status="error" />
-<StatusIcon status="loading" size="small" />
-```
-
-## Tag
-
-`Tag` is a small inline label. It accepts both `StatusProps` and `ColorProps`, plus `href` or `onClick` from `ClickableProps`, so it can be static or interactive.
-
-```tsx
-import { Tag } from "shelving/ui";
-
-<Tag success>Active</Tag>
-<Tag warning href="/billing">Overdue</Tag>
-<Tag color="purple" size="small">Beta</Tag>
-```
-
-## Markup renderer
-
-`Markup` parses a markup string and renders the resulting React nodes. It defaults to the full block + inline rule set and resolves links against the current `<Meta>` context. Wrap in `<Prose>` for longform typography.
-
-```tsx
-import { Prose, Markup } from "shelving/ui";
-
-<Prose>
-  <Markup>{article.body}</Markup>
-</Prose>
-```
-
-Override any `MarkupOptions` prop directly on `<Markup>` when you need a custom rule set or a specific base URL.
-
-## Element dispatch: `createMapper`
-
-`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.
-
-```tsx
-import { createMapper } from "shelving/ui";
-
-const [TreeMapping, TreeMapper] = createMapper({
-  "tree-element": TreeRow,
-});
-
-// In a consumer:
-<TreeMapper>{walkElements(children)}</TreeMapper>
-
-// Override one entry in a subtree:
-<TreeMapping mapping={{ "tree-element": SpecialTreeRow }}>
-  <TreeMapper>{walkElements(children)}</TreeMapper>
-</TreeMapping>
-```
-
-## Page metadata context
-
-`MetaContext` is the raw React context holding the current `Meta` (URL, base root, and other page-level properties). It is published by `<HTML>` and consumed internally by `<Markup>`, `<Link>`, `<Router>`, and similar components.
-
-`requireMeta` reads the context and optionally merges in override props — use this in components that need to resolve URLs against the current page.
-
-`requireMetaURL` resolves the current `url` against the meta `root` and returns the meta extended with the site-root-relative `path` and the extracted query `params`. Throws if `url` is unset or sits on a different origin to `root`.
-
-## See also
-
-- [ui/block](/ui/block) — block content components that compose with `Tag`, `Markup`, and `Prose`
-- [ui/inline](/ui/inline) — inline content components
-- [ui/notice](/ui/notice) — `Notice` component used inside `ErrorNotice`
-- [ui/router](/ui/router) — `<Router>` and `<Navigation>` that publish into `MetaContext`
-- [markup](/markup) — the markup parser and rule set underlying `<Markup>`

package/ui/notice/README.md

@@ -1,94 +0,0 @@
-# Notices
-
-Inline and global toast-style notices for user feedback. `<Notice>` is a standalone status banner; `<Notices>` is the global list that listens for dispatched events and shows them automatically.
-
-## Concepts
-
-**`<Notice>`** renders an `<aside>` with a status icon and a message. It accepts a `status` prop (`"info"`, `"success"`, `"error"`, `"danger"`, `"loading"`, etc.) and maps it to the appropriate colour and ARIA role. The icon defaults to `<StatusIcon>` but can be replaced or hidden.
-
-**`<Message>`** is a lighter variant — a `<p>` tag with the same status colours, for short inline feedback inside a form or card rather than a banner.
-
-**`<Notices>`** renders the global list of active notices. It subscribes to `"notice"` events on `window` (dispatched by the `notify` helpers in [ui/util](/ui/util)) and shows each one as a `<Notice>`. Notices auto-dismiss after 5 seconds unless they carry a `"loading"` status.
-
-**`NoticeStore` and `NoticesStore`** are the reactive stores behind `<Notices>`. `NoticesStore` is an `ArrayStore<NoticeStore>` that manages the list. Each `NoticeStore` is a `DataStore` holding one notice's message and status, and removes itself from the list when it closes.
-
-## Basic usage
-
-Place `<Notice>` anywhere to show inline status feedback.
-
-```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" />
-```
-
-When `status` is omitted, `<Notice>` defaults to `"info"` if `children` is present, or `"loading"` if not.
-
-Use `<Message>` for shorter inline feedback inside paragraphs or forms.
-
-```tsx
-import { Message } from "shelving/ui";
-
-<Message status="error">This field is required.</Message>
-```
-
-## Global notices
-
-Mount `<Notices>` once near the root of your app. It renders at that point in the DOM and listens automatically.
-
-```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";
-
-// Direct dispatch.
-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 `NoticesStore`
-
-The global `NOTICES` singleton is exported for advanced use — for example, keeping a reference to a specific notice so you can update or close it manually.
-
-```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);
-
-// Update the same notice in place.
-notice.show("Upload complete.", "success");
-
-// Or close it immediately.
-notice.close();
-```
-
-`NoticeStore` implements `AsyncDisposable`, so it can be used in an `await using` block to close automatically when the scope exits.
-
-## See also
-
-- [ui/util](/ui/util) — `notify`, `notifySuccess`, `notifyError`, `callNotified`, and `subscribeNotices`
-- [store](/store) — `ArrayStore` and `DataStore` that `NoticesStore` and `NoticeStore` extend

package/ui/page/README.md

@@ -1,56 +0,0 @@
-# Page
-
-Document-level components for the HTML shell and per-page metadata. These three components own the `<html>`, `<head>`, and per-page `<title>` / `<meta>` output for a shelving app.
-
-## Components
-
-| Component | Purpose |
-|---|---|
-| `<HTML>` | Renders the full `<html>` document shell with `<head>` and `<body>`. Use this as the outermost wrapper for SSR. |
-| `<Page>` | Wraps one page inside the app. Merges per-page meta props into context and emits hoistable head tags (title, description, meta, links, scripts) that React 19 lifts into `<head>`. Also updates `window.history` to match the page URL. |
-| `<Head>` | Low-level: emits the hoistable tags from the current `Meta` context. `<Page>` renders it automatically — you rarely need it directly. |
-
-`<HTML>` and `<Page>` both accept `PossibleMeta` props (`app`, `root`, `url`, `title`, `description`, `language`, `tags`, `links`, `stylesheets`, `modules`, `scripts`) and merge them into the context they provide to children.
-
-## 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>
-);
-```
-
-## Per-page metadata
-
-```tsx
-function UserPage({ id }: { id: string }) {
-  return (
-    <Page title="User profile" url={`/users/${id}`} description="View user details.">
-      <Section>…</Section>
-    </Page>
-  );
-}
-```
-
-The title is composed with the app name from the surrounding context: `"User profile - My App"`.
-
-## How hoisting works
-
-`<Page>` renders `<Head>` inline. React 19 automatically hoists `<title>`, `<meta>`, `<link>`, and `<script>` elements into the document `<head>`, so you don't need a portal. `<base>` is the exception — it is not hoistable and lives only in `<HTML>`.
-
-## See also
-
-- [`app`](/ui/app) — `<App>` for client-side-only roots (no `<html>` shell needed)
-- [`router`](/ui/router) — `<Navigation>` and `<Router>` for URL-driven rendering
-- [`layout`](/ui/layout) — layouts that go inside `<Page>`

package/ui/router/README.md

@@ -1,186 +0,0 @@
-# Router
-
-Client-side routing for shelving apps.
-
-Two pieces:
-
-| Component       | Job                                                                                            |
-| --------------- | ---------------------------------------------------------------------------------------------- |
-| `<Navigation>`  | One per app. Owns URL state, intercepts link clicks, listens for `popstate`.                  |
-| `<Router>`      | Pure matcher. Reads URL from `<Meta>`, matches `routes`, renders the matched element.         |
-
-Plus `requireNavigation()` for imperative `forward()` / `redirect()` calls from anywhere in the tree.
-
-`<Router>` reads URL state from `<Meta>`, so it works with no `<Navigation>` at all (SSR, static rendering, tests). `<Navigation>` is what publishes a *live* URL into `<Meta>` on the client.
-
-## Basic setup
-
-```tsx
-<HTML url={initialUrl} root="https://example.com/">
-  <Navigation>
-    <Router routes={{
-      "/": HomePage,
-      "/users/{id}": UserPage,
-      "/about": AboutPage,
-    }}/>
-  </Navigation>
-</HTML>
-```
-
-- Route keys are `AbsolutePath` strings starting with `/`.
-- Placeholders (`{id}`, `:id`, `[id]`, `${id}`, `{{id}}`) are passed to function/component routes as props (merged with URL `?query` params; placeholders win on conflict).
-- A string value (e.g. `"/users/123"`) is a redirect — visiting the key path navigates to the target.
-- `<Router>` itself accepts `PossibleMeta` props (`url`, `base`, etc.) to override the surrounding context.
-
-## Route value types
-
-| Value                 | Behaviour                                                              |
-| --------------------- | ---------------------------------------------------------------------- |
-| `RouteComponent`      | Rendered as `<Component {...params}/>` with merged placeholder + query. |
-| `AbsolutePath` string | Redirects to that path (placeholders resolved against the source).      |
-| `ReactElement`        | Rendered as-is — use for layout wrapping or composing inner routers.    |
-
-## Placeholder syntax
-
-All forms produce the same matched value — pick whichever reads best:
-
-| Form              | Single segment         | Catchall (one+ segments, also matches empty) |
-| ----------------- | ---------------------- | -------------------------------------------- |
-| Anonymous         | `*` (named `"0"`)      | `**` / `***` / `****` (named `"0"`)          |
-| Colon             | `:name`                | `:name*` / `:name**`                         |
-| Single brace      | `{name}`               | `{...name}` / `{name*}` / `{....name}`       |
-| Square bracket    | `[name]`               | `[...name]` / `[name*]`                      |
-| Dollar brace      | `${name}`              | `${...name}` / `${name*}`                    |
-| Double brace      | `{{name}}`             | `{{...name}}` / `{{name*}}`                  |
-
-Modifier chars are tolerant: one-or-more stars and three-or-more dots are all equivalent. So `{path*}`, `{path**}`, `{...path}`, and `{....path}` all behave the same.
-
-Catchall placeholders allow empty values, so a trailing catchall matches the trailing-slash-absent variant too — `/files/{...path}` matches both `/files`, `/files/`, and `/files/a/b/c`.
-
-## Layout wrapping
-
-Put layout JSX as the route value with another `<Router>` inside.
-
-```tsx
-const SIDEBARRED_ROUTES = {
-  "/users": <UsersPage/>,
-  "/users/{id}": <UserPage/>,
-  "/settings": <SettingsPage/>,
-};
-
-<Router routes={{
-  "/": <HomePage/>,
-  "/{...path}": (
-    <SidebarLayout>
-      <Router routes={SIDEBARRED_ROUTES}/>
-    </SidebarLayout>
-  ),
-}}/>
-```
-
-The outer router matches everything, wraps in `<SidebarLayout>`, and hands off to the inner router. Since `<Router>` reads its URL from `<Meta>`, the inner router sees the same URL.
-
-## Section / microsite pattern
-
-A self-contained "section" of the app — its own URL prefix, its own routes — composes via a catchall + a function route value that hands the captured sub-path to a nested router.
-
-```tsx
-<Router routes={{
-  "/": <HomePage/>,
-  "/users/{...path}": ({ path = "/" }) => (
-    <Router routes={{
-      "/": UsersPage,
-      "/{id}": UserPage,
-    }} url={path}/>
-  ),
-}}/>
-```
-
-The outer router captures everything under `/users` into the `path` placeholder, then the inner router treats `path` as its starting URL. The inner router's `"/"` matches the bare `/users`; `/{id}` matches `/users/123`.
-
-Pull that out into a dedicated component for readability:
-
-```tsx
-const USER_ROUTES = {
-  "/": UsersPage,
-  "/{id}": UserPage,
-  "/{id}/edit": UserEditPage,
-};
-
-export function UserRouter({ path = "/" }: { path?: AbsolutePath }) {
-  return <Router routes={USER_ROUTES} url={path}/>;
-}
-
-// then at the call site:
-<Router routes={{
-  "/": <HomePage/>,
-  "/users/{...path}": ({ path }) => <UserRouter path={path}/>,
-  "/blog/{...path}":  ({ path }) => <BlogRouter path={path}/>,
-}}/>
-```
-
-Each section module owns its routes and exposes one component. The top-level router stays a flat list of section prefixes.
-
-## Stacking layouts and sections
-
-The two patterns compose. Wrap a bunch of routes in a layout, then route further inside it:
-
-```tsx
-const SIDEBARRED_ROUTES = {
-  "/": <Dashboard/>,
-  "/users/{...path}":   ({ path }) => <UserRouter path={path}/>,
-  "/blog/{...path}":    ({ path }) => <BlogRouter path={path}/>,
-  "/settings": <SettingsPage/>,
-};
-
-<Router routes={{
-  "/login": <LoginPage/>,                       // no sidebar
-  "/{...path}": (                                // everything else wrapped
-    <SidebarLayout>
-      <Router routes={SIDEBARRED_ROUTES}/>
-    </SidebarLayout>
-  ),
-}}/>
-```
-
-`/login` skips the sidebar. Every other path goes through `<SidebarLayout>` and then the inner router decides what to render — including handing off to section routers via the catchall pattern.
-
-## Navigation
-
-Inside a component, get the navigation store for imperative URL changes:
-
-```tsx
-const nav = requireNavigation();
-nav.forward("/users/123");   // push history
-nav.redirect("/login");       // replace history
-```
-
-Same-origin anchor clicks are intercepted automatically and turned into `forward()` calls. Add a `download` attribute to opt out.
-
-## `<NavigationIsolate>`
-
-Force a full remount of children whenever the URL changes:
-
-```tsx
-<NavigationIsolate>
-  <ExpensiveStatefulThing/>
-</NavigationIsolate>
-```
-
-## SSR / static rendering
-
-`<Router>` has no client requirements — it reads from `<Meta>` and re-renders when context changes. For static rendering, set `url` and `root` on the outer wrapper and skip `<Navigation>`:
-
-```tsx
-renderToString(
-  <HTML url={path} root="https://example.com/">
-    <Router routes={…}/>
-  </HTML>
-);
-```
-
-For client-side SPAs, wrap the same tree in `<Navigation>` for live URL updates.
-
-## Base paths
-
-`root="https://example.com/app/"` is supported. The base path prefix is stripped from the URL before route matching via `matchURLPrefix`. URLs that fall outside the base render as `null` from the router.

package/ui/transition/README.md

@@ -1,80 +0,0 @@
-# Transition
-
-React 19 View Transition wrappers for animated enter and leave effects. Each component wraps its children in React's `<ViewTransition>` and applies a named CSS transition class, so swapping content between renders produces a smooth animation.
-
-## Components
-
-| Component | Default transition | Forward / back |
-|---|---|---|
-| `<FadeTransition>` | `fade` | — |
-| `<CollapseTransition>` | `collapse` | — |
-| `<VerticalTransition>` | `slideDown` | forward: `slideDown`, back: `slideUp` |
-| `<HorizontalTransition>` | `slideRight` | forward: `slideRight`, back: `slideLeft` |
-| `<Transition>` | configurable | configurable |
-
-`<VerticalTransition>` and `<HorizontalTransition>` are direction-aware: they read the transition type set by `setTransitionType()` and choose the correct slide direction.
-
-## Basic usage
-
-Wrap any content that should animate when it mounts or unmounts:
-
-```tsx
-import { FadeTransition } from "shelving/ui";
-
-function Panel({ visible }: { visible: boolean }) {
-  return visible ? (
-    <FadeTransition>
-      <div className="panel">…</div>
-    </FadeTransition>
-  ) : null;
-}
-```
-
-## Direction-aware routing transitions
-
-Set the transition type before a navigation, then wrap routed content in the appropriate transition:
-
-```tsx
-import { HorizontalTransition, setTransitionType } from "shelving/ui";
-
-function navigate(direction: "forward" | "back") {
-  startTransition(() => {
-    setTransitionType(direction);
-    nav.forward(nextUrl);
-  });
-}
-
-// In the layout:
-<HorizontalTransition>
-  <Router routes={ROUTES}/>
-</HorizontalTransition>
-```
-
-When `direction` is `"forward"` the content slides right; when `"back"` it slides left.
-
-## Overlay variant
-
-Add `overlay` to raise the transition group above surrounding content during animation (`z-index: 100`):
-
-```tsx
-<FadeTransition overlay>
-  <Notification/>
-</FadeTransition>
-```
-
-## Custom transitions
-
-Use `<Transition>` directly to specify any transition class names:
-
-```tsx
-<Transition default="zoom" forward="zoomIn" back="zoomOut">
-  {children}
-</Transition>
-```
-
-Class names must correspond to `::view-transition-class()` rules in your CSS.
-
-## See also
-
-- [`router`](/ui/router) — `<Navigation>` triggers route changes that transitions animate
-- [`dialog`](/ui/dialog) — animate dialog enter and leave

package/ui/tree/README.md

@@ -1,78 +0,0 @@
-# Tree components
-
-Shell components for a tree-based documentation site. Given a `TreeElement` from [extract](/extract), these components produce a complete site: a sidebar menu, client-side routing, and a rendered page for every element.
-
-## Concepts
-
-**`<TreeApp>` is the entry point.** It wraps `<App>` with error catching and a sidebar layout, then wires `<Navigation>` and a `<Router>` covering two routes: `/` renders the root via `<TreePage>`, and `/{...path}` passes every deeper URL to `<TreePage>` as well. The sidebar is always a `<TreeSidebar>`.
-
-**`<TreeRouter>` resolves and dispatches.** It resolves the current URL to an element with a single `map.get(path)` against the flattened tree (provided by `<TreeProvider>`), then hands the matched element to the right page renderer via `<TreeRouterMapper>`. It throws `NotFoundError` if nothing matches and no `fallback` is given.
-
-**`<TreeMenu>` and `<TreeSidebar>` build navigation.** `<TreeSidebar>` renders a single home link for the root, then its children via `<TreeMenuMapper>`. `<TreeMenu>` renders a menu from a tree element's children directly. Only generic `tree-element` nodes appear — code symbols are kept off the navigation.
-
-**`<TreeCards>` renders a card list.** It dispatches each child element to a card renderer via `<TreeCardMapper>`; each card links straight to its element's stamped `path`. Used by the page renderers in [ui/docs](/ui/docs) to fill out directory and file pages.
-
-**`<TreeProvider>` flattens the tree — the one transform the UI runs on.** It flattens the tree once (via `flattenTree()`), which stamps a canonical `path` on every element and indexes them into a map keyed by both flat name and canonical path, then shares it on `TreeContext`. Descendants read it with `useTreeMap()`: the router resolves a URL with `map.get(path)`, and cross-references (`<TreeButton>`, breadcrumbs) resolve by flat key (`"Store"`, `"Store.get"`) or canonical path (`"/schema/BooleanSchema"`) and link to the resolved element's `path`. Nested providers merge their maps, so links resolve across a combined set of trees.
-
-**`<TreeBreadcrumbs>` renders an ancestor trail.** Given a page's `path`, it looks each ancestor prefix up in the tree map (so it needs a `<TreeProvider>` above) and renders a `<nav>` of links separated by `›` icons, with section-level block spacing (`BLOCK_CLASS`, overridable via the `space` prop). Works with any tree — the current page is omitted (the page title already names it).
-
-**Mappings — override any renderer.** Each dispatch layer is backed by a `[Mapping, Mapper]` pair created by `createMapper()`. Wrap any subtree with a `*Mapping` component to swap the renderer for a specific element type without touching anything else.
-
-| Exported pair | Element types covered | What it overrides |
-|---|---|---|
-| `TreePageMapping` / `TreePageMapper` | `tree-element`, `tree-documentation` | Full-page renderer |
-| `TreeMenuMapping` / `TreeMenuMapper` | `tree-element`, `tree-documentation` | Sidebar menu item |
-| `TreeCardMapping` / `TreeCardMapper` | `tree-element`, `tree-documentation` | Card in a listing |
-
-## Basic usage
-
-```tsx
-import { TreeApp } from "shelving/ui";
-
-// tree is a TreeElement returned by DirectoryExtractor.
-<TreeApp tree={tree} />
-```
-
-That single line produces a complete documentation site.
-
-## Adding custom routes
-
-Pass extra routes to `<TreeApp>`. They 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) with 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` (sidebar items) and `TreeCardMapping` (cards inside directory listings).
-
-## Using menu and sidebar components directly
-
-For finer layout control, use `<TreeSidebar>` or `<TreeMenu>` outside `<TreeApp>`.
-
-```tsx
-import { TreeMenu, TreeSidebar } from "shelving/ui";
-
-// A home link + children menu combined — the default sidebar.
-<TreeSidebar tree={root} />
-
-// Just the navigation menu from a subtree's children.
-<TreeMenu tree={section} path="/docs" />
-```
-
-## See also
-
-- [extract](/extract) — builds the `TreeElement` tree that `<TreeApp>` consumes
-- [ui/docs](/ui/docs) — the default page and card renderers dispatched by the mappers
-- [ui/router](/ui/router) — `<Navigation>` and `<Router>` wired inside `<TreeApp>`