shelving 1.236.2 → 1.237.0

package/ui/block/README.md

@@ -1,144 +0,0 @@
-# Block content
-
-Block-level components for structuring page content. Every component here maps to a semantic HTML element and applies consistent spacing, typography, and layout from the design system's CSS modules.
-
-## Concepts
-
-### Semantic HTML, no custom markup
-
-Each component is a thin styled wrapper around a single HTML element: `<Card>` renders `<article>`, `<Section>` renders `<section>`, `<Table>` renders `<table>`, and so on. Pick the component whose HTML element fits the semantic meaning — do not reach for a `<Block>` when a `<Section>` or `<List>` is the right choice.
-
-[Section.tsx](./Section.tsx) exports all the standard landmark elements with the same props: `Section`, `Header`, `Footer`, `Nav`, `Aside`, and `Figure`. `<Panel>` is the odd one out — a full-width region that paints the current surface colour, used to break a page into stacked bands.
-
-### Styling props
-
-Block components share the styling props defined in [ui/style](../style/) — see the [ui README](../README.md) for the full system. The ones you'll use most here:
-
-- `space="none"` … `space="xxlarge"` — block margin (top + bottom). Every block has a sensible default; first and last children collapse their outer margins automatically.
-- `color="red"`, `status="error"` — retint the component and everything nested inside it.
-- `size="large"`, `code`, `serif`, `center` — typography overrides.
-- `narrow` / `wide` / `full` — constrain or unconstrain content width within the parent.
-- `gap="small"` — item spacing on `<List>` and flex containers.
-
-### `<Prose>` for longform text
-
-Wrap any block of mixed HTML content (paragraphs, lists, headings, code, tables) in `<Prose>` to apply cohesive longform typography in one step. All the inline and block component styles are applied as a compound class, so raw HTML elements produced by a markdown renderer just work.
-
-### Compound components
-
-Some block components ship multiple pieces intended to compose:
-
-- `Figure` + `Caption` (a `<figure>` with its `<figcaption>`)
-- `Video` + `VideoButtons` + `VideoButton` + `FullscreenVideoButton`
-- `Definitions` (raw `<dt>` / `<dd>` term/value pairs inside a styled `<dl>`)
-- `Address`, `PhysicalAddress`, `EmailAddress`
-
-## Canonical usage examples
-
-### Content card with a heading
-
-```tsx
-import { Card, Paragraph, Subheading } from "shelving/ui";
-
-<Card href="/products/42" title="Open product">
-  <Subheading>Widget Pro</Subheading>
-  <Paragraph>The best widget on the market.</Paragraph>
-</Card>
-```
-
-`href` turns the card into a navigable overlay. Real interactive elements inside (like inline `<Link>` components) stay clickable via `position: relative; z-index: 2` rules in the stylesheet.
-
-`<Card>` also accepts `status` and `color` — `<Card status="error">` for a prominent error panel, `<Card color="purple">` for decorative tinting. The card styles the box and its tint cascades into nested content; compose its contents however the use case needs.
-
-### Structured page section
-
-```tsx
-import { Section, Heading, Definitions } from "shelving/ui";
-
-<Section narrow>
-  <Heading>Account details</Heading>
-  <Definitions>
-    <dt>Name</dt><dd>Alice Smith</dd>
-    <dt>Email</dt><dd>alice@example.com</dd>
-    <dt>Plan</dt><dd>Pro</dd>
-  </Definitions>
-</Section>
-```
-
-`<Title>`, `<Heading>`, and `<Subheading>` render `<h1>`, `<h2>`, and `<h3>` respectively — pick the component that matches the level rather than overriding it with the `level` prop. Use `<Subheading>` for card titles, in-section labels, and panel titles.
-
-### Page banded into panels
-
-```tsx
-import { Panel, Block, Title, Paragraph } from "shelving/ui";
-
-<Panel as="header" color="primary">
-  <Block narrow>
-    <Title>Welcome</Title>
-  </Block>
-</Panel>
-<Panel padding="large">
-  <Block narrow>
-    <Paragraph>Each panel is a full-width band; the inner block constrains the content.</Paragraph>
-  </Block>
-</Panel>
-```
-
-### Prose content from a renderer
-
-```tsx
-import { Prose, Markup } from "shelving/ui";
-
-<Prose>
-  <Markup>{article.body}</Markup>
-</Prose>
-```
-
-Wrap `<Markup>` (or any component that emits raw HTML elements) in `<Prose>` to apply consistent longform typography.
-
-### Flex row of cards
-
-```tsx
-import { Card, Flex, Subheading } from "shelving/ui";
-
-<Flex wrap gap="small">
-  {products.map(p => (
-    <Card key={p.id} href={`/products/${p.id}`}>
-      <Subheading>{p.name}</Subheading>
-    </Card>
-  ))}
-</Flex>
-```
-
-`<Flex>` is a dumb flex box: `column` switches direction, `wrap` allows wrapping, and the justify/align booleans (`left`, `center`, `right`, `between`, `top`, `middle`, `bottom`, …) position children along each axis. It carries no outer spacing of its own.
-
-### Figure with caption
-
-```tsx
-import { Figure, Image, Caption } from "shelving/ui";
-
-<Figure>
-  <Image src="/images/dog.jpg" alt="Golden retriever" />
-  <Caption>A golden retriever at the park</Caption>
-</Figure>
-```
-
-### Video with controls
-
-```tsx
-import { Video, VideoButtons, FullscreenVideoButton } from "shelving/ui";
-
-<Video wide>
-  <video src={stream.url} autoPlay muted playsInline />
-  <VideoButtons>
-    <FullscreenVideoButton />
-  </VideoButtons>
-</Video>
-```
-
-## See also
-
-- [ui/inline](/ui/inline) — inline-level text components used inside block content
-- [ui/misc/Markup](/ui/misc) — renders a markup string into block and inline elements
-- [ui/form](/ui/form) — interactive form elements and buttons
-- [ui/layout](/ui/layout) — page-level layout structures

package/ui/dialog/README.md

@@ -1,80 +0,0 @@
-# Dialog
-
-Overlay components for modals and imperative dialogs. Two approaches: mount a `<Dialog>` declaratively in the tree, or use `DialogsStore` to push dialogs imperatively from anywhere in the app.
-
-## Components
-
-| Export | Purpose |
-|---|---|
-| `<Dialog>` | A native `<dialog>` element opened in modal mode. Closes on backdrop click, on links/buttons inside a `<nav>`, or via `<DialogCloseButton>`. |
-| `<DialogCloseButton>` | A button that closes its nearest wrapping `<dialog>`. Renders an X icon by default. |
-| `<DialogsContext>` | Creates a `DialogsStore` and provides it to descendants. |
-| `<Dialogs>` | Renders the list of dialogs currently in the nearest `DialogsStore`. Mount once near the root of the app. |
-| `DialogsStore` | An `ArrayStore<ReactElement>` with `.show(children)` and `.hideAll()`. Call `requireDialogs()` to get it from any component. |
-| `<Modal>` | A non-blocking `<aside>` overlay for persistent panels (drawers, toasts, side-sheets) — not a `<dialog>`. |
-
-## Declarative usage
-
-Mount `<Dialog>` directly when its lifetime matches a React state variable:
-
-```tsx
-import { Dialog, DialogCloseButton } from "shelving/ui";
-
-function ConfirmDelete({ onConfirm, onClose }: { onConfirm: () => void; onClose: () => void }) {
-  return (
-    <Dialog onClose={onClose}>
-      <p>Delete this item?</p>
-      <button type="button" onClick={onConfirm}>Delete</button>
-      <DialogCloseButton/>
-    </Dialog>
-  );
-}
-
-// In the parent:
-{showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => setShowConfirm(false)}/>}
-```
-
-## Imperative usage with DialogsStore
-
-Set up the context once near the app root, then call `.show()` from any component:
-
-```tsx
-import { DialogsContext, Dialogs, requireDialogs } from "shelving/ui";
-
-// App root — add <Dialogs> alongside your content.
-function AppRoot() {
-  return (
-    <DialogsContext>
-      <AppContent/>
-      <Dialogs/>
-    </DialogsContext>
-  );
-}
-
-// Anywhere in the tree:
-function DeleteButton({ id }: { id: string }) {
-  const dialogs = requireDialogs();
-  const open = () => dialogs.show(
-    <ConfirmDelete id={id} onConfirm={() => handleDelete(id)}/>
-  );
-  return <button type="button" onClick={open}>Delete</button>;
-}
-```
-
-`<Dialogs>` removes a dialog from the DOM 500 ms after it closes, giving CSS animations time to finish.
-
-## Modal
-
-`<Modal>` is an `<aside>` element — use it for persistent overlays that coexist with the page rather than blocking interaction:
-
-```tsx
-<Modal>
-  <NotificationPanel/>
-</Modal>
-```
-
-## See also
-
-- [`notice`](/ui/notice) — inline and global notices (toasts, banners)
-- [`form`](/ui/form) — form components to put inside dialogs
-- [`transition`](/ui/transition) — animate dialog enter / leave

package/ui/docs/README.md

@@ -1,71 +0,0 @@
-# Documentation pages
-
-Page and card renderers for the two tree element types. These are the defaults wired into [ui/tree](/ui/tree) — use them directly if you need a page or card outside the tree shell, or replace them via the `*Mapping` components.
-
-## Element types and their renderers
-
-| Element type | Page renderer | Card renderer |
-|---|---|---|
-| `tree-element` | `TreePage` | `TreeCard` |
-| `tree-documentation` | `DocumentationPage` | `DocumentationCard` |
-
-Each renderer receives the props of its element type (title, name, description, content, children, etc.). Card renderers also accept a `path` prop — the parent's URL path — so each card can compute its own `href` as `joinPath(path, name)`.
-
-## Pages
-
-**`TreePage`** renders a generic `tree-element` (a directory or file): its title, any absorbed prose content via `<Markup>`, then its children as a `<TreeCards>` listing. The `path` prop is threaded down so each child card links to the right path.
-
-**`DocumentationPage`** is the most detailed renderer. Before the title it renders `<TreeBreadcrumbs>` (a trail of links to the page's ancestors, from [ui/tree](/ui/tree)). The title carries a `<DocumentationKind>` tag. Below the title `<DocumentationButtons>` lists the symbol's relations (`member of`, `extends`, `implements`, `overrides`) as links. Then it renders the signature(s) as preformatted blocks (each carries the symbol's name, e.g. `refreshAll(maxAge?: number): Promise<void>`, with `readonly` folded into property signatures), prose content, and conditional sections for parameters, returns, throws, and examples. Child symbols follow as cards.
-
-## Linking between symbols
-
-Three components turn the raw relational metadata the extractor records (`class`, `readonly`, `overrides`, `extends`, `implements`) into navigation:
-
-**`DocumentationButton`** links to another symbol by reference string — a bare name (`"Store"`) or a qualified member (`"Store.get"`). It resolves the reference against the flattened tree map from `<TreeProvider>` (see [ui/tree](/ui/tree)): a hit becomes a link, a miss (e.g. a builtin like `Serializable`) renders as a non-linking label so the text still reads. Defaults to `small plain` button styling.
-
-**`DocumentationButtons`** renders a symbol's relations as a `<nav>` column of labelled `<DocumentationButton>`s — `overrides AbstractStore.get`, `implements Serializable`, `member of Store`, etc. Carries paragraph-level block spacing by default (composes `PARAGRAPH_CLASS`), overridable with the `space` prop. Renders nothing when the symbol has no relations. Used by both `DocumentationPage` and `DocumentationCard`.
-
-(The ancestor breadcrumb trail rendered above the title is `<TreeBreadcrumbs>`, which lives in [ui/tree](/ui/tree) since it works with any tree, not just documentation.)
-
-## Cards
-
-Cards are compact link tiles used in `<TreeCards>` directory listings.
-
-**`TreeCard`** shows the title and prose lead-in inside a `<Card>` linked to the element's path — used for both directories and files.
-
-**`DocumentationCard`** leads with the symbol's signature(s) as monospace `<Subheading>`s (one per overload) — the signature already carries the name (and `readonly` for properties), so there's no separate title or kind tag; the card's *colour* carries the kind. Symbols with no signature (classes, interfaces, modules) fall back to a plain-name heading. Below: its `<DocumentationButtons>` relations (excluding "member of"), and a prose lead-in.
-
-## DocumentationKind
-
-`<DocumentationKind>` renders a colour-coded `<Tag>` for a symbol's `kind` string. Built-in colour map:
-
-| Kind | Colour |
-|---|---|
-| `function` | blue |
-| `class` | purple |
-| `interface` | cyan |
-| `type` | pink |
-| `constant` | green |
-| `method` | orange |
-| `property` | yellow |
-
-Unknown kinds render as an uncoloured tag.
-
-## Usage
-
-The renderers are used automatically via [ui/tree](/ui/tree). To render a single page or card manually, spread element props directly:
-
-```tsx
-import { TreePage, DocumentationPage } from "shelving/ui";
-
-<TreePage {...treeElement.props} />
-<DocumentationPage {...documentationElement.props} />
-```
-
-To replace a renderer for one element type across the whole site, use `<TreePageMapping>` or `<TreeCardMapping>` from [ui/tree](/ui/tree).
-
-## See also
-
-- [ui/tree](/ui/tree) — `<TreeCards>` and the `*Mapping` override mechanism
-- [extract](/extract) — produces the `TreeElement` tree whose props these renderers consume
-- [markup](/markup) — renders the Markdown `content` field carried by each element

package/ui/form/README.md

@@ -1,165 +0,0 @@
-# Forms
-
-Forms and inputs for shelving apps. Build validated, schema-driven forms from a handful of composable pieces, or drop in a single `<Form>` component for a fully automatic experience.
-
-## Concepts
-
-### FormStore — form state
-
-`FormStore` is the brain of every form. It extends `DataStore` and owns:
-
-- The current (partial) field values.
-- A `messages` dictionary — error strings keyed by field name, plus a top-level `""` key for form-wide messages.
-- A `validated` getter that runs the schema and returns fully-typed data or throws a string on failure.
-- A `publish(name, value)` method that validates a single field, writes the result, and stores any per-field error.
-- A `submit(callback)` method that validates the whole form and, if valid, runs the callback.
-
-When `submit` calls the callback and the callback throws a plain **string**, `FormStore` parses it into field messages using the `"fieldName: message"` line format from [schema](/schema). Any non-string throw is surfaced as a global error notice. A successful return value is dispatched as a success notice.
-
-You rarely create `FormStore` directly — `<Form>` does it for you — but you can grab it from context with `requireForm()` when you need it.
-
-### `<Form>` — the outer wrapper
-
-`<Form>` creates a `FormStore` from a `schema` prop, wraps everything in an HTML `<form>`, disables the whole fieldset while busy, and calls `onSubmit` on a valid submit. If you provide no `children`, it renders `<FormFields>` (one auto-input per schema property) followed by `<FormFooter>` (submit button + error message).
-
-```tsx
-import { Form } from "shelving/ui";
-import { DATA, STRING, NumberSchema } from "shelving/schema";
-
-const PRODUCT_SCHEMA = DATA({
-  name: new StringSchema({ title: "Name", min: 1, max: 100 }),
-  price: new NumberSchema({ title: "Price", min: 0 }),
-});
-
-export function NewProductForm() {
-  return (
-    <Form
-      schema={PRODUCT_SCHEMA}
-      submit="Create product"
-      onSubmit={async data => {
-        await createProduct(data);
-        return "Product created"; // dispatched as a success notice
-      }}
-    />
-  );
-}
-```
-
-Pass `data` to pre-populate an edit form. Pass `messages` (a string or dictionary) to seed initial field errors — useful when a server returns validation failures.
-
-### `<Field>` — label + input + error
-
-`<Field>` is the visual wrapper for a single control. It renders a `<label>` with an optional title, description, and inline error message below the input. Use it when composing inputs by hand rather than relying on `<FormFields>`.
-
-```tsx
-<Field title="Email address" message={emailError}>
-  <TextInput name="email" value={email} onValue={setEmail} required />
-</Field>
-```
-
-`<FormField name="…">` combines `<Field>` with `useField()` and `<SchemaInput>` in one step — it reads the schema, current value, and error state from the surrounding `FormContext` automatically.
-
-### Typed input components
-
-Each input is a standalone, controlled component. All extend `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 |
-
-The typed inputs are: `TextInput`, `NumberInput`, `DateInput`, `CheckboxInput`, `RadioInput`, `SelectInput`, `FileInput`, `ArrayInput`, `DictionaryInput`, and `DataInput`. `ArrayInput` and `DictionaryInput` both accept an `items` schema to render a repeatable list of sub-inputs with add/remove buttons.
-
-### `SchemaInput` / `DataInput` — schema-driven rendering
-
-`SchemaInput` inspects a `Schema` instance and renders the right input automatically:
-
-| Schema type | Rendered as |
-|---|---|
-| `StringSchema` | `<TextInput>` |
-| `NumberSchema` | `<NumberInput>` (formatted on blur) |
-| `DateSchema` | `<DateInput>` |
-| `BooleanSchema` | `<CheckboxInput>` |
-| `ChoiceSchema` (≤ 8 options) | `<ChoiceRadioInputs>` |
-| `ChoiceSchema` (> 8 options) | `<SelectInput>` |
-| `ArraySchema` | `<ArrayInput>` |
-| `DictionarySchema` | `<DictionaryInput>` |
-| `DataSchema` | `<DataInput>` |
-
-`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.
-
-### `<Button>`, `<SubmitButton>`, `<Clickable>`
-
-`<Clickable>` renders a `<button>` or an `<a>` depending on whether `onClick` or `href` is provided. It tracks its own busy state and shows a loading spinner when its `onClick` promise is pending. `<Button>` is `<Clickable>` with styling variants (`strong`, `plain`, `outline`, `small`, `primary`, `danger`, `success`, …). `<SubmitButton>` reads the surrounding `FormContext`, disables itself while the form is busy, and defaults to a "Save →" label.
-
-### Popovers and combo inputs
-
-`<Popover>` is a layout primitive: its first child is the trigger, subsequent children appear in a floating panel when `open` is true. `<ButtonPopover>` wraps a `<Button>` trigger; `<ButtonInputPopover>` wraps a `<ButtonInput>` trigger styled to look like an input field. Use these to build date-pickers, tag selectors, and other inputs that need a dropdown panel.
-
-`<QueryInput>` is a ready-made combo box: it renders a schema-driven text input and calls an async `onQuery` callback on each keystroke (debounced), showing results as a radio list in a popover.
-
-### Notices and error surfacing
-
-When an `onSubmit` callback returns a non-empty `ReactNode`, `<Form>` dispatches it as a success notice. When it throws a **string**, the string is parsed into field messages — any line matching `"fieldName: message"` maps to that field's error display; an unmatched remainder appears as the form-wide message shown by `<FormMessage>`. Non-string throws become global error notices.
-
-`<FormMessage>` renders the top-level `""` message inline as a `<Message>`. `<FormNotice>` renders it as a larger `<Notice>` block. `<FormNotify>` (no JSX output) forwards the message to the global notice system via a side effect instead.
-
-## Canonical end-to-end example
-
-```tsx
-import { Form, Field, TextInput, NumberInput, CheckboxInput, SubmitButton, FormMessage } from "shelving/ui";
-import { DATA, StringSchema, NumberSchema, BOOLEAN } from "shelving/schema";
-
-const LISTING_SCHEMA = DATA({
-  title:     new StringSchema({ title: "Title", min: 1, max: 80 }),
-  price:     new NumberSchema({ title: "Price", min: 0 }),
-  published: BOOLEAN,
-});
-
-export function ListingForm({ listing }: { listing?: typeof LISTING_SCHEMA.type }) {
-  return (
-    <Form
-      schema={LISTING_SCHEMA}
-      data={listing}
-      submit={listing ? "Save changes" : "Publish listing"}
-      onSubmit={async data => {
-        await saveListing(data);
-        return listing ? "Listing updated" : "Listing published";
-      }}
-    />
-  );
-}
-```
-
-The default `<Form>` children (`<FormFields>` + `<FormFooter>`) handle layout automatically. Customise by providing explicit children when you need control over field order, groupings, or extra buttons:
-
-```tsx
-<Form schema={LISTING_SCHEMA} data={listing} onSubmit={handleSubmit}>
-  <Field title="Title" required>
-    <FormInput name="title" />
-  </Field>
-  <Field title="Price">
-    <FormInput name="price" />
-  </Field>
-  <FormInput name="published" />
-  <footer>
-    <SubmitButton>Save changes</SubmitButton>
-    <Button plain onClick={onCancel}>Cancel</Button>
-    <FormMessage />
-  </footer>
-</Form>
-```
-
-`<FormInput name="…">` uses `useField()` to pull the current value, error, and schema from context, then delegates to `<SchemaInput>` — so each field automatically renders the correct control type.
-
-## See also
-
-- [schema](/schema) — `DataSchema`, `StringSchema`, `NumberSchema`, `ChoiceSchema`, and other schema types that drive automatic input selection.
-- [ui/form/FormStore](/ui/form/FormStore) — the state class underlying every form.
-- [ui/form/SchemaInput](/ui/form/SchemaInput) — the schema-to-input dispatch component.
-- [ui](/ui) — top-level UI module index.
-- [react](/react) — `useStore`, `useInstance`, and other hooks used internally.

package/ui/inline/README.md

@@ -1,86 +0,0 @@
-# Inline content
-
-Inline-level components for annotating text. Every component here renders a single semantic HTML element — `<Strong>` renders `<strong>`, `<Code>` renders `<code>`, `<Mark>` renders `<mark>` — and applies the matching design-system styles.
-
-## Concepts
-
-### Semantic wrappers
-
-These components exist so that text annotations always carry the correct HTML semantics and class names. Prefer them over raw HTML elements inside React components: `<Strong>` instead of `<strong>`, `<Link href="…">` instead of `<a href="…">`.
-
-### Code family
-
-`Code.tsx` exports four components that all share the same monospace styling:
-
-| 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 |
-
-### `<Link>` delegates to `<Clickable>`
-
-`<Link>` renders an `<a>` when `href` is provided or a `<button>` when `onClick` is provided, via the shared `Clickable` helper. It handles busy state, URL resolution, and active-page highlighting automatically.
-
-### `<When>`, `<Ago>`, `<Until>` — time display
-
-These components format a date as a compact relative string (`in 6d`, `3w ago`) and wrap it in a `<time>` element with a machine-readable `dateTime` attribute and a `title` showing the full date. Pass `full` to append the absolute date alongside the relative one.
-
-- `When` — shows direction: `in 6d` or `3w ago`
-- `Ago` — always backward-looking duration: `6d`
-- `Until` — always forward-looking duration: `6d`
-
-## Canonical usage examples
-
-### Annotated paragraph
-
-```tsx
-import { Strong, Emphasis, Mark, Keyboard, Code, Small } from "shelving/ui";
-
-<p>
-  Press <Keyboard>Ctrl+S</Keyboard> to save. <Strong>Unsaved changes will be lost.</Strong>{" "}
-  Files are stored as <Emphasis>plain text</Emphasis> in{" "}
-  <Mark>UTF-8</Mark> encoding. <Small>Maximum 10 MB.</Small>
-</p>
-```
-
-Use `<Keyboard>` for key combinations, `<Code>` for inline code fragments, and `<Sample>` for program output — they share the same monospace appearance but carry different semantics.
-
-### Link inside body copy
-
-```tsx
-import { Link } from "shelving/ui";
-
-<p>
-  Read our <Link href="/privacy">privacy policy</Link> for details.
-</p>
-```
-
-### Relative timestamp
-
-```tsx
-import { When, Until } from "shelving/ui";
-
-// "in 3d" or "5h ago" with full ISO date as title tooltip
-<span>Last updated <When target={post.updatedAt} /></span>
-
-// Just the forward-looking duration: "in 2w"
-<span>Expires <Until target={subscription.expiresAt} /></span>
-```
-
-### Change tracking
-
-```tsx
-import { Deleted, Inserted } from "shelving/ui";
-
-<p>
-  Price: <Deleted>£9.99</Deleted> <Inserted>£7.99</Inserted>
-</p>
-```
-
-## See also
-
-- [ui/block](/ui/block) — block-level content components that inline components live inside
-- [ui/block/Prose](/ui/block) — applies cohesive longform typography to a subtree of block and inline elements
-- [ui/form/Clickable](/ui/form) — the underlying clickable primitive that `Link` delegates to

package/ui/layout/README.md

@@ -1,71 +0,0 @@
-# Layout
-
-Page-level layout containers. Each layout occupies the full viewport and handles scroll, safe areas, and responsive behaviour so individual pages don't have to.
-
-## Components
-
-| Component | Purpose |
-|---|---|
-| `<SidebarLayout>` | Fixed-width side column next to a scrollable main column. Collapses to an off-canvas drawer on narrow screens. |
-| `<CenteredLayout>` | Centers content horizontally with a narrow max-width. Good for login, registration, error, and focused-form pages. |
-
-`Layout.ts` also exports `useSafeKeyboardArea()` — a hook that adjusts the `--layout-inset-bottom` CSS variable when the on-screen keyboard appears on iOS (a Safari workaround until `interactive-widget` viewport support lands).
-
-## SidebarLayout
-
-```tsx
-import { SidebarLayout, Menu, MenuItem } 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>
-  );
-}
-```
-
-Pass `right` to place the sidebar on the right. The sidebar renders as `<nav>`, so it is a navigation landmark without additional markup. Inside a `<Navigation>` context the drawer closes automatically on route change.
-
-Override the sidebar width and background with CSS custom properties:
-
-```css
---sidebar-layout-width: 280px;
---sidebar-layout-bg: var(--tint-90);
-```
-
-## CenteredLayout
-
-```tsx
-import { CenteredLayout, Section } from "shelving/ui";
-
-function LoginPage() {
-  return (
-    <CenteredLayout>
-      <Section narrow>
-        <LoginForm/>
-      </Section>
-    </CenteredLayout>
-  );
-}
-```
-
-Pass `fullWidth` to remove the max-width constraint when centered positioning is still wanted but the content needs full width.
-
-## Composing with the router
-
-Layouts sit naturally inside `<Router>` route values. See the layout-wrapping pattern in [`router`](/ui/router) for examples of wrapping a group of routes in a shared layout.
-
-## See also
-
-- [`router`](/ui/router) — pattern for wrapping route groups in a shared layout
-- [`menu`](/ui/menu) — `<Menu>` and `<MenuItem>` for sidebar navigation
-- [`app`](/ui/app) — `<App>` wraps the outermost layout on the client
-- [`page`](/ui/page) — `<HTML>` and `<Page>` sit above layouts in the tree

package/ui/menu/README.md

@@ -1,33 +0,0 @@
-# Menu
-
-A `<menu>` list with URL-aware items. `<Menu>` and `<MenuItem>` are the building blocks for navigation in sidebars, dropdowns, and any other list of links.
-
-`<MenuItem>` reads the current page URL from the `Meta` context and automatically marks itself `active` (exact match) or `proud` (ancestor of the current page). When proud, it reveals its submenu children.
-
-## 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>
-```
-
-The first child of `<MenuItem>` is the link label. Any additional children form the submenu and are only rendered when the item is proud (i.e. when the current URL starts with the item's `href`). Nesting a `<Menu>` inside applies the `.menu .menu` indentation rule automatically.
-
-`<MenuItem>` forwards all `ClickableProps` — `href`, `onClick`, `disabled`, and so on.
-
-## See also
-
-- [`layout`](/ui/layout) — `<SidebarLayout>` renders a `<nav>` that typically contains a `<Menu>`
-- [`router`](/ui/router) — provides the URL context `<MenuItem>` reads
-- [`form`](/ui/form) — `<Clickable>` and `<Button>` used as the link primitive inside `<MenuItem>`