@pienter/ui 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 ## Unreleased
 
+## 0.9.0 - 2026-09-15
+
+### Added
+
+- `useUrlTab(keys, defaultKey, param = 'tab')` at
+  `@pienter/ui/composables/useUrlTab` keeps the active `Tabs` key in the URL
+  query, the single source of truth, so a shared link or a reload opens the
+  same tab. It returns a writable computed for `v-model`: the default key
+  drops the parameter, an unknown value falls back to it, and writes go
+  through `router.replace` so tab switches stay out of the back stack and
+  other query parameters survive. Requires the optional `vue-router` peer,
+  like `useUrlSort`.
+- `formFailure(cause, fallback)` in `@pienter/ui/utils/cms` turns a caught
+  save error into RecordForm's `{ issues, errors }`: a value carrying the
+  `ErrorResponse` envelope contributes its field issues and leaves `errors`
+  empty; otherwise `errors` holds the caught `Error` message or `fallback`.
+
+## 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
@@ -33,15 +75,81 @@
   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
 

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.
@@ -1421,7 +1425,21 @@ 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.
+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

package/README.md

@@ -32,6 +32,42 @@ 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`:
@@ -56,6 +92,10 @@ declarations, endpoint functions and saving. Use RecordForm’s `fields` slot an
 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.
+`useUrlTab` from `@pienter/ui/composables/useUrlTab` keeps the active tab key in
+the query string for `v-model` on Tabs, and `formFailure(cause, fallback)` from
+`@pienter/ui/utils/cms` turns a caught save error into RecordForm's `issues` and
+`errors`.
 
 The [CMS guide](../../docs/cms/README.md) contains working examples. The
 [backend contract](../../docs/cms/backend-contract.md) defines query parameters,

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

@@ -13,11 +13,11 @@
             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-base);
+            border-block-end: var(--stroke-sm) solid var(--border-clr-subtle);
         }
 
         & .pui-record-details__label {
-            color: var(--text-clr-dim);
+            color: var(--text-clr-muted);
             font-size: var(--step--1);
         }
 

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;

package/components/feedback/toast/ToastHost.vue

@@ -0,0 +1,165 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, watch } from 'vue';
+import Toast from './Toast.vue';
+import { toast as defaultController } from './toast.js';
+import type { ToastController, ToastItem } from './types.js';
+import { ensureLiveRegion } from '../../../utils/a11y/live-region.js';
+
+interface Timer {
+    handle?: ReturnType<typeof setTimeout>;
+    startedAt: number;
+    remaining: number;
+    autoDismiss: boolean;
+    hovered: boolean;
+    focused: boolean;
+}
+
+const props = withDefaults(
+    defineProps<{
+        controller?: ToastController;
+        label?: string;
+    }>(),
+    {
+        controller: () => defaultController,
+        label: 'Notifications',
+    },
+);
+const items = computed(() => props.controller.visible.value);
+const position = computed(() => props.controller.position.value);
+const timers = new Map<string, Timer>();
+
+function start(item: ToastItem, remaining = item.duration): void {
+    const timer: Timer = {
+        startedAt: Date.now(),
+        remaining,
+        autoDismiss: item.duration > 0,
+        hovered: false,
+        focused: false,
+    };
+    if (remaining > 0)
+        timer.handle = setTimeout(
+            () => props.controller.dismiss(item.id),
+            remaining,
+        );
+    timers.set(item.id, timer);
+}
+
+function pause(id: string): void {
+    const timer = timers.get(id);
+    if (!timer || timer.handle === undefined) return;
+    clearTimeout(timer.handle);
+    timer.remaining = Math.max(
+        0,
+        timer.remaining - (Date.now() - timer.startedAt),
+    );
+    timer.handle = undefined;
+}
+
+function resume(item: ToastItem): void {
+    const timer = timers.get(item.id);
+    if (
+        !timer ||
+        timer.handle !== undefined ||
+        !timer.autoDismiss ||
+        timer.hovered ||
+        timer.focused
+    )
+        return;
+    if (timer.remaining <= 0) {
+        props.controller.dismiss(item.id);
+        return;
+    }
+    timer.startedAt = Date.now();
+    timer.handle = setTimeout(
+        () => props.controller.dismiss(item.id),
+        timer.remaining,
+    );
+}
+
+function setHovered(item: ToastItem, hovered: boolean): void {
+    const timer = timers.get(item.id);
+    if (!timer) return;
+    timer.hovered = hovered;
+    if (hovered) pause(item.id);
+    else resume(item);
+}
+
+function setFocused(item: ToastItem, focused: boolean): void {
+    const timer = timers.get(item.id);
+    if (!timer) return;
+    timer.focused = focused;
+    if (focused) pause(item.id);
+    else resume(item);
+}
+
+function onFocusOut(item: ToastItem, event: FocusEvent): void {
+    const root = event.currentTarget as HTMLElement;
+    const target = event.relatedTarget;
+    setFocused(item, target instanceof Node && root.contains(target));
+}
+
+function dismiss(id: string): void {
+    props.controller.dismiss(id);
+}
+
+function runAction(item: ToastItem): void {
+    try {
+        item.action?.onClick();
+    } finally {
+        dismiss(item.id);
+    }
+}
+
+watch(
+    items,
+    (next) => {
+        const ids = new Set(next.map((item) => item.id));
+        for (const [id, timer] of timers) {
+            if (ids.has(id)) continue;
+            if (timer.handle !== undefined) clearTimeout(timer.handle);
+            timers.delete(id);
+        }
+        for (const item of next) if (!timers.has(item.id)) start(item);
+    },
+    { immediate: true },
+);
+
+onMounted(ensureLiveRegion);
+
+onBeforeUnmount(() => {
+    for (const timer of timers.values())
+        if (timer.handle !== undefined) clearTimeout(timer.handle);
+    timers.clear();
+});
+</script>
+
+<template>
+    <Teleport to="body">
+        <div
+            v-if="items.length"
+            class="pui-toast-region"
+            role="region"
+            :aria-label="label"
+            :data-position="position"
+        >
+            <Toast
+                v-for="item in items"
+                :key="item.id"
+                :tone="item.tone"
+                :title="item.title"
+                :message="item.message"
+                :dismissible="item.dismissible"
+                :icon="item.icon"
+                :action="item.action"
+                aria-keyshortcuts="Escape"
+                @dismiss="dismiss(item.id)"
+                @action="runAction(item)"
+                @keydown.escape.prevent="dismiss(item.id)"
+                @mouseenter="setHovered(item, true)"
+                @mouseleave="setHovered(item, false)"
+                @focusin="setFocused(item, true)"
+                @focusout="onFocusOut(item, $event)"
+            />
+        </div>
+    </Teleport>
+</template>

package/components/feedback/toast/toast.ts

@@ -0,0 +1,116 @@
+import { readonly, shallowRef, ref } from 'vue';
+import { announce } from '../../../utils/a11y/live-region.js';
+import type {
+    ToastConfig,
+    ToastController,
+    ToastItem,
+    ToastPosition,
+} from './types.js';
+
+const DEFAULT_CONFIG = {
+    maxVisible: 3,
+    defaultDuration: 5000,
+    position: 'bottom-right' as ToastPosition,
+};
+
+export function createToastController(
+    initialConfig: ToastConfig = {},
+): ToastController {
+    const config = { ...DEFAULT_CONFIG };
+    const visible = shallowRef<ToastItem[]>([]);
+    const position = ref<ToastPosition>(config.position);
+    const queued: ToastItem[] = [];
+    let nextId = 0;
+
+    function configure(next: ToastConfig): void {
+        if (
+            next.maxVisible !== undefined &&
+            Number.isFinite(next.maxVisible) &&
+            next.maxVisible > 0
+        )
+            config.maxVisible = Math.floor(next.maxVisible);
+        if (
+            next.defaultDuration !== undefined &&
+            Number.isFinite(next.defaultDuration) &&
+            next.defaultDuration >= 0
+        )
+            config.defaultDuration = next.defaultDuration;
+        if (next.position) {
+            config.position = next.position;
+            position.value = next.position;
+        }
+        if (visible.value.length > config.maxVisible) {
+            const overflow = visible.value.slice(config.maxVisible);
+            visible.value = visible.value.slice(0, config.maxVisible);
+            queued.unshift(...overflow);
+        }
+        drain();
+    }
+
+    function generateId(): string {
+        nextId += 1;
+        return `pui-toast-${Date.now().toString(36)}-${nextId}`;
+    }
+
+    function drain(): void {
+        if (visible.value.length >= config.maxVisible || !queued.length) return;
+        const slots = config.maxVisible - visible.value.length;
+        visible.value = [...visible.value, ...queued.splice(0, slots)];
+    }
+
+    function dismiss(id: string): void {
+        const next = visible.value.filter((item) => item.id !== id);
+        if (next.length !== visible.value.length) {
+            visible.value = next;
+            drain();
+            return;
+        }
+        const queuedIndex = queued.findIndex((item) => item.id === id);
+        if (queuedIndex >= 0) queued.splice(queuedIndex, 1);
+    }
+
+    configure(initialConfig);
+
+    return {
+        visible: readonly(visible),
+        position: readonly(position),
+        show(options) {
+            const requestedDuration =
+                options.duration ?? config.defaultDuration;
+            const item: ToastItem = {
+                ...options,
+                id: options.id ?? generateId(),
+                duration: Number.isFinite(requestedDuration)
+                    ? Math.max(0, requestedDuration)
+                    : config.defaultDuration,
+                dismissible: options.dismissible ?? true,
+            };
+            if (visible.value.length < config.maxVisible)
+                visible.value = [...visible.value, item];
+            else queued.push(item);
+            if (typeof document !== 'undefined')
+                announce(
+                    [item.title, item.message].filter(Boolean).join('. '),
+                    item.tone === 'danger' ? 'assertive' : 'polite',
+                );
+            return item.id;
+        },
+        dismiss,
+        dismissAll() {
+            queued.length = 0;
+            visible.value = [];
+        },
+        configure,
+    };
+}
+
+export const toast = createToastController();
+
+export type {
+    ToastConfig,
+    ToastController,
+    ToastItem,
+    ToastOptions,
+    ToastPosition,
+    ToastTone,
+} from './types.js';