@kerfjs/ui 5.0.0-beta.7 → 5.0.0-beta.71

package/ai/components/workbench.md

@@ -0,0 +1,118 @@
+# 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; 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.
+
+**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.
+
+## 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.
+- 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`.