npm - shelving - Versions diffs - 1.213.0 → 1.214.0 - Mend

shelving 1.213.0 → 1.214.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.213.0",
+	"version": "1.214.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -35,6 +35,7 @@
 		"./cloudflare": "./cloudflare/index.js",
 		"./db": "./db/index.js",
 		"./error": "./error/index.js",
+		"./extract": "./extract/index.js",
 		"./firestore/client": "./firestore/client/index.js",
 		"./firestore/lite": "./firestore/lite/index.js",
 		"./firestore/server": "./firestore/server/index.js",

package/ui/README.md ADDED Viewed

@@ -0,0 +1,83 @@
+# ui
+A React component library for building Shelving apps — forms, content, layout, routing, dialogs, and the documentation-site components, all in one place.
+The `ui` module exists so an app never hand-rolls the same form field, card, or router twice. Every component picks up its look from shared CSS and exposes its variations as plain boolean props. You build a screen by composing these pieces, and reach for a custom-styled element only when nothing here fits.
+`ui` is consumed as source — it ships `.tsx` and `.module.css` files and needs a bundler that understands CSS Modules and JSX. It is not part of the root `shelving` package; import it from `shelving/ui`.
+## How components work
+A few conventions run through every component (see also the React Components section of `AGENTS.md`):
+- **Variants, not CSS.** Visual options are boolean props — `<Button small primary>`, `<Section narrow>`. Each maps to a class in the component's CSS Module. You never pass `style` or raw `className`.
+- **Composition.** Higher-level components — a `*Page`, a `*Card` — take their identity from library components like `Card`, `Section`, `Button`, and `Tag` rather than shipping their own styling.
+- **Sentence case.** Titles, headings, and button labels capitalise only the first word.
+- **Theming via CSS variables.** Colour and spacing come from CSS custom properties with fallback chains, so a theme is a small set of variable overrides.
+## Module map
+### Content
+| Folder | What's inside |
+|---|---|
+| [block](/ui/block) | Block-level content — `Card`, `Section`, `Heading`, `Table`, `List`, `Prose`, `Figure`, `Flex` |
+| [inline](/ui/inline) | Inline content — `Code`, `Strong`, `Emphasis`, `Link`, `Mark`, `Small` |
+| [misc](/ui/misc) | Cross-cutting pieces — `Markup`, `Tag`, `Status`, `Loading`, `Color`, `Catcher`, `Mapper` |
+### Structure
+| Folder | What's inside |
+|---|---|
+| [app](/ui/app) | The `<App>` root component |
+| [page](/ui/page) | Document-level components — `<HTML>`, `<Head>`, `<Page>` |
+| [layout](/ui/layout) | Page layouts — `SidebarLayout`, `CenteredLayout` |
+| [router](/ui/router) | Client-side routing — `<Navigation>`, `<Router>` |
+### Interaction
+| Folder | What's inside |
+|---|---|
+| [form](/ui/form) | Forms and inputs — `<Form>`, `<Field>`, typed inputs, `<Button>`, `FormStore` |
+| [dialog](/ui/dialog) | `<Dialog>` and `<Modal>` overlays |
+| [menu](/ui/menu) | `<Menu>` and `<MenuItem>` |
+| [notice](/ui/notice) | Inline and global notices |
+| [transition](/ui/transition) | CSS enter / leave transitions |
+### Documentation site
+| Folder | What's inside |
+|---|---|
+| [tree](/ui/tree) | `<TreeApp>` and the components that turn a tree into a site |
+| [docs](/ui/docs) | Page and card renderers for directories, files, and code symbols |
+| [util](/ui/util) | UI helper functions — context, meta, CSS class composition |
+## Quick start
+A minimal single-screen app:
+```tsx
+import { App, CenteredLayout, Section, Heading, Paragraph } from "shelving/ui";
+function HelloApp() {
+  return (
+    <App app="My app">
+      <CenteredLayout>
+        <Section narrow>
+          <Heading>Hello</Heading>
+          <Paragraph>Welcome to the app.</Paragraph>
+        </Section>
+      </CenteredLayout>
+    </App>
+  );
+}
+```
+For a routed, multi-page app, wrap the tree in [`<Navigation>` and `<Router>`](/ui/router). For a documentation site, hand an extracted tree to [`<TreeApp>`](/ui/tree) — see the [extract](/extract) guide.
+## See also
+- [extract](/extract) — builds the tree that the documentation components render
+- [markup](/markup) — Markdown rendering used by `<Markup>` and `<Prose>`
+- [store](/store) — reactive state behind `FormStore`, `NavigationStore`, and notices
+- [react](/react) — store and provider hooks used alongside these components

package/ui/app/README.md ADDED Viewed

@@ -0,0 +1,32 @@
+# 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

package/ui/block/README.md ADDED Viewed

@@ -0,0 +1,115 @@
+# 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>` or `<Flex>` when a `<Section>` or `<List>` is the right choice.
+`Section.tsx` exports all the standard landmark elements under the same variants (`narrow`, `wide`, `spacious`): `Section`, `Header`, `Footer`, `Nav`, and `Aside`.
+### Width and layout variants
+Several layout components accept `narrow` and `wide` boolean props that constrain content width within the parent. `<Flex>` has richer layout control with `column`, `wrap`, `left`, `center`, `right`, `flush`, and `reverse` variants.
+### `<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:
+- `Video` + `VideoButtons` + `VideoButton` + `FullscreenVideoButton`
+- `Definitions` + `Definition` (term/value pairs inside a `<dl>`)
+- `Address`, `PhysicalAddress`, `EmailAddress`
+## Canonical usage examples
+### Content card with a heading
+```tsx
+import { Card, Heading, Paragraph } from "shelving/ui";
+<Card href="/products/42" title="Open product">
+  <Heading level={2}>Widget Pro</Heading>
+  <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.
+### Structured page section
+```tsx
+import { Section, Heading, Definitions, Definition } from "shelving/ui";
+<Section narrow>
+  <Heading>Account details</Heading>
+  <Definitions row>
+    <Definition term="Name">Alice Smith</Definition>
+    <Definition term="Email">alice@example.com</Definition>
+    <Definition term="Plan">Pro</Definition>
+  </Definitions>
+</Section>
+```
+`<Subheading>` uses the same `level` prop as `<Heading>` but applies secondary typography styles — use it for in-section labels and panel titles.
+### 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 { Flex, Card, Heading } from "shelving/ui";
+<Flex wrap>
+  {products.map(p => (
+    <Card key={p.id} href={`/products/${p.id}`}>
+      <Heading level={3}>{p.name}</Heading>
+    </Card>
+  ))}
+</Flex>
+```
+### Figure with caption
+```tsx
+import { Figure, Image } from "shelving/ui";
+<Figure caption="A golden retriever at the park">
+  <Image src="/images/dog.jpg" alt="Golden retriever" />
+</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 ADDED Viewed

@@ -0,0 +1,80 @@
+# 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 ADDED Viewed

@@ -0,0 +1,65 @@
+# Documentation pages
+Page and card renderers for the three 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-directory` | `DirectoryPage` | `DirectoryCard` |
+| `tree-file` | `FilePage` | `FileCard` |
+| `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
+**`DirectoryPage`** renders the directory's title, its `README.md` prose via `<Markup>`, then its children as a `<TreeCards>` listing.
+**`FilePage`** renders the file's title, its prose content, then its child code symbols as `<TreeCards>`. It reads the current URL pathname from context so each symbol card links to the right path.
+**`DocumentationPage`** is the most detailed renderer. It renders: a `<DocumentationKind>` tag, type signatures as preformatted blocks, prose content, and conditional sections for parameters, returns, throws, and examples. Child symbols follow as cards.
+## Cards
+Cards are compact link tiles used in `<TreeCards>` directory listings.
+**`DirectoryCard`** and **`FileCard`** show the title and prose lead-in inside a `<Card>` linked to the element's path.
+**`DocumentationCard`** shows the symbol name alongside its `<DocumentationKind>` tag, the first signature block, 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 { DirectoryPage, FilePage, DocumentationPage } from "shelving/ui";
+<DirectoryPage {...directoryElement.props} />
+<FilePage {...fileElement.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 ADDED Viewed

@@ -0,0 +1,165 @@
+# 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 ADDED Viewed

@@ -0,0 +1,86 @@
+# 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