@pienter/ui 0.5.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,155 @@
 
 ## Unreleased
 
+## 0.8.0 - 2026-09-15
+
+### Breaking
+
+- Index drops `headingLevel`. The heading level now follows `placement`: `h1`
+  in the default module placement, `h2` in related placement. Replace
+  `heading-level="2"` on an embedded list with `placement="related"`.
+
+### Added
+
+- Index `placement` (`module` | `related`, default `module`), exposed as
+  `data-placement` on `.pui-index`. Module is the page itself and renders flat:
+  the heading and actions above a divider, an unboxed toolbar, the table with
+  DataTable's own border and radius, and the pagination footer as a band
+  below. Related is a list inside another record's detail page and renders as
+  one bordered region holding the header, toolbar, table and pagination
+  footer, with a second-level heading. Existing consumers are unchanged; the
+  toolbar and results no longer share a bordered body in module placement, so
+  consumer styles targeting that box no longer apply.
+- Index `sync-query` accepts a string as well as a boolean. The string is a
+  key prefix: `sync-query="contacts"` reads and writes `contacts.page`,
+  `contacts.page_size`, `contacts.search`, `contacts.sort` and
+  `contacts.filter[...]`, so a related index can share its parent page's URL.
+  Unrelated parameters, including the bare `page`, survive untouched.
+
+## 0.7.1 - 2026-09-15
+
+### Changed
+
+- RecordFields reuses field error arrays while draft values change, avoiding
+  repeated issue scans and unnecessary error-prop updates during typing.
+
+- Sidebar and Tabs skip navigation DOM scans for unrelated key presses; Sidebar
+  also handles Space activation before collecting visible entries.
+
+- Menus initialize roving focus with one enabled-item search and avoid repeating
+  full tabindex updates when keyboard navigation triggers a focus event.
+
+- NumberField stepper clicks emit one model update while preserving native input
+  and change events, so consumer validation and autosave handlers run once.
+
+## 0.7.0 - 2026-09-15
+
+### Changed
+
+- Index preserves structured backend errors and offers reset for rejected queries.
+  Refresh callbacks wait for navigation and loading to settle. Sortable columns
+  are checked against the endpoint's allowed fields before loading.
+
+- `Breadcrumb` is now a bar with an optional `actions` slot on the
+  inline-end side. The `pui-breadcrumb` block class moved from the `<ol>`
+  to the `<nav>`; the list is `pui-breadcrumb__trail`.
+- Index renders its pagination footer as a page-level band after the
+  results card instead of inside it, mirroring the header. Pages can pin
+  it to the viewport bottom; consumer styles targeting the footer's card
+  corner radii no longer apply.
+- Text inputs, textareas, selects, input groups and the tags input now rest
+  on the `--border-clr-input` border Button already uses, so control edges
+  clear 3:1 in both themes, and take the standard `:focus-visible` outline
+  ring instead of `outline: none` plus a translucent halo. The brand border
+  tint on focus stays; consumer overrides of the old `box-shadow` ring no
+  longer apply. Tabs and the tags-input remove button use the same tokenised
+  ring.
+- Breadcrumb links get a `:focus-visible` ring and the bar's gap reads the
+  `--space-s` token it was meant to. Record-details labels are
+  `--text-clr-muted` and its row separators `--border-clr-subtle`, matching
+  other in-panel dividers; Tabs' rule uses the same subtle border and its
+  active marker is `--stroke-lg`.
+- Sidebar honours `prefers-reduced-motion` for the drawer slide, backdrop
+  fade, caret rotation and width collapse, not only the rail flyout.
+- The tags-input remove button is a 24px target; pills keep their height by
+  dropping block padding.
+- Form renders its top-level error summary with the danger `Alert` instead of
+  a bespoke box, so it matches every other error surface; consumer styles
+  targeting `.pui-form__error-summary` no longer apply. The shared live region
+  is created when a Form mounts, so the first "N errors found" announcement is
+  no longer dropped.
+- Per-field error lists on every form primitive are `role="status"` rather
+  than `role="alert"`: a failed submit is announced once, assertively, by the
+  summary and the live region, and each field's errors stay reachable through
+  `aria-describedby`. Required fields show a visual `*` after the label.
+- Index announces result changes: the pagination summary and the selection
+  container are persistent `role="status"` regions, so page, sort, filter and
+  selection-count changes are read out. Its title now names the table through
+  `aria-labelledby`.
+- The tags input announces `Removed <tag>` on either removal path, and
+  DataTable row checkboxes are named after the first column's cell value
+  (`Select <value>`) instead of a uniform "Select row".
+- The block editor's drag handle leaves the tab order (`tabindex="-1"`) since
+  Enter and Space do nothing on it; the move buttons are the keyboard path and
+  the hint text now says so.
+- The shared field scaffold (`.pui-field`, its label, hint and required
+  marker, and the `.pui-input` / `.pui-textarea` surface) moved from
+  TextInput's stylesheet to `styles/4-components/form-field.css`, loaded by
+  `@pienter/ui/styles`. Textarea, Select, DateInput, Label and the other
+  primitives no longer depend on TextInput being on the page for their
+  border, focus ring and marker to render. Form's error summary list drops
+  the user-agent margin and indent.
+
+- Collapsed sidebar rail entries drop their own inline padding so a
+  nine-character caption such as "Companies" no longer breaks mid-word.
+
+### Added
+
+- `ToastHost` and the `toast` controller provide package-owned FIFO queuing,
+  auto-dismiss timing, persistent notifications, hover/focus pause, actions,
+  Escape dismissal and live-region announcements.
+- `AppLayout` provides a reusable Vue application shell with header slots,
+  Sidebar navigation, a responsive drawer, skip link and focusable main
+  landmark without depending on Vue Router.
+- An explicit `@pienter/ui/utils/a11y` export supports directory imports in
+  consumer TypeScript project builds.
+- Index's sort select shares state with table headers and supports allowed fields
+  without visible columns. Sort labels can be customized independently of columns.
+- Individual filter updates and refresh/loading access in Index action and
+  selection slots reduce consumer wiring.
+- `normalizeListQuery` validates structured query state directly, without a URL
+  encoding round trip.
+- Index `headingLevel` (`1 | 2 | 3`, default `1`) so a nested list can keep its
+  `title`, `description` and actions without a second `h1`; at level 2 or 3
+  the title sizes like a section heading. `tableLabel` names the table when
+  there is no title.
+- Table and DataTable `label` (a visually hidden `<caption>`) and `labelledby`
+  (`aria-labelledby` to a visible heading) give the `<table>` an accessible
+  name.
+- Select `required`, mirroring TextInput.
+- TagsInput `required`: the marker plus `aria-required` on the entry input,
+  since the native attribute would validate the typed text rather than the
+  tag list.
+- `ensureLiveRegion()` from `@pienter/ui/utils/a11y` creates the shared live
+  region ahead of the first `announce()`.
+
+## 0.6.0 - 2026-09-11
+
+### Changed
+
+- CMS surfaces use softer decorative borders and a lower-contrast canvas; the block editor no longer sits inside a second card. New `--bg-clr-canvas` and `--border-clr-subtle` semantic tokens leave control, text and focus contrast intact.
+- Form validation focuses a visible, enabled invalid control, including when other errors are in hidden tab panels.
+- Index separates page headings and actions from a bordered search, filter and results surface.
+- Compact CMS layouts use tighter table rows and inline pagination controls. Form fields no longer double label spacing or stretch controls beside hints.
+
+### Added
+
+- `RecordFields` and RecordForm’s `fields` slot for sidebar and tabbed layouts within one form; Tabs items can supply panel IDs and relationships.
+- `BlockEditor` for typed content blocks, with model updates, app-provided fields/factories, pointer drag-and-drop, keyboard movement, add/remove and controlled collapse.
+- `Breadcrumb` link slot for router links and `RecordForm` before-field slot for headings and other content between fields.
+- `Index`, `RecordForm`, and `RecordDetails` components for CMS pages composed with ordinary Vue routes, props, events, and slots. Index accepts an async loader and owns query state, debounced search, loading, retry, stale-request protection and optional Vue Router query synchronization.
+- Backend query and response types, JSON Schema, URL query codecs, and immutable record path helpers under `@pienter/ui/utils/cms`.
+
 ## 0.5.0 - 2026-08-30
 
 ### Breaking

package/CONVENTIONS.md

@@ -59,6 +59,7 @@ Current consumers:
 - `components/display/avatar/` — `Avatar` + `AvatarStack` (the stack is a visual layout for grouping avatars; stack styling lives in `avatar.css` alongside the avatar visual)
 - `components/form/select/` — `Select` + `Segmented` (the segmented control is a tab-like single-select visual; shares form-primitive scaffolding with Select; will be retrofit in Phase 4)
 - `components/action/button/` — `Button` + `IconButton` (the icon-only control is a square button. `button.css` shares the base/variant/size/state/focus rules across both via a `.pui-btn, .pui-icon-btn` selector group; a `.pui-btn`-only block holds the label, link variant, block layout, and loading fade that must not reach the icon button; a `.pui-icon-btn` rule adds the square box)
+- `components/feedback/toast/` — `Toast` + `ToastHost` (Toast renders one notification; ToastHost orchestrates the visible family and owns the shared `pui-toast-region` block in `toast.css`)
 
 Rules:
 
@@ -106,6 +107,7 @@ Variants and runtime states live on `data-*` attributes on the block element, ne
 | `data-status`      | Derived semantic status for form primitives (validation outcome)                                                                                           | `error`, `success`                                                                    |
 | `data-layout`      | Form-primitive scaffold layout selector — lives on `.pui-field`; flips between stacked label-above (default) and compact inline control-left + label-right | `stacked` (default; attribute may be omitted), `inline`                               |
 | `data-orientation` | Layout direction for grouped controls (RadioGroup items, future SegmentedControl, etc.) — lives on the group container                                     | `vertical` (default for RadioGroup), `horizontal`                                     |
+| `data-placement`   | Where a CMS surface is mounted, which decides its chrome and heading level — lives on `.pui-index`                                                         | `module` (default), `related`                                                         |
 
 The example values listed for each attribute are non-exhaustive — components add states as needed (e.g. `expanded`, `selected`, `active` for upcoming Disclosure, Tabs, Sidebar). New values follow the same kebab-case rule and live on the same attribute family.
 
@@ -236,14 +238,16 @@ above the rendered options, hint and errors below.
 - [ ] Hint renders as `<p class="pui-field__hint" id={hintId}>` only when the
       `hint` prop is set. Omit the element entirely when absent.
 - [ ] Errors render as `<ul class="pui-field__hint" id={errorsId}
-role="alert">` with one `<li>` per error message, only when errors are
+role="status">` with one `<li>` per error message, only when errors are
       present. Omit the element entirely when the errors array is empty.
-    - `role="alert"` (which carries implicit `aria-live="assertive"` and
-      `aria-atomic="true"`) is appropriate for submit-time validation messages
-      that arrive as a batch. For live/as-you-type validation — out of scope
-      for v1 — use `role="status"` or `aria-live="polite"` instead, to avoid
-      interrupting the user mid-keystroke. When live validation lands, this
-      rule is reopened.
+    - `role="status"` (polite, atomic) keeps a submit batch from being read
+      three times over: Form's summary `Alert` and `announce(…, 'assertive')`
+      own the interrupting channel, and the list stays reachable through
+      `aria-describedby` on the control. Do not put `role="alert"` on a
+      per-field list.
+- [ ] When the primitive takes `required`, the label text is followed by
+      `<span class="pui-field__required" aria-hidden="true">*</span>`; the
+      native attribute carries the semantics, the marker is visual only.
 - [ ] Control element receives `aria-invalid="true"` (string, per the
       boolean-attr-only-when-truthy rule) when errors are present; omit the
       attribute when not.
@@ -310,18 +314,16 @@ short string label sits directly inside the wrapping label element. ARIA:
 `aria-invalid` and `aria-describedby` land on the fieldset (group-level);
 each input carries always-emit `aria-checked="true|false"`.
 
-**pui-field scaffold CSS — co-located with TextInput for now**: the shared
-`.pui-field`, `.pui-field__label`, `.pui-field__hint`, and
-`.pui-field[data-layout='inline']` rules live in
-`packages/ui/components/form/text-input/text-input.css` because TextInput was
-the first form-primitive consumer. Per-control element rules
-(`.pui-input`, `.pui-switch`, etc.) live in their own component CSS. **When
-the fifth form-primitive ships** (Checkbox, RadioGroup, Select, Textarea,
-NumberField, DateInput will push that count over), extract the
-`pui-field*` rules to `packages/ui/styles/4-components/form-field.css` so
-the scaffold isn't tied to one component's filename. The `data-layout`
-documentation in this file points consumers at the scaffold regardless
-of where the file lives.
+**pui-field scaffold CSS lives in the styles entry**: the shared
+`.pui-field`, `.pui-field__label`, `.pui-field__required`, `.pui-field__hint`,
+`.pui-field[data-layout='inline']` rules and the `.pui-input` /
+`.pui-textarea` control surface live in
+`packages/ui/styles/4-components/form-field.css`, imported by
+`styles/main.css` so every consumer of `@pienter/ui/styles` gets them
+regardless of which primitive is on the page. Per-control element rules
+(`.pui-select__control`, `.pui-switch`, `.pui-inputgroup`, etc.) stay in
+their own component CSS and recolour from the parent
+`.pui-field[data-status]`.
 
 ### Pure-markup with slots
 
@@ -453,8 +455,8 @@ Locked during Phase 2 alongside Form (2026-05-03). Form is the **orchestrator**:
 
 **Error display rules**:
 
-- Per-field errors land in the form-primitive's `pui-field__hint role="alert"` element, set `aria-invalid="true"` on the control, set `data-status="error"` on the wrapper. The consumer wires `:errors` on each form-primitive child (typical Vue data flow).
-- Top-level errors (`response.errors[]` or consumer-supplied `:errors` prop) land in `.pui-form__error-summary` at the top of the form, with `role="alert"` and `aria-live="assertive"`.
+- Per-field errors land in the form-primitive's `pui-field__hint role="status"` element, set `aria-invalid="true"` on the control, set `data-status="error"` on the wrapper. The consumer wires `:errors` on each form-primitive child (typical Vue data flow).
+- Top-level errors (`response.errors[]` or consumer-supplied `:errors` prop) render in an `Alert tone="danger"` at the top of the form; Alert carries `role="alert"`.
 - Success: `statusMessage` renders inside `.pui-form__status` with `aria-live="polite"`, and is also announced via the global ARIA live region by the shared `announce()` primitive.
 
 **Submit lifecycle**:
@@ -848,12 +850,12 @@ One consumer is implementation; two is duplication; three is a pattern.
 Modern HTML provides native overlay primitives that reduce hand-rolled
 focus traps, portals, and escape-key handling. Use them where they fit:
 
-| Overlay archetype                                          | Native API                                                                                       | Examples                                                                                                                                                                                                                                                                                                |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Modal, alert dialog, sheet                                 | `<dialog>` + `showModal()` / `close()`                                                           | Modal, AlertDialog, Sheet (slide-side variants of the dialog primitive)                                                                                                                                                                                                                                 |
-| Anchored popover, tooltip, dropdown menu, combobox listbox | Popover API (`popover` attribute + `showPopover()` / `hidePopover()`)                            | Popover, Tooltip, DropdownMenu, Combobox                                                                                                                                                                                                                                                                |
-| Navigation drawer, sidebar                                 | **Manual**                                                                                       | Sidebar drawer is `<nav>`, not `<dialog>` — keep manual `inert` / focus-trap mechanics. The semantic landmark is more important than the modal mechanics.                                                                                                                                               |
-| Toast                                                      | **Manual** — `<ol class="pui-toast-region">` with `aria-live="polite"` and `aria-atomic="false"` | Toasts are non-modal status notifications. The visual layer is a fixed-position `<ol>`; auto-dismiss + queue are owned by whoever renders the region. The Popover API was considered and rejected: it requires a single element, but the toast region holds N siblings whose lifetimes are independent. |
+| Overlay archetype                                          | Native API                                                                          | Examples                                                                                                                                                                                                                                                                                                                |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Modal, alert dialog, sheet                                 | `<dialog>` + `showModal()` / `close()`                                              | Modal, AlertDialog, Sheet (slide-side variants of the dialog primitive)                                                                                                                                                                                                                                                 |
+| Anchored popover, tooltip, dropdown menu, combobox listbox | Popover API (`popover` attribute + `showPopover()` / `hidePopover()`)               | Popover, Tooltip, DropdownMenu, Combobox                                                                                                                                                                                                                                                                                |
+| Navigation drawer, sidebar                                 | **Manual**                                                                          | Sidebar drawer is `<nav>`, not `<dialog>` — keep manual `inert` / focus-trap mechanics. The semantic landmark is more important than the modal mechanics.                                                                                                                                                               |
+| Toast                                                      | **Manual** — `<ToastHost>` teleports a `role="region"` container to `document.body` | Toasts are non-modal status notifications. `ToastHost` renders the visible queue and owns timing and interaction; the package toast controller owns queue state and announces through the single global live region. The Popover API was considered and rejected because one region holds independently timed siblings. |
 
 **What native APIs give us (free)**: top-layer rendering (escapes any
 ancestor stacking context / overflow), focus trap (`Tab` cycles within
@@ -1252,6 +1254,7 @@ follow the shape of an existing one.
 | Accordion    | [`components/layout/accordion/AUDIT.md`](./components/layout/accordion/AUDIT.md)           |
 | Alert        | [`components/feedback/alert/AUDIT.md`](./components/feedback/alert/AUDIT.md)               |
 | AlertDialog  | [`components/overlay/alert-dialog/AUDIT.md`](./components/overlay/alert-dialog/AUDIT.md)   |
+| AppLayout    | [`components/layout/app-layout/AUDIT.md`](./components/layout/app-layout/AUDIT.md)         |
 | Avatar       | [`components/display/avatar/AUDIT.md`](./components/display/avatar/AUDIT.md)               |
 | AvatarStack  | [`components/display/avatar/AUDIT.md`](./components/display/avatar/AUDIT.md)               |
 | Badge        | [`components/display/badge/AUDIT.md`](./components/display/badge/AUDIT.md)                 |
@@ -1293,6 +1296,7 @@ follow the shape of an existing one.
 | Textarea     | [`components/form/textarea/AUDIT.md`](./components/form/textarea/AUDIT.md)                 |
 | TextInput    | [`components/form/text-input/AUDIT.md`](./components/form/text-input/AUDIT.md)             |
 | Toast        | [`components/feedback/toast/AUDIT.md`](./components/feedback/toast/AUDIT.md)               |
+| ToastHost    | [`components/feedback/toast/AUDIT.md`](./components/feedback/toast/AUDIT.md)               |
 | Toggle       | [`components/action/toggle/AUDIT.md`](./components/action/toggle/AUDIT.md)                 |
 | ToggleGroup  | [`components/action/toggle-group/AUDIT.md`](./components/action/toggle-group/AUDIT.md)     |
 | Tooltip      | [`components/overlay/tooltip/AUDIT.md`](./components/overlay/tooltip/AUDIT.md)             |
@@ -1326,7 +1330,7 @@ export interface FormSubmitResponse {
 **Mapping rules**:
 
 - `ok: true` clears all errors, renders `statusMessage` in `.pui-form__status`, and announces it politely.
-- `ok: false` renders `errors` in `.pui-form__error-summary`, applies `fieldErrors` to the matching form-primitive wrappers (per-field error list inside `pui-field__hint role="alert"` + `aria-invalid="true"` on the control), focuses the first invalid field via `focusFirstInvalid`, and announces the error count assertively.
+- `ok: false` renders `errors` in the danger `Alert`, applies `fieldErrors` to the matching form-primitive wrappers (per-field error list inside `pui-field__hint role="status"` + `aria-invalid="true"` on the control), focuses the first invalid field via `focusFirstInvalid`, and announces the error count assertively.
 - `redirect` is a passive value — orchestration does NOT navigate; consumers act on it inside their `@submit` handler.
 
 **Field error normalization**: `fieldErrors[name]` MAY be a single string or an array of strings. Orchestration normalizes to `string[]` via the shared `normalizeFieldErrors` helper before applying to the DOM.
@@ -1409,3 +1413,62 @@ Pinned upstream SHAs used across the table:
 | toggle        | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/toggle.tsx          | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/toggle/src                      | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
 | toggle-group  | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/toggle-group.tsx    | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/toggle-group/src                | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
 | tooltip       | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/tooltip.tsx         | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/tooltip/src                     | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+
+## CMS page composition
+
+`Index`, `RecordForm`, and `RecordDetails` compose existing primitives. Consumers
+register routes and supply endpoint-specific data functions, rendering and actions.
+
+Index accepts `load(query, { signal })`, `columns` and `queryOptions`. It owns
+query state, rows, metadata, loading, failures and retry. Search is debounced;
+search/filter/sort/page-size changes reset page to 1. New requests and unmount
+abort earlier work; stale responses are ignored even when loaders ignore the signal.
+`sync-query` opts into Vue Router query decoding and history synchronization.
+Without it, state stays local. Index imports the optional `vue-router` peer, but
+requires an installed router instance only for URL synchronization. A string
+value is a key prefix: `sync-query="contacts"` reads and writes `contacts.page`,
+`contacts.search`, `contacts.filter[...]` and so on, so a related index shares
+its parent page's URL without touching the page's own parameters.
+
+`placement` selects the chrome for the two CMS placements (`CONTEXT.md`, ADR
+0008), exposed as `data-placement` on `.pui-index`. `module` (default) is the
+page itself: an `h1` header above a divider, an unboxed toolbar, the table with
+DataTable's own border, and the pagination footer as a band below. `related` is
+a list inside another record's detail page: one bordered region holding the
+`h2` header, toolbar, table and pagination footer, divided by the subtle border
+token. The heading level follows the placement; there is no heading-level prop.
+An index definition — one collection's columns, query options, copy and cell
+slots — is a consumer component composing `Index` and taking `placement` and a
+parent id as props. The library ships no definition type or helper.
+
+Index applies the existing default sort cycle; Table/DataTable still emit a column
+key as intent, per ADR 0005. A toolbar select shares that sort state and includes
+all allowed fields, including those without visible columns. Sortable columns
+must belong to the allowed sort vocabulary; labels may be overridden with
+`sortLabels`. Filter slots can update one key without replacing siblings. Action
+and selection slots receive loading state and an awaitable refresh callback.
+Structured backend query errors offer reset; other load failures offer retry.
+Use DataTable when the consumer needs controlled data
+and request state. Index's compact row spacing uses
+`--pui-table-cell-padding-block`, which Table otherwise defaults to `--space-xs`.
+
+RecordForm emits detached JSON snapshots, preserving every supplied property.
+Consumers construct an explicit writable object from backend records. Typed path
+segments identify nested fields and array indices; fields display issues for
+their path and descendants. The form summary retains unmatched issues.
+`--pui-record-form-columns` customizes the field grid, defaulting to one column.
+
+RecordForm's `fields` slot replaces its default RecordFields rendering for
+custom sidebar/tab layouts. RecordFields takes the same draft and renders a
+subset, with `--pui-record-fields-columns` as its grid seam. It never renders a
+form element. Callers expose the relevant tab when backend issues arrive.
+
+BlockEditor owns an ordered array of stable `id`/`type` blocks and emits updates
+for edits, addition, removal and reordering. Creation factories and slot content
+stay caller-owned. Optional `v-model:collapsed` lets pages reveal invalid blocks.
+Its colocated audit records pointer, keyboard, focus and cancellation behavior.
+
+The backend contract lives in `docs/cms/backend-contract.md` with a distributable
+JSON Schema at `utils/cms/schema.json`. It defines request/response data only;
+endpoint URLs, authentication, permissions and domain operations belong to the
+application.

package/README.md

@@ -32,6 +32,72 @@ import { icons } from '@pienter/ui/icons';
 import { generateId } from '@pienter/ui/utils/a11y/id.js';
 ```
 
+### Application layout and notifications
+
+`AppLayout` supplies the application landmarks and responsive Sidebar shell.
+Provide product-specific brand and tools through slots, navigation as
+`SidebarItem[]`, and routed content through the default slot. It does not import
+Vue Router; adapt Sidebar clicks through its `navigate` event and pass the
+current route as `active-href`.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import AppLayout from '@pienter/ui/components/AppLayout.vue';
+import ToastHost from '@pienter/ui/components/ToastHost.vue';
+import { toast } from '@pienter/ui/toast';
+
+const drawerOpen = ref(false);
+</script>
+
+<template>
+    <AppLayout
+        v-model:drawer-open="drawerOpen"
+        :top-items="navigation"
+        :active-href="route.path"
+    >
+        <template #brand>My project</template>
+        <RouterView />
+    </AppLayout>
+    <ToastHost />
+</template>
+```
+
+Call `toast.show({ tone: 'success', title: 'Page saved' })` from any Vue
+module. The default controller shows three notifications at once for five
+seconds. Use `duration: 0` for a persistent notification or
+`createToastController()` when an application needs isolated state.
+
+### CMS pages
+
+Compose ordinary Vue routes with `Index`, `RecordForm`, and `RecordDetails`:
+
+```ts
+import Index from '@pienter/ui/components/Index.vue';
+import RecordForm from '@pienter/ui/components/RecordForm.vue';
+import RecordFields from '@pienter/ui/components/RecordFields.vue';
+import BlockEditor from '@pienter/ui/components/BlockEditor.vue';
+import RecordDetails from '@pienter/ui/components/RecordDetails.vue';
+import type { RecordFormField } from '@pienter/ui/components/RecordForm.types';
+import { decodeListQuery, encodeListQuery } from '@pienter/ui/utils/cms';
+```
+
+Index receives `load(query, { signal })`, columns and query options. It handles
+loading, search, pagination, errors and retry; `sync-query` enables Vue Router URL
+synchronization. Index requires the `vue-router` package; an installed router
+instance is needed only when synchronization is enabled. RecordForm receives `v-model`, fields and validation issues,
+emitting a JSON payload on `submit`. RecordDetails receives a record and fields.
+Use slots for custom cells, controls, values and actions. Your pages own route
+declarations, endpoint functions and saving. Use RecordForm’s `fields` slot and
+RecordFields to put groups in sidebars and tab panels while retaining one form.
+BlockEditor accepts `v-model`, block creation factories and a `block` slot; it
+provides drag-and-drop, keyboard movement, add/remove and collapse controls.
+
+The [CMS guide](../../docs/cms/README.md) contains working examples. The
+[backend contract](../../docs/cms/backend-contract.md) defines query parameters,
+response envelopes and validation paths; its JSON Schema ships at
+`@pienter/ui/utils/cms/schema.json`.
+
 ### Themes
 
 The default theme follows the operating-system color preference, using

package/components/display/record-details/RecordDetails.vue

@@ -0,0 +1,61 @@
+<script lang="ts">
+export type { RecordDetailsField } from './types.js';
+</script>
+
+<script setup lang="ts" generic="T extends object">
+import { readPath } from '../../../utils/cms/index.js';
+import type { RecordDetailsField } from './types.js';
+
+const props = withDefaults(
+    defineProps<{
+        record: T;
+        fields: readonly RecordDetailsField[];
+        emptyValue?: string;
+    }>(),
+    { emptyValue: '—' },
+);
+
+function valueFor(field: RecordDetailsField): unknown {
+    return readPath(props.record, field.path ?? [field.name]);
+}
+
+function displayValue(value: unknown): string {
+    if (value === undefined || value === null || value === '')
+        return props.emptyValue;
+    if (typeof value === 'boolean') return value ? 'Yes' : 'No';
+    if (typeof value === 'object') return JSON.stringify(value);
+    return String(value);
+}
+</script>
+
+<template>
+    <div class="pui-record-details">
+        <dl class="pui-record-details__list">
+            <div
+                v-for="field in fields"
+                :key="field.name"
+                class="pui-record-details__field"
+            >
+                <dt class="pui-record-details__label">{{ field.label }}</dt>
+                <dd class="pui-record-details__value">
+                    <slot
+                        :name="`field:${field.name}`"
+                        :field="field"
+                        :value="valueFor(field)"
+                        :record="record"
+                    >
+                        {{ displayValue(valueFor(field)) }}
+                    </slot>
+                </dd>
+            </div>
+        </dl>
+        <slot />
+        <div v-if="$slots.actions" class="pui-record-details__actions">
+            <slot name="actions" :record="record" />
+        </div>
+    </div>
+</template>
+
+<style>
+@import './record-details.css';
+</style>

package/components/display/record-details/record-details.css

@@ -0,0 +1,37 @@
+@layer components {
+    .pui-record-details {
+        display: grid;
+        gap: var(--space-s);
+
+        & .pui-record-details__list {
+            display: grid;
+            margin: 0;
+        }
+
+        & .pui-record-details__field {
+            display: grid;
+            grid-template-columns: minmax(0, 1fr) minmax(0, 3fr);
+            gap: var(--space-s);
+            padding-block: var(--space-xs);
+            border-block-end: var(--stroke-sm) solid var(--border-clr-subtle);
+        }
+
+        & .pui-record-details__label {
+            color: var(--text-clr-muted);
+            font-size: var(--step--1);
+        }
+
+        & .pui-record-details__value {
+            margin: 0;
+            min-inline-size: 0;
+            overflow-wrap: anywhere;
+            white-space: pre-wrap;
+        }
+
+        & .pui-record-details__actions {
+            display: flex;
+            flex-wrap: wrap;
+            gap: var(--space-xs);
+        }
+    }
+}

package/components/display/record-details/types.ts

@@ -0,0 +1,8 @@
+import type { ValuePath } from '../../../utils/cms/index.js';
+
+export interface RecordDetailsField {
+    name: string;
+    label: string;
+    /** Defaults to the literal property name, without splitting dots. */
+    path?: ValuePath;
+}

package/components/feedback/toast/Toast.vue

@@ -31,10 +31,9 @@
 import { computed } from 'vue';
 import Icon from '../../display/icon/Icon.vue';
 import type { IconName } from '../../../icons/index.js';
+import type { ToastTone } from './types.js';
 
-type Tone = 'brand' | 'success' | 'warning' | 'danger';
-
-const toneIconMap: Record<Tone, IconName> = {
+const toneIconMap: Record<ToastTone, IconName> = {
     brand: 'info',
     success: 'circle-check',
     warning: 'alert-triangle',
@@ -43,7 +42,7 @@ const toneIconMap: Record<Tone, IconName> = {
 
 const props = withDefaults(
     defineProps<{
-        tone?: Tone;
+        tone?: ToastTone;
         title: string;
         message?: string;
         dismissible?: boolean;