@kerfjs/ui 5.0.0-beta.103 → 5.0.0-beta.105

package/ai/components/wa-toast.md

@@ -2,20 +2,22 @@
 
 <!-- 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-toast` · Web Awesome · component · Feedback · recommendation: supported
+`@kerfjs/ui:wa-toast` · Web Awesome · component · Feedback · recommendation: avoid
 
 ## When to use
 
-Placement-aware stack of transient notifications.
+Ecosystem toast stack; use kerfjs/overlay toast() with @kerfjs/ui/overlay-toast.css.
+
+- Placement-aware stack of transient notifications.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- Do not use it in Kerf UI; call toast() from kerfjs/overlay with @kerfjs/ui/overlay-toast.css imported, which styles the region, tones, StateBanner content, and motion.
 
 **Alternatives:**
 
-- [StateBanner](./state-banner.md) (prefer-kerf)
-- [EmptyState](./empty-state.md) (prefer-kerf)
+- [Toast](./toast.md) (prefer-kerf) — Use kerfjs/overlay toast() styled by @kerfjs/ui/overlay-toast.css for a transient notification.
+- [StateBanner](./state-banner.md) (prefer-kerf) — Use a StateBanner in place for a persistent status tied to one surface.
 
 ## Imports
 
@@ -55,6 +57,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Toast Item](./wa-toast-item.md), [StateBanner](./state-banner.md), [EmptyState](./empty-state.md).
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage), [`docs/component-selection.md#web-awesome-overlap-policy`](../../docs/component-selection.md#web-awesome-overlap-policy).
+- Components: [Toast Item](./wa-toast-item.md), [Toast](./toast.md), [StateBanner](./state-banner.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-toast`.

package/ai/components/wa-tooltip.md

@@ -2,15 +2,21 @@
 
 <!-- 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-tooltip` · Web Awesome · component · Feedback · recommendation: supported
+`@kerfjs/ui:wa-tooltip` · Web Awesome · component · Feedback · recommendation: avoid
 
 ## When to use
 
-Brief contextual label anchored to a control.
+Ecosystem tooltip; use kerfjs/overlay tooltip() with @kerfjs/ui/overlay-tooltip.css.
+
+- Brief contextual label anchored to a control.
 
 **Not when:**
 
-- Do not choose it from catalog presence alone; confirm that its semantic and interaction contract matches the product need.
+- Do not use it in Kerf UI; call tooltip() from kerfjs/overlay with @kerfjs/ui/overlay-tooltip.css imported. Icon-only Kerf controls already get help tags.
+
+**Alternatives:**
+
+- [Tooltip](./tooltip.md) (prefer-kerf) — Use kerfjs/overlay tooltip() styled by @kerfjs/ui/overlay-tooltip.css for a hover and focus tooltip.
 
 ## Imports
 
@@ -50,6 +56,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Popup](./wa-popup.md).
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
+- Components: [Popup](./wa-popup.md), [Tooltip](./tooltip.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-tooltip`.

package/ai/components/wa-tree-item.md

@@ -11,6 +11,7 @@ Specialized tree row; use only as part of a required tree.
 **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
 
@@ -51,5 +52,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## Related
 
 - Components: [Checkbox](./wa-checkbox.md), [Icon](./wa-icon.md), [Spinner](./wa-spinner.md).
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage), [`docs/component-selection.md#web-awesome-overlap-policy`](../../docs/component-selection.md#web-awesome-overlap-policy).
+- 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-tree-item`.

package/ai/components/wa-tree.md

@@ -11,6 +11,7 @@ Specialized hierarchy; use only when the product requires tree behavior.
 **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
 
@@ -51,5 +52,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## Related
 
 - Components: [Tree Item](./wa-tree-item.md).
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage), [`docs/component-selection.md#web-awesome-overlap-policy`](../../docs/component-selection.md#web-awesome-overlap-policy).
+- 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-tree`.

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

@@ -11,6 +11,7 @@ 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
 
@@ -51,5 +52,5 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 ## Related
 
 - Components: [Icon](./wa-icon.md).
-- Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage), [`docs/component-selection.md#web-awesome-overlap-policy`](../../docs/component-selection.md#web-awesome-overlap-policy).
+- 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; 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`.