@kerfjs/ui 5.0.0-beta.10 → 5.0.0-beta.101

package/ai/components/anchored-surface.md

@@ -0,0 +1,99 @@
+# AnchoredSurface
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:anchored-surface` · Kerf UI · component · Feedback
+
+A styled non-modal surface for app-owned interactive help or popup content, anchored to an element or pointer.
+
+## When to use
+
+Present arbitrary app-owned content next to an element or pointer with Kerf UI surface styling and kerfjs/overlay lifecycle.
+
+- Show interactive help or other arbitrary content near a control or pointer, including inside a modal dialog.
+
+**Not when:**
+
+- Use PopupMenu for a typed action menu, Select for a choice, and a modal dialog for a task that must block the page.
+
+**Alternatives:**
+
+- [PopupMenu](./popup-menu.md) (nearest)
+- [Popup](./wa-popup.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/anchored-surface` — exports `openAnchoredSurface`, `openAnchoredSurfaceAt`.
+- CSS: the browser build of `@kerfjs/ui/anchored-surface` pulls its CSS automatically; import `@kerfjs/ui/anchored-surface.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/anchored-surface`](../public-api-signatures-v1.md#kerfjsuianchored-surface) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- element anchor
+- pointer anchor
+- top or bottom placement
+- modal-dialog host
+- tone: 'dark' (the inverse tone of a dark ToolbarControlGroup, for popups anchored to media chrome)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** content and action policy; opening trigger and programmatic close after an action; accessible name.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- The non-modal surface has role dialog and the required label. Focus moves to the first focusable descendant by default and returns to the opener on close; initialFocus: false leaves focus on the trigger. Escape and outside press dismiss by default.
+
+## Usage examples
+
+### Interactive help
+
+The trigger owns when to open; the returned handle closes when an action completes.
+
+```tsx
+const handle = openAnchoredSurface(button, () => <HelpPanel />, {
+  label: 'Field help',
+});
+// Close from the app's action handler: handle.close();
+```
+
+### Popup anchored to dark media chrome
+
+tone: 'dark' matches a ToolbarControlGroup tone="dark": the surface takes the opposite of the anchor's color scheme (openAnchoredSurfaceAt reads it from point.context) and follows a live OS-preference or ancestor theme switch while open, so its content inherits the inverse text, border, and focus colors without overrides.
+
+```tsx
+openAnchoredSurface(volumeButton, () => <VolumeControls />, {
+  label: 'Volume',
+  tone: 'dark',
+  placement: 'top',
+});
+```
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public tokens it reads: `--kui-anchored-surface-inset`, `--kui-anchored-surface-radius`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [PopupMenu](./popup-menu.md), [Popup](./wa-popup.md).
+- Docs: [`docs/anchored-surface.md`](../../docs/anchored-surface.md).
+- UX catalog route: `?component=anchored-surface`.

package/ai/components/application-tabs.md

@@ -0,0 +1,65 @@
+# Application Tabs
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:application-tabs` · Kerf UI · CSS composition · Navigation
+
+Controlled document tabs with application-owned state and panels.
+
+## When to use
+
+Show AppTab and TabBar in a complete controlled composition.
+
+- Compose application state, panels, actions, overflow, and reordering around TabBar and AppTab.
+
+**Not when:**
+
+- Use SegmentedControl instead for a compact local choice.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+**Variants (configure, do not restyle):**
+
+- overflow
+- keyboard and pointer reordering
+- adding and closing documents
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [AppTab](./tabs.md), [TabBar](./tab-bar.md), [ToolbarControlGroup](./toolbar-control-group.md), [Text](./text.md), [Card](./wa-card.md).
+
+## State and wiring
+
+**The app owns:** ordered tabs; selected tab; tabpanels; add and close policy; routing and persistence.
+
+No wiring helper.
+
+## Geometry
+
+Margin: child · border: child · padding: child (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Keep one selected tab synchronized with one named tabpanel and retain the wireTabBars disposer.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [AppTab](./tabs.md), [TabBar](./tab-bar.md), [ToolbarControlGroup](./toolbar-control-group.md), [Text](./text.md), [Card](./wa-card.md).
+- Docs: [`docs/accessibility.md`](../../docs/accessibility.md), [`docs/accessibility.md#tabs`](../../docs/accessibility.md#tabs).
+- UX catalog route: `?component=application-tabs`.

package/ai/components/backdrop-image.md

@@ -0,0 +1,84 @@
+# BackdropImage
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:backdrop-image` · Kerf UI · component · Structure
+
+An image block at the top of a scrolling view that can lag the scroll, fade into an app color, and keep painting that color under the content below.
+
+## When to use
+
+Open a scrolling Pane or NavStack view with a hero or tiled backdrop image (an artist, album, or place page) that lags the scroll and progressively blurs on a compositor-only scroll timeline, dissolves through a mask into an app-chosen color, and continues that color under the following content, with Kerf-owned static fallbacks.
+
+- A scrolling view opens with a large mood or identity image (an artist, album, place, or collection header) whose page should read as one surface with it.
+- The image should lag the scroll (parallax), blur progressively as it scrolls away, or dissolve into a color without app scroll listeners, animated filters, or background-attachment: fixed.
+
+**Not when:**
+
+- Do not use for inline content images, thumbnails, avatars, or media a person inspects; render an img or the matching media component.
+- Do not hand-roll scroll listeners, background-attachment: fixed, animated blur filters, or mask gradients around an image in app CSS.
+- Do not put it in a region that does not scroll vertically; parallax needs a scroll container ancestor.
+
+**Alternatives:**
+
+- [Pane](./pane.md) (composes-with) — Place BackdropImage first in a Pane's scrolling content (or a NavStack view) so its scroller drives the parallax.
+- [SunkenPanel](./sunken-panel.md) (nearest) — Use SunkenPanel for a lowered work surface without imagery.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/backdrop-image` — exports `BackdropImage`.
+- CSS: the browser build of `@kerfjs/ui/backdrop-image` pulls its CSS automatically; import `@kerfjs/ui/backdrop-image.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/backdrop-image`](../public-api-signatures-v1.md#kerfjsuibackdrop-image) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- fitted image (cover, contain, fill) with a focal position
+- tiled background (repeat, repeat-x, repeat-y)
+- parallax none, subtle, or a 0 to 1 lag factor
+- progressive blur from a once-filtered copy or an app-supplied blurred asset, with an optional dim
+- fade into a color that also paints below
+- bottom or full scrim under overlay content
+- image running beneath clear or overlay chrome (underChrome)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the image, its alt text (empty for a decorative image), and responsive candidates; the fade color, whether the image lags the scroll, and whether it blurs (and any pre-blurred asset); overlay content and its contrast against the image and scrim; the content below the image; whether the image runs up beneath overlay or clear chrome and the top safe area (underChrome); it must then be the first child of the Pane's content.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The root bleeds to the Pane's resolved inline insets (the safe area) and hands them back to its overlay and content, so their items keep the ordinary text axis.
+- The image block is height tall (default 320px) and grows with taller overlay content.
+
+## Accessibility
+
+- alt describes a meaningful image; pass an empty alt for a decorative one. A tiled image with alt text is exposed as role="img". Parallax and the progressive blur run only with prefers-reduced-motion: no-preference and scroll-driven animation support, and are off under data-kui-effects="static" and on slow-update displays, leaving a static, sharp image; the blurred copy is decorative and aria-hidden. Reduced transparency or increased contrast replaces the fade with a hard edge on solid fadeTo and puts overlay content on a solid fadeTo band. Overlay text needs a scrim or fade color that keeps it at AA.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-backdrop-image`.
+
+Never put `kui-backdrop-image` on an element you write; render `BackdropImage` instead (`KUI-L103`).
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [Pane](./pane.md), [SunkenPanel](./sunken-panel.md).
+- Docs: [`docs/backdrop-image.md`](../../docs/backdrop-image.md), [`docs/backdrop-image.md#fallbacks`](../../docs/backdrop-image.md#fallbacks).
+- UX catalog route: `?component=backdrop-image`.

package/ai/components/badge.md

@@ -0,0 +1,76 @@
+# Badge
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:badge` · Kerf UI · component · Foundation
+
+Self-styled, non-interactive status, count, and category metadata configured through semantic tone, appearance, shape, and size props.
+
+## When to use
+
+Present compact metadata without application-authored badge CSS or consumer styling of component internals.
+
+- Show a short status, count, category, or metadata label whose presentation should be configured rather than restyled.
+
+**Not when:**
+
+- Do not use Badge as a button, link, or removable chip; choose an interactive control with the correct native semantics.
+- Do not rely on tone alone to communicate meaning.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/badge` — exports `Badge`.
+- CSS: the browser build of `@kerfjs/ui/badge` pulls its CSS automatically; import `@kerfjs/ui/badge.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/badge`](../public-api-signatures-v1.md#kerfjsuibadge) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- neutral, info, pop, success, warning, or danger tone
+- quiet, solid, or outline appearance
+- pill or rounded shape
+- compact or default size, or a text-free dot (size: 'dot')
+- labeled or decorative duplicate
+- leading icon
+- title tooltip and data-\* rootAttributes
+- maxWidth caps the badge and truncates long text with an ellipsis, defaulting the title to string or number content
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** metadata text; semantic tone mapping; accessible label for abbreviated content.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: foundation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Badge is non-interactive. Supply label when visible content is abbreviated, and ariaHidden when it repeats an accessible name owned by the surrounding component. A text-free dot must take either label (exposed as an image) or ariaHidden, which the types enforce.
+- Keep meaningful text visible because tone is supplementary.
+- A label replaces abbreviated or symbolic visible text; the badge is then a labeled image (role img).
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-badge`, `kui-badge__icon`, `kui-badge__label`.
+
+Never put `kui-badge`, `kui-badge__icon`, `kui-badge__label` on an element you write; render `Badge` instead (`KUI-L103`).
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=badge`.

package/ai/components/chip.md

@@ -0,0 +1,76 @@
+# Chip
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:chip` · Kerf UI · component · Foundation
+
+A short tag with semantic or inherited tone, an optional accessible remove button, or a native link and download form, including compact and disabled variants.
+
+## When to use
+
+Render removable tags and file or link chips without application rules on Web Awesome internals or anchor chrome.
+
+- Show a short tag that the application can remove through a delegated action, including a compact or disabled tag.
+- Show a downloadable file or a short link with chip geometry, such as the referenced files of a chat message; set tone inherit inside a brand-loud or neutral ContentItem bubble.
+
+**Not when:**
+
+- Use Badge for non-interactive status and count metadata.
+- Do not use the remove button without a specific accessible name.
+- Use ListItemLink for a navigation row and ToolbarActionLink for a toolbar link.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/chip` — exports `Chip`.
+- CSS: the browser build of `@kerfjs/ui/chip` pulls its CSS automatically; import `@kerfjs/ui/chip.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/chip`](../public-api-signatures-v1.md#kerfjsuichip) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- neutral, info, pop, success, warning, danger, or inherit tone
+- quiet, solid, or outline appearance
+- pill or rounded shape
+- compact or default size
+- removable, link, or plain, enabled or disabled
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** tag text and identity; remove action and list update; link destination and download file name; disabled policy.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: foundation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- The remove control is a native button and requires an action and a specific removeLabel. A disabled chip disables that button and removes it from keyboard interaction.
+- A link chip is a native anchor named by its visible label; external adds a safe rel, a new tab, and an "(opens in new tab)" name suffix, and a disabled link chip drops its destination and leaves the tab order.
+- The inherit tone paints no fill, so its label keeps the surrounding text contrast, and its focus ring follows the surrounding foreground.
+- Keep meaningful tag text visible because tone is supplementary.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-chip`.
+
+Never put `kui-chip` on an element you write; render `Chip` instead (`KUI-L103`).
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=chip`.

package/ai/components/choice-chips.md

@@ -0,0 +1,87 @@
+# ChoiceChips
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:choice-chips` · Kerf UI · component · Controls
+
+A wrapping set of separated pill chips backed by native radios (one exclusive value) or, with multiple, native checkboxes (any number of values), with optional leading color swatches or icons.
+
+## When to use
+
+Choose one value, or with multiple any number of values, from a visible set too large for a segmented track, such as a color palette with labeled swatches or a set of annotation intents.
+
+- Expose one exclusive choice among several visible options that must wrap onto more rows, such as a labeled color palette with swatches.
+- Set multiple when the person may turn any number of visible, wrapping options on or off, such as label filters or annotation intents.
+
+**Not when:**
+
+- Use SegmentedControl for a few compact choices on one track.
+- Use Select when the choice list is long or space is tight; a multiple Select keeps a long multi-value list behind one trigger.
+- Do not use it for removable tags (Chip).
+
+**Alternatives:**
+
+- [SegmentedControl](./segmented-control.md) (nearest)
+- [Select](./select.md) (nearest)
+- [Radio Group](./wa-radio-group.md) (prefer-over) — Use ChoiceChips instead of button-appearance radios that must wrap; a joined button group wraps into ragged rows with shared borders.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/choice-chips` — exports `ChoiceChips`.
+- JavaScript: `@kerfjs/ui/css-values` — exports `fillColor`.
+- CSS: the browser build of `@kerfjs/ui/choice-chips` pulls its CSS automatically; import `@kerfjs/ui/choice-chips.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/choice-chips`](../public-api-signatures-v1.md#kerfjsuichoice-chips), [`@kerfjs/ui/css-values`](../public-api-signatures-v1.md#kerfjsuicss-values) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- color swatch, transparent (struck-through) swatch, icon, or text-only choices
+- single (radios) or multiple (checkboxes) selection
+- default or compact size
+- disabled group or disabled choices
+- required (single selection only)
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `choices[].swatch`: color grammar; raw values: forbid; shorthands `transparent`; helpers `fillColor`, `uiColor`, `colorVar` — e.g. `swatch: fillColor("#3b82f6")`
+
+## Composition
+
+- Parents: any.
+- Contexts: `wrapping-exclusive-choice`, `wrapping-multiple-choice`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+- value — controlled
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Name the radio group (or, with multiple, the checkbox group) with label or with labelledBy pointing at a visible heading.
+- Every choice keeps a visible text label; a swatch or icon is decorative.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-choice-chips`.
+
+Never put `kui-choice-chips` on an element you write; render `ChoiceChips` instead (`KUI-L103`).
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md), [SegmentedControl](./segmented-control.md), [Select](./select.md), [Radio Group](./wa-radio-group.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/accessibility.md#choicechips`](../../docs/accessibility.md#choicechips).
+- UX catalog route: `?component=choice-chips`.

package/ai/components/collapsible-panel.md

@@ -0,0 +1,103 @@
+# CollapsiblePanel
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:collapsible-panel` · Kerf UI · component · Structure
+
+A standalone controlled left or right rail or bottom drawer with standard collapse icons and optional compact-overlay behavior through wireSidebar.
+
+## When to use
+
+Add one independently collapsible peripheral panel without adopting the complete multi-panel Workbench shell.
+
+- An application needs one collapsible side rail or bottom drawer outside a full Workbench.
+- The panel should become a dismissable, focus-managed overlay on compact devices.
+
+**Not when:**
+
+- Do not use CollapsiblePanel for a complete editor shell with multiple coordinated rails and a drawer; use Workbench.
+- Do not preserve an empty icon-only rail when collapsed; move the restore control into adjacent visible chrome.
+
+**Alternatives:**
+
+- [Workbench](./workbench.md) (larger-composition) — Use Workbench when the central work area coordinates multiple peripheral panels.
+- [Collapsible Sidebar](./recipe-collapsible-sidebar.md) (recipe) — Use the production recipe for collapse, restore, compact overlay, focus, and persistence ownership.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/collapsible-panel` — exports `CollapsiblePanelSide`, `collapsiblePanelToggleIcon`, `CollapsiblePanelToolbarToggle`, `CollapsiblePanelToolbar`, `CollapsiblePanelToggleProps`, `CollapsiblePanelToggle`, `CollapsiblePanelProps`, `CollapsiblePanel`, `CollapsiblePanelRelocatedProps`, `CollapsiblePanelRelocated`.
+- CSS: the browser build of `@kerfjs/ui/collapsible-panel` pulls its CSS automatically; import `@kerfjs/ui/collapsible-panel.css` manually only without the `browser` export condition.
+- Wiring: `wireSidebar` from `@kerfjs/ui/wire-sidebar` (required).
+- Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/collapsible-panel`](../public-api-signatures-v1.md#kerfjsuicollapsible-panel), [`@kerfjs/ui/wire-sidebar`](../public-api-signatures-v1.md#kerfjsuiwire-sidebar), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- left rail
+- right rail
+- bottom drawer
+- collapsed
+- compact overlay
+- compact responsive replacement
+- hidden separator
+- slide, fade-slide, or instant content
+- clipped, scrolling, or popup-visible content
+- safe-area restore control
+- chrome dividers only while scrolled (wired by wireScrollDividers)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** controlled collapsed state; panel content and size; toggle placement; persistence policy; compact-device policy.
+
+**Wiring:** `wireSidebar`, `wireScrollDividers` is required.
+
+- Use wireSidebar as documented.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-collapsible-responsive` on `the root passed to wireSidebar` (`wireSidebar`): With a deviceClass: "inline" on a wide device class, otherwise the compact presentation ("overlay" or "hidden"). Re-applied if a re-render drops it.
+- `data-collapsible-overlay` on `the root passed to wireSidebar` (`wireSidebar`): With a deviceClass on a compact device: "true" for the overlay presentation, "false" for hidden. Absent on a wide device class. Re-applied if a re-render drops it.
+- `data-morph-preserve` on `kui-collapsible-panel__backdrop` (`wireSidebar`): Keeps the injected compact-overlay backdrop through the application's re-render; the helper creates and removes the backdrop itself.
+- `data-scroll-overflow` on `kui-pane__content of each panel and work-area Pane` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
+- `data-scroll-divider` on `kui-pane__header and kui-pane__footer of each panel and work-area Pane` (`wireScrollDividers`): The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it.
+- `data-header-overlay` on `kui-pane` (`wireScrollDividers`): measured once the wiring has measured a Pane's overlay header (headerPresentation: overlay) and published its border-box height as --kui-scroll-clearance-block-start on the Pane root, plus a classic content scrollbar's inline size as --kui-pane-scrollbar-inline-size, which the header leaves uncovered. Re-applied if a re-render drops it.
+
+## Geometry
+
+Margin: none · border: self · padding: child (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The panel owns its dock-edge separator and size track; its child content owns internal padding and scrolling.
+
+## Accessibility
+
+- Give the panel region and every collapse or restore control an accessible label.
+- Keep the restore control outside the disappearing panel and use wireSidebar for focus transfer, Escape, backdrop dismissal, and compact focus trapping.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-collapsible-panel`, `kui-collapsible-panel--left`, `kui-collapsible-panel--right`, `kui-collapsible-panel--bottom`, `kui-collapsible-panel__content`, `kui-collapsible-panel__restore`, `kui-collapsible-panel__backdrop`, `kui-collapsible-panel__toggle`.
+
+Never put `kui-collapsible-panel`, `kui-collapsible-panel--left`, `kui-collapsible-panel--right`, `kui-collapsible-panel--bottom`, `kui-collapsible-panel__content`, `kui-collapsible-panel__restore`, `kui-collapsible-panel__backdrop`, `kui-collapsible-panel__toggle` on an element you write; render `CollapsiblePanel` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-collapsible-panel-width`, `--kui-collapsible-panel-height`, `--kui-collapsible-panel-popup-z`, `--kui-collapsible-panel-overlay-z`, `--kui-collapsible-panel-restore-inset`, `--kui-collapsible-panel-restore-z`, `--kui-collapsible-panel-backdrop-z`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md), [Workbench](./workbench.md), [Collapsible Sidebar](./recipe-collapsible-sidebar.md).
+- Docs: [`docs/collapsible-panel.md`](../../docs/collapsible-panel.md), [`docs/collapsible-panel.md#recipe-and-coverage`](../../docs/collapsible-panel.md#recipe-and-coverage).
+- UX catalog route: `?component=collapsible-panel`.