npm - shelving - Versions diffs - 1.236.2 → 1.237.0 - Mend

shelving 1.236.2 → 1.237.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 (219) hide show

package/extract/IndexExtractor.js +9 -2
package/extract/MergingExtractor.d.ts +3 -1
package/extract/MergingExtractor.js +41 -3
package/extract/TypescriptExtractor.d.ts +1 -0
package/extract/TypescriptExtractor.js +12 -2
package/package.json +1 -1
package/ui/README.md +19 -274
package/ui/app/App.d.ts +1 -0
package/ui/app/App.js +1 -0
package/ui/app/App.md +58 -0
package/ui/app/App.tsx +1 -0
package/ui/block/Card.d.ts +1 -0
package/ui/block/Card.js +1 -0
package/ui/block/Card.md +85 -0
package/ui/block/Card.tsx +1 -0
package/ui/block/Heading.d.ts +1 -0
package/ui/block/Heading.js +1 -0
package/ui/block/Heading.md +70 -0
package/ui/block/Heading.tsx +1 -0
package/ui/block/List.d.ts +1 -0
package/ui/block/List.js +1 -0
package/ui/block/List.md +51 -0
package/ui/block/List.tsx +1 -0
package/ui/block/Panel.d.ts +1 -0
package/ui/block/Panel.js +1 -0
package/ui/block/Panel.md +50 -0
package/ui/block/Panel.tsx +1 -0
package/ui/block/Paragraph.d.ts +1 -0
package/ui/block/Paragraph.js +1 -0
package/ui/block/Paragraph.md +48 -0
package/ui/block/Paragraph.tsx +1 -0
package/ui/block/Prose.d.ts +1 -0
package/ui/block/Prose.js +1 -0
package/ui/block/Prose.md +49 -0
package/ui/block/Prose.tsx +1 -0
package/ui/block/Section.d.ts +6 -0
package/ui/block/Section.js +6 -0
package/ui/block/Section.md +56 -0
package/ui/block/Section.tsx +6 -0
package/ui/block/Subheading.d.ts +1 -0
package/ui/block/Subheading.js +1 -0
package/ui/block/Subheading.md +58 -0
package/ui/block/Subheading.tsx +1 -0
package/ui/block/Table.d.ts +1 -0
package/ui/block/Table.js +1 -0
package/ui/block/Table.md +54 -0
package/ui/block/Table.tsx +1 -0
package/ui/block/Title.d.ts +1 -0
package/ui/block/Title.js +1 -0
package/ui/block/Title.md +57 -0
package/ui/block/Title.tsx +1 -0
package/ui/dialog/Dialog.d.ts +1 -0
package/ui/dialog/Dialog.js +1 -0
package/ui/dialog/Dialog.md +73 -0
package/ui/dialog/Dialog.tsx +1 -0
package/ui/dialog/Modal.d.ts +1 -0
package/ui/dialog/Modal.js +1 -0
package/ui/dialog/Modal.md +40 -0
package/ui/dialog/Modal.tsx +1 -0
package/ui/docs/DocumentationButtons.d.ts +2 -0
package/ui/docs/DocumentationButtons.js +2 -0
package/ui/docs/DocumentationButtons.md +38 -0
package/ui/docs/DocumentationButtons.tsx +2 -0
package/ui/docs/DocumentationCard.d.ts +1 -0
package/ui/docs/DocumentationCard.js +1 -0
package/ui/docs/DocumentationCard.md +35 -0
package/ui/docs/DocumentationCard.tsx +1 -0
package/ui/docs/DocumentationKind.d.ts +1 -1
package/ui/docs/DocumentationKind.js +9 -4
package/ui/docs/DocumentationKind.tsx +10 -5
package/ui/docs/DocumentationPage.d.ts +1 -0
package/ui/docs/DocumentationPage.js +2 -0
package/ui/docs/DocumentationPage.md +46 -0
package/ui/docs/DocumentationPage.tsx +2 -0
package/ui/form/Button.d.ts +1 -0
package/ui/form/Button.js +1 -0
package/ui/form/Button.md +88 -0
package/ui/form/Button.tsx +1 -0
package/ui/form/Field.d.ts +6 -1
package/ui/form/Field.js +6 -1
package/ui/form/Field.md +59 -0
package/ui/form/Field.tsx +6 -1
package/ui/form/Form.d.ts +1 -0
package/ui/form/Form.md +118 -0
package/ui/form/Form.tsx +1 -0
package/ui/form/FormStore.md +47 -0
package/ui/form/SchemaInput.d.ts +1 -0
package/ui/form/SchemaInput.md +64 -0
package/ui/form/SchemaInput.tsx +1 -0
package/ui/inline/Code.d.ts +1 -0
package/ui/inline/Code.js +1 -0
package/ui/inline/Code.md +58 -0
package/ui/inline/Code.tsx +1 -0
package/ui/inline/Link.d.ts +1 -0
package/ui/inline/Link.js +1 -0
package/ui/inline/Link.md +47 -0
package/ui/inline/Link.tsx +1 -0
package/ui/inline/Mark.d.ts +1 -0
package/ui/inline/Mark.js +1 -0
package/ui/inline/Mark.md +40 -0
package/ui/inline/Mark.tsx +1 -0
package/ui/inline/Strong.d.ts +1 -0
package/ui/inline/Strong.js +1 -0
package/ui/inline/Strong.md +34 -0
package/ui/inline/Strong.tsx +1 -0
package/ui/layout/CenteredLayout.d.ts +1 -0
package/ui/layout/CenteredLayout.js +1 -0
package/ui/layout/CenteredLayout.md +38 -0
package/ui/layout/CenteredLayout.tsx +1 -0
package/ui/layout/SidebarLayout.d.ts +1 -0
package/ui/layout/SidebarLayout.js +1 -0
package/ui/layout/SidebarLayout.md +65 -0
package/ui/layout/SidebarLayout.tsx +1 -0
package/ui/menu/Menu.d.ts +2 -0
package/ui/menu/Menu.js +2 -0
package/ui/menu/Menu.md +51 -0
package/ui/menu/Menu.tsx +2 -0
package/ui/menu/MenuItem.md +54 -0
package/ui/misc/Catcher.d.ts +1 -0
package/ui/misc/Catcher.js +1 -0
package/ui/misc/Catcher.md +41 -0
package/ui/misc/Catcher.tsx +1 -0
package/ui/misc/Loading.d.ts +1 -0
package/ui/misc/Loading.js +1 -0
package/ui/misc/Loading.md +28 -0
package/ui/misc/Loading.tsx +1 -0
package/ui/misc/Mapper.md +40 -0
package/ui/misc/Markup.d.ts +1 -0
package/ui/misc/Markup.js +1 -0
package/ui/misc/Markup.md +34 -0
package/ui/misc/Markup.tsx +1 -0
package/ui/misc/StatusIcon.d.ts +1 -0
package/ui/misc/StatusIcon.js +1 -0
package/ui/misc/StatusIcon.md +25 -0
package/ui/misc/StatusIcon.tsx +1 -0
package/ui/misc/Tag.d.ts +1 -0
package/ui/misc/Tag.js +1 -0
package/ui/misc/Tag.md +47 -0
package/ui/misc/Tag.tsx +1 -0
package/ui/notice/Notice.d.ts +1 -0
package/ui/notice/Notice.js +1 -0
package/ui/notice/Notice.md +53 -0
package/ui/notice/Notice.tsx +1 -0
package/ui/notice/Notices.d.ts +1 -0
package/ui/notice/Notices.js +1 -0
package/ui/notice/Notices.md +59 -0
package/ui/notice/Notices.tsx +1 -0
package/ui/page/HTML.d.ts +1 -0
package/ui/page/HTML.js +1 -0
package/ui/page/HTML.md +36 -0
package/ui/page/HTML.tsx +1 -0
package/ui/page/Head.d.ts +1 -0
package/ui/page/Head.js +1 -0
package/ui/page/Head.md +26 -0
package/ui/page/Head.tsx +1 -0
package/ui/page/Page.d.ts +1 -0
package/ui/page/Page.js +1 -0
package/ui/page/Page.md +42 -0
package/ui/page/Page.tsx +1 -0
package/ui/router/Navigation.d.ts +1 -0
package/ui/router/Navigation.js +1 -0
package/ui/router/Navigation.md +41 -0
package/ui/router/Navigation.tsx +1 -0
package/ui/router/NavigationStore.md +34 -0
package/ui/router/Router.d.ts +1 -0
package/ui/router/Router.js +1 -0
package/ui/router/Router.md +143 -0
package/ui/router/Router.tsx +1 -0
package/ui/style/TINT_CLASS.md +55 -0
package/ui/transition/CollapseTransition.d.ts +1 -0
package/ui/transition/CollapseTransition.js +1 -0
package/ui/transition/CollapseTransition.md +34 -0
package/ui/transition/CollapseTransition.tsx +1 -0
package/ui/transition/FadeTransition.d.ts +1 -0
package/ui/transition/FadeTransition.js +1 -0
package/ui/transition/FadeTransition.md +36 -0
package/ui/transition/FadeTransition.tsx +1 -0
package/ui/transition/HorizontalTransition.d.ts +1 -0
package/ui/transition/HorizontalTransition.js +1 -0
package/ui/transition/HorizontalTransition.md +44 -0
package/ui/transition/HorizontalTransition.tsx +1 -0
package/ui/transition/Transition.d.ts +1 -0
package/ui/transition/Transition.js +1 -0
package/ui/transition/Transition.md +70 -0
package/ui/transition/Transition.tsx +1 -0
package/ui/transition/VerticalTransition.d.ts +1 -0
package/ui/transition/VerticalTransition.js +1 -0
package/ui/transition/VerticalTransition.md +34 -0
package/ui/transition/VerticalTransition.tsx +1 -0
package/ui/tree/TreeApp.d.ts +1 -0
package/ui/tree/TreeApp.js +1 -0
package/ui/tree/TreeApp.md +59 -0
package/ui/tree/TreeApp.tsx +1 -0
package/ui/tree/TreeMenu.d.ts +1 -0
package/ui/tree/TreeMenu.js +1 -0
package/ui/tree/TreeMenu.md +35 -0
package/ui/tree/TreeMenu.tsx +1 -0
package/ui/tree/TreeSidebar.d.ts +1 -0
package/ui/tree/TreeSidebar.js +1 -0
package/ui/tree/TreeSidebar.md +24 -0
package/ui/tree/TreeSidebar.tsx +1 -0
package/ui/util/getClass.md +55 -0
package/ui/util/notify.md +50 -0
package/ui/util/requireContext.md +24 -0
package/ui/app/README.md +0 -32
package/ui/block/README.md +0 -144
package/ui/dialog/README.md +0 -80
package/ui/docs/README.md +0 -71
package/ui/form/README.md +0 -165
package/ui/inline/README.md +0 -86
package/ui/layout/README.md +0 -71
package/ui/menu/README.md +0 -33
package/ui/misc/README.md +0 -121
package/ui/notice/README.md +0 -94
package/ui/page/README.md +0 -56
package/ui/router/README.md +0 -186
package/ui/transition/README.md +0 -80
package/ui/tree/README.md +0 -78
package/ui/util/README.md +0 -153

package/ui/page/HTML.tsx CHANGED Viewed

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

package/ui/page/Head.d.ts CHANGED Viewed

@@ -5,6 +5,7 @@ import { type ReactElement } from "react";
  * - Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
  * - Updates `window.history` to match the page URL.
  *
+ * @kind component
  * @returns The hoistable head elements derived from the current `<Meta>` context.
  * @example <Page title="Settings"><Head />…</Page>
  * @see https://dhoulb.github.io/shelving/ui/page/Head/Head

package/ui/page/Head.js CHANGED Viewed

@@ -11,6 +11,7 @@ const R_HTTP_EQUIV = /^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$/;
  * - Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
  * - Updates `window.history` to match the page URL.
  *
+ * @kind component
  * @returns The hoistable head elements derived from the current `<Meta>` context.
  * @example <Page title="Settings"><Head />…</Page>
  * @see https://dhoulb.github.io/shelving/ui/page/Head/Head

package/ui/page/Head.md ADDED Viewed

@@ -0,0 +1,26 @@
+# Head
+Low-level emitter of hoistable head metadata from the current `Meta` context. It outputs `<title>`, `<meta>`, `<link>`, stylesheet, module, and script elements inline, and React 19 hoists each one into the document `<head>`. It also syncs `window.history` to the page URL.
+**Things to know:**
+- [`Page`](/ui/Page) renders `<Head>` automatically — you rarely need it directly.
+- It does not render `<base>`, which is not hoistable; that lives in the [`HTML`](/ui/HTML) shell.
+- The composed title combines the page `title` with the app name from context.
+## Usage
+```tsx
+import { Page, Head } from "shelving/ui";
+// <Page> already renders <Head> for you; render it directly only for custom shells.
+<Page title="Settings">
+  <Head/>
+  …
+</Page>
+```
+## See also
+- [`Page`](/ui/Page) — renders `Head` and supplies the per-page meta it reads
+- [`HTML`](/ui/HTML) — owns the literal `<head>` and the non-hoistable `<base>`

package/ui/page/Head.tsx CHANGED Viewed

@@ -13,6 +13,7 @@ const R_HTTP_EQUIV = /^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$/;
  * - Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
  * - Updates `window.history` to match the page URL.
  *
+ * @kind component
  * @returns The hoistable head elements derived from the current `<Meta>` context.
  * @example <Page title="Settings"><Head />…</Page>
  * @see https://dhoulb.github.io/shelving/ui/page/Head/Head

package/ui/page/Page.d.ts CHANGED Viewed

@@ -13,6 +13,7 @@ export interface PageProps extends PossibleMeta, ChildProps {
  * - Sets the document title and other head metadata via `<Head>`, which emits hoistable tags inline; React 19 hoists each one into the document `<head>`. `<base>` is not emitted here — it lives in the `<HTML>` shell's `<Head>`.
  * - Also updates `window.history` to match the page URL.
  *
+ * @kind component
  * @param children The page content.
  * @param meta Per-page meta (title, description, etc.) merged with the surrounding `<Meta>` context.
  * @returns The page element with its meta applied.

package/ui/page/Page.js CHANGED Viewed

@@ -6,6 +6,7 @@ import { Head } from "./Head.js";
  * - Sets the document title and other head metadata via `<Head>`, which emits hoistable tags inline; React 19 hoists each one into the document `<head>`. `<base>` is not emitted here — it lives in the `<HTML>` shell's `<Head>`.
  * - Also updates `window.history` to match the page URL.
  *
+ * @kind component
  * @param children The page content.
  * @param meta Per-page meta (title, description, etc.) merged with the surrounding `<Meta>` context.
  * @returns The page element with its meta applied.

package/ui/page/Page.md ADDED Viewed

@@ -0,0 +1,42 @@
+# Page
+Wraps one page (or screen) inside an app, applying its per-page metadata. It merges `PossibleMeta` props into context and emits hoistable head tags (title, description, meta, links, stylesheets, scripts) that React 19 lifts into the document `<head>`. It also updates `window.history` to match the page URL.
+**Things to know:**
+- Accepts `PossibleMeta` props (`app`, `root`, `url`, `title`, `description`, `language`, `tags`, `links`, `stylesheets`, `modules`, `scripts`) and merges them with the surrounding `Meta` context.
+- The page title is composed with the app name from context — `title="User profile"` under `app="My App"` renders `"User profile - My App"`.
+- It renders [`Head`](/ui/Head) inline; React 19 hoists each `<title>`, `<meta>`, `<link>`, and `<script>` into `<head>`, so no portal is needed. `<base>` is the exception — that lives in [`HTML`](/ui/HTML).
+## Usage
+```tsx
+import { Page, Section } from "shelving/ui";
+function UserPage({ id }: { id: string }) {
+  return (
+    <Page title="User profile" url={`/users/${id}`} description="View user details.">
+      <Section>…</Section>
+    </Page>
+  );
+}
+```
+Layouts go inside `<Page>`:
+```tsx
+import { Page, CenteredLayout } from "shelving/ui";
+<Page title="Sign in">
+  <CenteredLayout>
+    <LoginForm/>
+  </CenteredLayout>
+</Page>
+```
+## See also
+- [`HTML`](/ui/HTML) — the document shell that sits above pages
+- [`Head`](/ui/Head) — the hoistable-tag emitter that `Page` renders
+- [`SidebarLayout`](/ui/SidebarLayout) / [`CenteredLayout`](/ui/CenteredLayout) — layouts that live inside a page
+- [`Router`](/ui/Router) — matches URLs to the pages it renders

package/ui/page/Page.tsx CHANGED Viewed

@@ -16,6 +16,7 @@ export interface PageProps extends PossibleMeta, ChildProps {}
  * - Sets the document title and other head metadata via `<Head>`, which emits hoistable tags inline; React 19 hoists each one into the document `<head>`. `<base>` is not emitted here — it lives in the `<HTML>` shell's `<Head>`.
  * - Also updates `window.history` to match the page URL.
  *
+ * @kind component
  * @param children The page content.
  * @param meta Per-page meta (title, description, etc.) merged with the surrounding `<Meta>` context.
  * @returns The page element with its meta applied.

package/ui/router/Navigation.d.ts CHANGED Viewed

@@ -19,6 +19,7 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {
  *
  * TODO: switch click/popstate handling to the browser Navigation API when broadly supported.
  *
+ * @kind component
  * @param children The app subtree to provide navigation to.
  * @param meta Initial meta (url/base) merged with the surrounding `<Meta>` context.
  * @returns The navigation provider wrapping `children`.

package/ui/router/Navigation.js CHANGED Viewed

@@ -16,6 +16,7 @@ import { NavigationStore } from "./NavigationStore.js";
  *
  * TODO: switch click/popstate handling to the browser Navigation API when broadly supported.
  *
+ * @kind component
  * @param children The app subtree to provide navigation to.
  * @param meta Initial meta (url/base) merged with the surrounding `<Meta>` context.
  * @returns The navigation provider wrapping `children`.

package/ui/router/Navigation.md ADDED Viewed

@@ -0,0 +1,41 @@
+# Navigation
+The top-level navigation provider for a client-side app. It owns a single [`NavigationStore`](/ui/NavigationStore), publishes the live URL into the `<Meta>` context so descendant [`Router`](/ui/Router)s re-render on navigation, and wires up browser history. Use exactly one `<Navigation>` per app — nested routers all share its single store.
+**Things to know:**
+- Same-origin anchor clicks are intercepted automatically and turned into `forward()` calls. Add a `download` attribute to an anchor to opt out.
+- It listens for `popstate` so the store stays in sync with browser back/forward.
+- It initialises the store from the surrounding `<Meta>` url/base, so set those on an ancestor [`HTML`](/ui/HTML) / [`Page`](/ui/Page).
+- [`Router`](/ui/Router) works with no `<Navigation>` at all (SSR, static rendering, tests) — `<Navigation>` is only what makes the URL *live* on the client.
+## Usage
+```tsx
+import { HTML, Navigation, Router } from "shelving/ui";
+<HTML url={initialUrl} root="https://example.com/">
+  <Navigation>
+    <Router routes={ROUTES}/>
+  </Navigation>
+</HTML>
+```
+### Imperative navigation
+Read the navigation store from anywhere in the tree with `requireNavigation()` for imperative URL changes:
+```tsx
+import { requireNavigation } from "shelving/ui";
+const nav = requireNavigation();
+nav.forward("/users/123");   // push a new history entry
+nav.redirect("/login");      // replace the current history entry
+```
+## See also
+- [`Router`](/ui/Router) — matches the URL `<Navigation>` publishes and renders the page
+- [`NavigationStore`](/ui/NavigationStore) — the store `<Navigation>` owns and `requireNavigation()` returns
+- [`HTML`](/ui/HTML) / [`Page`](/ui/Page) — supply the initial url/base meta
+- [`HorizontalTransition`](/ui/HorizontalTransition) — animate the route changes `<Navigation>` triggers

package/ui/router/Navigation.tsx CHANGED Viewed

@@ -25,6 +25,7 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {}
  *
  * TODO: switch click/popstate handling to the browser Navigation API when broadly supported.
  *
+ * @kind component
  * @param children The app subtree to provide navigation to.
  * @param meta Initial meta (url/base) merged with the surrounding `<Meta>` context.
  * @returns The navigation provider wrapping `children`.

package/ui/router/NavigationStore.md ADDED Viewed

@@ -0,0 +1,34 @@
+# NavigationStore
+The store holding the current navigation URL and driving browser history. It extends `URLStore` — the current location is its `value` — and is owned by [`Navigation`](/ui/Navigation). Reach for it via [`requireNavigation()`](/ui/Navigation) rather than constructing your own.
+**Things to know:**
+- `forward()` pushes a new browser history entry; `redirect()` replaces the current one. Both resolve the destination against the store's `base`.
+- It is a [`store`](/store) `URLStore`, so components can subscribe to it for re-renders.
+## Usage
+```tsx
+import { requireNavigation } from "shelving/ui";
+function LogoutButton() {
+  const nav = requireNavigation();
+  return <Button onClick={() => nav.redirect("/login")}>Log out</Button>;
+}
+```
+Constructed directly only when wiring navigation by hand (e.g. tests):
+```tsx
+import { NavigationStore } from "shelving/ui";
+const nav = new NavigationStore("/");
+nav.forward("/home");
+```
+## See also
+- [`Navigation`](/ui/Navigation) — owns the store and exposes it via `requireNavigation()`
+- [`Router`](/ui/Router) — renders the page for whatever URL the store holds
+- [`store`](/store) — the `URLStore` base and subscription model

package/ui/router/Router.d.ts CHANGED Viewed

@@ -23,6 +23,7 @@ export interface RouterProps extends PossibleMeta {
  * - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
  * - Returns `null` when there's no URL in context or the URL is outside the base.
  *
+ * @kind component
  * @param routes The route table to match the current URL against.
  * @param fallback Element to render when nothing matches; explicit `null` renders nothing instead of throwing.
  * @param meta Optional meta (url/base) overrides for this router scope.

package/ui/router/Router.js CHANGED Viewed

@@ -12,6 +12,7 @@ import { MetaContext, requireMetaURL } from "../misc/MetaContext.js";
  * - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
  * - Returns `null` when there's no URL in context or the URL is outside the base.
  *
+ * @kind component
  * @param routes The route table to match the current URL against.
  * @param fallback Element to render when nothing matches; explicit `null` renders nothing instead of throwing.
  * @param meta Optional meta (url/base) overrides for this router scope.

package/ui/router/Router.md ADDED Viewed

@@ -0,0 +1,143 @@
+# Router
+A pure URL matcher: it reads the current URL from the surrounding `<Meta>` context, matches it against a `routes` table, and renders the matched element. It has no client requirements, so it works for SSR, static rendering, and tests with no [`Navigation`](/ui/Navigation) at all — wrap it in [`Navigation`](/ui/Navigation) on the client to get live URL updates.
+**Things to know:**
+- Route keys are `AbsolutePath` strings starting with `/`. Placeholders (`{id}`, `:id`, `[id]`, `${id}`, `{{id}}`) are passed to function/component route values as props, merged with URL `?query` params (placeholders win on conflict).
+- `<Router>` accepts `PossibleMeta` props (`url`, `base`, etc.) to override the surrounding context — this is how nested routers scope themselves.
+- With a `base` set, the path used for matching is the URL after `matchURLPrefix` strips the base prefix; URLs outside the base render as `null`.
+- Pass `fallback` to control no-match behaviour. An explicit `null` renders nothing; leaving it `undefined` throws a `NotFoundError`.
+## Usage
+### Basic setup
+```tsx
+import { HTML, Navigation, Router } from "shelving/ui";
+<HTML url={initialUrl} root="https://example.com/">
+  <Navigation>
+    <Router routes={{
+      "/": HomePage,
+      "/users/{id}": UserPage,
+      "/about": AboutPage,
+    }}/>
+  </Navigation>
+</HTML>
+```
+### Route value types
+| Value | Behaviour |
+|---|---|
+| Component | Rendered as `<Component {...params}/>` with merged placeholder + query props. |
+| `AbsolutePath` string | Redirects to that path (placeholders resolved against the source). |
+| `ReactElement` | Rendered as-is — use for layout wrapping or composing inner routers. |
+| `null` / `false` | Skipped, as if the route were absent — lets a route be conditionally disabled. |
+### 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*}` |
+| 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}` behave the same. Catchall placeholders allow empty values, so a trailing catchall matches the trailing-slash-absent variant — `/files/{...path}` matches `/files`, `/files/`, and `/files/a/b/c`.
+### Layout wrapping
+Put layout JSX as the route value with another `<Router>` inside. Since `<Router>` reads its URL from `<Meta>`, the inner router sees the same URL.
+```tsx
+const SIDEBARRED_ROUTES = {
+  "/users": <UsersPage/>,
+  "/users/{id}": <UserPage/>,
+  "/settings": <SettingsPage/>,
+};
+<Router routes={{
+  "/": <HomePage/>,
+  "/{...path}": (
+    <SidebarLayout sidebar={<Nav/>}>
+      <Router routes={SIDEBARRED_ROUTES}/>
+    </SidebarLayout>
+  ),
+}}/>
+```
+### Section / microsite pattern
+A self-contained "section" — its own URL prefix and routes — composes via a catchall plus a function route value that hands the captured sub-path to a nested router as its `url`.
+```tsx
+const USER_ROUTES = {
+  "/": UsersPage,
+  "/{id}": UserPage,
+  "/{id}/edit": UserEditPage,
+};
+export function UserRouter({ path = "/" }: { path?: AbsolutePath }) {
+  return <Router routes={USER_ROUTES} url={path}/>;
+}
+// At the call site — the top-level router stays a flat list of section prefixes:
+<Router routes={{
+  "/": <HomePage/>,
+  "/users/{...path}": ({ path }) => <UserRouter path={path}/>,
+  "/blog/{...path}":  ({ path }) => <BlogRouter path={path}/>,
+}}/>
+```
+The outer router captures everything under `/users` into `path`; the inner router treats it as its starting URL, so its `"/"` matches the bare `/users` and `/{id}` matches `/users/123`.
+### Stacking layouts and sections
+The two patterns compose — wrap a group of routes in a layout, then route further inside, handing off to section routers via the catchall:
+```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 sidebar={<Nav/>}>
+      <Router routes={SIDEBARRED_ROUTES}/>
+    </SidebarLayout>
+  ),
+}}/>
+```
+### SSR / static rendering
+`<Router>` re-renders when context changes and needs no client. 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={ROUTES}/>
+  </HTML>
+);
+```
+### Base paths
+`root="https://example.com/app/"` is supported — the base path prefix is stripped from the URL before matching, and URLs that fall outside the base render as `null`.
+## See also
+- [`Navigation`](/ui/Navigation) — publishes a live URL into `<Meta>` for client-side routing
+- [`HTML`](/ui/HTML) / [`Page`](/ui/Page) — supply the `<Meta>` URL the router reads
+- [`SidebarLayout`](/ui/SidebarLayout) / [`CenteredLayout`](/ui/CenteredLayout) — wrap route groups in a shared layout
+- [`HorizontalTransition`](/ui/HorizontalTransition) — animate route changes

package/ui/router/Router.tsx CHANGED Viewed

@@ -31,6 +31,7 @@ export interface RouterProps extends PossibleMeta {
  * - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
  * - Returns `null` when there's no URL in context or the URL is outside the base.
  *
+ * @kind component
  * @param routes The route table to match the current URL against.
  * @param fallback Element to render when nothing matches; explicit `null` renders nothing instead of throwing.
  * @param meta Optional meta (url/base) overrides for this router scope.

package/ui/style/TINT_CLASS.md ADDED Viewed

@@ -0,0 +1,55 @@
+# TINT_CLASS
+All colour in the library flows from a single anchor variable, **`--tint-50`**, defined in `Tint.module.css`. From that one hue a 21-step ladder — `--tint-00`, `--tint-05`, … `--tint-95`, `--tint-100` — is computed with `color-mix()` in OKLCH: `--tint-00` is black, `--tint-50` is the anchor hue itself, `--tint-100` is white, and every step in between mixes the anchor toward one extreme or the other.
+The anchor defaults to `--color-gray`, so the default ladder is a neutral grey ramp — grey is just the colour you get when nothing moves the anchor. The page baseline paints from the extremes: `body { color: var(--tint-00); background: var(--tint-100); }`.
+## The recompute trick
+The ladder is computed at `:root` and *recomputed* under `TINT_CLASS` (the `.tint` class). That recomputation is the whole trick: move the anchor at any scope, apply `TINT_CLASS`, and all 21 shades rebuild from the new hue at that scope. Colour and status classes are exactly that — they only move the anchor:
+```css
+/* Color.module.css — a colour variant just moves the anchor. */
+.red {
+	--tint-50: var(--color-red);
+}
+/* Status.module.css — a status maps a semantic name onto a palette colour. */
+.success {
+	--tint-50: var(--color-success);
+}
+```
+[`getColorClass`](/ui/getColorClass) and [`getStatusClass`](/ui/getStatusClass) compose `TINT_CLASS` automatically, so `<Card color="red">` is: move the anchor to red, rebuild the ladder, and let the card paint from the same steps it always paints from. Descendants inherit the rebuilt ladder, which is why a [`Tag`](/ui/Tag) or [`Preformatted`](/ui/Preformatted) nested in a red card tints to match it.
+## How components paint from the ladder
+Components paint from the ladder by convention:
+| Step | Used for |
+|---|---|
+| `--tint-00` | Body text, headings — maximum contrast |
+| `--tint-50` | The hue itself — accents, labels, `Tag` backgrounds, `strong` button backgrounds |
+| `--tint-80` | Borders |
+| `--tint-90` | Surfaces — [`Card`](/ui/Card), `Preformatted`, [`Button`](/ui/Button) backgrounds |
+| `--tint-95` | Hover state of those surfaces |
+| `--tint-100` | The page background; text on `--tint-50` backgrounds |
+Pairings follow contrast: long text reads at `00`-on-`90` or `00`-on-`100`; short labels read at `100`-on-`50`.
+## Theming
+A theme is a CSS file of custom-property overrides at `:root`, imported after the base styles. Work from broadest to narrowest:
+1. **Move a palette colour.** Overriding `--color-gray` moves the default anchor, retinting every neutral ladder in the app — the broadest possible change. Overriding `--color-red`, `--color-primary`, etc. re-aims every variant and status that maps to it.
+2. **Retint one component family.** Set its tint hook: `--card-tint: var(--color-purple)` makes all cards (and their nested content) purple-tinted, with text, border, surface, and hover shades all derived for free.
+3. **Override one property.** Per-property hooks are the scalpel: `--button-radius: 999px`, `--card-border: none`, `--tag-case: none`.
+**Don't override individual ladder steps (`--tint-90`, etc.) at `:root`.** The ladder is *recomputed* from the anchor inside every `TINT_CLASS` scope — which includes every component that accepts `color=` or `status=` — so a step override at `:root` only reaches untinted regions and produces inconsistent surfaces. Move the anchor (option 1 or 2) instead, and the steps follow.
+## See also
+- [`getColorClass`](/ui/getColorClass) — moves the anchor to a named palette colour and composes `TINT_CLASS`.
+- [`getStatusClass`](/ui/getStatusClass) — moves the anchor via a semantic status name.
+- [`Card`](/ui/Card) — a painting component whose Styling section shows the per-component tint hook in practice.
+- [`ui`](/ui) — the styling system overview: design tokens, cascade layers, and styling props.

package/ui/transition/CollapseTransition.d.ts CHANGED Viewed

@@ -11,6 +11,7 @@ export interface CollapseTransitionProps extends TransitionProps {
 /**
  * Transition that collapses its children in and out by animating their size.
  *
+ * @kind component
  * @param props Shared transition variant props plus `children`.
  * @returns A `<Transition>` element configured with the `collapse` class.
  * @example <CollapseTransition>{visible && <Panel />}</CollapseTransition>

package/ui/transition/CollapseTransition.js CHANGED Viewed

@@ -4,6 +4,7 @@ import { Transition } from "./Transition.js";
 /**
  * Transition that collapses its children in and out by animating their size.
  *
+ * @kind component
  * @param props Shared transition variant props plus `children`.
  * @returns A `<Transition>` element configured with the `collapse` class.
  * @example <CollapseTransition>{visible && <Panel />}</CollapseTransition>

package/ui/transition/CollapseTransition.md ADDED Viewed

@@ -0,0 +1,34 @@
+# CollapseTransition
+A [`Transition`](/ui/Transition) preset that collapses its children in and out by animating their size, clipping the overflow during the animation.
+**Things to know:**
+- Uses the `collapse` transition class — there is no direction-aware variant, so forward and back animate identically.
+- Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
+## Usage
+```tsx
+import { CollapseTransition } from "shelving/ui";
+function Details({ open }: { open: boolean }) {
+  return open ? (
+    <CollapseTransition>
+      <Panel>…</Panel>
+    </CollapseTransition>
+  ) : null;
+}
+```
+## Styling
+This preset exposes no own `--collapse-transition-*` hooks. Its `CollapseTransition.css` only sets `overflow: hidden` on `::view-transition-image-pair(.collapse)` so the collapsing content is clipped.
+**Global tokens it reads** — none.
+## See also
+- [`Transition`](/ui/Transition) — the base wrapper and `overlay` variant
+- [`FadeTransition`](/ui/FadeTransition) — opacity-based alternative
+- [`VerticalTransition`](/ui/VerticalTransition) / [`HorizontalTransition`](/ui/HorizontalTransition) — direction-aware slides

package/ui/transition/CollapseTransition.tsx CHANGED Viewed

@@ -12,6 +12,7 @@ export interface CollapseTransitionProps extends TransitionProps {}
 /**
  * Transition that collapses its children in and out by animating their size.
  *
+ * @kind component
  * @param props Shared transition variant props plus `children`.
  * @returns A `<Transition>` element configured with the `collapse` class.
  * @example <CollapseTransition>{visible && <Panel />}</CollapseTransition>

package/ui/transition/FadeTransition.d.ts CHANGED Viewed

@@ -10,6 +10,7 @@ export interface FadeTransitionProps extends TransitionProps {
 /**
  * Transition that fades its children in and out by animating their opacity.
  *
+ * @kind component
  * @param props Shared transition variant props plus `children`.
  * @returns A `<Transition>` element configured with the `fade` class.
  * @example <FadeTransition>{visible && <Toast />}</FadeTransition>

package/ui/transition/FadeTransition.js CHANGED Viewed

@@ -3,6 +3,7 @@ import { Transition } from "./Transition.js";
 /**
  * Transition that fades its children in and out by animating their opacity.
  *
+ * @kind component
  * @param props Shared transition variant props plus `children`.
  * @returns A `<Transition>` element configured with the `fade` class.
  * @example <FadeTransition>{visible && <Toast />}</FadeTransition>

package/ui/transition/FadeTransition.md ADDED Viewed

@@ -0,0 +1,36 @@
+# FadeTransition
+A [`Transition`](/ui/Transition) preset that fades its children in and out by animating opacity. Wrap any content that should animate when it mounts or unmounts.
+**Things to know:**
+- Uses the `fade` transition class — there is no direction-aware variant, so forward and back animate identically.
+- Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
+## Usage
+```tsx
+import { FadeTransition } from "shelving/ui";
+function Panel({ visible }: { visible: boolean }) {
+  return visible ? (
+    <FadeTransition>
+      <div className="panel">…</div>
+    </FadeTransition>
+  ) : null;
+}
+```
+## Styling
+| Variable | Styles | Default |
+|---|---|---|
+| `--fade-transition-duration` | Duration of the fade-in and fade-out keyframes | `var(--duration-fast)` |
+**Global tokens it reads** — `--duration-fast`.
+## See also
+- [`Transition`](/ui/Transition) — the base wrapper and `overlay` variant
+- [`CollapseTransition`](/ui/CollapseTransition) — size-based alternative
+- [`VerticalTransition`](/ui/VerticalTransition) / [`HorizontalTransition`](/ui/HorizontalTransition) — direction-aware slides

package/ui/transition/FadeTransition.tsx CHANGED Viewed

@@ -11,6 +11,7 @@ export interface FadeTransitionProps extends TransitionProps {}
 /**
  * Transition that fades its children in and out by animating their opacity.
  *
+ * @kind component
  * @param props Shared transition variant props plus `children`.
  * @returns A `<Transition>` element configured with the `fade` class.
  * @example <FadeTransition>{visible && <Toast />}</FadeTransition>

package/ui/transition/HorizontalTransition.d.ts CHANGED Viewed

@@ -11,6 +11,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/HorizontalTransition.js CHANGED Viewed

@@ -4,6 +4,7 @@ import { Transition } from "./Transition.js";
 /**
  * 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>