@happyvertical/smrt-ui 0.51.38 → 0.52.0

package/dist/components/feedback/__tests__/WorkingStrip.test.js

@@ -0,0 +1,172 @@
+import { render, screen } from '@testing-library/svelte';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+import WorkingStrip from '../WorkingStrip.svelte';
+describe('WorkingStrip', () => {
+    it('renders nothing but an empty live region while idle', () => {
+        const { container } = render(WorkingStrip, {
+            props: { status: { phase: 'idle', label: null } },
+        });
+        expect(screen.queryByTestId('working-strip')).toBeNull();
+        const live = container.querySelector('[aria-live="polite"]');
+        expect(live?.textContent?.trim()).toBe('');
+    });
+    it('announces the status and reopens the surface from the strip', async () => {
+        const onopen = vi.fn();
+        const onstop = vi.fn();
+        const { container } = render(WorkingStrip, {
+            props: {
+                status: { phase: 'working', label: 'Writing the summary' },
+                canStop: true,
+                onopen,
+                onstop,
+                openLabel: 'Open the assistant',
+            },
+        });
+        expect(container.querySelector('[aria-live="polite"]')?.textContent).toContain('Writing the summary');
+        await userEvent.click(screen.getByRole('button', {
+            name: 'Writing the summary. Open the assistant',
+        }));
+        expect(onopen).toHaveBeenCalledTimes(1);
+        await userEvent.click(screen.getByRole('button', { name: 'Stop' }));
+        expect(onstop).toHaveBeenCalledTimes(1);
+    });
+    it('falls back to default labels and hides Stop unless it can stop', () => {
+        render(WorkingStrip, {
+            props: { status: { phase: 'working', label: null } },
+        });
+        expect(screen.getByTestId('working-strip').textContent).toContain('Working…');
+        expect(screen.queryByRole('button', { name: 'Stop' })).toBeNull();
+    });
+    it('shows Done without a spinner or Stop', () => {
+        const { container } = render(WorkingStrip, {
+            props: {
+                status: { phase: 'done', label: null },
+                canStop: true,
+                variant: 'inline',
+            },
+        });
+        const strip = screen.getByTestId('working-strip');
+        expect(strip).toHaveAttribute('data-phase', 'done');
+        expect(strip.textContent).toContain('Done');
+        expect(container.querySelector('.working-strip__spinner')).toBeNull();
+        expect(screen.queryByRole('button', { name: 'Stop' })).toBeNull();
+    });
+    it('goes green with a check once done, red with a cross once failed', () => {
+        const { rerender } = render(WorkingStrip, {
+            props: {
+                status: { phase: 'done', label: null, goal: 'Show me meetings' },
+                variant: 'floating',
+            },
+        });
+        const strip = screen.getByTestId('working-strip');
+        expect(strip).toHaveAttribute('data-phase', 'done');
+        expect(strip.textContent).toContain('Show me meetings');
+        expect(strip.textContent).toContain('✓');
+        rerender({
+            status: { phase: 'failed', label: null, goal: 'Show me meetings' },
+            variant: 'floating',
+        });
+        expect(screen.getByTestId('working-strip')).toHaveAttribute('data-phase', 'failed');
+        expect(screen.getByTestId('working-strip').textContent).toContain("Couldn't finish");
+    });
+    it('offers Pause while working, Continue while paused, and Esc pauses', async () => {
+        const onpause = vi.fn();
+        const onresume = vi.fn();
+        const onstop = vi.fn();
+        const { rerender } = render(WorkingStrip, {
+            props: {
+                status: { phase: 'working', label: 'Opening Events' },
+                variant: 'floating',
+                canStop: true,
+                onpause,
+                onresume,
+                onstop,
+            },
+        });
+        await userEvent.click(screen.getByRole('button', { name: 'Pause' }));
+        expect(onpause).toHaveBeenCalledTimes(1);
+        screen.getByRole('button', { name: 'Pause' }).focus();
+        await userEvent.keyboard('{Escape}');
+        expect(onpause).toHaveBeenCalledTimes(2);
+        rerender({
+            status: { phase: 'paused', label: null },
+            variant: 'floating',
+            canStop: true,
+            onpause,
+            onresume,
+            onstop,
+        });
+        expect(screen.queryByRole('button', { name: 'Pause' })).toBeNull();
+        await userEvent.click(screen.getByRole('button', { name: 'Continue' }));
+        expect(onresume).toHaveBeenCalledTimes(1);
+        await userEvent.click(screen.getByRole('button', { name: 'Stop' }));
+        expect(onstop).toHaveBeenCalledTimes(1);
+    });
+    it('asks for the person assertively while waiting, with Review', async () => {
+        const onreview = vi.fn();
+        const { container } = render(WorkingStrip, {
+            props: {
+                status: {
+                    phase: 'waiting',
+                    label: 'A change is ready for you',
+                    goal: 'Fill the event form',
+                },
+                variant: 'floating',
+                onreview,
+            },
+        });
+        expect(container.querySelector('[aria-live="assertive"]')?.textContent).toContain('A change is ready for you');
+        expect(container.querySelector('[aria-live="polite"]')?.textContent?.trim()).toBe('');
+        await userEvent.click(screen.getByRole('button', { name: 'Review' }));
+        expect(onreview).toHaveBeenCalledTimes(1);
+    });
+    it('never takes focus by itself', async () => {
+        const outside = document.createElement('button');
+        document.body.append(outside);
+        outside.focus();
+        const { rerender } = render(WorkingStrip, {
+            props: {
+                status: { phase: 'working', label: 'Step one' },
+                variant: 'floating',
+                onpause: vi.fn(),
+                onopen: vi.fn(),
+            },
+        });
+        rerender({
+            status: { phase: 'waiting', label: 'Your turn' },
+            variant: 'floating',
+            onreview: vi.fn(),
+            onopen: vi.fn(),
+        });
+        expect(document.activeElement).toBe(outside);
+        outside.remove();
+    });
+    it('throttles polite step announcements', async () => {
+        vi.useFakeTimers();
+        try {
+            const { container, rerender } = render(WorkingStrip, {
+                props: {
+                    status: { phase: 'working', label: 'Step one' },
+                    announceIntervalMs: 2000,
+                },
+            });
+            const live = () => container.querySelector('[aria-live="polite"]')?.textContent?.trim();
+            expect(live()).toBe('Step one');
+            await rerender({
+                status: { phase: 'working', label: 'Step two' },
+                announceIntervalMs: 2000,
+            });
+            await rerender({
+                status: { phase: 'working', label: 'Step three' },
+                announceIntervalMs: 2000,
+            });
+            expect(live()).toBe('Step one');
+            await vi.advanceTimersByTimeAsync(2000);
+            expect(live()).toBe('Step three');
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+});

package/dist/components/feedback/index.d.ts

@@ -1,16 +1,20 @@
 /**
  * Feedback components - User feedback and status indicators
  */
+export { SWIPE_DISMISS_THRESHOLD, type SwipeDirection, type SwipeDismissOptions, swipeDismiss, swipeDismisses, } from '../../actions/swipe-dismiss.js';
 export { default as Alert } from './Alert.svelte';
 export { default as ConfirmDialog } from './ConfirmDialog.svelte';
 export { default as Drawer, default as Sheet } from './Drawer.svelte';
 export { default as LoadingOverlay } from './LoadingOverlay.svelte';
 export { default as Meter } from './Meter.svelte';
 export { default as Modal } from './Modal.svelte';
+export { default as PhoneSheet } from './PhoneSheet.svelte';
 export { default as Progress } from './Progress.svelte';
 export { default as ProgressBar } from './ProgressBar.svelte';
 export { default as Spinner } from './Spinner.svelte';
 export { default as ToastViewport } from './ToastViewport.svelte';
 export type { Toast, ToastAction, Toaster, ToastInput, ToastVariant, } from './toast.js';
 export { createToaster, toaster } from './toast.js';
+export { default as WorkingStrip } from './WorkingStrip.svelte';
+export { WORKING_ASSERTIVE_PHASES, type WorkingPhase, type WorkingStatus, } from './working-status.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/components/feedback/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/feedback/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAClE,YAAY,EACV,KAAK,EACL,WAAW,EACX,OAAO,EACP,UAAU,EACV,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/feedback/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACL,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,YAAY,EACZ,cAAc,GACf,MAAM,gCAAgC,CAAC;AAIxC,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAClE,YAAY,EACV,KAAK,EACL,WAAW,EACX,OAAO,EACP,UAAU,EACV,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EACL,wBAAwB,EACxB,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/components/feedback/index.js

@@ -1,6 +1,8 @@
 /**
  * Feedback components - User feedback and status indicators
  */
+// Swipe-to-dismiss (used by PhoneSheet; phone drawers use it too).
+export { SWIPE_DISMISS_THRESHOLD, swipeDismiss, swipeDismisses, } from '../../actions/swipe-dismiss.js';
 // Note: Component prop types (ConfirmDialogProps, etc.) are available
 // via svelte-package build output but cannot be re-exported here because
 // tsc --noEmit cannot resolve type exports from .svelte files.
@@ -10,8 +12,11 @@ export { default as Drawer, default as Sheet } from './Drawer.svelte';
 export { default as LoadingOverlay } from './LoadingOverlay.svelte';
 export { default as Meter } from './Meter.svelte';
 export { default as Modal } from './Modal.svelte';
+export { default as PhoneSheet } from './PhoneSheet.svelte';
 export { default as Progress } from './Progress.svelte';
 export { default as ProgressBar } from './ProgressBar.svelte';
 export { default as Spinner } from './Spinner.svelte';
 export { default as ToastViewport } from './ToastViewport.svelte';
 export { createToaster, toaster } from './toast.js';
+export { default as WorkingStrip } from './WorkingStrip.svelte';
+export { WORKING_ASSERTIVE_PHASES, } from './working-status.js';

package/dist/components/feedback/working-status.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Generic "something is working" status rendered by `WorkingStrip`.
+ *
+ * - `idle`: nothing is shown;
+ * - `working`: a spinner and what is happening ("Writing the summary…");
+ * - `paused`: the work is on hold until the person continues it;
+ * - `waiting`: the work needs the person (a change to review, a choice to
+ *   make, a question to answer) — shown prominently, announced assertively;
+ * - `done`: a short confirmation ("Done · 2 changes") the host clears after
+ *   a few seconds;
+ * - `failed`: the work stopped on a problem — announced assertively;
+ * - `cancelled`: the person stopped it.
+ *
+ * Transport-neutral: an assistant run, an upload, or a background job can
+ * all feed it.
+ */
+export type WorkingPhase = 'idle' | 'working' | 'paused' | 'waiting' | 'done' | 'failed' | 'cancelled';
+export interface WorkingStatus {
+    /** Lifecycle phase. */
+    phase: WorkingPhase;
+    /**
+     * What to say: the current step while working ("Opening Events"), the
+     * outcome otherwise. `null` falls back to a default for the phase.
+     */
+    label: string | null;
+    /**
+     * What the work is for, in the person's own words ("Show me upcoming
+     * meetings"). Shown above the step on the floating pill; optional.
+     */
+    goal?: string | null;
+}
+/** Phases whose change is announced assertively (the person is needed). */
+export declare const WORKING_ASSERTIVE_PHASES: readonly WorkingPhase[];
+//# sourceMappingURL=working-status.d.ts.map

package/dist/components/feedback/working-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"working-status.d.ts","sourceRoot":"","sources":["../../../src/components/feedback/working-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,SAAS,GACT,QAAQ,GACR,SAAS,GACT,MAAM,GACN,QAAQ,GACR,WAAW,CAAC;AAEhB,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,KAAK,EAAE,YAAY,CAAC;IACpB;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,EAAE,SAAS,YAAY,EAG3D,CAAC"}

package/dist/components/feedback/working-status.js

@@ -0,0 +1,5 @@
+/** Phases whose change is announced assertively (the person is needed). */
+export const WORKING_ASSERTIVE_PHASES = [
+    'waiting',
+    'failed',
+];

package/dist/components/forms/Checkbox.svelte

@@ -123,6 +123,7 @@ useControlRegistration(() => {
 <label
   class="checkbox {className}"
   class:checkbox--disabled={disabled}
+  data-smrt-hit-target
   data-smrt-control={controlId}
   data-smrt-form={interactionContext?.formId}
   data-smrt-subject-type={resolvedInteraction === false ? undefined : resolvedInteraction.subject?.type}
@@ -150,14 +151,37 @@ useControlRegistration(() => {
 </label>
 
 <style>
-  .checkbox { display: inline-flex; align-items: center; gap: var(--smrt-spacing-2, .5rem); cursor: pointer; color: var(--smrt-color-on-surface); }
+  /* The visible box stays 18px. A transparent 44x44 hit area (WCAG 2.5.8 / M3 touch target) is
+     centred on it with ::before, so clicks nearby still land on the wrapping <label>. It adds no
+     layout. The box and the label text sit above every hit area (z-index 1 over 0), so one
+     control's hit area never steals a click from another control's box or text.
+     The hit area is painted above plain content around it, so it only grows sideways when the
+     checkbox stands alone in its parent. Beside anything else (a row title, a link, other text)
+     it keeps to the box's own column and grows vertically only. Resize it with
+     --smrt-control-hit-size (0px turns it off). */
+  .checkbox { --_box: 1.125rem; --_hit: max(var(--smrt-control-hit-size, 2.75rem), var(--_box)); position: relative; display: inline-flex; align-items: center; gap: var(--smrt-spacing-2, .5rem); cursor: pointer; color: var(--smrt-color-on-surface); }
+  .checkbox::before { content: ''; position: absolute; z-index: 0; inset-block-start: 50%; inset-inline-start: calc(var(--_box) / 2); inline-size: var(--_hit); block-size: var(--_hit); margin-block-start: calc(var(--_hit) / -2); margin-inline-start: calc(var(--_hit) / -2); }
   .checkbox--disabled { opacity: .5; cursor: not-allowed; }
   input { position: absolute; width: 1px; height: 1px; opacity: 0; pointer-events: none; }
-  .checkbox__box { width: 1.125rem; height: 1.125rem; display: grid; place-items: center; border: 2px solid var(--smrt-color-outline); border-radius: var(--smrt-radius-extra-small, 3px); background: var(--smrt-color-surface); transition: background var(--smrt-duration-short2), border-color var(--smrt-duration-short2); }
+  .checkbox__box { position: relative; z-index: 1; width: 1.125rem; height: 1.125rem; display: grid; place-items: center; border: 2px solid var(--smrt-color-outline); border-radius: var(--smrt-radius-extra-small, 3px); background: var(--smrt-color-surface); transition: background var(--smrt-duration-short2), border-color var(--smrt-duration-short2); }
+  .checkbox__label { position: relative; z-index: 1; }
   input:checked + .checkbox__box, input:indeterminate + .checkbox__box { background: var(--smrt-color-primary); border-color: var(--smrt-color-primary); color: var(--smrt-color-on-primary); }
   input:focus-visible + .checkbox__box { outline: 2px solid var(--smrt-color-primary); outline-offset: 3px; }
   .checkbox__check { font-size: .8rem; font-weight: 800; line-height: 1; }
   .checkbox__dash { width: .6rem; height: 2px; background: currentColor; }
+  .checkbox:not(:only-child)::before { inline-size: var(--_box); margin-inline-start: calc(var(--_box) / -2); }
   .checkbox[data-smrt-highlighted='true'] { outline: 3px solid var(--smrt-color-tertiary); outline-offset: 4px; border-radius: var(--smrt-radius-small); }
+
+  /* Table cells: neighbouring cells hold links and other controls, so the hit area never leaves
+     the cell's column. It grows vertically only (box wide)... */
+  :global(:is(td, th)) .checkbox::before { inline-size: var(--_box); margin-inline-start: calc(var(--_box) / -2); }
+  /* ...unless the checkbox is the cell's only content: then the whole cell, clipped to its own
+     edges, is the hit area (the 44px target the header and every row share). The cell only needs
+     a containing block, so :where() keeps that rule at zero specificity: a sticky header or a
+     pinned column's own position always wins (a sticky cell contains the hit area too). */
+  :global(:where(td:has(> [data-smrt-hit-target]:only-child), th:has(> [data-smrt-hit-target]:only-child))) { position: relative; }
+  :global(:is(td, th):has(> [data-smrt-hit-target]:only-child)) > .checkbox { position: static; }
+  :global(:is(td, th):has(> [data-smrt-hit-target]:only-child)) > .checkbox::before { inset: 0; inline-size: auto; block-size: auto; margin: 0; }
+
   @media (prefers-reduced-motion: reduce) { .checkbox__box { transition: none; } }
 </style>

package/dist/components/forms/Combobox.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+import { untrack } from 'svelte';
 import {
   emitControlChange,
   highlightControl,
@@ -36,6 +37,12 @@ export interface Props {
   allowCustom?: boolean;
   /** Interaction options or false to disable all. */
   interaction?: ControlInteractionOptions | false;
+  /**
+   * Label for `value` while its option is not in `options` yet (options load
+   * asynchronously, or only the current record is known). Without it the
+   * field stays empty rather than flashing the raw value (an id).
+   */
+  valueLabel?: string;
   /** Callback when the selected value changes. */
   onvaluechange?: (value: string) => void;
   /** CSS class to apply to the combobox container. */
@@ -51,6 +58,7 @@ let {
   required = false,
   allowCustom = false,
   interaction,
+  valueLabel,
   onvaluechange,
   class: className = '',
 }: Props = $props();
@@ -61,12 +69,24 @@ const interactionContext = tryGetControlInteractionContext();
 let rootEl = $state<HTMLDivElement | null>(null);
 let inputEl = $state<HTMLInputElement | null>(null);
 let open = $state(false);
-let query = $state(value);
+/** The text for a value: its option's label, never a raw id (see valueLabel). */
+function labelForValue(candidate: string): string {
+  if (!candidate) return '';
+  const option = options.find((item) => String(item.value) === candidate);
+  if (option) return option.label;
+  if (valueLabel) return valueLabel;
+  return allowCustom ? candidate : '';
+}
+let query = $state(untrack(() => labelForValue(value)));
+/** The person has typed since opening: only then does the list filter. */
+let typed = $state(false);
 let activeIndex = $state(0);
 const filtered = $derived(
-  options.filter((option) =>
-    option.label.toLowerCase().includes(query.toLowerCase()),
-  ),
+  typed
+    ? options.filter((option) =>
+        option.label.toLowerCase().includes(query.toLowerCase()),
+      )
+    : options,
 );
 const controlId = $derived(
   interaction === false ? undefined : (interaction?.id ?? name ?? inputId),
@@ -76,6 +96,7 @@ function commit(option: ControlOption, userEdit = false) {
   const changed = String(option.value) !== value;
   value = String(option.value);
   query = option.label;
+  typed = false;
   open = false;
   onvaluechange?.(value);
   if (userEdit && changed) {
@@ -94,6 +115,7 @@ function setValue(next: unknown) {
   else if (allowCustom) {
     value = candidate;
     query = candidate;
+    typed = false;
     onvaluechange?.(candidate);
   }
 }
@@ -104,8 +126,24 @@ function prepareValue(next: unknown) {
   if (allowCustom) return candidate;
   return candidate;
 }
+function openList() {
+  if (open) return;
+  open = true;
+  // Reopening shows every option, starting at the current choice.
+  typed = false;
+  const selected = options.findIndex(
+    (option) => String(option.value) === value,
+  );
+  activeIndex = selected >= 0 ? selected : 0;
+}
+function closeList() {
+  open = false;
+  // Leaving without choosing puts the chosen label back.
+  typed = false;
+}
 function handleInput(event: Event & { currentTarget: HTMLInputElement }) {
   query = event.currentTarget.value;
+  typed = true;
   open = true;
   activeIndex = 0;
   if (allowCustom) {
@@ -116,7 +154,10 @@ function handleInput(event: Event & { currentTarget: HTMLInputElement }) {
 function handleKeydown(event: KeyboardEvent) {
   if (event.key === 'ArrowDown') {
     event.preventDefault();
-    open = true;
+    if (!open) {
+      openList();
+      return;
+    }
     const enabled = filtered
       .map((option, index) => (option.disabled ? -1 : index))
       .filter((index) => index >= 0);
@@ -134,16 +175,16 @@ function handleKeydown(event: KeyboardEvent) {
     event.preventDefault();
     commit(filtered[activeIndex], true);
   } else if (event.key === 'Escape') {
-    open = false;
+    closeList();
   }
 }
 $effect(() => {
   if (!open) return;
   const dismissPointer = (event: PointerEvent) => {
-    if (rootEl && !rootEl.contains(event.target as Node)) open = false;
+    if (rootEl && !rootEl.contains(event.target as Node)) closeList();
   };
   const dismissFocus = (event: FocusEvent) => {
-    if (rootEl && !rootEl.contains(event.target as Node)) open = false;
+    if (rootEl && !rootEl.contains(event.target as Node)) closeList();
   };
   document.addEventListener('pointerdown', dismissPointer, true);
   document.addEventListener('focusin', dismissFocus, true);
@@ -152,9 +193,21 @@ $effect(() => {
     document.removeEventListener('focusin', dismissFocus, true);
   };
 });
+// Follow the value (and options that load later) unless the person is typing.
+$effect(() => {
+  const label = labelForValue(value);
+  if (!typed) query = label;
+});
+// Validity follows the committed `value`, not the visible text: a value whose
+// option has not loaded shows an empty field but is filled in, and text typed
+// without choosing an option is not a value.
 $effect(() => {
-  const option = options.find((item) => String(item.value) === value);
-  if (option && document.activeElement !== inputEl) query = option.label;
+  if (!inputEl) return;
+  inputEl.setCustomValidity(
+    required && !disabled && !value && query.trim() !== ''
+      ? 'Choose an option from the list.'
+      : '',
+  );
 });
 useControlRegistration(() => {
   const root = rootEl;
@@ -203,9 +256,12 @@ 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><input bind:this={inputEl} id={inputId} {name} role="combobox" autocomplete="off" {placeholder} {disabled} {required} value={query}
+  <label for={inputId}>{label}</label>
+  <!-- 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}
-    onfocus={() => open = true} oninput={handleInput} onkeydown={handleKeydown} />
+    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}
 </div>

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

@@ -18,6 +18,12 @@ export interface Props {
     allowCustom?: boolean;
     /** Interaction options or false to disable all. */
     interaction?: ControlInteractionOptions | false;
+    /**
+     * Label for `value` while its option is not in `options` yet (options load
+     * asynchronously, or only the current record is known). Without it the
+     * field stays empty rather than flashing the raw value (an id).
+     */
+    valueLabel?: string;
     /** 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":"AAQA,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,gDAAgD;IAChD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA+KD,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":"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;AAiOD,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

@@ -0,0 +1,128 @@
+<script lang="ts">
+/**
+ * DictationButton — the microphone next to a text field (see `Dictation`).
+ *
+ * Tap to start listening, tap again to stop. It is always there, so people
+ * who cannot (or do not know to) press and hold the field can still speak.
+ * 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).
+ */
+import { M } from '../../i18n/strings.ui.js';
+import { useI18n } from '../../i18n/use-i18n.js';
+import Button from '../ui/Button.svelte';
+import type { Dictation } from './dictation.svelte.js';
+import { primeReadyBeep } from './ready-beep.js';
+
+export interface Props {
+  /** The dictation this button starts and stops. */
+  dictation: Dictation;
+  /** Disable the button (for example while the form sends). */
+  disabled?: boolean;
+  /** Accessible name to start (default "Speak instead of typing"). */
+  label?: string;
+  /** Accessible name to stop (default "Stop listening"). */
+  stopLabel?: string;
+  /** Tooltip (default mentions press-and-hold on the text box). */
+  title?: string;
+  /** Extra class names. */
+  class?: string;
+}
+
+let {
+  dictation,
+  disabled = false,
+  label,
+  stopLabel,
+  title,
+  class: className = '',
+}: Props = $props();
+
+const { t } = useI18n();
+const active = $derived(dictation.active);
+// While a recording is being written down, a tap would do nothing.
+const busy = $derived(dictation.state === 'transcribing');
+const name = $derived(
+  active
+    ? (stopLabel ?? t(M['ui.dictation.stop']))
+    : (label ?? t(M['ui.dictation.start'])),
+);
+
+function handleClick() {
+  // A tap is a user gesture: wake the audio so the ready beep can play.
+  primeReadyBeep();
+  void dictation.unlock();
+  void dictation.toggle();
+}
+</script>
+
+<Button
+  type="button"
+  variant="ghost"
+  size="sm"
+  class={`smrt-dictation-button${active ? ' smrt-dictation-button--listening' : ''} ${className}`.trim()}
+  aria-label={name}
+  aria-pressed={active}
+  aria-busy={busy || undefined}
+  title={active ? name : (title ?? t(M['ui.dictation.start_hint']))}
+  disabled={disabled || busy}
+  onclick={handleClick}
+  data-dictation-state={dictation.state}
+>
+  <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>
+    <path d="M5 10a7 7 0 0 0 14 0"></path>
+    <path d="M12 17v4"></path>
+  </svg>
+  {#if active}
+    <span class="smrt-dictation-dot" aria-hidden="true"></span>
+  {/if}
+</Button>
+
+<style>
+  :global(.smrt-dictation-button) {
+    position: relative;
+    flex-shrink: 0;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: 44px;
+    block-size: 44px;
+    min-inline-size: 44px;
+    padding: 0;
+    border-radius: var(--smrt-radius-full, 9999px);
+    color: var(--smrt-color-on-surface-variant, #43474e);
+  }
+
+  :global(.smrt-dictation-button--listening) {
+    background: var(--smrt-color-error-container, #ffdad6);
+    color: var(--smrt-color-on-error-container, #410002);
+  }
+
+  .smrt-dictation-dot {
+    position: absolute;
+    inset-block-start: 6px;
+    inset-inline-end: 6px;
+    inline-size: 10px;
+    block-size: 10px;
+    border-radius: 50%;
+    background: var(--smrt-color-error, #ba1a1a);
+    animation: smrt-dictation-pulse 1.2s ease-in-out infinite;
+  }
+
+  @keyframes smrt-dictation-pulse {
+    0%,
+    100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0.35;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .smrt-dictation-dot {
+      animation: none;
+    }
+  }
+</style>

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

@@ -0,0 +1,19 @@
+import type { Dictation } from './dictation.svelte.js';
+export interface Props {
+    /** The dictation this button starts and stops. */
+    dictation: Dictation;
+    /** Disable the button (for example while the form sends). */
+    disabled?: boolean;
+    /** Accessible name to start (default "Speak instead of typing"). */
+    label?: string;
+    /** Accessible name to stop (default "Stop listening"). */
+    stopLabel?: string;
+    /** Tooltip (default mentions press-and-hold on the text box). */
+    title?: string;
+    /** Extra class names. */
+    class?: string;
+}
+declare const DictationButton: import("svelte").Component<Props, {}, "">;
+type DictationButton = ReturnType<typeof DictationButton>;
+export default DictationButton;
+//# sourceMappingURL=DictationButton.svelte.d.ts.map

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

@@ -0,0 +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"}