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

package/docs/list-detail-dialog.md

@@ -0,0 +1,100 @@
+# List-detail dialog
+
+`@kerfjs/ui/list-detail-dialog` is the modal form of a list-detail layout: a
+list column beside the selected item's detail, each running the dialog's full
+height. It is one of three dialog types:
+
+| Type                                                           | Use it for                                               |
+| -------------------------------------------------------------- | -------------------------------------------------------- |
+| `DialogSurface` ([surface-scaffold.md](surface-scaffold.md))   | One pane: a title, a body, and footer buttons.           |
+| `ListDetailDialog` (this page)                                 | Pick a record from a list and show its detail beside it. |
+| `WorkbenchDialog` ([workbench-dialog.md](workbench-dialog.md)) | An editing task with side panels.                        |
+
+```ts
+import {
+  ListDetailDialog,
+  openDialog,
+} from "@kerfjs/ui/list-detail-dialog";
+import { deviceClass } from "@kerfjs/ui/device-class";
+```
+
+In a browser bundler that honors the `browser` export condition, the import
+also loads the stylesheets of every component it renders (DialogSurface,
+SplitView, NavStack, Pane, and the toolbar components). Without that
+condition, import `@kerfjs/ui/list-detail-dialog.css`, which pulls in the same
+stylesheets, or `@kerfjs/ui/styles.css`.
+
+## Where things go
+
+- **The detail column owns the dialog's identity.** Its header toolbar carries
+  the primary title (an xl level-2 heading, with an optional `description`
+  line), the `actions` you pass, and the close control, last. Record actions go
+  in the detail `footer`, pinned below the scrolling detail.
+- **The list column is secondary.** Its header carries `list.title` at the
+  default toolbar size, so it reads as pane identity beside the primary title,
+  followed by your `list.toolbar` controls. An add control or count can go in
+  `list.footer`.
+- **The surface draws no header.** Both columns start at the dialog's top
+  edge, so the divider between them runs the dialog's full height.
+- **The description is yours to name.** The detail `description` describes the
+  selected record, not the dialog, so it is not the dialog's accessible
+  description. Pass `describedBy`, the id of app-owned summary copy, to render
+  `aria-describedby` on the dialog.
+
+Each column is a `Pane`: its header and footer stay pinned and its content
+scrolls on its own. Pass content that owns its geometry, usually a `List`.
+
+## Responsive by device class
+
+The component is declarative. The app derives `compact` from the device class
+and tracks its own selection and, on compact devices, whether the detail is
+pushed:
+
+```tsx
+const device = deviceClass();
+const selected = signal("atlas");
+const detailOpen = signal(false);
+
+<ListDetailDialog
+  id="projects"
+  label="Project Details"
+  compact={device.value.compact}
+  detailActive={detailOpen.value}
+  backLabel="Back to Projects"
+  list={{
+    title: "Recent Projects",
+    content: <List>{rows}</List>,
+  }}
+  detail={{
+    title: project.name,
+    content: <List>{details}</List>,
+    footer: actions,
+  }}
+/>;
+```
+
+- **Roomy** (`compact: false`): a modal of `size` `large` with a definite
+  height (default 560px, bounded by the viewport; pass `maxHeight` instead to
+  size it to its content). The list column is 280px, at most 40% of the
+  dialog, by default; set `list.width` like SplitView's `listWidth`.
+- **Compact** (`compact: true`): the dialog fills the screen and becomes a
+  `NavStack`. The list is the root view (titled `list.title`, with its toolbar
+  controls); `detailActive` pushes the detail (titled `detail.title`, with its
+  `actions`). Every view keeps the close control, and each view's `footer` is
+  pinned below it. The stack's back control dispatches `nav-back`; set
+  `detailActive` back to `false` in response. Wire `wireNavStack` above it for
+  the push and pop motion.
+
+Render one `ListDetailDialog` for both presentations, so crossing the compact
+breakpoint while it is open morphs it in place and it stays open.
+
+## Opening and closing
+
+It is a `DialogSurface` underneath: open it with `openDialog(element)` and close
+it with `closeDialog(element)`, the close control, Escape, an element with
+`data-dialog-close`, or (with `lightDismiss`) a press on the backdrop. Both
+functions are re-exported from this subpath. Give sibling dialogs distinct
+`rootAttributes['data-key']` values so a re-render morphs each into itself.
+
+See the [list-detail dialog recipe](recipes.md#list-detail-dialog) for a
+complete, production-backed example.

package/docs/manual-test-plan.md

@@ -0,0 +1,55 @@
+# Manual test plan
+
+Checks that automation cannot make truthfully. Run the catalog with
+`npm run dev:lan` and open the printed URL on the device (see
+[`ux-demo.md`](ux-demo.md)). Record the device, OS, and browser versions and the
+result on the tracking ticket.
+
+## DialogSurface bottom sheet: virtual keyboard and safe areas
+
+Route: `?component=surface-scaffold`, example "Resizable Bottom Sheet". Run on
+an iPhone (Safari) and an Android phone (Chrome).
+
+1. Open the sheet and focus the Message field. The keyboard pushes the sheet's
+   content above it, and the panel runs behind the keyboard with no gap.
+2. Rotate the phone, and pinch-zoom while the keyboard is open. The content
+   stays clear of the keyboard; while zoomed, the measured overlap is 0 and the
+   page relies on `dvh`.
+3. Dismiss the keyboard. The bottom padding returns to the home-indicator safe
+   area, and the sheet's square bottom edge meets the screen edge.
+4. Drag the grabber, with and without the keyboard open. The sheet resizes
+   between its minimum height and the screen less the top safe area.
+
+Playwright cannot raise a virtual keyboard; the overlap formula is unit-tested
+(`tests/unit/dialog-surface-controller.test.tsx`) and a simulated keyboard is covered
+in `tests/browser/dialog-bottom-sheet.spec.ts`.
+
+## Automated coverage summary
+
+The feed-card route `?component=content-item`, example "Image-Tinted Feed
+Cards", has unit coverage for image state transitions and three-engine browser
+coverage for independent timelines, reverse scrolling, image error/recovery,
+light/dark tint contrast, reduced motion, increased contrast, and forced
+colors. Wide and narrow light/dark captures were inspected for text, controls,
+image clipping, and card spacing. A 50/200-card Chromium trace checks node and
+listener growth; it uses repeated sample artwork, so a production feed with
+unique high-resolution assets still needs its own image-cache profiling.
+The composed BackdropImage card has browser checks for its edge geometry,
+fade, scrim, and focusable overlay at wide and narrow sizes; inspect the same
+states in both captured WebKit views.
+
+The remaining device-only checks above require a real mobile keyboard.
+The List View Transitions catalog example has unit coverage for its row edits,
+pending-snapshot queue, and clip lifecycle, with browser coverage for real controls, fallback,
+reduced motion, and wide/narrow layout. Its animation was visually inspected
+at both widths; the browser tests verify names and state after each edit.
+The real catalog scroll position is checked during and after all four List
+transition actions at wide and narrow viewports. During motion, check that
+named rows stay within the visible example and do not cover the catalog footer
+or neighboring examples; the browser suite checks the computed transition
+clip at wide and narrow viewports. Also check that the catalog header, sidebar,
+and surrounding examples remain painted throughout the transition; browser
+captures compare a header pixel before and during motion at narrow, medium,
+and review-sized viewports.
+The row viewport has a fixed height across Reorder, Insert Delta, Remove Last,
+and Reset; inspect the disappearing last row within it at wide and narrow sizes.

package/docs/message-composer.md

@@ -0,0 +1,156 @@
+# MessageComposer
+
+`MessageComposer` (`@kerfjs/ui/message-composer`, CSS `@kerfjs/ui/message-composer.css`) is the chat
+or prompt composer: the place a person writes a message, assistant prompt, or
+reply and sends it with a trailing action. It replaces app-owned composer
+chrome, such as a `wa-textarea` and a button wrapped in application CSS that
+draws a frame, a focus border, and a shadow.
+
+## Contract
+
+```tsx
+<MessageComposer
+  id="assistant-message"
+  name="message"
+  label="Message"
+  placeholder="Ask about this build"
+  hint="Answers use the latest nightly build."
+  minRows={1}
+  maxRows={8}
+  trailing={
+    <Button tone="brand" action="send-message">
+      Send
+    </Button>
+  }
+/>
+```
+
+- **Frame.** The root is a raised surface (`--kui-color-surface-raised`) with
+  the standard 1px neutral border, the large radius (`--kui-radius-l`), and
+  `--kui-shadow-l`. While focus is anywhere within it, including on a trailing
+  action, the border turns `--kui-color-brand-border-loud`. The frame owns
+  8px padding, so a composer placed 8px from a container edge puts its text on
+  the same 17px column as a `List` of content items beside it.
+- **Field.** A native, borderless `<textarea>` named by `label`. It sizes to
+  its content with `field-sizing: content`, between `minRows` (default 1) and
+  `maxRows` (default 8) lines, and scrolls past the maximum. Both bounds are
+  positive integers, and `maxRows` is at least `minRows`; otherwise `MessageComposer`
+  throws a `RangeError`. In an engine without `field-sizing`, the field keeps
+  a fixed height of three lines, clamped to the bounds, and scrolls.
+- **Action row.** Below the field, a compact `Toolbar` (footer semantics,
+  named "<label> Actions") that the composer insets for you. Its leading zone
+  holds optional `leading` controls, such as an attach button or a model
+  `Select` in a `ToolbarControlGroup`, then the optional quiet `hint`; its
+  trailing zone holds `trailing`, normally one brand Send `Button`. Every
+  toolbar convention applies, from control groups to responsive relocation.
+  With an `id`, the hint is the field's accessible description
+  (`<id>-hint`).
+- **Value.** `value` seeds the field (a restored draft, or `''`). The app
+  reads the textarea in its send action, clears it, and re-renders.
+- **Disabled.** `disabled` disables the field; the app disables or marks busy
+  its own actions.
+- **Placement.** Pass it as a `DialogSurface`'s `footer`, or use `slot` to
+  assign it to a web component slot. `rootAttributes` takes safe `data-*`
+  identity.
+- **Enter to send.** `submitOnEnter` opts in to the keyboard contract below;
+  it marks the root `data-submit-on-enter="true"` (protected from
+  `rootAttributes`) and gives the field `aria-keyshortcuts="Enter"`.
+
+The app owns sending, any other keyboard shortcut, what a sent message looks
+like, and where the composer sits.
+
+## Enter to send
+
+Set `submitOnEnter` and call `wireMessageComposers` once over an ancestor of every
+such composer; it returns a disposer:
+
+```ts
+import { wireMessageComposers } from '@kerfjs/ui/wire-message-composers';
+
+const stopMessageComposers = wireMessageComposers(app);
+```
+
+In an opted-in composer's field:
+
+| Key                                          | Result                                                                                                    |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Enter, Cmd+Enter, Ctrl+Enter                 | Clicks the composer's **first trailing action**; the newline is suppressed.                               |
+| Shift+Enter, Alt+Enter                       | Inserts a newline, as in any textarea.                                                                    |
+| Enter committing an IME composition          | Left to the input method: `isComposing`, keyCode 229, or between `compositionstart` and `compositionend`. |
+| Enter on an empty or whitespace-only message | Nothing: no send and no newline.                                                                          |
+| Auto-repeating Enter (key held down)         | Nothing.                                                                                                  |
+
+The first trailing action is the first `button` (a `Button`), `wa-button`, or
+`[data-action]` element inside `actions`. Clicking it means the keyboard send
+runs the same delegated `data-action` handler as a pointer send, so the app
+writes one send handler that reads the field, clears it, and re-renders. The
+click does not move focus, so the person keeps typing. Nothing is sent while
+the field is `disabled`, or while that action has a `disabled` attribute or
+property, `aria-busy="true"` (a busy `Button`), a `loading` attribute (a busy
+`wa-button`), or `aria-disabled="true"`; the Enter is still suppressed, so a message waiting on
+a busy Send does not gain a newline.
+
+Leave `submitOnEnter` off for a long-form prompt where Enter should be a
+newline, and send with the action alone. A visible `hint` may also state the
+shortcut ("Enter to send, Shift+Enter for a new line") when the audience may
+not expect it; `aria-keyshortcuts` already announces it to assistive
+technology.
+
+## In a chat dialog
+
+A chat dialog floats the composer over its transcript. Use a `DialogSurface`
+with `bodyLayout="fill-last"` and `footerPresentation="floating"` (and
+`footerInset="none"`, since the composer draws its own frame), and slot the
+composer into the footer:
+
+```tsx
+<DialogSurface
+  id="assistant"
+  label="Assistant"
+  height={remify(560)}
+  bodyInset="none"
+  bodyLayout="fill-last"
+  footerPresentation="floating"
+  footerOffset={remify(8)}
+  footerInset="none"
+  footer={<MessageComposer submitOnEnter id="assistant-message" name="message" label="Message" placeholder="Ask about this build" trailing={send} />}
+>
+  <StateBanner title="Answers use the latest nightly build." tone="neutral" />
+  <List gap="xs" controlInsets="tb" scrollable scrollClearance="block-end">{messages}</List>
+</DialogSurface>;
+```
+
+The floating footer is transparent, so the composer's own frame and shadow
+lift it over the transcript. The transcript's `scrollClearance="block-end"`
+lets messages scroll visibly beneath the composer while the last one still
+comes to rest above it, following the composer's measured height as it grows.
+Without the opt-in, the dialog body reserves that height below the transcript
+instead.
+
+## Do not
+
+- Wrap it in a framed `ContentItem`, card, or bordered container; it owns its
+  frame, padding, and shadow.
+- Style its field, frame, or action row from application CSS. A variation it
+  does not offer is a component gap.
+- Use it for an ordinary form field submitted with the rest of a form; use
+  a `multiline` `TextField`.
+
+## Verification
+
+`tests/unit/message-composer.test.tsx` covers serialization, the hint description,
+row bounds, and protected attributes; `tests/unit/wire-message-composers.test.tsx`
+covers the Enter-to-send matrix (modifiers, IME, empty, repeat, disabled
+field and actions, first action only, disposal). `tests/browser/message-composer.spec.ts` covers
+the focus-within border, growth up to `maxRows` and then scrolling, the action
+row geometry, and the send flow at wide and phone widths, and, in Chromium,
+Firefox, and WebKit, Enter, Shift+Enter, Cmd/Ctrl+Enter, empty messages, and
+IME composition (dispatched composition events and keyCode 229). In
+Chromium it also drives a real IME composition through the DevTools protocol
+(`Input.imeSetComposition`, then `Input.insertText` to commit). That test
+asserts the engine's own event order: an Enter keydown flagged `isComposing`
+while composing, the committing `Process` keydown with keyCode 229, then
+`compositionend`. None of those sends, the committed text lands in the field,
+and the next Enter sends it;
+`tests/browser/surface-scaffold.spec.ts` covers the composer in the floating
+footer of the chat dialog, including Enter to send.