@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/ai/components/wa-zoomable-frame.md

@@ -0,0 +1,56 @@
+# Zoomable Frame
+
+<!-- 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:wa-zoomable-frame` · Web Awesome · component · Media · recommendation: avoid
+
+## When to use
+
+Avoid for application UI; keep embedded-media behavior application-owned.
+
+**Not when:**
+
+- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- Use it only in an application that has adopted the optional Web Awesome integration (registration imports plus @kerfjs/ui/webawesome.css); a Kerf-only application uses a Kerf component or a native element instead.
+
+## Imports
+
+- Theme CSS: import `@kerfjs/ui/webawesome.css` once.
+- Registration: import `@awesome.me/webawesome/dist/components/zoomable-frame/zoomable-frame.js` once (a side effect).
+- Custom element: `<wa-zoomable-frame>`.
+- Declared side effects: custom-element-registration.
+
+## Props
+
+Typed JSX attributes: [`webawesome-jsx-signatures-v1.md`](../webawesome-jsx-signatures-v1.md) (import `@kerfjs/ui/webawesome` for types only). Use the Web Awesome attribute API; do not reach into its shadow DOM.
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Icon](./wa-icon.md).
+
+## State and wiring
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: child (layout role: media). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+No component-specific obligations beyond native semantics and a visible or accessible name for every control.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not restyle its shadow DOM or uncataloged `::part()` targets (`KUI-L011`).
+
+## Related
+
+- Components: [Icon](./wa-icon.md).
+- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage), [`docs/component-selection.md#web-awesome-integration`](../../docs/component-selection.md#web-awesome-integration).
+- UX catalog route: `?component=wa-zoomable-frame`.

package/ai/components/workbench-dialog.md

@@ -0,0 +1,90 @@
+# WorkbenchDialog
+
+<!-- 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:workbench-dialog` · Kerf UI · component · Structure
+
+A modal workbench dialog: a header-less DialogSurface whose body is a Workbench. The work area's toolbar carries the dialog's primary title, actions, and close control; side rails keep their own toolbars and run the dialog's full height; compact devices get a full-screen dialog whose rails open as overlays over the work area.
+
+## When to use
+
+Present an editing task with side panels (layers, an inspector) inside a modal, with the dialog's title and close control in the work area and rails that overlay the work area on compact devices instead of narrowing it.
+
+- A modal editing task needs a work area with side panels (a slide or record editor with layers and an inspector): render WorkbenchDialog with main and leftRail/rightRail, open it with openDialog(), pass compact from deviceClass().value.compact, and wire wireWorkbench on the Workbench id (\<id>-workbench) with each rail's collapsed signal.
+- On compact devices the rails should start hidden and open as overlays from toolbar toggles, keeping the work area's width.
+
+**Not when:**
+
+- Do not use it for a single-pane dialog; use DialogSurface.
+- Do not use it to pick a record from a list beside its detail; use ListDetailDialog.
+- Do not compose DialogSurface around a Workbench by hand for this layout; the surface header would span the rails and the close control would not follow a hidden rail's toggle.
+- Do not use it when the task needs a durable route; use a page with Workbench.
+
+**Alternatives:**
+
+- [ListDetailDialog](./list-detail-dialog.md) (nearest) — Use ListDetailDialog to pick a record from a list and show its detail.
+- [Surface Scaffolds](./surface-scaffold.md) (nearest) — Use DialogSurface for a single-pane dialog.
+- [Workbench](./workbench.md) (responsive-alternative) — Use Workbench for the same layout as a page rather than a modal.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/workbench-dialog` — exports `WorkbenchDialog`, `WorkbenchDialogProps`, `WorkbenchDialogRootAttributes`, `openDialog`, `closeDialog`.
+- CSS: the browser build of `@kerfjs/ui/workbench-dialog` pulls its CSS automatically; import `@kerfjs/ui/workbench-dialog.css` manually only without the `browser` export condition.
+- Wiring: `wireWorkbench` from `@kerfjs/ui/wire-workbench` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/workbench-dialog`](../public-api-signatures-v1.md#kerfjsuiworkbench-dialog), [`@kerfjs/ui/wire-workbench`](../public-api-signatures-v1.md#kerfjsuiwire-workbench) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- roomy modal: full-height left and right rails with their own toolbars beside the work area
+- a hidden rail's toggle relocates into the work area's toolbar, before the close control
+- work-area leading groups, actions, a description under the title, a fixed footer, and a bottom toolbar
+- a bottom drawer under the work area
+- compact full-screen dialog with overlay rails that start hidden
+- definite height (default 560px) or a height cap, viewport gutter, size or preferred width, and light dismiss
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Surface Scaffolds](./surface-scaffold.md), [Workbench](./workbench.md), [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** open state (openDialog and closeDialog); device-class policy (compact), and starting the rails collapsed on compact devices; each rail's collapsed state and toggle actions (wireWorkbench closes an overlay rail on Escape or an outside press); the work area, rail content, actions, and bottom toolbar; dismissal policy (lightDismiss).
+
+**Wiring:** `wireWorkbench` is optional.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-responsive-overlay-active` on `kui-workbench__rail and kui-workbench__drawer` (`wireWorkbench`): Present while a panel's numeric responsiveOverlayAt threshold applies to the Workbench width; the same measurement drives overlay layout and collapsed-state transitions.
+- `data-numeric-overlays` on `kui-workbench` (`wireWorkbench`): Space-separated left, right, drawer, rail-open, and open tokens mirror numeric overlay state for local CSS invalidation. Absent when no numeric overlay is active.
+- `data-handle-inset` on `kui-workbench__rail` (`wireWorkbench`): Written by the shared resize wiring when the work-area minimum or a parent clamp holds a rail's maximum near its size. It carries no Workbench styling; the Workbench handle stays at the rail's inner edge.
+- `data-resizing` on `kui-workbench__rail` (`wireWorkbench`): Present on a resizable rail or the drawer while a pointer drag resizes it.
+
+## Geometry
+
+Margin: parent · 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 dialog draws no header and no body inset; the Workbench's work area and rails own their chrome and content insets, and the rail dividers run the dialog's full height.
+
+## Accessibility
+
+- It is a native modal \<dialog> named by label: the page is inert, focus stays inside, Escape asks to close, and focus returns to the opener on close.
+- The title is a level-2 heading, and its description (id \<id>-description) is the dialog's accessible description unless describedBy names other content; the close control is named Close (closeLabel) and stays the outermost trailing control. An open overlay rail takes focus, keeps Tab inside it, and closes on Escape before the dialog does.
+
+## 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: [Surface Scaffolds](./surface-scaffold.md), [Workbench](./workbench.md), [Pane](./pane.md), [Toolbar](./toolbar.md), [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [LucideIcon](./lucide-icon.md), [ListDetailDialog](./list-detail-dialog.md).
+- Docs: [`docs/workbench-dialog.md`](../../docs/workbench-dialog.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=workbench-dialog`.

package/ai/components/workbench.md

@@ -0,0 +1,120 @@
+# Workbench
+
+<!-- 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:workbench` · Kerf UI · component · Structure
+
+A desktop-class multi-panel workspace with independently collapsible, optionally drag-resizable left and right rails and a bottom drawer around one central work area.
+
+## When to use
+
+Arrange a complex tool or editor as a stable central work area with optional peripheral rails and a bottom drawer.
+
+- A desktop-class tool needs a central work area plus independently collapsible navigator, inspector, or console regions.
+- A desktop-class tool should let people size its peripheral panels by dragging or with the keyboard; opt each panel in with resizable and wire it with wireWorkbench.
+
+**Not when:**
+
+- Do not shrink the full multi-panel shell onto compact devices; present peripheral content through NavStack or overlay drawers instead.
+- Do not use Workbench for one standalone collapsible rail or drawer; use CollapsiblePanel.
+- Do not offer resizing where rails present as compact overlay drawers or are replaced; set a panel's responsiveOverlayAt, or pass deviceClass so wireWorkbench suspends resizing on compact classes.
+
+**Alternatives:**
+
+- [Pane](./pane.md) (composes-with) — Use Pane inside Workbench regions when fixed header/footer chrome must surround one scroll owner.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/workbench` — exports `Workbench`, `WorkbenchChromePlacement`, `WorkbenchCompactOverlay`, `WorkbenchMainBottomToolbar`, `WorkbenchMainToolbar`, `WorkbenchPanel`, `WorkbenchStaticPanel`, `WorkbenchNavigationPanel`, `WorkbenchPanelResizable`, `WorkbenchPanelToggle`, `WorkbenchPanelToolbar`, `WorkbenchProps`, `WorkbenchResponsiveOverlayAt`.
+- CSS: the browser build of `@kerfjs/ui/workbench` pulls its CSS automatically; import `@kerfjs/ui/workbench.css` manually only without the `browser` export condition.
+- Wiring: `wireWorkbench` from `@kerfjs/ui/wire-workbench` (optional).
+- Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/workbench`](../public-api-signatures-v1.md#kerfjsuiworkbench), [`@kerfjs/ui/wire-workbench`](../public-api-signatures-v1.md#kerfjsuiwire-workbench), [`@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):**
+
+- main only
+- left rail
+- right rail
+- bottom drawer
+- all panels
+- independently collapsed panels
+- navigation panel with per-screen toolbar, fixed header, and one scroll owner; standard toggle remains last and relocates while collapsed
+- opt-in drag and keyboard resizable panels with min/max limits
+- resizable rails that leave the work area a minimum width and shrink in proportion when the Workbench narrows
+- rails or a drawer that present as overlays below a narrow or compact Workbench container breakpoint
+- transient overlay panels wired with wireWorkbench: collapsed on entering the breakpoint, closed by Escape or an outside press
+- hidden separator
+- slide, fade-slide, or instant content
+- clipped, scrolling, or popup-visible content
+- inline, overlay, or hidden responsive presentation
+- narrow or compact single-track responsive fill
+- safe-area restore control
+- chrome dividers only while scrolled (wired by wireScrollDividers)
+
+## Composition
+
+- Parents: any.
+- Contexts: `desktop-application-shell`.
+- Children: unrestricted.
+- Built from: [NavStack](./nav-stack.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `main` — JSX prop `main`; accepts `workspace-region`; exactly 1.
+- `left-rail` — no declared JSX prop; accepts `panel-region`; 0–1.
+- `right-rail` — no declared JSX prop; accepts `panel-region`; 0–1.
+- `bottom-drawer` — no declared JSX prop; accepts `panel-region`; 0–1.
+
+## State and wiring
+
+**The app owns:** panel presence and content; optional accessible name for the central region (mainLabel); collapsed state; panel sizes; navigation panel view stack and push/pop actions when navStack is supplied; responsive replacement below desktop; collapse controls and focus policy; optional main and panel focus stops and persistent outlines.
+
+**Wiring:** `wireWorkbench`, `wireScrollDividers` is optional.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-responsive-overlay-active` on `kui-workbench__rail and kui-workbench__drawer` (`wireWorkbench`): Present while a panel's numeric responsiveOverlayAt threshold applies to the Workbench width; the same measurement drives overlay layout and collapsed-state transitions.
+- `data-numeric-overlays` on `kui-workbench` (`wireWorkbench`): Space-separated left, right, drawer, rail-open, and open tokens mirror numeric overlay state for local CSS invalidation. Absent when no numeric overlay is active.
+- `data-handle-inset` on `kui-workbench__rail` (`wireWorkbench`): Written by the shared resize wiring when the work-area minimum or a parent clamp holds a rail's maximum near its size. It carries no Workbench styling; the Workbench handle stays at the rail's inner edge.
+- `data-resizing` on `kui-workbench__rail` (`wireWorkbench`): Present on a resizable rail or the drawer while a pointer drag resizes it.
+- `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.
+
+- Workbench owns the rail and drawer separators; each region's content owns its internal padding and scroll behavior.
+
+## Accessibility
+
+- Give the Workbench and each meaningful rail or drawer an accessible label.
+- Give the central region mainLabel when it needs its own named landmark.
+- Keep collapse controls outside the disappearing region and move focus when a controlled rerender replaces a collapse control with its restore control.
+- A resizable panel's separator is a focusable role="separator" with its size in aria-valuenow and limits in aria-valuemin/aria-valuemax; arrow keys resize by 16px, Shift+arrow by 64px, and Home/End jump to the limits. It leaves the tab order while its panel is collapsed or not inline.
+- Given a panel's collapsed signal, wireWorkbench closes an open overlay panel on Escape or an outside press and, however the panel closed, returns focus stranded inside it to the control that opened it, else to its restore control.
+- An overlay panel can cover the toolbar toggle that opened it (a narrow right rail covers an editor toolbar's trailing toggle), so give every panel that may overlay its own close control in its header: a Pane header Toolbar with a single ToolbarControlGroup around the collapsiblePanelToggleIcon(side, false) button.
+
+## 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-workbench`, `kui-workbench__rail`, `kui-workbench__rail--left`, `kui-workbench__rail--right`, `kui-workbench__drawer`, `kui-workbench__center`, `kui-workbench__main`, `kui-workbench__panel-content`, `kui-workbench__handle`, `kui-workbench__handle-icon`, `kui-workbench__restore`, `kui-workbench__backdrop`.
+
+Never put `kui-workbench`, `kui-workbench__rail`, `kui-workbench__rail--left`, `kui-workbench__rail--right`, `kui-workbench__drawer`, `kui-workbench__center`, `kui-workbench__main`, `kui-workbench__panel-content`, `kui-workbench__handle`, `kui-workbench__handle-icon`, `kui-workbench__restore`, `kui-workbench__backdrop` on an element you write; render `Workbench` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-workbench-rail-width`, `--kui-workbench-drawer-height`, `--kui-workbench-popup-z`, `--kui-workbench-overlay-z`, `--kui-workbench-overlay-max-width`, `--kui-workbench-overlay-max-height`, `--kui-workbench-restore-inset`, `--kui-workbench-restore-z`, `--kui-workbench-overlay-dismiss-margin`. 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: [NavStack](./nav-stack.md), [Pane](./pane.md).
+- Docs: [`docs/workbench.md`](../../docs/workbench.md), [`docs/workbench.md#state-lives-in-the-app`](../../docs/workbench.md#state-lives-in-the-app).
+- UX catalog route: `?component=workbench`.