gridsmith-ui 0.19.0 → 0.21.0

package/dist/index.d.ts

@@ -106,8 +106,19 @@ interface FieldControlWiring {
     required?: boolean;
     error?: boolean;
 }
+/**
+ * A field's label: any text or element, never nothing. Sprint 25.12 A31 (R28-59): run 75 labelled only the first of its
+ * repeated rows (`label={index === 0 ? … : undefined}`), and every other row's fields had no name. A label that
+ * shouldn't show takes `hideLabel`; repeated rows use AddAnother, which shows each label once.
+ */
+type FieldLabel = Exclude<ReactNode, null | undefined | boolean>;
 interface FieldProps {
-    label: ReactNode;
+    label: FieldLabel;
+    /**
+     * The label is read out but not shown (Sprint 25.12 A31): for a field whose purpose the page shows another way, such
+     * as a column heading above repeated rows. In an AddAnother group it shows again when the group stacks its rows.
+     */
+    hideLabel?: boolean;
     /** The single form control. Receives id, aria-describedby, aria-invalid/error and required automatically. */
     children: ReactElement | ((props: FieldControlProps) => ReactNode);
     /** Persistent help text (format requirements, why a field is disabled). Shown below the control, above any error. */
@@ -123,7 +134,8 @@ interface FieldProps {
      * - `onSubmit`: on submit only.
      *
      * Whatever the timing, it runs on every submit, and FormWrapper's `onSubmit` gets its message under this Field's
-     * `id`. A message that shows is checked again as the value changes, so it goes as soon as the value is right. Focus
+     * `id`, or no key at all when the value passes, so an empty `errors` means the form is valid. A message that shows is
+     * checked again as the value changes, so it goes as soon as the value is right. Focus
      * moving into the control's own popup (a Dropdown's list, a DatePicker's calendar) is not leaving the field. Outside
      * a FormWrapper it runs when the field is left (round 26, R26-2).
      */
@@ -145,7 +157,7 @@ interface FieldProps {
  * In a SettingsLayout panel a Field keeps the narrow page's reading width however wide the page is (the panel's
  * --ds-form-max, Sprint 25.9); a `max-w-*` class of your own wins.
  */
-declare function Field({ label, children, hint, error, required, labelAction, id: idProp, validate, className }: FieldProps): react_jsx_runtime.JSX.Element;
+declare function Field({ label, children, hint, error, required, labelAction, hideLabel, id: idProp, validate, className }: FieldProps): react_jsx_runtime.JSX.Element;
 
 interface Option {
     id: string;
@@ -172,7 +184,7 @@ interface DropdownProps extends FieldControlWiring {
     /** Accessible name for the trigger, for when there is no visible `label` (e.g. in a toolbar). */
     "aria-label"?: string;
 }
-declare function Dropdown({ options, value, onChange, label, disabled, placeholder, multiple, searchable, size: sizeProp, className, ref, container, error, showChips, "aria-label": ariaLabel, ...wiring }: DropdownProps): react_jsx_runtime.JSX.Element;
+declare function Dropdown({ options, value, onChange: onChangeProp, label, disabled, placeholder, multiple, searchable, size: sizeProp, className, ref, container, error, showChips, "aria-label": ariaLabel, ...wiring }: DropdownProps): react_jsx_runtime.JSX.Element;
 
 interface ComboboxOption {
     value: string;
@@ -192,10 +204,11 @@ interface ComboboxProps extends FieldControlWiring {
     error?: boolean;
     size?: ControlSize;
 }
-declare function Combobox({ value, onChange, options, placeholder, disabled, loading, className, ref, container, error, size: sizeProp, ...wiring }: ComboboxProps): react_jsx_runtime.JSX.Element;
+declare function Combobox({ value, onChange: onChangeProp, options, placeholder, disabled, loading, className, ref, container, error, size: sizeProp, ...wiring }: ComboboxProps): react_jsx_runtime.JSX.Element;
 
 type CheckboxSize = "sm" | "md";
-interface CheckboxProps {
+/** A Field passes its wiring (0.21.0): its label names the box, and its hint and error describe it. */
+interface CheckboxProps extends FieldControlWiring {
     checked: boolean;
     onChange: (checked: boolean) => void;
     label?: string;
@@ -205,7 +218,7 @@ interface CheckboxProps {
     className?: string;
     ref?: Ref<HTMLInputElement>;
 }
-declare function Checkbox({ checked, onChange, label, size, disabled, indeterminate, className, ref }: CheckboxProps): react_jsx_runtime.JSX.Element;
+declare function Checkbox({ checked, onChange: onChangeProp, label, size, disabled, indeterminate, className, ref, ...wiring }: CheckboxProps): react_jsx_runtime.JSX.Element;
 interface CheckboxGroupProps {
     value: string[];
     onChange: (value: string[]) => void;
@@ -229,7 +242,8 @@ interface RadioOption {
     label: string;
     disabled?: boolean;
 }
-interface RadioGroupProps {
+/** A Field passes its wiring (0.21.0): its label names the group, and its hint and error describe it. */
+interface RadioGroupProps extends FieldControlWiring {
     value: string;
     onChange: (value: string) => void;
     options: RadioOption[];
@@ -237,7 +251,7 @@ interface RadioGroupProps {
     className?: string;
     label?: string;
 }
-declare function RadioGroup({ value, onChange, options, orientation, className, label }: RadioGroupProps): react_jsx_runtime.JSX.Element;
+declare function RadioGroup({ value, onChange: onChangeProp, options, orientation, className, label, ...wiring }: RadioGroupProps): react_jsx_runtime.JSX.Element;
 
 interface DatePickerProps extends Omit<FieldControlWiring, "id"> {
     value: Date | null;
@@ -266,7 +280,7 @@ interface DatePickerProps extends Omit<FieldControlWiring, "id"> {
         end?: Date | null;
     };
 }
-declare function DatePicker({ value, onChange, placeholder, disabled, className, ref, container, error, label, id, size: sizeProp, min, max, range, ...wiring }: DatePickerProps): react_jsx_runtime.JSX.Element;
+declare function DatePicker({ value, onChange: onChangeProp, placeholder, disabled, className, ref, container, error, label, id, size: sizeProp, min, max, range, ...wiring }: DatePickerProps): react_jsx_runtime.JSX.Element;
 
 interface DateRange {
     start: Date | null;
@@ -305,10 +319,58 @@ declare const DEFAULT_DATE_RANGE_PRESETS: DateRangePreset[];
  * the end (clicking before the start restarts the selection). Closes on
  * Escape or outside click. Pair with <Field> for label/hint/error wiring.
  */
-declare function DateRangePicker({ value, onChange, placeholder, disabled, error, label, id, className, ref, container, min, max, presets, weekStartsOn, size: sizeProp, ...wiring }: DateRangePickerProps): react_jsx_runtime.JSX.Element;
+declare function DateRangePicker({ value, onChange: onChangeProp, placeholder, disabled, error, label, id, className, ref, container, min, max, presets, weekStartsOn, size: sizeProp, ...wiring }: DateRangePickerProps): react_jsx_runtime.JSX.Element;
 
+type FileUploadStatus = "added" | "queued" | "uploading" | "done" | "error";
+/** One file in the list: the page's own (`files`), or FileUpload's (the file was picked here). */
+interface FileUploadItem {
+    /** The page's id for the file (with `files`), or FileUpload's own. */
+    id: string;
+    name: string;
+    /** In bytes. */
+    size?: number;
+    /**
+     * "added": picked, with nothing uploading it (a FileUpload with only onFiles); "queued": waiting its turn;
+     * "uploading"; "done"; "error".
+     */
+    status: FileUploadStatus;
+    /** 0–100 while uploading. */
+    progress?: number;
+    /** Why it failed, in words ("The file is over 10 MB"). */
+    error?: string;
+    /** The picked File, when FileUpload has it. */
+    file?: File;
+}
+interface FileUploadRequestOptions {
+    /** Report progress, 0–100. */
+    onProgress: (percent: number) => void;
+    /** Aborted when the user cancels, the FileUpload goes, or its overlay closes: stop the request. */
+    signal: AbortSignal;
+}
 interface FileUploadProps {
-    onFiles: (files: File[]) => void;
+    /** The files the user picked or dropped, after the accept and size checks. */
+    onFiles?: (files: File[]) => void;
+    /**
+     * The page's uploads as they really are (Sprint 25.12 A33, R28-63): each file's status, progress and error. The list
+     * shows exactly these; the page adds what onFiles gives it, and answers onCancel, onRetry and onRemove. Pass `files`
+     * or `upload`, not both.
+     */
+    files?: FileUploadItem[];
+    /**
+     * Uploads one file. FileUpload runs it for each picked file, at most three at once while the rest wait, and keeps the
+     * list itself: report progress with onProgress, resolve when done, reject to fail (the error's message says why), and
+     * stop when the signal aborts. Cancel aborts; Retry runs it again with a fresh signal.
+     */
+    upload?: (file: File, options: FileUploadRequestOptions) => Promise<unknown>;
+    /** A running upload's Cancel. With `upload`, FileUpload has already aborted it and taken it off the list. */
+    onCancel?: (item: FileUploadItem) => void;
+    /** A failed upload's Retry. With `upload`, FileUpload runs it again itself. */
+    onRetry?: (item: FileUploadItem) => void;
+    /**
+     * A file's Remove. With `files` the page takes it off its list; otherwise FileUpload does, and tells the page. Without
+     * it, Remove shows only on a failed file: the page would still have a file the user removed (0.21.0).
+     */
+    onRemove?: (item: FileUploadItem) => void;
     /**
      * The types the zone takes, as for an `<input type="file">`: ".csv", "image/*", "application/pdf". The zone says them
      * in words ("CSV files"), and a picked or dropped file that isn't one gets a message instead of reaching onFiles.
@@ -328,7 +390,7 @@ interface FileUploadProps {
     /** The file input's id. A Field passes its own, so its label opens the picker. */
     id?: string;
 }
-declare function FileUpload({ onFiles, accept, multiple, maxSize, className, error, label, id }: FileUploadProps): react_jsx_runtime.JSX.Element;
+declare function FileUpload({ onFiles, files, upload, onCancel, onRetry, onRemove, accept, multiple, maxSize, className, error, label, id }: FileUploadProps): react_jsx_runtime.JSX.Element;
 
 interface SliderRangeProps {
     /**
@@ -362,7 +424,7 @@ interface SliderRangeProps {
      */
     formatValue?: (value: number) => string;
 }
-declare function SliderRange({ value, onChange, min, max, step, disabled, showValue, className, ref, error, label, "aria-label": ariaLabel, "aria-describedby": describedByProp, trackStyle, formatValue }: SliderRangeProps): react_jsx_runtime.JSX.Element;
+declare function SliderRange({ value, onChange: onChangeProp, min, max, step, disabled, showValue, className, ref, error, label, "aria-label": ariaLabel, "aria-describedby": describedByProp, trackStyle, formatValue }: SliderRangeProps): react_jsx_runtime.JSX.Element;
 
 interface TimePickerProps extends Omit<FieldControlWiring, "id"> {
     value: string;
@@ -378,7 +440,7 @@ interface TimePickerProps extends Omit<FieldControlWiring, "id"> {
     id?: string;
     size?: ControlSize;
 }
-declare function TimePicker({ value, onChange, use24Hour, minuteStep, disabled, className, ref, container, error, id, size: sizeProp, ...wiring }: TimePickerProps): react_jsx_runtime.JSX.Element;
+declare function TimePicker({ value, onChange: onChangeProp, use24Hour, minuteStep, disabled, className, ref, container, error, id, size: sizeProp, ...wiring }: TimePickerProps): react_jsx_runtime.JSX.Element;
 
 interface NumberInputProps {
     value: number;
@@ -398,7 +460,7 @@ interface NumberInputProps {
     /** Forwarded to the inner input element so a Label htmlFor can be associated. */
     id?: string;
 }
-declare function NumberInput({ value, onChange, min, max, step, disabled, placeholder, prefix, suffix, size: sizeProp, className, error, allowDecimals, id, }: NumberInputProps): react_jsx_runtime.JSX.Element;
+declare function NumberInput({ value, onChange: onChangeProp, min, max, step, disabled, placeholder, prefix, suffix, size: sizeProp, className, error, allowDecimals, id, }: NumberInputProps): react_jsx_runtime.JSX.Element;
 
 interface TagInputProps {
     value: string[];
@@ -413,7 +475,7 @@ interface TagInputProps {
     /** Accessible name for the input when no visible Label is associated via id. Default "Add tag". */
     "aria-label"?: string;
 }
-declare function TagInput({ value, onChange, placeholder, maxTags, disabled, className, error, id, "aria-label": ariaLabel }: TagInputProps): react_jsx_runtime.JSX.Element;
+declare function TagInput({ value, onChange: onChangeProp, placeholder, maxTags, disabled, className, error, id, "aria-label": ariaLabel }: TagInputProps): react_jsx_runtime.JSX.Element;
 
 interface PinInputProps {
     value: string;
@@ -427,9 +489,10 @@ interface PinInputProps {
     /** Forwarded to the first pin box so a Label htmlFor can be associated. */
     id?: string;
 }
-declare function PinInput({ value, onChange, length, mask, disabled, size: sizeProp, className, error, id, }: PinInputProps): react_jsx_runtime.JSX.Element;
+declare function PinInput({ value, onChange: onChangeProp, length, mask, disabled, size: sizeProp, className, error, id, }: PinInputProps): react_jsx_runtime.JSX.Element;
 
-interface RatingProps {
+/** A Field passes its wiring (0.21.0): its label names the stars, and its hint and error describe them. */
+interface RatingProps extends FieldControlWiring {
     value: number;
     onChange?: (value: number) => void;
     max?: number;
@@ -439,7 +502,7 @@ interface RatingProps {
     className?: string;
     error?: boolean;
 }
-declare function Rating({ value, onChange, max, allowHalf, readOnly, size, className, error, }: RatingProps): react_jsx_runtime.JSX.Element;
+declare function Rating({ value, onChange: onChangeProp, max, allowHalf, readOnly, size, className, error, ...wiring }: RatingProps): react_jsx_runtime.JSX.Element;
 
 interface ColorPickerProps {
     value: string;
@@ -450,7 +513,7 @@ interface ColorPickerProps {
     className?: string;
     error?: boolean;
 }
-declare function ColorPicker({ value, onChange, showAlpha, swatches, disabled, className, error, }: ColorPickerProps): react_jsx_runtime.JSX.Element;
+declare function ColorPicker({ value, onChange: onChangeProp, showAlpha, swatches, disabled, className, error, }: ColorPickerProps): react_jsx_runtime.JSX.Element;
 
 interface InlineFieldErrorProps {
     message: string;
@@ -489,11 +552,18 @@ interface FormFieldError {
 }
 interface FormWrapperProps {
     /**
-     * Called on each submit with the fields' errors, by Field id: the message of every Field whose `validate` finds its
-     * value wrong, undefined for the rest. Save only when there are none. Checks of your own that set a Field's `error`
-     * still work, and the form reads them from the page as before.
+     * Called on each submit, valid or not, with the fields that failed, by Field id: the message of every Field whose
+     * `validate` finds its value wrong. A field that passes has no key, so save when `errors` is empty
+     * (`Object.keys(errors).length === 0`). Checks of your own that set a Field's `error` still work, and the form reads
+     * them from the page as before.
+     *
+     * In a Drawer, Dialog or Sheet, return the save's promise: the overlay stops asking before discarding once it
+     * resolves, and keeps asking if it's rejected. If you catch a failure to show it, throw it again, so the promise
+     * rejects: one that resolves is a save. Returning nothing works for a save that keeps the form on screen or shows a
+     * confirmation in its place; a submit that moves on to another step keeps the overlay's changes until the flow saves
+     * (Sprint 25.12 A15). A field still invalid once the page has answered means nothing saved.
      */
-    onSubmit: (errors: FormErrors) => void;
+    onSubmit: (errors: FormErrors) => unknown;
     validationMode?: ValidationMode;
     children: ReactNode;
     /**
@@ -503,8 +573,8 @@ interface FormWrapperProps {
     actions?: ReactNode;
     actionsAlign?: "start" | "end";
     /**
-     * Renders a secondary Cancel before the actions. Inside a Drawer, a Dialog, or a Sheet given `dirty`, it closes the
-     * overlay through its unsaved-changes check — the question Escape and the close control ask while the form is dirty —
+     * Renders a secondary Cancel before the actions. Inside a Drawer, a Dialog or a Sheet, it closes the overlay through
+     * its unsaved-changes check — the question Escape and the close control ask once the user has changed something —
      * and then this function runs, unless it is the overlay's own onClose; it does not run when the user keeps editing.
      * Anywhere else this function runs. Never hand-wire a Cancel to the overlay's close: it skips the question (round 21).
      */
@@ -530,6 +600,40 @@ interface FormWrapperProps {
 }
 declare function FormWrapper({ onSubmit, validationMode: validationModeProp, children, actions: actionsProp, actionsAlign: actionsAlignProp, onCancel, cancelLabel, focusFirstError, errorSummary, className, ref }: FormWrapperProps): react_jsx_runtime.JSX.Element;
 
+interface AddAnotherProps<T> {
+    /** The rows. Each keeps its own id (`getId`), never its index, so its values, field ids and errors stay with it when another row goes. */
+    items: T[];
+    getId: (item: T) => string;
+    /** A row's name in words, from its position: `(i) => \`person ${i + 1}\``. It names every field in the row ("Email address, person 2") and the row's Remove button. */
+    itemName: (index: number) => string;
+    /** The fields' labels, in order. They show once, as the group's column headings; on a narrow group each field shows its own. */
+    columns: string[];
+    /**
+     * A row's fields. `label(column)` names a field for its row: wrap each control in
+     * `<Field hideLabel label={label("Email address")}>`, so it's read out in full while the heading shows it once.
+     */
+    renderRow: (item: T, index: number, label: (column: string) => string) => ReactNode;
+    onAdd: () => void;
+    onRemove: (id: string) => void;
+    /** The Add button's text (default "Add another"). */
+    addLabel?: string;
+    /** The group's own label, as a legend above it (for example "Team members"). */
+    label?: string;
+    /** Fewest rows kept (default 1): a row can't be removed below it. */
+    minItems?: number;
+    /** Most rows allowed: Add goes once there are this many. */
+    maxItems?: number;
+    className?: string;
+}
+/**
+ * Repeated rows of fields: MOJ's "Add another" (Sprint 25.12 A31, R28-59; the owner's P24). Builders dropped the labels
+ * of every row but the first to avoid repeating them on screen, and those fields had no name. Here the labels show
+ * once, as column headings, while every field is named for its row; Add and Remove name the row they act on, and
+ * focus moves to the new row after an add, or to the previous row after a removal. On a narrow group the rows stack,
+ * the headings go, and each field shows its own label.
+ */
+declare function AddAnother<T>({ items, getId, itemName, columns, renderRow, onAdd, onRemove, addLabel, label, minItems, maxItems, className }: AddAnotherProps<T>): react_jsx_runtime.JSX.Element;
+
 interface TransferItem {
     id: string;
     label: string;
@@ -545,7 +649,7 @@ interface TransferListProps {
     className?: string;
     ref?: Ref<HTMLDivElement>;
 }
-declare function TransferList({ available, selected, onChange, availableTitle, selectedTitle, searchable, className, ref, }: TransferListProps): react_jsx_runtime.JSX.Element;
+declare function TransferList({ available, selected, onChange: onChangeProp, availableTitle, selectedTitle, searchable, className, ref, }: TransferListProps): react_jsx_runtime.JSX.Element;
 
 interface MentionSuggestion {
     id: string;
@@ -562,7 +666,7 @@ interface MentionInputProps {
     disabled?: boolean;
     className?: string;
 }
-declare function MentionInput({ value: controlledValue, onChange, suggestions, trigger, placeholder, disabled, className, }: MentionInputProps): react_jsx_runtime.JSX.Element;
+declare function MentionInput({ value: controlledValue, onChange: onChangeProp, suggestions, trigger, placeholder, disabled, className, }: MentionInputProps): react_jsx_runtime.JSX.Element;
 
 type CardVariant = "default" | "featured" | "interactive" | "outline" | "ghost";
 type CardSelectType = "radio" | "checkbox" | "toggle";
@@ -697,7 +801,12 @@ declare const DescriptionList: react.ForwardRefExoticComponent<DescriptionListPr
 type StatusDotVariant = "success" | "warning" | "error" | "info" | "neutral" | "offline";
 interface StatusDotProps {
     variant?: StatusDotVariant;
-    label?: string;
+    /**
+     * The status in words ("Online", "Healthy"), drawn beside the dot and read as the status. Required: a dot alone would
+     * show the status by colour only (WCAG 1.4.1). Words a page already writes beside a dot are its label: pass them here
+     * and never write them again (Sprint 25.12 A48, R28-87).
+     */
+    label: string;
     pulse?: boolean;
     className?: string;
 }
@@ -2260,7 +2369,7 @@ interface SegmentedControlProps extends FieldControlWiring {
      */
     maxOptions?: number;
 }
-declare function SegmentedControl({ value, onChange, options, size: sizeProp, variant, fullWidth, onHoverChange, className, "aria-label": ariaLabel, maxOptions, ...wiring }: SegmentedControlProps): react_jsx_runtime.JSX.Element;
+declare function SegmentedControl({ value, onChange: onChangeProp, options, size: sizeProp, variant, fullWidth, onHoverChange, className, "aria-label": ariaLabel, maxOptions, ...wiring }: SegmentedControlProps): react_jsx_runtime.JSX.Element;
 
 interface BottomNavItem {
     label: string;
@@ -2711,36 +2820,64 @@ type ToastVariant = "default" | "success" | "warning" | "error";
 type ToastPosition = "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-center" | "bottom-center";
 interface ToastAction {
     label: string;
-    onClick: () => void;
+    /** Runs once when pressed; the toast then closes. It may return a promise (useDestructiveAction's Undo confirms itself when it settles). */
+    onClick: () => unknown;
 }
 interface ToastProps {
     variant?: ToastVariant;
     message: ReactNode;
     visible: boolean;
     onDismiss: () => void;
+    /** Milliseconds a plain toast stays. 0 or Infinity keeps it until dismissed. */
     duration?: number;
     pauseOnHover?: boolean;
+    /**
+     * The toast's action. Sprint 25.12 A40 (the sourced overlays#18): a toast with an action never closes on a timer while
+     * the action can still be taken. With `actionWindow` the action lapses after that long: in a ToastProvider the toast
+     * then stays as a plain message for its `duration`, and a standalone toast closes (onDismiss). Without one it stays until
+     * the user acts or dismisses it.
+     */
     action?: ToastAction;
+    /** How long the action is offered once the toast shows, in ms (an Undo's window). A standalone toast closes when it ends. */
+    actionWindow?: number;
     position?: ToastPosition;
     mode?: "light" | "dark";
     container?: Element | DocumentFragment;
     /**
-     * Render only the toast card, without the portal and fixed positioning.
-     * Used by ToastProvider, which owns stacking and placement. Standalone
-     * usage should leave this unset.
+     * Render only the toast card, without the portal, the fixed position or a live region of its own. ToastProvider
+     * renders cards this way: it owns their stacking, their timers' pause and their announcements. Standalone use
+     * leaves this unset, and the toast announces itself.
      */
     inline?: boolean;
+    /** ToastProvider: every timer pauses while the stack is hovered or holds focus. */
+    paused?: boolean;
+    /** ToastProvider: the action's window ran out (the provider drops the action and the plain time starts). */
+    onActionLapse?: () => void;
+    /** ToastProvider: the action was pressed (the provider runs it once and closes the toast). */
+    onAction?: () => void;
+    /** ToastProvider: a new value restarts the toast's time (a toast for the same item replaced this one). */
+    restartKey?: number;
 }
-declare function Toast({ variant, message, visible, onDismiss, duration, pauseOnHover, action, position, mode, container, inline }: ToastProps): react_jsx_runtime.JSX.Element | null;
+declare function Toast({ variant, message, visible, onDismiss, duration, pauseOnHover, action, actionWindow, position, mode, container, inline, paused, onActionLapse, onAction, restartKey }: ToastProps): react_jsx_runtime.JSX.Element | null;
 
 interface ToastOptions {
     variant?: ToastVariant;
-    /** Milliseconds before auto-dismiss. 0 or Infinity keeps the toast until dismissed. */
+    /** Milliseconds a plain toast stays once shown. 0 or Infinity keeps it until dismissed. */
     duration?: number;
+    /**
+     * An action (Undo, Retry). A toast with an action stays until the user acts or dismisses it, or until its action
+     * lapses (`actionWindow`); pressing it runs it once and closes the toast (Sprint 25.12 A40, A41).
+     */
     action?: ToastAction;
+    /** How long the action is offered once the toast shows, in ms (an Undo's window); the toast then stays as a plain message for its `duration`. */
+    actionWindow?: number;
     /** Supply to update an existing toast in place instead of adding a new one. */
     id?: string;
-    /** Coalescing key (round 15): while the visible slots are full, a new toast replaces the queued toast with the same key instead of joining the queue behind it. Defaults to the variant. */
+    /**
+     * The item this toast is about (Sprint 25.12 A7, D28): a new toast with the same key takes the place of the one on
+     * screen, or the one waiting, and its time starts again — six flips of one switch give one toast. Toasts without a
+     * key never merge, whatever their wording; toasts with an action, and errors, never merge.
+     */
     key?: string;
 }
 interface PromiseToastMessages<T> {
@@ -2749,7 +2886,7 @@ interface PromiseToastMessages<T> {
     error: ReactNode | ((error: unknown) => ReactNode);
 }
 interface ToastApi {
-    /** Enqueue a toast. Returns its id. */
+    /** Show a toast (it waits behind the stack when the stack is full). Returns its id. */
     toast: (message: ReactNode, options?: ToastOptions) => string;
     success: (message: ReactNode, options?: Omit<ToastOptions, "variant">) => string;
     warning: (message: ReactNode, options?: Omit<ToastOptions, "variant">) => string;
@@ -2763,31 +2900,38 @@ interface ToastApi {
 }
 interface ToastProviderProps {
     children: ReactNode;
-    /** Maximum toasts shown at once; further toasts queue until one dismisses. Default 1 — the house rule (feedback-notifications rule 4: one at a time, the rest queued). */
+    /**
+     * Most toasts shown at once (the project's notifications.toastMaxVisible). The rest wait behind a "+N" count, their
+     * time starting only when shown. Default 3 (Sprint 25.12 A40, the owner's R28-81: every deletion's confirmation
+     * shows); 1 is the least.
+     */
     maxVisible?: number;
     /** Where the stack is anchored. Default "bottom-right". */
     position?: ToastPosition;
-    /** Default auto-dismiss duration in ms. Default 5000. */
+    /** Default time a plain toast stays, in ms. Default 5000. */
     duration?: number;
-    /**
-     * Round 15 (the owner's 52.4): ten toggle flips queued ten toasts, each waiting its full duration. While the visible
-     * slots are full, a new toast replaces the queued toast that shares its key (the variant by default) — the user sees
-     * the current one and the latest, never a backlog. Default true.
-     */
+    /** Toasts with the same explicit `key` replace each other (D28). Default true. */
     coalesce?: boolean;
     /** Independent colour mode for toasts, when the theme configures one. */
     mode?: "light" | "dark";
-    /** Pause a toast's timer while hovered. Default true. */
+    /** Pause every toast's time while the stack is hovered (focus inside it always pauses). Default true. */
     pauseOnHover?: boolean;
 }
 declare function useToast(): ToastApi;
 /** The toast API when a ToastProvider is above, else null — for components that can do without one (useDestructiveAction in dialog mode). */
 declare function useToastOptional(): ToastApi | null;
 /**
- * Queue-backed toast manager. Wrap the app once (get_app_shell does this),
- * then call useToast() anywhere. Enforces the configured maximum visible
- * count, stacks toasts at the configured position, and provides success /
- * error / promise helpers so pages never hand-roll their own queue.
+ * Toasts for the whole app. Wrap it once (get_app_shell does), then call useToast() anywhere (Sprint 25.12 A40):
+ * - up to `maxVisible` show at once; the rest wait behind a "+N" count, their time starting only when shown, with
+ *   toasts that carry an action and errors ahead of plain confirmations; "Clear all" empties the stack;
+ * - only toasts for the same item (the same `key`) replace each other (D28);
+ * - hovering the stack, or focus inside it, pauses every toast's time, an Undo's window included;
+ * - two live regions, polite and assertive, present from the start, announce each toast once as it comes; the cards
+ *   themselves stay quiet;
+ * - F8 moves focus to the stack (a region named "Notifications"), and a toast with an action says so as it's announced;
+ *   when an action or the dismiss button closes a toast, focus returns where it was, else to the next toast, else
+ *   to the page's main content;
+ * - on a phone the stack sits above the bottom tab bar.
  */
 declare function ToastProvider({ children, maxVisible, position, duration, mode, pauseOnHover, coalesce }: ToastProviderProps): react_jsx_runtime.JSX.Element;
 
@@ -3107,12 +3251,27 @@ interface DestructiveActionOptions {
     confirmLabel?: string;
     /** The text the user must type when the action is on the type-to-confirm list (the item's name). */
     typeToConfirm?: string;
-    /** Performs the action. In undo mode it runs at once. */
-    onConfirm: () => void | Promise<void>;
-    /** Restores what the action removed; the Undo toast's action in undo mode. Without it the toast has no Undo. */
-    onUndo?: () => void;
-    /** The toast's message in undo mode ("Office removed"). */
+    /**
+     * Performs the action. In undo mode it runs at once. Reject (throw) when it fails: the hook then says so and claims
+     * nothing. Any return is allowed; a promise is awaited.
+     */
+    onConfirm: () => unknown;
+    /**
+     * Restores what the action removed; the Undo toast's action in undo mode. Without it the toast has no Undo. It may
+     * return a promise: once it resolves the hook confirms with a toast (`restoredMessage`), and a rejection shows an
+     * error toast (Sprint 25.12 A41).
+     */
+    onUndo?: () => unknown;
+    /**
+     * The completed action's message, in both modes ("Office removed"): the confirmation toast in dialog mode, and the
+     * text beside Undo in undo mode. Without it the hook says the action's verb in the past tense ("Removed"). A page
+     * that shows its own toast during `onConfirm` isn't given a second one (Sprint 25.12 A34).
+     */
+    doneMessage?: ReactNode;
+    /** The older name of `doneMessage`, for undo mode. */
     undoMessage?: ReactNode;
+    /** The toast once an Undo has worked ("Office restored"); "Restored" without one. */
+    restoredMessage?: ReactNode;
     /** `high` always confirms in a dialog, even in undo mode; the preference's high-severity list does the same by key. */
     severity?: "low" | "high";
 }
@@ -3275,4 +3434,4 @@ interface UseTextOverflowResult {
  */
 declare function useTextOverflow(options?: UseTextOverflowOptions): UseTextOverflowResult;
 
-export { Accordion, ActionPanel, ActionPanelGroup, Alert, type AlertPlacement, AppShell, type AppShellContextValue, type AppShellFocus, type AppShellPreferences, type AppShellTheme, AsidePanel, type AsidePanelProps, type AsidePanelSide, Avatar, AvatarGroup, type AvatarGroupItem, type AvatarGroupProps, type AvatarStatus, Badge, type BadgePaletteColor, type BadgeSeverity, type BadgeSize, type BadgeVariant, BottomNav, type BottomNavItem, type BreadcrumbItem$1 as BreadcrumbItem, Breadcrumbs, type BreadcrumbsSeparator, type BreadcrumbsSize, type BreadcrumbsVariant, BreakpointKey, BulkActionBar, Button, ButtonSizeContext, Calendar, type CalendarDay, Card, CardContent, CardDescription, CardFooter, CardGrid, type CardGridProps, CardHeader, type CardSelectType, CardTitle, type CardVariant, Carousel, type ChatMessage, type ChatMessageAction, type ChatMessageLayout, ChatMessageList, type ChatMessageSender, type ChatMessageSource, type ChatMessageStatus, ChatPanel, type ChatPanelProps, type ChatPanelStatusTone, Checkbox, CheckboxGroup, CheckboxGroupItem, CodeBlock, Collapsible, ColorPicker, type Column, Combobox, CommandPalette, ContextMenu, type ControlSize, ControlSizeContext, CornerPanel, type CornerPanelEdge, type CornerPanelProps, DEFAULT_DATE_RANGE_PRESETS, DataList, type DateInput, DatePicker, type DateRange, DateRangePicker, type DateRangePickerProps, type DateRangePreset, type DateRangeWords, type DescriptionItem, DescriptionList, type DescriptionListOrientation, type DescriptionListSize, type DestructiveActionHandle, type DestructiveActionOptions, Dialog, Divider, Dock, Drawer, Dropdown, DropdownMenu, type DropdownMenuDivider, type DropdownMenuEntry, type DropdownMenuItem, EmptyState, EntityCell, Field, type FieldControlProps, type FieldProps, FileUpload, type FitLabelsOptions, type FittedLabel, FormWrapper, Gantt, type GanttGroup, type GanttItem, type GanttProps, type GanttStatus, type GanttTone, type GridKeyboard, type GridKeyboardOptions, HoverCard, InlineFieldError, Input, Kbd, Label, type LabelBox, Launcher, type LauncherEdge, type LauncherProps, type LauncherVariant, type LauncherWhenOpen, Link, type LinkProps, MentionInput, MobileHeaderMenu, type MobileHeaderMenuItemData, type MobileHeaderMenuType, NavItem, type NavItemProps, type NavItemType, NavMenu, type NavMenuItem, Navbar, type NavbarSize, type NavbarType, type NavbarVariant, NotificationCenter, NumberInput, PageContainer, type PageContainerWidth, PageHeader, type PageHeaderBehavior, type PageHeaderIntensity, type PageHeaderProps, type PageHeaderVariant, type Pager, Pagination, type PaginationOptions, PinInput, Popover, PreferencesContext, Progress, type PromiseToastMessages, RadioGroup, Rating, type ResolvedPreferences, ScrollArea, SectionHeading, type SectionHeadingProps, SegmentedControl, SettingsLayout, type SettingsLayoutProps, type SettingsSection, Sheet, Sidebar, type SidebarContextValue, type SidebarItem, SidebarNav, type SidebarNavSize, type SidebarPosition, type SidebarSection, type SidebarType, Skeleton, SkipLink, SliderRange, Spinner, StackedList, type StackedListVariant, StatsCard, StatusDot, type StatusDotVariant, Stepper, TIME_ZOOMS, type Tab, Table, type TableDensity, type TableProps, TableToolbar, type TableToolbarActiveFilter, type TableToolbarFilterOption, Tabs, Tag, TagInput, type TagPaletteColor, type TagVariant, TextOverflow, type TextOverflowProps, Textarea, TimeBar, type TimeBarProps, TimePicker, TimeRow, type TimeRowProps, type TimeScale, TimeScaleHeader, type TimeScaleHeaderProps, type TimeScaleOptions, type TimeTick, TimeViewport, type TimeViewportHandle, type TimeViewportLayout, type TimeViewportProps, type TimeViewportState, type TimeZoom, Timeline, Toast, type ToastAction, type ToastApi, type ToastOptions, type ToastPosition, ToastProvider, type ToastVariant, Toggle, Tooltip, Tour, TransferList, TreeView, type Trend, type UseTextOverflowOptions, type UseTextOverflowResult, dateOfDay, dayOf, endDayOf, fitLabel, fitLabels, formatDateRange, preferenceActionKey, timeExtent, useAppShell, useContentWidth, useDestructiveAction, useFittedLabels, useFormContext, useGridKeyboard, usePagination, usePreferences, useSidebar, useTextMeasure, useTextOverflow, useTimeScale, useTimeViewport, useTimeViewportLayout, useToast, useToastOptional, useUnsavedChanges };
+export { Accordion, ActionPanel, ActionPanelGroup, AddAnother, type AddAnotherProps, Alert, type AlertPlacement, AppShell, type AppShellContextValue, type AppShellFocus, type AppShellPreferences, type AppShellTheme, AsidePanel, type AsidePanelProps, type AsidePanelSide, Avatar, AvatarGroup, type AvatarGroupItem, type AvatarGroupProps, type AvatarStatus, Badge, type BadgePaletteColor, type BadgeSeverity, type BadgeSize, type BadgeVariant, BottomNav, type BottomNavItem, type BreadcrumbItem$1 as BreadcrumbItem, Breadcrumbs, type BreadcrumbsSeparator, type BreadcrumbsSize, type BreadcrumbsVariant, BreakpointKey, BulkActionBar, Button, ButtonSizeContext, Calendar, type CalendarDay, Card, CardContent, CardDescription, CardFooter, CardGrid, type CardGridProps, CardHeader, type CardSelectType, CardTitle, type CardVariant, Carousel, type ChatMessage, type ChatMessageAction, type ChatMessageLayout, ChatMessageList, type ChatMessageSender, type ChatMessageSource, type ChatMessageStatus, ChatPanel, type ChatPanelProps, type ChatPanelStatusTone, Checkbox, CheckboxGroup, CheckboxGroupItem, CodeBlock, Collapsible, ColorPicker, type Column, Combobox, CommandPalette, ContextMenu, type ControlSize, ControlSizeContext, CornerPanel, type CornerPanelEdge, type CornerPanelProps, DEFAULT_DATE_RANGE_PRESETS, DataList, type DateInput, DatePicker, type DateRange, DateRangePicker, type DateRangePickerProps, type DateRangePreset, type DateRangeWords, type DescriptionItem, DescriptionList, type DescriptionListOrientation, type DescriptionListSize, type DestructiveActionHandle, type DestructiveActionOptions, Dialog, Divider, Dock, Drawer, Dropdown, DropdownMenu, type DropdownMenuDivider, type DropdownMenuEntry, type DropdownMenuItem, EmptyState, EntityCell, Field, type FieldControlProps, type FieldLabel, type FieldProps, FileUpload, type FileUploadItem, type FileUploadRequestOptions, type FileUploadStatus, type FitLabelsOptions, type FittedLabel, FormWrapper, Gantt, type GanttGroup, type GanttItem, type GanttProps, type GanttStatus, type GanttTone, type GridKeyboard, type GridKeyboardOptions, HoverCard, InlineFieldError, Input, Kbd, Label, type LabelBox, Launcher, type LauncherEdge, type LauncherProps, type LauncherVariant, type LauncherWhenOpen, Link, type LinkProps, MentionInput, MobileHeaderMenu, type MobileHeaderMenuItemData, type MobileHeaderMenuType, NavItem, type NavItemProps, type NavItemType, NavMenu, type NavMenuItem, Navbar, type NavbarSize, type NavbarType, type NavbarVariant, NotificationCenter, NumberInput, PageContainer, type PageContainerWidth, PageHeader, type PageHeaderBehavior, type PageHeaderIntensity, type PageHeaderProps, type PageHeaderVariant, type Pager, Pagination, type PaginationOptions, PinInput, Popover, PreferencesContext, Progress, type PromiseToastMessages, RadioGroup, Rating, type ResolvedPreferences, ScrollArea, SectionHeading, type SectionHeadingProps, SegmentedControl, SettingsLayout, type SettingsLayoutProps, type SettingsSection, Sheet, Sidebar, type SidebarContextValue, type SidebarItem, SidebarNav, type SidebarNavSize, type SidebarPosition, type SidebarSection, type SidebarType, Skeleton, SkipLink, SliderRange, Spinner, StackedList, type StackedListVariant, StatsCard, StatusDot, type StatusDotVariant, Stepper, TIME_ZOOMS, type Tab, Table, type TableDensity, type TableProps, TableToolbar, type TableToolbarActiveFilter, type TableToolbarFilterOption, Tabs, Tag, TagInput, type TagPaletteColor, type TagVariant, TextOverflow, type TextOverflowProps, Textarea, TimeBar, type TimeBarProps, TimePicker, TimeRow, type TimeRowProps, type TimeScale, TimeScaleHeader, type TimeScaleHeaderProps, type TimeScaleOptions, type TimeTick, TimeViewport, type TimeViewportHandle, type TimeViewportLayout, type TimeViewportProps, type TimeViewportState, type TimeZoom, Timeline, Toast, type ToastAction, type ToastApi, type ToastOptions, type ToastPosition, ToastProvider, type ToastVariant, Toggle, Tooltip, Tour, TransferList, TreeView, type Trend, type UseTextOverflowOptions, type UseTextOverflowResult, dateOfDay, dayOf, endDayOf, fitLabel, fitLabels, formatDateRange, preferenceActionKey, timeExtent, useAppShell, useContentWidth, useDestructiveAction, useFittedLabels, useFormContext, useGridKeyboard, usePagination, usePreferences, useSidebar, useTextMeasure, useTextOverflow, useTimeScale, useTimeViewport, useTimeViewportLayout, useToast, useToastOptional, useUnsavedChanges };