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

package/ai/components/surface-scaffold.md

@@ -15,6 +15,7 @@ Configure recurring dialog and popup geometry without consumer ::part() override
 - A modal needs a typed preferred width, viewport gutter, or dynamic viewport-bounded height cap while retaining native body scrolling and footer actions.
 - A dialog that must leave the page interactive and close on Escape or an outside press uses PopoverDialogSurface; one that fills its body with a SplitView or Pane uses height and bodyLayout="fill".
 - A chat-style dialog floats its composer over the transcript with footerPresentation="floating" and keeps a heading or notice above one scrolling transcript with bodyLayout="fill-last".
+- A phone-first task (compose, quick edit, a picker) should rise from the bottom edge as a sheet the person can resize: presentation="bottom-sheet" with height, and resizable with minHeight / maxHeight bounds.
 - A dialog's title bar should float over the body on the translucent chrome material so a transcript scrolls visibly beneath both the title bar and a floating composer (headerPresentation="floating" with bodyLayout="fill" and a List or Pane that opts into scrollClearance="both").
 
 **Not when:**
@@ -25,20 +26,22 @@ Configure recurring dialog and popup geometry without consumer ::part() override
 
 ## Imports
 
-- JavaScript: `@kerfjs/ui/surface-scaffold` — exports `DialogSurface`, `PopoverDialogSurface`, `PopupSurface`.
+- JavaScript: `@kerfjs/ui/surface-scaffold` — exports `DialogSurface`, `PopoverDialogSurface`, `PopupSurface`, `wireOverlaySheets`.
 - CSS: the browser build of `@kerfjs/ui/surface-scaffold` pulls its CSS automatically; import `@kerfjs/ui/surface-scaffold.css` manually only without the `browser` export condition.
 - Registration: import `@kerfjs/ui/surface-scaffold/register` once (a side effect).
+- Wiring: `wireOverlaySheets` from `@kerfjs/ui/wire-overlay-sheets` (optional).
 - Declared side effects: browser-condition-css, custom-element-registration.
 
 ## Props
 
-Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signatures-v1.md#kerfjsuisurface-scaffold) in `public-api-signatures-v1.md`. Do not infer props from examples.
+Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signatures-v1.md#kerfjsuisurface-scaffold), [`@kerfjs/ui/wire-overlay-sheets`](../public-api-signatures-v1.md#kerfjsuiwire-overlay-sheets) in `public-api-signatures-v1.md`. Do not infer props from examples.
 
 **Variants (configure, do not restyle):**
 
 - small, medium, or large dialog
 - data-\* rootAttributes (a data-key) so sibling dialogs morph by identity
-- modal, side-sheet, or fullscreen dialog
+- modal, side-sheet, fullscreen, or bottom-sheet dialog
+- bottom sheet attached to the bottom edge: square bottom corners, safe-area and virtual-keyboard clearance behind the panel, slide (or standard) enter and exit motion, and an optional resizable top grabber bounded by minHeight and maxHeight
 - typed modal preferred width, viewport gutter, and maximum height, including viewport cap
 - definite viewport-bounded modal height and a fill body layout for one child
 - fill-last body layout: fixed rows above one filling, scrolling last child
@@ -50,12 +53,15 @@ Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signat
 - non-modal light-dismiss PopoverDialogSurface, overlay or embedded in flow, named by label or labelledBy and described by describedBy
 - none, compact, or comfortable body and footer inset
 - standard, compact, or zero-inset popup menu
+- core kerfjs/overlay confirm/prompt/form/choice as a bottom sheet styled by @kerfjs/ui/overlay-sheet.css
+- resizable core kerfjs/overlay bottom sheet: the kui-overlay-sheet-resizable class plus wireOverlaySheets adds the resizable DialogSurface sheet grabber
 
 **CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
 
 - `preferredWidth`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `preferredWidth={remify(832)}`
 - `viewportGutter`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `viewportGutter={remify(8)}`
 - `footerOffset`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `footerOffset={remify(8)}`
+- `minHeight`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `minHeight={remify(200)}`
 - `maxHeight`: length grammar; raw values: forbid; shorthands `viewport`; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `maxHeight="viewport"`
 
 ## Composition
@@ -67,9 +73,9 @@ Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signat
 
 ## State and wiring
 
-**The app owns:** open state; focus lifecycle; dismissal policy; content; outer placement.
+**The app owns:** open state; focus lifecycle; dismissal policy; content; outer placement; whether core kerfjs/overlay dialogs presented as bottom sheets take this package's geometry and slide (import @kerfjs/ui/overlay-sheet.css; exitClass 'kui-overlay-sheet-exit' for the slide out; the kui-overlay-sheet-resizable class plus wireOverlaySheets for a resize grabber).
 
-No wiring helper.
+**Wiring:** `wireOverlaySheets` is optional.
 
 ## Geometry
 
@@ -80,6 +86,7 @@ Margin: parent · border: child · padding: self (layout role: structure). `self
 - Supply the wrapped wa-dialog label and retain Web Awesome's native modal and focus behavior.
 - Name a PopoverDialogSurface with label or labelledBy, and describe it with describedBy (rendered as aria-describedby), usually a title ToolbarText descriptionId.
 - A floating header's title uses the normal text color, which keeps WCAG AA over the 80% raised chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter.
+- A resizable bottom sheet's grabber is a focusable horizontal separator ("Resize sheet") with aria-valuemin, aria-valuenow, and aria-valuemax in visible px; the arrow keys, Page Up/Down, Home, and End resize it, and its slide motion falls back to Web Awesome's under prefers-reduced-motion.
 - Use popup surfaces only for real dropdown menus with named triggers.
 
 ## Styling boundary
@@ -94,7 +101,7 @@ Never put `kui-popover-dialog-surface` on an element you write; render `PopoverD
 
 Never put `kui-popup-surface` on an element you write; render `PopupSurface` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-radius-l`, `--kui-wa-container-inset`, `--kui-wa-surface-inset`, `--kui-chrome-material-raised`, `--kui-chrome-material-filter`, `--kui-scroll-clearance-block-start`, `--kui-scroll-clearance-block-end`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-layout-pill-radius`, `--kui-wa-container-inset`, `--kui-wa-surface-inset`, `--kui-chrome-material-raised`, `--kui-chrome-material-filter`, `--kui-scroll-clearance-block-start`, `--kui-scroll-clearance-block-end`, `--kui-safe-area-block-start`, `--kui-safe-area-block-end`. 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`).
 

package/ai/components/tab-navigator.md

@@ -45,6 +45,9 @@ Exact prop names and types: [`@kerfjs/ui/tab-navigator`](../public-api-signature
 - permanent or no bar divider (chromeDividers always or none)
 - sunken active-scene separator (separator auto or hidden)
 - translucent tab bar laid over the active scene (barPresentation overlay, measured by wireTabNavigator)
+- app-chosen navigator or per-scene background color (background, tab.background); the overlay bar keeps the chrome material
+- scoped tint (tint)
+- clear (transparent) bars with an optional scroll-edge material (barPresentation: clear, scrollEdge: material)
 
 ## Composition
 
@@ -55,7 +58,7 @@ Exact prop names and types: [`@kerfjs/ui/tab-navigator`](../public-api-signature
 
 ## State and wiring
 
-**The app owns:** controlled active tab id; tab labels, icons, and content; tab badge counts or dots and their localized badgeLabel phrases; routing and persistence; responsive replacement on larger device classes; whether the bar divider follows the scroll, always shows, or never shows (chromeDividers); whether the bar's top separator follows a sunken active surface or stays hidden (separator); optional active-scene focus (tabIndex) and persistent outline (outlined).
+**The app owns:** controlled active tab id; tab labels, icons, and content; tab badge counts or dots and their localized badgeLabel phrases; routing and persistence; responsive replacement on larger device classes; whether the bar divider follows the scroll, always shows, or never shows (chromeDividers); whether the bar's top separator follows a sunken active surface or stays hidden (separator); optional active-scene focus (tabIndex) and persistent outline (outlined); an optional app-chosen color for the navigator and its docked bar (background) and per scene (tab.background), each a typed CssColor that replaces the default or sunken fill; an optional scoped tint for the navigator (tint) or one scene (tab.tint): tint: { color, scheme } re-derives surface and text tokens from an app color with text kept at AA.
 
 **Wiring:** `wireTabNavigator`, `wireScrollDividers` is required.
 
@@ -82,6 +85,8 @@ Margin: none · border: conditional · padding: self (layout role: structure). `
 - A focusable scene is a tabpanel named by its tab label; optional scene tabIndex applies only while active.
 - A tab badge is aria-hidden; supply badgeLabel so the tab's accessible name becomes "\<label>, \<badgeLabel>" (it defaults to the badge text). The dot form, badge: true, has no text, so its badgeLabel is required.
 - Over the overlay bar's translucent material, unselected labels lift halfway toward --kui-color-text and the selected label mixes 40% of it into the brand color, so both keep 4.5:1 over worst-case content; the material turns opaque under reduced transparency or increased contrast and paints Canvas with a CanvasText edge in forced colors.
+- A background color is app-chosen: Keep text at WCAG AA over the color: a dark background needs dark-tone content or a scoped tint; forced colors paint Canvas instead.
+- Clear bars have no material of their own: keep their controls in glass ToolbarControlGroups; they turn opaque under reduced transparency or increased contrast and paint Canvas in forced colors.
 
 ## Styling boundary
 

package/ai/components/toolbar-control-group.md

@@ -16,6 +16,7 @@ Provide complete toolbar action geometry through configuration, including semant
 - For an avatar control, set content=avatar and avatarImage instead of inserting an img; one button paints the group and multiple buttons paint only the pressed highlight.
 - In a Workbench or CollapsiblePanel toolbar, mark a group relocateOnCollapse to keep it available in the work-area toolbar when the panel closes; place it directly or in an array in any toolbar zone.
 - Use tileTone for a contained single group containing only a direct decorative SVG icon; interactive or mixed groups retain their existing control chrome.
+- Set material=glass on a group floating over imagery or a clear (transparent) toolbar: it paints the translucent, blurred chrome material with a specular edge, controls keep AA in the normal text color, and the fill turns opaque under reduced transparency, increased contrast, or static effects. Keep the solid default on an opaque toolbar.
 - Set expandedOverflow=visible on an expanded search to anchor application suggestions, date pickers, or help below the group without overriding its geometry.
 - Use typed hideBelow/showBelow lengths with wireToolbarVisibility(root) for per-item toolbar priority; keep primary actions available and provide a showBelow overflow alternative.