@tai42/studio-sdk 0.12.0 → 0.13.0

package/src/components/date-range-picker.tsx

@@ -0,0 +1,256 @@
+/**
+ * `DateRangePicker` — the compact time-window control observability screens share.
+ * It emits ONE of two shapes:
+ *
+ * - a relative token from a PRESET chip, `{ kind: 'relative', token }` — the backend
+ *   resolves `\d+[hdw]` tokens, so a preset stays a token rather than freezing to an
+ *   instant at click time;
+ * - an ABSOLUTE range from the two native `datetime-local` inputs,
+ *   `{ kind: 'absolute', from, to }` with ISO instants — native inputs keep the
+ *   control inside the platform date UI, no third-party calendar.
+ *
+ * Absolute ranges are normalized by {@link normalizeCustomRange}; the active window
+ * is rendered by {@link formatRangeLabel}, always with the YEAR present.
+ */
+import { useState, type CSSProperties, type ReactNode } from 'react';
+
+import { Field } from './field';
+import { TextInput } from './inputs';
+import { Button } from './primitives';
+
+/** A relative preset: a `\d+[hdw]` token the backend resolves, plus its chip label. */
+export interface DateRangePreset {
+  readonly token: string;
+  readonly label: string;
+}
+
+/** The presets a picker offers when the caller names none. */
+export const DEFAULT_DATE_RANGE_PRESETS: readonly DateRangePreset[] = [
+  { token: '24h', label: 'Last 24 hours' },
+  { token: '7d', label: 'Last 7 days' },
+  { token: '30d', label: 'Last 30 days' },
+  { token: '90d', label: 'Last 90 days' },
+];
+
+/**
+ * A named time window: either a relative token the backend resolves against its
+ * own clock, or an absolute pair of ISO instants.
+ */
+export type DateRangeValue =
+  | { readonly kind: 'relative'; readonly token: string }
+  | { readonly kind: 'absolute'; readonly from: string; readonly to: string };
+
+const RELATIVE_TOKEN = /^(\d+)([hdw])$/;
+
+const UNIT_NOUN: Record<string, string> = { h: 'hour', d: 'day', w: 'week' };
+
+/**
+ * A relative token as a readable phrase (`7d` → `Last 7 days`). A token outside the
+ * `\d+[hdw]` grammar raises rather than rendering a silent placeholder.
+ */
+function relativePhrase(token: string): string {
+  const match = RELATIVE_TOKEN.exec(token);
+  if (match === null) {
+    throw new Error(`Invalid relative range token: ${token}`);
+  }
+  const amount = Number(match[1]);
+  const noun = UNIT_NOUN[match[2] ?? ''] ?? '';
+  return `Last ${String(amount)} ${noun}${amount === 1 ? '' : 's'}`;
+}
+
+/**
+ * The active window as human text: a relative token as its preset label (or a
+ * derived phrase), an absolute range as both instants with the YEAR present.
+ */
+const ABSOLUTE_FORMAT = new Intl.DateTimeFormat(undefined, {
+  year: 'numeric',
+  month: 'short',
+  day: 'numeric',
+  hour: '2-digit',
+  minute: '2-digit',
+});
+
+export function formatRangeLabel(
+  value: DateRangeValue,
+  presets: readonly DateRangePreset[] = DEFAULT_DATE_RANGE_PRESETS,
+): string {
+  if (value.kind === 'relative') {
+    const preset = presets.find((candidate) => candidate.token === value.token);
+    return preset?.label ?? relativePhrase(value.token);
+  }
+  const from = new Date(value.from);
+  const to = new Date(value.to);
+  return `${ABSOLUTE_FORMAT.format(from)} – ${ABSOLUTE_FORMAT.format(to)}`;
+}
+
+/** A `datetime-local` string parsed as a local instant, or a loud error on garbage. */
+function parseLocalInput(value: string, field: string): Date {
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    throw new Error(`Invalid ${field} datetime: ${value}`);
+  }
+  return parsed;
+}
+
+function pad(value: number): string {
+  return String(value).padStart(2, '0');
+}
+
+/** A local instant as the `YYYY-MM-DDTHH:mm` a `datetime-local` input reads. */
+function toLocalInputValue(date: Date): string {
+  return (
+    `${String(date.getFullYear())}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+    `T${pad(date.getHours())}:${pad(date.getMinutes())}`
+  );
+}
+
+/**
+ * A raw from/to pair resolved to a clean absolute range. Order matters: SWAP the
+ * reversed pair first (earlier instant becomes start), THEN cap both ends at `now` —
+ * capping first can leave a future instant on the post-swap end. The end is
+ * INCLUSIVE of its minute, extended to `:59.999`, so `23:59` reaches the day's end.
+ */
+export function normalizeCustomRange(
+  fromInput: string,
+  toInput: string,
+  now: Date,
+): { readonly from: string; readonly to: string } {
+  let start = parseLocalInput(fromInput, 'from');
+  let end = parseLocalInput(toInput, 'to');
+
+  if (start.getTime() > end.getTime()) {
+    [start, end] = [end, start];
+  }
+
+  // Inclusive end: extend the selected minute to its final millisecond.
+  end = new Date(end);
+  end.setSeconds(59, 999);
+
+  const nowMs = now.getTime();
+  if (start.getTime() > nowMs) start = new Date(nowMs);
+  if (end.getTime() > nowMs) end = new Date(nowMs);
+
+  return { from: start.toISOString(), to: end.toISOString() };
+}
+
+export interface DateRangePickerProps {
+  readonly value: DateRangeValue;
+  readonly onValueChange: (value: DateRangeValue) => void;
+  /** The preset chips to offer. Defaults to {@link DEFAULT_DATE_RANGE_PRESETS}. */
+  readonly presets?: readonly DateRangePreset[];
+  /** The control group's accessible name. */
+  readonly 'aria-label'?: string;
+  readonly disabled?: boolean;
+  /**
+   * The clock the absolute-range clamp reads. Defaults to the wall clock; a caller
+   * (or a test) injects a fixed instant to pin the "no future" boundary.
+   */
+  readonly now?: () => Date;
+}
+
+const CUSTOM_ROW_STYLE: CSSProperties = { alignItems: 'flex-end' };
+const FIELD_STYLE: CSSProperties = { flex: 1 };
+
+/**
+ * The range control: a row of preset chips over the two `datetime-local` inputs and
+ * an Apply action, with the active window echoed as text below.
+ *
+ * Controlled: the caller owns `value` and receives the next window through
+ * `onValueChange` — a preset click emits its token immediately, while the custom
+ * inputs hold a working draft until Apply commits the normalized absolute range.
+ *
+ * The drafts track the controlled value, re-seeded on a NEW absolute `value` (keyed
+ * on `from`/`to`), so edits against an unchanged value are preserved but a genuinely
+ * different value replaces an in-progress draft.
+ */
+export function DateRangePicker({
+  value,
+  onValueChange,
+  presets = DEFAULT_DATE_RANGE_PRESETS,
+  'aria-label': ariaLabel = 'Date range',
+  disabled = false,
+  now = () => new Date(),
+}: DateRangePickerProps): ReactNode {
+  const nextFrom = value.kind === 'absolute' ? value.from : null;
+  const nextTo = value.kind === 'absolute' ? value.to : null;
+
+  const [fromDraft, setFromDraft] = useState(() =>
+    nextFrom !== null ? toLocalInputValue(new Date(nextFrom)) : '',
+  );
+  const [toDraft, setToDraft] = useState(() =>
+    nextTo !== null ? toLocalInputValue(new Date(nextTo)) : '',
+  );
+  // The absolute ends that last seeded the drafts (null while a preset is active).
+  // Comparing against the incoming ends re-seeds only when the caller swaps in a
+  // different absolute value, leaving drafts typed against an unchanged value alone.
+  const [seeded, setSeeded] = useState<{ from: string | null; to: string | null }>(() => ({
+    from: nextFrom,
+    to: nextTo,
+  }));
+
+  if (seeded.from !== nextFrom || seeded.to !== nextTo) {
+    setSeeded({ from: nextFrom, to: nextTo });
+    if (nextFrom !== null && nextTo !== null) {
+      setFromDraft(toLocalInputValue(new Date(nextFrom)));
+      setToDraft(toLocalInputValue(new Date(nextTo)));
+    }
+  }
+
+  const activeToken = value.kind === 'relative' ? value.token : null;
+  const canApply = !disabled && fromDraft !== '' && toDraft !== '';
+
+  const applyCustom = (): void => {
+    onValueChange({ kind: 'absolute', ...normalizeCustomRange(fromDraft, toDraft, now()) });
+  };
+
+  return (
+    <div role="group" aria-label={ariaLabel} className="tai-stack tai-stack-3">
+      <div className="tai-row">
+        {presets.map((preset) => (
+          <button
+            key={preset.token}
+            type="button"
+            className="tai-chip"
+            aria-pressed={activeToken === preset.token}
+            onClick={() => {
+              onValueChange({ kind: 'relative', token: preset.token });
+            }}
+            disabled={disabled}
+          >
+            {preset.label}
+          </button>
+        ))}
+      </div>
+
+      <div className="tai-row" style={CUSTOM_ROW_STYLE}>
+        <Field label="From" style={FIELD_STYLE}>
+          <TextInput
+            type="datetime-local"
+            value={fromDraft}
+            onChange={(event) => {
+              setFromDraft(event.target.value);
+            }}
+            disabled={disabled}
+          />
+        </Field>
+        <Field label="To" style={FIELD_STYLE}>
+          <TextInput
+            type="datetime-local"
+            value={toDraft}
+            onChange={(event) => {
+              setToDraft(event.target.value);
+            }}
+            disabled={disabled}
+          />
+        </Field>
+        <Button type="button" variant="primary" onClick={applyCustom} disabled={!canApply}>
+          Apply range
+        </Button>
+      </div>
+
+      <p role="status" className="tai-muted" style={{ margin: 0 }}>
+        {formatRangeLabel(value, presets)}
+      </p>
+    </div>
+  );
+}

package/src/components/dialog.tsx

@@ -1,16 +1,14 @@
 /**
  * `Dialog` — a design-system wrapper over Radix Dialog: an accessible modal (role
- * `dialog`, focus trap, Escape to close) labelled by its title. Modality is
- * enforced by the focus trap and by Radix marking the rest of the page inert, not
- * by an `aria-modal` attribute — the panel ships none.
+ * `dialog`, focus trap, Escape to close) labelled by its title. Modality comes from
+ * the focus trap and Radix marking the page inert, not an `aria-modal` attribute.
  *
- * Radix owns every modal behaviour — the focus trap, the background scroll lock,
- * Escape, and focus return to the trigger — so this component adds no second
- * mechanism. It contributes only the design-system surface: `tai-overlay` paints
- * the scrim from `--tai-color-scrim`, and `tai-dialog` sizes the panel with a
- * `min()` so it still fits a 320 px viewport. The one gap Radix leaves — focus
- * return for a dialog that renders no trigger — is filled by
- * `useModalFocusReturn`, which stands down whenever a trigger IS rendered.
+ * Radix owns every modal behaviour (focus trap, scroll lock, Escape, focus return
+ * to the trigger); this component adds only the design-system surface (`tai-overlay`
+ * scrim, `tai-dialog` panel). The one gap Radix leaves — focus return for a dialog
+ * with no trigger — is filled by `useModalFocusReturn`, which stands down when a
+ * trigger IS rendered. The `fullscreen`, `contentClassName` and `chromeless` opt-ins
+ * (see the props) reshape the panel without giving up any Radix behaviour.
  */
 import * as RadixDialog from '@radix-ui/react-dialog';
 import type { ReactElement, ReactNode } from 'react';
@@ -35,6 +33,24 @@ export interface DialogProps {
   readonly open?: boolean;
   readonly defaultOpen?: boolean;
   readonly onOpenChange?: (open: boolean) => void;
+  /**
+   * Fill the viewport edge to edge instead of centring a fixed-size panel. The
+   * overlay, the focus trap and every other Radix behaviour are unchanged.
+   */
+  readonly fullscreen?: boolean;
+  /**
+   * A class merged onto `RadixDialog.Content` after the surface classes, for a
+   * host that must reach the content element itself — e.g. a plugin hanging its
+   * CSS-scoping root on the panel so its styles apply inside the Radix portal.
+   */
+  readonly contentClassName?: string;
+  /**
+   * Drop the forced visual `Title` and the `tai-stack` children wrapper, rendering
+   * `children` directly for a chrome-free content mode. The `title` is still
+   * required and still names the dialog — it renders visually-hidden — so the
+   * accessible name never depends on the visible chrome.
+   */
+  readonly chromeless?: boolean;
 }
 
 export function Dialog({
@@ -45,9 +61,17 @@ export function Dialog({
   open,
   defaultOpen,
   onOpenChange,
+  fullscreen = false,
+  contentClassName,
+  chromeless = false,
 }: DialogProps) {
   const focusReturn = useModalFocusReturn(trigger !== undefined);
   if (trigger !== undefined) assertSlotElement(trigger, 'Dialog `trigger`');
+
+  const contentClasses = ['tai-dialog'];
+  if (fullscreen) contentClasses.push('tai-dialog-fullscreen');
+  if (contentClassName !== undefined) contentClasses.push(contentClassName);
+
   return (
     <RadixDialog.Root open={open} defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
       {trigger !== undefined ? <RadixDialog.Trigger asChild>{trigger}</RadixDialog.Trigger> : null}
@@ -58,17 +82,34 @@ export function Dialog({
             Passing the prop as `undefined` is Radix's opt-out — it has to be
             ABSENT when a description IS rendered, or it would clear the wiring. */}
         <RadixDialog.Content
-          className="tai-dialog"
+          className={contentClasses.join(' ')}
           {...focusReturn}
           {...(description === undefined ? { 'aria-describedby': undefined } : {})}
         >
-          <RadixDialog.Title className="tai-dialog-title">{title}</RadixDialog.Title>
-          <div className="tai-stack">
-            {description !== undefined ? (
-              <RadixDialog.Description className="tai-muted">{description}</RadixDialog.Description>
-            ) : null}
-            {children}
-          </div>
+          {/* The title always names the dialog; `chromeless` only hides it, moving
+              it behind `tai-visually-hidden` so the accessible name is unchanged. */}
+          <RadixDialog.Title className={chromeless ? 'tai-visually-hidden' : 'tai-dialog-title'}>
+            {title}
+          </RadixDialog.Title>
+          {chromeless ? (
+            <>
+              {description !== undefined ? (
+                <RadixDialog.Description className="tai-visually-hidden">
+                  {description}
+                </RadixDialog.Description>
+              ) : null}
+              {children}
+            </>
+          ) : (
+            <div className="tai-stack">
+              {description !== undefined ? (
+                <RadixDialog.Description className="tai-muted">
+                  {description}
+                </RadixDialog.Description>
+              ) : null}
+              {children}
+            </div>
+          )}
         </RadixDialog.Content>
       </RadixDialog.Portal>
     </RadixDialog.Root>

package/src/components/dirty-guard.tsx

@@ -0,0 +1,153 @@
+/**
+ * Unsaved-changes guard for tabbed editors. `Tabs` unmount inactive panels, so a
+ * tab switch tears an editor down and drops its edits. One registry closes the gap:
+ * editors report dirtiness via {@link useRegisterDirty}; {@link GuardedTabs} holds a
+ * switch away from a dirty editor behind a confirm; the same registry arms
+ * {@link useNavigationGuard}, so a route navigation confirms through the SAME dialog
+ * and a full-page unload raises the native prompt. The dialog is one shared
+ * {@link ConfirmDialog} driven by a pending-promise resolver, so the guard's
+ * `Promise<boolean>` handler and the tab switch both settle against it.
+ */
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+
+import { ConfirmDialog } from './confirm-dialog';
+import { Tabs } from './tabs';
+import type { TabItem } from './tabs';
+import { useNavigationGuard } from '../navigation';
+
+interface DirtyGuardValue {
+  /** Register (or clear) one editor's dirty state, keyed by a stable id. */
+  readonly setDirty: (id: string, dirty: boolean) => void;
+  /**
+   * Resolve `true` when it is safe to leave (nothing dirty, or the operator
+   * confirmed the discard); `false` to stay put.
+   */
+  readonly confirmLeaveIfDirty: () => Promise<boolean>;
+}
+
+const DirtyGuardContext = createContext<DirtyGuardValue | null>(null);
+
+function DirtyGuardProvider({ children }: { readonly children: ReactNode }): ReactNode {
+  const dirtyIds = useRef<Set<string>>(new Set());
+  // Mirror the registry's non-empty state into React so the navigation guard's
+  // `when` re-arms as editors go dirty/clean.
+  const [anyDirty, setAnyDirty] = useState(false);
+  const [open, setOpen] = useState(false);
+  const resolverRef = useRef<((ok: boolean) => void) | null>(null);
+
+  const setDirty = useCallback((id: string, dirty: boolean): void => {
+    if (dirty) dirtyIds.current.add(id);
+    else dirtyIds.current.delete(id);
+    setAnyDirty(dirtyIds.current.size > 0);
+  }, []);
+
+  const confirmLeaveIfDirty = useCallback((): Promise<boolean> => {
+    if (dirtyIds.current.size === 0) return Promise.resolve(true);
+    return new Promise<boolean>((resolve) => {
+      // Settle a still-pending confirm as "stay" before it is orphaned by the new one.
+      resolverRef.current?.(false);
+      resolverRef.current = resolve;
+      setOpen(true);
+    });
+  }, []);
+
+  const settle = useCallback((ok: boolean): void => {
+    setOpen(false);
+    const resolve = resolverRef.current;
+    resolverRef.current = null;
+    resolve?.(ok);
+  }, []);
+
+  // The route navigation guard is armed from the SAME registry, so it confirms
+  // through this dialog and any armed guard raises the native unload prompt.
+  useNavigationGuard(anyDirty, confirmLeaveIfDirty);
+
+  return (
+    <DirtyGuardContext.Provider value={{ setDirty, confirmLeaveIfDirty }}>
+      {children}
+      {open ? (
+        <ConfirmDialog
+          title="Discard unsaved changes?"
+          confirmLabel="Discard changes"
+          pendingLabel="Discarding"
+          confirmVariant="danger"
+          isPending={false}
+          onConfirm={() => {
+            settle(true);
+          }}
+          onClose={() => {
+            settle(false);
+          }}
+        >
+          <p style={{ margin: 0 }}>This editor has unsaved changes. Leaving now discards them.</p>
+        </ConfirmDialog>
+      ) : null}
+    </DirtyGuardContext.Provider>
+  );
+}
+
+/**
+ * Report an editor's dirty state to the enclosing {@link GuardedTabs}. A no-op
+ * outside a provider (an editor rendered standalone, e.g. in isolation tests) so
+ * the hook is always safe to call.
+ */
+export function useRegisterDirty(dirty: boolean): void {
+  const ctx = useContext(DirtyGuardContext);
+  const id = useId();
+  useEffect(() => {
+    ctx?.setDirty(id, dirty);
+  }, [ctx, id, dirty]);
+  // Clear the registration on unmount (a tab switch unmounts the editor) so a
+  // torn-down editor never leaves the guard armed.
+  useEffect(() => () => ctx?.setDirty(id, false), [ctx, id]);
+}
+
+function GuardedTabsInner({
+  items,
+  defaultValue,
+}: {
+  readonly items: readonly TabItem[];
+  readonly defaultValue?: string;
+}): ReactNode {
+  const ctx = useContext(DirtyGuardContext);
+  const [active, setActive] = useState<string | undefined>(defaultValue ?? items[0]?.value);
+  // The tab set is dynamic (plugin/capability-gated tabs). If the active value is
+  // no longer present, fall back to the first tab rather than render no panel.
+  const effective = items.some((item) => item.value === active) ? active : items[0]?.value;
+
+  const onValueChange = (next: string): void => {
+    void ctx?.confirmLeaveIfDirty().then((ok) => {
+      if (ok) setActive(next);
+    });
+  };
+
+  return <Tabs items={items} value={effective} onValueChange={onValueChange} />;
+}
+
+/**
+ * A drop-in replacement for {@link Tabs} that guards a switch away from a dirty
+ * editor. Wraps the tabs in a {@link DirtyGuardProvider}, so an editor rendered in
+ * any panel can arm the guard through {@link useRegisterDirty}.
+ */
+export function GuardedTabs({
+  items,
+  defaultValue,
+}: {
+  readonly items: readonly TabItem[];
+  readonly defaultValue?: string;
+}): ReactNode {
+  return (
+    <DirtyGuardProvider>
+      <GuardedTabsInner items={items} defaultValue={defaultValue} />
+    </DirtyGuardProvider>
+  );
+}

package/src/components/extension-picker.tsx

@@ -25,6 +25,7 @@ import type { Extension } from '@tai42/api-client';
 import { Badge } from './badge';
 import { Checkbox } from './checkbox';
 import { groupByKind, kindVariant } from './extension-grouping';
+import { EmptyState } from './primitives';
 
 export interface ExtensionPickerProps {
   /** The extension catalog (`GET /api/extensions`) the checklist is drawn from. */
@@ -47,6 +48,17 @@ export function ExtensionPicker({
   const groups = groupByKind(available);
   const selected = new Set(value);
 
+  // An empty catalog renders the shared EmptyState HERE — inside the picker — so
+  // every call site inherits it rather than each guarding an empty checklist (a
+  // bare div that reads as broken). No provider has published an extension yet.
+  if (available.length === 0) {
+    return (
+      <div data-testid={idPrefix} className="tai-stack">
+        <EmptyState title="No extensions are available." />
+      </div>
+    );
+  }
+
   /**
    * Toggle a single extension. For a NON-STACKABLE kind (`backend`), checking one
    * first strips any other selected member of that kind before appending, so the

package/src/components/form-dialog.tsx

@@ -0,0 +1,133 @@
+/**
+ * `FormDialog` — a modal whose body is a real `<form>`, so implicit submission
+ * gives Enter-in-a-field → submit. Composes {@link Dialog} and owns the submit
+ * lifecycle: a `type="submit"` default button, a busy state that disables it and
+ * shows a Spinner while the action runs, and a close-on-success-ONLY async contract.
+ *
+ * The contract: `onSubmit` may return a promise; the dialog closes (via `onClose`)
+ * only when it RESOLVES. A rejection or synchronous throw keeps the dialog open and
+ * renders the failure through `ErrorState`, so the operator can retry the filled fields.
+ *
+ * The caller owns mount/unmount: mount only while active, and any close gesture
+ * (Cancel, Escape, overlay) calls `onClose`. `submitDisabled` blocks submission by
+ * click AND by Enter — a disabled default button is not an implicit-submission target.
+ */
+import { useEffect, useRef, useState, type ReactNode, type SyntheticEvent } from 'react';
+
+import { Dialog } from './dialog';
+import { Button, ErrorState, Spinner } from './primitives';
+import { errorMessage } from '../errors';
+
+export interface FormDialogProps {
+  readonly title: string;
+  readonly description?: string;
+  /** The submit button's resting label (e.g. `Create scope`). */
+  readonly submitLabel: string;
+  /** The Spinner's accessible label while the action runs (e.g. `Creating`). */
+  readonly pendingLabel: string;
+  /**
+   * The action the form performs. A returned promise is awaited: the dialog
+   * closes only when it RESOLVES; a rejection (or a synchronous throw) keeps the
+   * dialog open and renders the failure loudly. A `void` return closes the
+   * dialog synchronously.
+   */
+  readonly onSubmit: () => void | Promise<void>;
+  /**
+   * Called on a close gesture (Cancel, Escape, overlay) and on a successful
+   * submit — at most once per dialog lifecycle. A close landing mid-submit wins:
+   * the later resolution does not fire a second `onClose`.
+   */
+  readonly onClose: () => void;
+  /** Blocks submission by click and by Enter while incomplete (a disabled default button is not an implicit-submission target). */
+  readonly submitDisabled?: boolean;
+  readonly submitVariant?: 'primary' | 'danger';
+  /** The Cancel button's label. */
+  readonly cancelLabel?: string;
+  /** The form body — the caller's fields. */
+  readonly children: ReactNode;
+}
+
+export function FormDialog({
+  title,
+  description,
+  submitLabel,
+  pendingLabel,
+  onSubmit,
+  onClose,
+  submitDisabled = false,
+  submitVariant = 'primary',
+  cancelLabel = 'Cancel',
+  children,
+}: FormDialogProps): ReactNode {
+  const [isPending, setIsPending] = useState(false);
+  const [submitError, setSubmitError] = useState<unknown>(null);
+  // Latches on the first close gesture so `onClose` fires at most once per lifecycle;
+  // a close mid-submit wins, and the later resolution must not close again.
+  const closedRef = useRef(false);
+  // Guards post-await setters from touching state after a mid-submit close unmounts.
+  const mountedRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  function close(): void {
+    if (closedRef.current) return;
+    closedRef.current = true;
+    onClose();
+  }
+
+  function handleSubmit(event: SyntheticEvent<HTMLFormElement>): void {
+    // SPA: the form never navigates, so the default GET is prevented.
+    event.preventDefault();
+    // Also covers a programmatic `requestSubmit` and a second Enter mid-flight, so the
+    // action fires at most once per run.
+    if (isPending || submitDisabled) return;
+    setSubmitError(null);
+    setIsPending(true);
+    // `Promise.resolve().then(onSubmit)` routes a synchronous throw into the rejection
+    // path too, so a sync failure surfaces like an async one.
+    Promise.resolve()
+      .then(() => onSubmit())
+      .then(
+        () => {
+          // A mid-submit close already settled the lifecycle; don't close or set state again.
+          if (closedRef.current || !mountedRef.current) return;
+          setIsPending(false);
+          close();
+        },
+        (reason: unknown) => {
+          if (closedRef.current || !mountedRef.current) return;
+          setIsPending(false);
+          setSubmitError(reason);
+        },
+      );
+  }
+
+  return (
+    <Dialog
+      title={title}
+      description={description}
+      open
+      onOpenChange={(next) => {
+        if (!next) close();
+      }}
+    >
+      <form onSubmit={handleSubmit}>
+        {children}
+        {submitError != null ? <ErrorState message={errorMessage(submitError)} /> : null}
+        <div className="tai-dialog-actions">
+          <Button type="button" onClick={close}>
+            {cancelLabel}
+          </Button>
+          <Button type="submit" variant={submitVariant} disabled={isPending || submitDisabled}>
+            {isPending ? <Spinner label={pendingLabel} /> : null}
+            {submitLabel}
+          </Button>
+        </div>
+      </form>
+    </Dialog>
+  );
+}