@happyvertical/smrt-ui 0.55.0 → 0.55.10

package/AGENTS.md

@@ -17,7 +17,7 @@ SMRT has one shared set of UI primitives, split across two packages by concern:
   `Tooltip`, `Skeleton`, `Tree`, `Pagination`, `DataTable`, `ContentList`, … — **plus the
   Provider-free base FORM primitives** under `./forms` (`Form`, `Input`,
   `Select`, `Textarea`, `Checkbox`, `Switch`, `RadioGroup`, `Slider`,
-  `RangeSlider`, `Combobox`, `MultiSelect`, `TagsInput`, `FilePicker`,
+  `RangeSlider`, `Combobox`, `RelationInput`, `MultiSelect`, `TagsInput`, `FilePicker`,
   `FormGroup`), relocated here in #1589's
   deferred-forms phase so domain packages can adopt them without pulling in the
   smrt-svelte Provider or closing a build-graph cycle. These are dependency-free:
@@ -53,6 +53,7 @@ components are exempt — they *are* the primitives.
 | `./calendar` | `CalendarView` (time-zone-aware month/week grids + phone agenda) and its Svelte-free date model (`toEntries`, `layoutMonth`, `layoutWeek`, `dateKeyInZone`, …); deprecated `Calendar`, `DayView` |
 | `./chat` | `MessageBubble`, `ReactionPicker`, `TypingIndicator` |
 | `./forms` | Provider-free fields, choice controls, sliders/ranges, combobox/listbox/multiselect/tags, date/time/file controls, `CameraCapture`/`SignaturePad` capture, plus the transport-neutral control interaction registry |
+| `.` permissions | `PermissionCheck` and the domain-agnostic `PermissionPicker` for grouped, searchable native role-grant forms over host-supplied catalog records |
 | `./form-retry` | **Svelte-free** form retry (#3291): submission key, in-flight refusal, conditional reset, opt-in restore-after-reload, browser `runOnce()` digest. Also re-exported from `./forms`. Framework-free TS typed structurally against SvelteKit's `SubmitFunction` — never import `@sveltejs/kit` here. Guide: `docs/content/form-retry.md` |
 | `./i18n` | i18n **client**: `useI18n`, `<Trans>`, `defineMessages`, `renderTemplate` (no `smrt-languages` import — the server resolver stays in `smrt-svelte/i18n/server`) |
 | `./registry` | `ModuleUIRegistry` for cross-package component discovery |

package/README.md

@@ -14,6 +14,8 @@ pnpm add @happyvertical/smrt-ui
   import { ThemeProvider } from '@happyvertical/smrt-ui/themes';
   import { Button } from '@happyvertical/smrt-ui/ui';
   import { Form, FormGroup, Input, Switch } from '@happyvertical/smrt-ui/forms';
+  import '@happyvertical/smrt-ui/themes/styles/base.css';
+  import '@happyvertical/smrt-ui/themes/styles/material.css';
 </script>
 
 <ThemeProvider preset="material" colorScheme="system">
@@ -30,7 +32,7 @@ pnpm add @happyvertical/smrt-ui
 | Area | Components |
 | --- | --- |
 | Fields | `Form`, `Field`/`FormGroup`, `Fieldset`, `InputGroup`, `ErrorSummary`, `FormActionBar` |
-| Text and structured input | `Input`, `Textarea`, `Select`, `Combobox`, `Listbox`, `MultiSelect`, `TagsInput`, `SearchInput` |
+| Text and structured input | `Input`, `Textarea`, `Select`, `Combobox`, `RelationInput`, `Listbox`, `MultiSelect`, `TagsInput`, `SearchInput` |
 | Choices | `Checkbox`, `RadioGroup`/`Radio`, `Switch`, `Toggle`, `ToggleButton`, `SegmentedControl` |
 | Values and files | `Slider`, `RangeSlider`, `DatePicker`, `TimePicker`, `FilePicker` |
 | Capture | `CameraCapture`, `SignaturePad` |
@@ -38,7 +40,7 @@ pnpm add @happyvertical/smrt-ui
 | Disclosure and overlays | `Popover`, `Disclosure`, `Accordion`/`AccordionItem`, `Modal`, `Drawer`/`Sheet`, `PhoneSheet`, `ConfirmDialog` |
 | Feedback | `Alert`, `ToastViewport`, `Progress`, `Meter`, `Spinner`, `LoadingOverlay`, `WorkingStrip` |
 | Collections | `CollectionToolbar`, `CollectionList`/`ContentList`, `DataTable`, `Pagination` |
-| Layout and navigation | `Container`, `Grid`, `Header`, `Footer`, `PageHeader`, `EmptyState`, `Tabs`, `FilterChips` |
+| Layout and navigation | `Container`, `PageLayout`, `Grid`, `ActionGroup`, `Header`, `Footer`, `PageHeader`, `EmptyState`, `Tabs`, `FilterChips` |
 | Calendar | `CalendarView` (deprecated: `Calendar`, `DayView`) |
 
 ### Phone surfaces
@@ -79,6 +81,36 @@ pnpm add @happyvertical/smrt-ui
   body (`Content-Type` is the recording's type, `?language=&durationMs=`)
   and answers `{ text }`; 413, 503 and 401/403 become "too long", "not set
   up" and "not allowed" messages.
+- Hands-free dictation: `new Dictation({ mode: 'hands-free', handsFreeCapture:
+  createHandsFreeCapture, … })` keeps the microphone on and writes each
+  sentence down when the speaker pauses; one tap on the microphone ends it.
+  `createHandsFreeCapture` comes from `@happyvertical/smrt-ui/forms/hands-free`,
+  the one entry that imports the optional peer `@happyvertical/speech`
+  (>= 0.102.5: on-device voice activity detection with an adaptive noise
+  floor, pre-roll and a 30 s split; no audio leaves the page). It needs a
+  speech source with `transcribePcm` (smrt-svelte's on-device `whisper-local`
+  and `moonshine`); with any of the three missing it is plain press-to-talk.
+  Utterances are written down one at a time in the order spoken
+  (`dictation.queued` counts those waiting); `speaking` and `level` (0 to 1)
+  drive the button: a steady ring while listening, a halo that swells with the
+  voice while speaking, a spinner while writing down, all still under
+  `prefers-reduced-motion`. `vad` tunes `silenceMs` (default 800),
+  `minSpeechMs`, `preRollMs`, `maxUtteranceMs` and `sensitivity`.
+  The help text ("Just talk; I write it down when you pause...") is the
+  microphone's tooltip and `aria-describedby`, not a line in the form;
+  `DictationStatus` keeps a visually hidden polite live region ("Listening",
+  "Hearing you...", "Writing it down...") and shows errors. Its `sending` prop
+  adds the one short visible hint, "Sending...". The chat composer's
+  `sendOnPause` / `sendOnPauseMs` (default 1200) builds send-on-pause on it.
+  Half-duplex: browsers do not reliably cancel `speechSynthesis` from the
+  microphone, so call `dictation.suspend()` while the page reads a reply aloud
+  and `dictation.resume()` after (the chat composer/dock do this from their
+  `speaking` prop). The microphone stays open but nothing is heard (an
+  utterance in progress is discarded, a ~350 ms guard follows `resume()`);
+  `dictation.suspended` drives the dimmed, dashed-outline button and the
+  "Paused while the assistant speaks" tooltip/live region. A custom
+  `HandsFreeCapture` may implement optional `suspend()` / `resume()`;
+  `Dictation` ignores utterances that arrive while suspended either way.
 
 ### Link tabs
 
@@ -93,11 +125,15 @@ under the phone top bar. Pair it with `useLinkSurface` (smrt-svelte) so
 agents can switch tabs too.
 
 Use the focused subpaths (`/forms`, `/form-retry`, `/ui`, `/feedback`, `/data`,
-`/data-surface`, `/layout`, `/themes`) to keep imports explicit. The
+`/data-surface`, `/currency`, `/layout`, `/themes`) to keep imports explicit. The
 Svelte-free `/data-surface` entry exposes the registry contracts and shared
 protocol limits for server adapters; the Svelte-free `/form-retry` entry
-exposes the form-retry helper. The package root remains a compatibility
-barrel.
+exposes the form-retry helper. The Svelte-free `/currency` entry exposes
+`ISO_4217_MINOR_UNITS`, the shared ISO 4217 registry used for deterministic
+minor-unit scaling. A missing code is unsupported; a `null` value is a valid
+ISO fund, metal, test, or no-currency code without a defined minor unit, so
+callers handling integer minor-unit money must reject both cases rather than
+inventing a decimal precision. The package root remains a compatibility barrel.
 
 ### Calendar dates and shop time
 
@@ -124,6 +160,50 @@ controls with no name or an empty name are omitted. Disabled controls, including
 those inside disabled fieldsets, are omitted by native `FormData`. Native form
 reset restores the initial selection and its label, unless reset is canceled.
 
+### RelationInput
+
+`RelationInput` (`/forms`) moved here from `@happyvertical/smrt-svelte/forms` in #3637 (originally #3600); smrt-svelte keeps a deprecated re-export. Labels are props (`createLabel`, `clearLabel`, `loadingText`, ...); there is no message catalog.
+
+Searchable single-select for relation (foreign-key) fields, a thin wrapper over
+`Combobox`. It is presentation only: the caller supplies the data,
+so the same lookup an assistant uses to turn "Acme" into a record id backs the
+picker. Option shape is `RelationOption` — `{ id, label, detail? }`.
+
+- **Props.** `name`, `label`, `value` (bindable id, `''` = none), `required`,
+  `disabled`, `error`, `placeholder`, `description`, `search(query)`, optional
+  `resolve(id)` and `onCreate(query)`, plus `debounceMs` (250), `interaction`,
+  `onchange` and overridable text (`createLabel`, `clearLabel`, `loadingText`,
+  `emptyText`, `errorText`, `resultsText`).
+- **`search`** runs with `''` when the list opens and then debounced per
+  keystroke; a response for a superseded query is dropped. A rejected search
+  shows `errorText` and the next keystroke retries.
+- **`resolve`** supplies the label of a `value` that has not been searched yet
+  (initial value, parent rebind, form reset). Without it such a value shows an
+  empty field, never the raw id. A `null` result also leaves the field empty.
+- **`onCreate`** adds a "New ..." button; it receives the text most recently
+  searched for and may return the created `RelationOption`, which is selected.
+- **Form integration** is through `Combobox`'s control registration (`Form`
+  provides the registry), not a `FieldDefinition`: agents see a `combobox`
+  control whose value is the id. The form posts the id under `name`.
+- **Known limit.** An agent staging a value through the registered control can
+  only choose among the options last listed (the registry matches against
+  `options`; `allowCustom` is off), so it cannot write an id it has not
+  searched. It fails closed. Writing a resolved id needs an async hook on
+  `Combobox` and is tracked separately.
+- **Stale options.** Typing clears the listed options until the new search
+  answers, so Enter or a click can never pick a record for an older query.
+- **Clear button** shows only when not `required`, not `disabled`, and a value
+  is set; it returns focus to the field.
+- **Accessibility** is the combobox pattern (`role=combobox`, `aria-expanded`,
+  `aria-activedescendant`, listbox/option, Arrow/Enter/Escape) plus a polite
+  `role=status` live region announcing searching / "N results" / no matches,
+  `aria-busy` while fetching, and `aria-invalid` + `aria-describedby` for
+  `error` and `description`.
+- Options render `detail` under the label, so the option's accessible name
+  includes it. The `Combobox` additions that make this possible (`filter`,
+  `onquery`, `status`, `busy`, `invalid`, `describedby`, `optionContent`) are
+  generic and default to the previous behaviour.
+
 ### MultiSelect form submission
 
 A named `MultiSelect` submits one hidden native input per selected option value,
@@ -944,6 +1024,7 @@ hand-authored, and every text pairing clears WCAG AA.
 ```svelte
 <script>
   import { ThemeProvider } from '@happyvertical/smrt-ui/themes';
+  import '@happyvertical/smrt-ui/themes/styles/base.css';
   import '@happyvertical/smrt-ui/themes/styles/all.css';
   import '@happyvertical/smrt-ui/themes/styles/fonts.css';
 </script>
@@ -953,6 +1034,33 @@ hand-authored, and every text pairing clears WCAG AA.
 </ThemeProvider>
 ```
 
+The application baseline is intentionally separate from theme tokens. Import
+`base.css` once at the app entry point to remove the browser body margin, use
+border-box sizing, apply the active theme to the document, and make native form
+controls inherit the app typeface. It does not reset lists or content margins.
+
+PageLayout keeps wide tables and tab rows within the available page width,
+including when nested inside a semantic section. Their own scroll containers
+remain scrollable. Place visual sections directly under PageLayout to use its
+vertical gap.
+
+Use `PageLayout` inside an application shell to give each route responsive
+gutters, block padding, vertical rhythm, and the width appropriate to its
+content. It never creates a scroll container or claims viewport height.
+Use `ActionGroup` for adjacent page or card actions; it wraps with token spacing
+and can justify actions at the start or end without form-specific behavior.
+
+```svelte
+<script>
+  import { PageHeader, PageLayout } from '@happyvertical/smrt-ui/layout';
+</script>
+
+<PageLayout maxWidth="xl" gap="md">
+  <PageHeader title="Projects" subtitle="Plan and track active work" />
+  <!-- collection, cards, form, or detail content -->
+</PageLayout>
+```
+
 Run the shared playground to inspect the full catalog under every preset and
 light/dark scheme.
 

package/dist/components/forms/CodeSelect.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
 import type { ComponentProps } from 'svelte';
 import type { CodeSelectProps } from './code-select-types.js';
+import FieldLabel from './FieldLabel.svelte';
 import Input from './Input.svelte';
 import Select from './Select.svelte';
 
@@ -18,9 +19,17 @@ let {
   locale: _locale,
   name,
   form,
+  label,
+  id: idProp,
+  required,
   ...rest
 }: Props = $props();
 const hiddenId = $props.id();
+const labelId = `${hiddenId}-label`;
+const controlId = $derived(idProp ?? `${hiddenId}-control`);
+const labelProps = $derived(
+  label ? { id: controlId, 'aria-labelledby': labelId } : { id: idProp },
+);
 let select: Select | undefined = $state();
 let input: Input | undefined = $state();
 const choices = $derived(options.filter((option) => option.value !== ''));
@@ -38,10 +47,11 @@ export function getElement(): HTMLInputElement | HTMLSelectElement | null {
   return (freeText ? input : select)?.getElement() ?? null;
 }
 </script>
+{#if label}<FieldLabel id={labelId} for={controlId} {label} {required} />{/if}
 {#if freeText}
-  <Input {...inputRest} bind:this={input} bind:value type="text" {name} {form} {placeholder} disabled={disabled || readOnly} />
+  <Input {...inputRest} {...labelProps} {required} bind:this={input} bind:value type="text" {name} {form} {placeholder} disabled={disabled || readOnly} />
 {:else}
-  <Select {...rest} bind:this={select} bind:value {name} {form} disabled={disabled || readOnly}>
+  <Select {...rest} {...labelProps} {required} bind:this={select} bind:value {name} {form} disabled={disabled || readOnly}>
     <option value="">{placeholder}</option>
     {#if retained}<option value={value}>{value}</option>{/if}
     {#each choices as option}<option value={option.value} disabled={option.disabled}>{option.label ?? option.value}</option>{/each}

package/dist/components/forms/CodeSelect.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CodeSelect.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/forms/CodeSelect.svelte.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAK9D,UAAU,KAAM,SAAQ,eAAe;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAkDD,QAAA,MAAM,UAAU;iBArBG,IAAI;sBAIC,gBAAgB,GAAG,iBAAiB,GAAG,IAAI;WAiBX,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}
+{"version":3,"file":"CodeSelect.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/forms/CodeSelect.svelte.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAM9D,UAAU,KAAM,SAAQ,eAAe;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA4DD,QAAA,MAAM,UAAU;iBAtBG,IAAI;sBAIC,gBAAgB,GAAG,iBAAiB,GAAG,IAAI;WAkBX,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/dist/components/forms/Combobox.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-import { untrack } from 'svelte';
+import { type Snippet, untrack } from 'svelte';
 import {
   emitControlChange,
   highlightControl,
@@ -17,6 +17,7 @@ import {
   matchingOption,
   prepareTextControlValue,
 } from './control-value-validation.js';
+import FieldLabel from './FieldLabel.svelte';
 import { useControlRegistration } from './use-control-registration.svelte.js';
 export interface Props {
   /** Array of options to select from. */
@@ -43,6 +44,31 @@ export interface Props {
    * field stays empty rather than flashing the raw value (an id).
    */
   valueLabel?: string;
+  /**
+   * Whether typing filters `options` by label. Set `false` when the caller
+   * supplies the matching options itself (server-side search via `onquery`),
+   * so a result that matched on something other than its label stays listed.
+   */
+  filter?: boolean;
+  /**
+   * Called with the text to search for when the list opens (empty) and on
+   * every keystroke. Pair with `filter={false}` and fresh `options`.
+   */
+  onquery?: (query: string) => void;
+  /**
+   * Message announced politely to assistive technology while the list is open
+   * ("Searching…", "3 results", "No results"). It is also shown inside the
+   * list while there are no options to list.
+   */
+  status?: string;
+  /** Marks the combobox busy while options are being fetched. */
+  busy?: boolean;
+  /** Marks the field invalid (`aria-invalid`). */
+  invalid?: boolean;
+  /** Ids of elements describing the field (error text, hints). */
+  describedby?: string;
+  /** Custom content for one option row; defaults to the label. */
+  optionContent?: Snippet<[ControlOption]>;
   /** Callback when the selected value changes. */
   onvaluechange?: (value: string) => void;
   /** CSS class to apply to the combobox container. */
@@ -59,6 +85,13 @@ let {
   allowCustom = false,
   interaction,
   valueLabel,
+  filter = true,
+  onquery,
+  status,
+  busy = false,
+  invalid = false,
+  describedby,
+  optionContent,
   onvaluechange,
   class: className = '',
 }: Props = $props();
@@ -83,7 +116,7 @@ let query = $state(untrack(() => labelForValue(value)));
 let typed = $state(false);
 let activeIndex = $state(0);
 const filtered = $derived(
-  typed
+  typed && filter
     ? options.filter((option) =>
         option.label.toLowerCase().includes(query.toLowerCase()),
       )
@@ -136,6 +169,7 @@ function openList() {
     (option) => String(option.value) === value,
   );
   activeIndex = selected >= 0 ? selected : 0;
+  onquery?.('');
 }
 function closeList() {
   open = false;
@@ -147,6 +181,7 @@ function handleInput(event: Event & { currentTarget: HTMLInputElement }) {
   typed = true;
   open = true;
   activeIndex = 0;
+  onquery?.(query);
   if (allowCustom) {
     value = query;
     onvaluechange?.(value);
@@ -179,6 +214,10 @@ function handleKeydown(event: KeyboardEvent) {
     closeList();
   }
 }
+// Options that arrive late can be fewer than the highlighted row.
+$effect(() => {
+  if (activeIndex >= filtered.length) activeIndex = 0;
+});
 $effect(() => {
   const form = inputEl?.form;
   if (!form) return;
@@ -296,19 +335,23 @@ useControlRegistration(() => {
 <div bind:this={rootEl} class="combobox {className}" data-smrt-control={controlId} data-smrt-form={interactionContext?.formId}
   data-smrt-subject-type={interaction === false ? undefined : interaction?.subject?.type}
   data-smrt-subject-id={interaction === false ? undefined : interaction?.subject?.id}>
-  <label for={inputId}>{label}</label>
+  <FieldLabel for={inputId} {label} {required} />
   <!-- The form posts the committed value (an option id), never the label the person sees. -->
   {#if name}<input type="hidden" {name} {value} {disabled} />{/if}
   <input bind:this={inputEl} id={inputId} role="combobox" autocomplete="off" {placeholder} {disabled} required={required && !value} aria-required={required ? 'true' : undefined} value={query}
-    aria-expanded={open} aria-controls={listId} aria-autocomplete="list" aria-activedescendant={open && filtered[activeIndex] ? `${listId}-${activeIndex}` : undefined}
+    aria-expanded={open} aria-controls={listId} aria-busy={busy ? 'true' : undefined} aria-invalid={invalid ? 'true' : undefined} aria-describedby={describedby} aria-autocomplete="list" aria-activedescendant={open && filtered[activeIndex] ? `${listId}-${activeIndex}` : undefined}
     onfocus={openList} onclick={openList} oninput={handleInput} onkeydown={handleKeydown} />
   {#if open && filtered.length}<div id={listId} class="options" role="listbox">{#each filtered as option, index (option.value)}<button id={`${listId}-${index}`} type="button" role="option"
-      aria-selected={String(option.value) === value} class:active={index === activeIndex} disabled={option.disabled} onpointerdown={(event) => event.preventDefault()} onclick={() => commit(option, true)}>{option.label}</button>{/each}</div>{/if}
+      aria-selected={String(option.value) === value} class:active={index === activeIndex} disabled={option.disabled} onpointerdown={(event) => event.preventDefault()} onclick={() => commit(option, true)}>{#if optionContent}{@render optionContent(option)}{:else}{option.label}{/if}</button>{/each}</div>
+  {:else if open && status}<div class="options empty" aria-hidden="true">{status}</div>{/if}
+  {#if status !== undefined}<div class="sr-status" role="status" aria-live="polite">{open ? status : ''}</div>{/if}
 </div>
 <style>
-  .combobox { position: relative; display: grid; gap: var(--smrt-spacing-1); color: var(--smrt-color-on-surface); }
-  label { font: var(--smrt-typography-label-large-font); } input { box-sizing: border-box; width: 100%; padding: var(--smrt-spacing-2) var(--smrt-spacing-3); border: 1px solid var(--smrt-color-outline); border-radius: var(--smrt-radius-small); background: var(--smrt-color-surface); color: inherit; }
+  .combobox { position: relative; display: grid; gap: 0; color: var(--smrt-color-on-surface); }
+  input { box-sizing: border-box; width: 100%; padding: var(--smrt-spacing-2) var(--smrt-spacing-3); border: 1px solid var(--smrt-color-outline); border-radius: var(--smrt-radius-small); background: var(--smrt-color-surface); color: inherit; }
   input:focus { outline: 2px solid var(--smrt-color-primary); outline-offset: 1px; } .options { position: absolute; z-index: var(--smrt-z-index-dropdown); top: 100%; left: 0; right: 0; display: grid; padding: var(--smrt-spacing-1); border: 1px solid var(--smrt-color-outline-variant); border-radius: var(--smrt-radius-small); background: var(--smrt-color-surface-container); box-shadow: var(--smrt-elevation-2); }
   .options button { padding: var(--smrt-spacing-2) var(--smrt-spacing-3); border: 0; border-radius: var(--smrt-radius-extra-small); background: transparent; color: var(--smrt-color-on-surface); text-align: left; } .options button.active { background: var(--smrt-color-secondary-container); }
+  .options.empty { padding: var(--smrt-spacing-2) var(--smrt-spacing-3); color: var(--smrt-color-on-surface-variant); }
+  .sr-status { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0; }
   :global(.combobox[data-smrt-highlighted='true']) { outline: 3px solid var(--smrt-color-tertiary); outline-offset: 4px; }
 </style>

package/dist/components/forms/Combobox.svelte.d.ts

@@ -1,3 +1,4 @@
+import { type Snippet } from 'svelte';
 import type { ControlInteractionOptions, ControlOption } from './control-interaction.js';
 export interface Props {
     /** Array of options to select from. */
@@ -24,6 +25,31 @@ export interface Props {
      * field stays empty rather than flashing the raw value (an id).
      */
     valueLabel?: string;
+    /**
+     * Whether typing filters `options` by label. Set `false` when the caller
+     * supplies the matching options itself (server-side search via `onquery`),
+     * so a result that matched on something other than its label stays listed.
+     */
+    filter?: boolean;
+    /**
+     * Called with the text to search for when the list opens (empty) and on
+     * every keystroke. Pair with `filter={false}` and fresh `options`.
+     */
+    onquery?: (query: string) => void;
+    /**
+     * Message announced politely to assistive technology while the list is open
+     * ("Searching…", "3 results", "No results"). It is also shown inside the
+     * list while there are no options to list.
+     */
+    status?: string;
+    /** Marks the combobox busy while options are being fetched. */
+    busy?: boolean;
+    /** Marks the field invalid (`aria-invalid`). */
+    invalid?: boolean;
+    /** Ids of elements describing the field (error text, hints). */
+    describedby?: string;
+    /** Custom content for one option row; defaults to the label. */
+    optionContent?: Snippet<[ControlOption]>;
     /** Callback when the selected value changes. */
     onvaluechange?: (value: string) => void;
     /** CSS class to apply to the combobox container. */

package/dist/components/forms/Combobox.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Combobox.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/forms/Combobox.svelte.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,yBAAyB,EACzB,aAAa,EACd,MAAM,0BAA0B,CAAC;AAWlC,MAAM,WAAW,KAAK;IACpB,uCAAuC;IACvC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,mDAAmD;IACnD,WAAW,CAAC,EAAE,yBAAyB,GAAG,KAAK,CAAC;IAChD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAyQD,QAAA,MAAM,QAAQ,gDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"Combobox.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/forms/Combobox.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,OAAO,EAAW,MAAM,QAAQ,CAAC;AAM/C,OAAO,KAAK,EACV,yBAAyB,EACzB,aAAa,EACd,MAAM,0BAA0B,CAAC;AAYlC,MAAM,WAAW,KAAK;IACpB,uCAAuC;IACvC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,mDAAmD;IACnD,WAAW,CAAC,EAAE,yBAAyB,GAAG,KAAK,CAAC;IAChD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,aAAa,CAAC,EAAE,OAAO,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;IACzC,gDAAgD;IAChD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAyRD,QAAA,MAAM,QAAQ,gDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}

package/dist/components/forms/DictationButton.svelte

@@ -7,6 +7,16 @@
  * 44px target, named by `aria-label`, `aria-pressed` while listening, and a
  * listening dot that does not rely on color alone (the name changes too).
  * Pair it with `DictationStatus` for the words ("Listening…", errors).
+ *
+ * Hands-free (`mode: 'hands-free'`): a steady ring means it is listening,
+ * a halo that swells with the voice means someone is speaking, and a small
+ * spinner means sentences are being written down. The ring is the
+ * non-motion cue; the halo and spinner stop moving for people who ask for
+ * reduced motion. While the page speaks a reply (`Dictation.suspend()`) the
+ * button dims with a dashed outline and its tooltip reads "Paused while the
+ * assistant speaks". Tapping ends it either way. The help text ("Just talk;
+ * I write it down when you pause...") is the tooltip and the button's
+ * `aria-describedby`, never a line of text in the form.
  */
 import { M } from '../../i18n/strings.ui.js';
 import { useI18n } from '../../i18n/use-i18n.js';
@@ -40,6 +50,11 @@ let {
 
 const { t } = useI18n();
 const active = $derived(dictation.active);
+const handsFree = $derived(dictation.handsFree);
+// Paused while the assistant speaks (half-duplex): not hearing, still open.
+const paused = $derived(active && handsFree && dictation.suspended);
+const speaking = $derived(active && handsFree && dictation.speaking && !paused);
+const writing = $derived(handsFree && dictation.queued > 0);
 // While a recording is being written down, a tap would do nothing.
 const busy = $derived(dictation.state === 'transcribing');
 const name = $derived(
@@ -47,6 +62,22 @@ const name = $derived(
     ? (stopLabel ?? t(M['ui.dictation.stop']))
     : (label ?? t(M['ui.dictation.start'])),
 );
+const uid = $props.id();
+const helpId = `smrt-dictation-help-${uid}`;
+const hint = $derived(
+  active
+    ? handsFree
+      ? paused
+        ? t(M['ui.dictation.paused_speaking'])
+        : t(M['ui.dictation.listening_hands_free'])
+      : name
+    : (title ??
+        t(
+          dictation.wantsHandsFree
+            ? M['ui.dictation.start_hands_free']
+            : M['ui.dictation.start_hint'],
+        )),
+);
 
 function handleClick() {
   // A tap is a user gesture: wake the audio so the ready beep can play.
@@ -60,14 +91,19 @@ function handleClick() {
   type="button"
   variant="ghost"
   size="sm"
-  class={`smrt-dictation-button${active ? ' smrt-dictation-button--listening' : ''} ${className}`.trim()}
+  class={`smrt-dictation-button${active ? ' smrt-dictation-button--listening' : ''}${active && handsFree ? ' smrt-dictation-button--hands-free' : ''}${speaking ? ' smrt-dictation-button--speaking' : ''}${paused ? ' smrt-dictation-button--paused' : ''} ${className}`.trim()}
   aria-label={name}
   aria-pressed={active}
   aria-busy={busy || undefined}
-  title={active ? name : (title ?? t(M['ui.dictation.start_hint']))}
+  title={hint}
+  aria-describedby={hint !== name ? helpId : undefined}
   disabled={disabled || busy}
   onclick={handleClick}
   data-dictation-state={dictation.state}
+  data-dictation-mode={handsFree ? 'hands-free' : undefined}
+  data-dictation-speaking={speaking || undefined}
+  data-dictation-paused={paused || undefined}
+  style={speaking ? `--smrt-dictation-level: ${dictation.level}` : undefined}
 >
   <svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
     <rect x="9" y="2" width="6" height="12" rx="3"></rect>
@@ -77,7 +113,13 @@ function handleClick() {
   {#if active}
     <span class="smrt-dictation-dot" aria-hidden="true"></span>
   {/if}
+  {#if writing || (handsFree && dictation.state === 'transcribing')}
+    <span class="smrt-dictation-writing" aria-hidden="true"></span>
+  {/if}
 </Button>
+{#if hint !== name}
+  <span id={helpId} class="smrt-dictation-help">{hint}</span>
+{/if}
 
 <style>
   :global(.smrt-dictation-button) {
@@ -99,6 +141,16 @@ function handleClick() {
     color: var(--smrt-color-on-error-container, #410002);
   }
 
+  /* Read out with the button's name; never shown. */
+  .smrt-dictation-help {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
   .smrt-dictation-dot {
     position: absolute;
     inset-block-start: 6px;
@@ -110,6 +162,54 @@ function handleClick() {
     animation: smrt-dictation-pulse 1.2s ease-in-out infinite;
   }
 
+  /* Hands-free: a steady ring while listening ... */
+  :global(.smrt-dictation-button--hands-free) {
+    box-shadow: 0 0 0 2px var(--smrt-color-error, #ba1a1a);
+  }
+
+  /* ... and a halo that swells with the voice while someone is speaking. */
+  :global(.smrt-dictation-button--speaking) {
+    box-shadow:
+      0 0 0 3px var(--smrt-color-error, #ba1a1a),
+      0 0 0
+        calc(4px + 10px * var(--smrt-dictation-level, 0))
+        color-mix(in srgb, var(--smrt-color-error, #ba1a1a) 28%, transparent);
+    transition: box-shadow 80ms linear;
+  }
+
+  /* Paused while the assistant speaks: a dashed, dimmed ring (not color alone). */
+  :global(.smrt-dictation-button--paused) {
+    opacity: 0.6;
+    box-shadow: none;
+    outline: 2px dashed var(--smrt-color-outline, #73777f);
+    outline-offset: -2px;
+  }
+
+  :global(.smrt-dictation-button--paused) .smrt-dictation-dot {
+    animation: none;
+    opacity: 0.4;
+  }
+
+  /* Sentences are being written down. */
+  .smrt-dictation-writing {
+    position: absolute;
+    inset-block-end: 6px;
+    inset-inline-end: 6px;
+    inline-size: 10px;
+    block-size: 10px;
+    border-radius: 50%;
+    border: 2px solid var(--smrt-color-outline-variant, #c4c6cf);
+    border-block-start-color: var(--smrt-color-primary, #2f5ea8);
+    background: var(--smrt-color-surface, #fff);
+    animation: smrt-dictation-spin 0.9s linear infinite;
+  }
+
+  @keyframes smrt-dictation-spin {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+
   @keyframes smrt-dictation-pulse {
     0%,
     100% {
@@ -121,8 +221,15 @@ function handleClick() {
   }
 
   @media (prefers-reduced-motion: reduce) {
-    .smrt-dictation-dot {
+    .smrt-dictation-dot,
+    .smrt-dictation-writing {
       animation: none;
     }
+
+    /* Still ringed, but the halo no longer animates with the voice. */
+    :global(.smrt-dictation-button--speaking) {
+      transition: none;
+      box-shadow: 0 0 0 4px var(--smrt-color-error, #ba1a1a);
+    }
   }
 </style>

package/dist/components/forms/DictationButton.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DictationButton.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/forms/DictationButton.svelte.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAIvD,MAAM,WAAW,KAAK;IACpB,kDAAkD;IAClD,SAAS,EAAE,SAAS,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAoDD,QAAA,MAAM,eAAe,2CAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}
+{"version":3,"file":"DictationButton.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/forms/DictationButton.svelte.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAIvD,MAAM,WAAW,KAAK;IACpB,kDAAkD;IAClD,SAAS,EAAE,SAAS,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA+ED,QAAA,MAAM,eAAe,2CAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}