@kerfjs/ui 5.0.0-beta.4 → 5.0.0-beta.41

package/docs/catalog.md

@@ -0,0 +1,364 @@
+# Catalog — a reusable component-gallery shell
+
+`@kerfjs/ui/catalog` is an opt-in, whole-screen shell for building a **component
+catalog** — the collapsible category sidebar + titled preview stage + resources
+footer that the kerf UI catalog itself uses. Point it at your own components and
+you get the same shell without rebuilding it. Like the app layouts, it is a
+subpath-only, tree-shakeable module that adds nothing to the main barrel.
+
+```bash
+npm install @kerfjs/ui # kerfjs is a peer; @kerfjs/ui/select/register is needed only if entries use `related`
+```
+
+- `Catalog(props)` returns the shell as `SafeHtml` (a `<main class="kui-catalog">`).
+  It is **controlled and stateless**: your app owns the `active`, `collapsed`, and
+  `theme` signals and computes the preview `content` from `active` in its own
+  `mount()` render.
+- `wireCatalog(root, options)` wires the interactions (sidebar selection, the
+  related-entry popup menu, and the collapse/theme toggles) with one delegated
+  listener set and returns a disposer; it can also mirror the active id into the
+  URL and reveal the active sidebar row after a controlled render.
+
+## What you supply
+
+- **`sections`** — category-grouped entries: `{ category, entries: [{ id, name,
+description?, tags?, resources?, related? }] }`. Each entry becomes a sidebar
+  `ListItem` under a `ListHeader` for its category. Short `tags` render as quiet
+  trailing pills for decision metadata such as `Discouraged`.
+- **`content`** — the rendered preview for the active entry. Keep a map of `id →
+() => SafeHtml` in your app and call `renderers[active]()` in your render.
+- **`brand`** — `{ title, subtitle?, logoUrl? }` for the sidebar header.
+- **`secondarySections`** — an optional secondary "ecosystem" group shown below the
+  primary sections with a quieter treatment: `{ label, sections, collapsible?,
+expanded? }`. When `collapsible`, the label is a disclosure toggle controlling
+  `expanded` (the app owns it; wire it with `wireCatalog`'s `onToggleSecondary`).
+- Optional slots: `headerActions` (extra header controls), `sidebarFooter` (extra
+  sidebar content), and `status` (a footer status line).
+
+Per-entry `resources` render as "open in new tab" links in the footer, and
+`related` renders a "Related entries" popup menu — a `single` `ToolbarControlGroup`
+around a `wa-dropdown` (grouped by each entry's `group`), so register its elements
+with `@kerfjs/ui/select/register` when you use it.
+
+## Catalog demo authoring contract
+
+This section is the single authoritative contract for tools and people that
+author Catalog previews. The machine-readable discovery entry is
+[`catalog-authoring.json`](../ai/catalog-authoring.json); exact props remain in
+[`public-api-signatures-v1.md`](../ai/public-api-signatures-v1.md#kerfjsuicatalog).
+The component catalog deliberately does not duplicate these rules: it describes
+which component to choose, while this contract describes how to present the
+chosen component.
+
+### Choose the demo mode
+
+Classify every entry before rendering it:
+
+| Entry kind            | Preview purpose                                                         | Geometry overlay                                                                    |
+| --------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Focused component     | Show one public component, its meaningful variants, and adverse states. | `true`; the overlay inspects each selected specimen.                                |
+| Composition or recipe | Show several components cooperating as one product surface.             | `false`; child geometry remains unmarked so the composition can be read as a whole. |
+
+Keep `geometryOverlay` present and compute it from the active entry. Do not make
+it a permanent catalog-wide `true`, and do not give individual specimens their
+own overlay implementation.
+
+### Required structure
+
+- `Catalog` is the one shell. The app owns active-entry state and passes one
+  active preview through `content`.
+- `CatalogExampleStack` is the group for one preview's rows. Put route/test
+  metadata such as `data-demo` on its rendered root through `rootAttributes`.
+  Pass `label` when the stack needs an accessible name: the rendered `section`
+  is then exposed as a named region. An unlabeled stack remains an ordinary
+  grouping rather than adding an unnecessary landmark.
+- `CatalogExample` is one row: optional generated `ListHeader` label, optional
+  generated note, then one specimen or one intentionally coupled specimen
+  cluster. Use one row per variant/state; do not hand-author the helper's private
+  classes.
+- The specimen is an immediate child of `CatalogExample`. A focused component
+  row should place the component root there, without a decorative card or
+  spacing wrapper. A composition row may place the composition root there.
+
+Use `align="glyph"` for a bare glyph/text specimen, `align="inline-control"`
+for a control whose own inline padding contributes about 8px, and `align="none"`
+(the default) for a content item or composition that owns its geometry.
+
+```tsx
+import { CatalogExample, CatalogExampleStack } from "@kerfjs/ui/catalog";
+
+const buttonPreview = (
+  <CatalogExampleStack
+    label="Button variants"
+    rootAttributes={{ "data-demo": "button" }}
+  >
+    <CatalogExample label="Icon" note="A bare glyph." align="glyph">
+      <LucideIcon icon={Plus} name="plus" />
+    </CatalogExample>
+    <CatalogExample label="Control" align="inline-control">
+      <SegmentedControl id="view" label="View" value="list" choices={choices} />
+    </CatalogExample>
+    <CatalogExample
+      label="Authoring note"
+      note="Explanatory chrome is not a specimen."
+      rootAttributes={{ "data-catalog-geometry-overlay-skip": "" }}
+    >
+      <p>Use the public helper contract.</p>
+    </CatalogExample>
+  </CatalogExampleStack>
+);
+```
+
+The overlay selects every immediate child of a `CatalogExample`; the helper
+marks its generated label and note so they are excluded automatically. It does
+not recursively promote a nested child to be the specimen. Outside an example
+row, it selects only top-level
+`[data-component]` roots in the canvas and ignores nested component descendants.
+These rules keep a row's label/group scaffolding out of the measurement and make
+the authored nesting determine exactly what is inspected.
+
+### Metadata ownership
+
+Use `rootAttributes` on either helper for authoring metadata such as `data-demo`
+or `data-catalog-geometry-overlay-skip`; the metadata lands on that helper's
+rendered root. The slot accepts only `data-*` strings. Structural
+`data-catalog-example`, `data-catalog-example-stack`, and `data-align` semantics
+remain helper-owned and are rejected case-insensitively at runtime, including
+from structurally widened or JavaScript objects. Do not copy the helpers'
+private `kui-catalog-*` classes into preview markup.
+
+The app owns entry ids, `kind`, routing, sources, relationships, and test hooks.
+The helpers own their structural markers, label/note anatomy, alignment marker,
+and private classes. Component metadata such as margin/border/padding ownership
+lives in `component-catalog.json`; do not infer or overwrite it from overlay
+pixels.
+
+### Geometry overlay and legend
+
+Pass the conditional `geometryOverlay` boolean to `Catalog`, then call
+`wireCatalogGeometryOverlay(root)` once after the first render and retain its
+disposer alongside `wireCatalog`'s.
+
+| Overlay mark            | Meaning                                                                                              | It is not                                                                |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Orange translucent band | A positive computed margin on the selected specimen, after subtracting the helper's alignment inset. | Padding, gap, or empty content. Zero and negative margins are not drawn. |
+| Accent solid edge       | The selected specimen's computed border widths and radius, except `none`/`hidden` styles.            | A focus ring, outline, child border, or metadata ownership claim.        |
+| Quiet dashed outline    | The border-box bound of a transparent selected specimen with no visible border.                      | A real CSS border, padding edge, or proof that the specimen owns size.   |
+
+The overlay recomputes from live rendered styles when specimens resize, preview
+markup changes, theme/root attributes change, or loaded/inline stylesheets
+change. Component CSS is therefore the source of truth; do not duplicate margin
+or border values in demo data. The overlay does not visualize padding, gaps,
+negative/zero margins, scroll overflow, hit targets, or nested descendants.
+Inspect computed styles and the machine-readable `geometry` metadata for those
+facts. Opaque borderless specimens do not receive the dashed bound.
+
+```tsx
+<Catalog
+  {...props}
+  geometryOverlay={activeEntry.kind === "component"}
+  content={renderers[active.value]()}
+/>
+```
+
+Put `rootAttributes={{ "data-catalog-geometry-overlay-skip": "" }}` on a
+`CatalogExample` or `CatalogExampleStack` only when that whole subtree is
+explanatory chrome rather than a specimen. The marker excludes the marked root
+and every descendant from selection; it does not merely hide one band. It is
+normally unnecessary in a composition because the active entry already sets the
+global overlay to `false`.
+
+Use the overlay together with machine-readable geometry ownership metadata; the
+overlay verifies what is rendered, while metadata tells people and AI tools
+whether the component, its parent, or its children are responsible for margin,
+border, and padding. Catalogs for downstream components should conform to the
+[`component-catalog-extension.schema.json`](../ai/component-catalog-extension.schema.json)
+contract and can start from the checked
+[`component-catalog-extension.json`](./examples/component-catalog-extension.json)
+example; provide those entries beside Kerf's shipped catalog to AI tools.
+
+### Automated conformance and reviewed exceptions
+
+Run `npm run check:demo-conformance` after changing a first-party demo, its
+catalog kind, or the shell's overlay logic. The TypeScript-AST gate verifies
+facts that source can prove without guessing at rendered intent:
+
+- focused component routes import and use `CatalogExampleStack` and
+  `CatalogExample` from the public package;
+- focused route metadata uses the helpers' `rootAttributes` slot, example rows
+  are not empty, and composition routes do not add redundant skip markers;
+- every `@kerfjs/ui` import is a published package export and relative imports
+  do not reach into `ui/src`;
+- demo JSX does not copy private `kui-catalog-*` structural classes; and
+- the shell derives both geometry-overlay enablement and documented demo mode
+  from the active entry's source and kind.
+
+The gate deliberately does not infer component ownership from arbitrary class
+names, margins, borders, or nested descendants. Runtime selection and geometry
+remain the browser suite's job.
+
+A focused route may bypass the two public layout helpers only when the route's
+stage geometry is itself the reviewed specimen. Add the narrow waiver to
+[`catalog-conformance-exceptions.json`](../ux-demo/catalog-conformance-exceptions.json)
+with the exact route, source file, stable diagnostic ids, a substantive reason,
+and the reviewing `KF-*` ticket. Only helper/metadata rules are waivable;
+private imports, private markup, empty examples, composition overlay drift, and
+shell-mode drift always fail. The gate rejects duplicate, malformed, unused,
+and stale exceptions, so delete a waiver when its route adopts the standard
+helpers.
+
+## Selection reveal
+
+Set `revealSelection: true` on `wireCatalog` for a long desktop sidebar. After
+`onSelect` updates controlled state, the helper waits one animation frame, finds
+the exact matching `data-item-id`, and scrolls it into view without changing
+focus. A newer selection or disposal cancels the pending reveal. The default
+media guard is the Catalog desktop layout (`min-width: 52.01rem`), so compact
+layouts keep their existing scroll position.
+
+Pass an options object instead of `true` to customize `block`, `inline`,
+`behavior`, or `media`; `media: false` deliberately enables the behavior at all
+sizes. For an initial deep link that did not come through `wireCatalog`, call
+`revealCatalogEntry(app, initialId, { block: "center" })` after the first mount.
+
+## Complete example
+
+```tsx
+import { mount, signal, type SafeHtml } from "kerfjs";
+import {
+  Catalog,
+  CatalogExample,
+  CatalogExampleStack,
+  type CatalogSection,
+} from "@kerfjs/ui/catalog";
+import {
+  revealCatalogEntry,
+  wireCatalog,
+  wireCatalogGeometryOverlay,
+} from "@kerfjs/ui/wire-catalog";
+import "@kerfjs/ui/styles.css"; // or import each primitive's CSS + @kerfjs/ui/catalog.css
+
+type DemoKind = "component" | "composition";
+type DemoEntry = CatalogSection["entries"][number] & { kind: DemoKind };
+
+// 1. Describe selection and overlay mode once.
+const entries: DemoEntry[] = [
+  {
+    id: "button",
+    name: "Button",
+    kind: "component",
+    description: "A pressable control.",
+    resources: [
+      { label: "Source", href: "/src/button.tsx", detail: "src/button.tsx" },
+    ],
+  },
+  {
+    id: "profile-form",
+    name: "Profile form",
+    kind: "composition",
+    description: "A labeled field and save action working together.",
+  },
+];
+const sections: CatalogSection[] = [
+  {
+    category: "Examples",
+    entries: entries.map(({ kind: _kind, ...entry }) => entry),
+  },
+];
+
+// 2. Every preview uses one public group and public example rows.
+const renderers: Record<string, () => SafeHtml> = {
+  button: () => (
+    <CatalogExampleStack
+      label="Button states"
+      rootAttributes={{ "data-demo": "button" }}
+    >
+      <CatalogExample label="Default" align="inline-control">
+        <Button label="Save" />
+      </CatalogExample>
+      <CatalogExample
+        label="Authoring note"
+        note="This explanatory row is deliberately excluded from inspection."
+        rootAttributes={{ "data-catalog-geometry-overlay-skip": "" }}
+      >
+        <p>The application owns product copy and actions.</p>
+      </CatalogExample>
+    </CatalogExampleStack>
+  ),
+  "profile-form": () => (
+    <CatalogExampleStack
+      label="Profile form composition"
+      rootAttributes={{ "data-demo": "profile-form" }}
+    >
+      <CatalogExample label="Complete composition">
+        <ProfileForm />
+      </CatalogExample>
+    </CatalogExampleStack>
+  ),
+};
+
+// 3. App-owned state (domain: which entry; transient: collapsed; global: theme).
+const initial =
+  new URLSearchParams(location.search).get("c") ?? sections[0].entries[0].id;
+const active = signal(initial);
+const collapsed = signal(false);
+const theme = signal<"light" | "dark">("light");
+const activeEntry = () => entries.find(({ id }) => id === active.value) ?? entries[0];
+
+const app = document.getElementById("app")!;
+mount(app, () => (
+  <Catalog
+    brand={{ title: "Acme UI", subtitle: "Design system" }}
+    sections={sections}
+    active={active.value}
+    content={renderers[active.value]?.() ?? <></>}
+    collapsed={collapsed.value}
+    theme={theme.value}
+    geometryOverlay={activeEntry().kind === "component"}
+  />
+));
+
+wireCatalog(app, {
+  onSelect: (id) => {
+    active.value = id;
+  },
+  onToggleSidebar: () => {
+    collapsed.value = !collapsed.value;
+  },
+  onToggleTheme: () => {
+    theme.value = theme.value === "dark" ? "light" : "dark";
+    document.documentElement.dataset.theme = theme.value; // apply your theme however you like
+  },
+  urlParam: "c", // mirror the active id into ?c=<id>
+  revealSelection: true, // reveal long desktop sidebars without moving focus
+});
+wireCatalogGeometryOverlay(app);
+
+// Optional for an initial deep link whose row may start outside the viewport.
+revealCatalogEntry(app, initial, { block: "center" });
+```
+
+## Ownership boundary
+
+`Catalog` renders the shell; the app owns everything stateful:
+
+- **`active`** is domain state (which entry is shown) — the app's signal, updated in
+  `onSelect`, read to compute `content`.
+- **`collapsed`** is transient UI — the app's signal, flipped in `onToggleSidebar`.
+- **`theme`** is a global preference — the app's signal; `wireCatalog` only reports
+  the toggle, the app applies the theme (the shell reads `theme` to show the toggle's
+  opposite-state label). Omit `theme` to hide the toggle entirely.
+
+## Custom action names
+
+The shell emits `data-action="catalog-select"` (sidebar items),
+`catalog-toggle-sidebar`, and `catalog-toggle-theme`. Override them with
+`selectAction` / `toggleSidebarAction` / `toggleThemeAction` on `Catalog` (and the
+matching options on `wireCatalog`) if they collide with your own action table.
+
+## CSS
+
+`Catalog` composes public primitives (`Toolbar`, `ListHeader`, `ListItem`, `Select`,
+…). Import `@kerfjs/ui/styles.css` for the whole layer, or `@kerfjs/ui/catalog.css`
+plus each composed primitive's CSS. The shell is theme-aware and responsive: it
+stacks the sidebar above the detail below ~832px and hides it when collapsed.

package/docs/collapsible-panel.md

@@ -0,0 +1,142 @@
+# CollapsiblePanel + wireSidebar — reusable sidebar / drawer support
+
+`@kerfjs/ui/collapsible-panel` and `@kerfjs/ui/wire-sidebar` are the standalone,
+reusable pieces for an app's own **side rails** and **bottom drawers** — the same
+collapse semantics the `Workbench` shell and the catalog sidebar use, but outside
+a full shell so you can dock one panel wherever your layout needs it. They are
+subpath-only, tree-shakeable modules that add nothing to the main barrel.
+
+```bash
+npm install @kerfjs/ui # kerfjs is a peer
+```
+
+Import the panel CSS (`@kerfjs/ui/collapsible-panel.css`) alongside `foundation.css`.
+
+## The pieces
+
+- **`CollapsiblePanel({ id, side, collapsed?, size?, label?, children })`** — the
+  docked panel: a `'left'` / `'right'` rail or a `'bottom'` drawer. It owns only
+  presentation. Collapsing snaps the panel's own size to zero in one reflow while
+  the fixed-size content slides out via `transform` (composited, clipped) — never
+  a per-frame width/height animation. A bottom drawer anchors that fixed-size
+  content to its stable bottom edge, so opening and closing move monotonically
+  through the transform alone instead of transitioning from a changing layout
+  origin and snapping at the end. The app owns the `collapsed` signal; `size`
+  overrides the CSS default width/height.
+  Reusable shell policies are typed props: `separator`, `collapseMotion`,
+  `contentOverflow`, and `presentation`. A collapsed panel may also receive a
+  `restoreControl`, which Kerf places at the safe-area-aware `restorePosition`.
+  Overlay presentation also clamps fixed-size animated content to the configured
+  responsive overlay maximum, so a remembered desktop size cannot escape a narrow
+  viewport.
+- **`CollapsiblePanelToggle({ side, collapsed, action, panelId?, label? })`** and
+  **`collapsiblePanelToggleIcon(side, collapsed)`** — the standard toggle
+  affordance and its icon convention, so every sidebar reads the same: `PanelLeft*`
+  for a left rail, `PanelRight*` for a right rail, `PanelBottom*` for a bottom
+  drawer — the `Close` glyph while open, the `Open` glyph while collapsed. Placement
+  is the app's: put a collapse toggle in the panel's own header and an expand toggle
+  somewhere always-visible (a toolbar) so it is reachable while collapsed.
+- **`wireSidebar(root, { panels, deviceClass?, storage? })`** — the interaction
+  semantics. Each `panels` entry is `{ id, collapsed, toggleAction, storageKey? }`.
+  It:
+  - **toggles** the panel's `collapsed` signal when any `[data-action=toggleAction]`
+    button is clicked, and remembers the trigger;
+  - **manages focus** — moves focus into the panel when it opens, and restores it
+    to the trigger when it closes;
+  - **presents a compact overlay** when `deviceClass.compact` is true (pass a
+    `deviceClass()` signal): the open panel floats over the content with a
+    dismissable backdrop, Escape and backdrop-click collapse it, and Tab is trapped
+    within the panel (the ARIA dialog pattern);
+  - accepts `compactPresentation: "hidden"` when a compact application replaces
+    the panel with different navigation instead of overlaying it;
+  - keeps compact overlays exclusive by default, collapsing another open panel
+    when a new one opens (`exclusiveCompact: false` opts out);
+  - **persists** the collapsed state to `storage` (default `localStorage`) under
+    `storageKey`, seeding the signal on wire-up.
+
+  Returns a disposer. Retain it and call it on teardown.
+
+## Example
+
+```tsx
+import { signal, mount } from "kerfjs";
+import { deviceClass } from "@kerfjs/ui/device-class";
+import {
+  CollapsiblePanel,
+  CollapsiblePanelToggle,
+} from "@kerfjs/ui/collapsible-panel";
+import { wireSidebar } from "@kerfjs/ui/wire-sidebar";
+import "@kerfjs/ui/collapsible-panel.css";
+
+const navCollapsed = signal(false);
+const device = deviceClass();
+
+const app = document.querySelector("#app")!;
+mount(app, () => (
+  <div class="layout">
+    <CollapsiblePanel
+      id="nav"
+      side="left"
+      collapsed={navCollapsed.value}
+      label="Navigator"
+    >
+      <header>
+        <CollapsiblePanelToggle
+          side="left"
+          collapsed={navCollapsed.value}
+          action="toggle-nav"
+          panelId="nav"
+        />
+      </header>
+      {/* nav items */}
+    </CollapsiblePanel>
+    <main>
+      {navCollapsed.value && (
+        <CollapsiblePanelToggle
+          side="left"
+          collapsed
+          action="toggle-nav"
+          label="Show navigator"
+        />
+      )}
+      {/* content */}
+    </main>
+  </div>
+));
+
+const stop = wireSidebar(app, {
+  panels: [
+    {
+      id: "nav",
+      collapsed: navCollapsed,
+      toggleAction: "toggle-nav",
+      storageKey: "app.nav-collapsed",
+    },
+  ],
+  deviceClass: device,
+});
+```
+
+## When to use which
+
+- One or two independent rails / a drawer you place yourself → **`CollapsiblePanel` +
+  `wireSidebar`**.
+- A whole Xcode-like workspace (left rail + right rail + bottom drawer + work area
+  in one shell) → **[`Workbench`](workbench.md)**, which owns the layout and the same
+  collapse animation.
+- Drag-to-resize a panel → compose **[`ResizableRegion`](../src/resizable-region.tsx)**
+  / `wireResizableRegions`; the app owns the size signal.
+
+The app still owns everything domain-specific — which panels exist, their order,
+sizes, content, and any per-project persistence — exactly as with the other layouts.
+
+## Recipe and coverage
+
+The catalog ships a runnable **Collapsible sidebar** recipe — a left rail and a
+bottom drawer with the standard toggles, the compact overlay, and per-panel
+persistence: [open it](../ux-demo/?component=recipe-collapsible-sidebar) or read
+[`recipes.md`](recipes.md#collapsible-sidebar) · [TSX source](../ux-demo/recipes/collapsible-sidebar.tsx).
+It is covered end-to-end across Chromium, Firefox, and WebKit by
+`tests/browser/collapsible-sidebar-recipe.spec.ts` (collapse/expand, focus
+move/restore, the compact overlay + Escape/backdrop dismiss, and the Tab trap),
+alongside the component/wire unit tests.