gridsmith-ui 0.23.0 → 0.25.0

package/dist/index.d.ts

@@ -1,11 +1,13 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ReactNode, InputHTMLAttributes, LabelHTMLAttributes, TextareaHTMLAttributes, Ref, ReactElement, CSSProperties, HTMLAttributes, RefObject, KeyboardEvent, AnchorHTMLAttributes, ComponentType } from 'react';
+import { ButtonHTMLAttributes, ReactNode, InputHTMLAttributes, LabelHTMLAttributes, TextareaHTMLAttributes, Ref, ReactElement, CSSProperties, HTMLAttributes, RefObject, KeyboardEvent, AnchorHTMLAttributes, ElementType } from 'react';
+import { IconSlot, IconName } from './icons.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { IconName } from './icons.js';
+import { M as MentionSuggestion } from './MentionList-CoNBRFGR.js';
 import { C as ColumnKind, B as BreakpointKey } from './table-utils-BkjNEWts.js';
 export { a as BreakpointWidthProvider, u as useBreakpoint } from './table-utils-BkjNEWts.js';
-import { P as Pager, A as AppShellPreferences } from './use-pagination-DiJo0aW5.js';
-export { a as PaginationOptions, b as PreferencesContext, R as ResolvedPreferences, p as preferenceActionKey, u as usePagination, c as usePreferences } from './use-pagination-DiJo0aW5.js';
+import { P as Pager, A as AppShellPreferences } from './use-pagination-BnKOnBdz.js';
+export { a as PaginationOptions, b as PreferencesContext, R as ResolvedPreferences, p as preferenceActionKey, u as usePagination, c as usePreferences } from './use-pagination-BnKOnBdz.js';
+export { B as BreadcrumbItem, a as Breadcrumbs, b as BreadcrumbsSeparator, c as BreadcrumbsSize, d as BreadcrumbsVariant } from './Breadcrumbs-CGS8GKl-.js';
 
 type ButtonVariant = "default" | "secondary" | "tertiary" | "outline" | "ghost" | "destructive" | "success" | "warning" | "link";
 type ButtonSize = "xs" | "sm" | "md" | "lg" | "icon-xs" | "icon-sm" | "icon" | "icon-lg";
@@ -15,8 +17,10 @@ declare const ButtonSizeContext: react.Context<ControlSize | null>;
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     variant?: ButtonVariant;
     size?: ButtonSize;
-    iconLeft?: ReactNode;
-    iconRight?: ReactNode;
+    /** An icon name ("clock"), drawn as the theme's icon at the button's icon size, or an element. Not text: use children. */
+    iconLeft?: IconSlot;
+    /** As iconLeft, after the label. */
+    iconRight?: IconSlot;
     loading?: boolean;
     children?: ReactNode;
 }
@@ -205,8 +209,87 @@ interface ComboboxProps extends FieldControlWiring {
     container?: Element | DocumentFragment;
     error?: boolean;
     size?: ControlSize;
+    /** The control's name when no Field labels it (a toolbar's filter). Inside a Field, the Field's label names it. */
+    "aria-label"?: string;
 }
-declare function Combobox({ value, onChange: onChangeProp, 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, "aria-label": ariaLabel, ...wiring }: ComboboxProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * The browser's own name for a zone (Sprint 25.17 A28, R28-51): one browser always names a zone one way, so a stored
+ * "Asia/Calcutta" and a listed "Asia/Kolkata" are one zone, with no alias table shipped. An id the browser doesn't know
+ * stays as given.
+ */
+declare function canonicalTimeZone(zone: string): string;
+/** The browser's time zone, by its own name; "UTC" where the browser names none. */
+declare function browserTimeZone(): string;
+/**
+ * A zone's offset from UTC at an instant, as the page's language names it ("GMT+1", "GMT-5", "GMT+5:30"): read at that
+ * instant, so it follows daylight saving.
+ */
+declare function timeZoneOffset(zone: string, at?: Date): string;
+interface TimezoneSelectProps extends FieldControlWiring {
+    /**
+     * The stored zone, an IANA id ("Europe/London"). Empty: the field is empty, and the browser's zone is the list's first
+     * option, marked as the user's, to pick with one key. Start the page's state from the stored zone, else
+     * browserTimeZone(), to show the browser's as chosen.
+     */
+    value?: string;
+    /** Called with the chosen zone's id, by the browser's own name. */
+    onChange: (zone: string) => void;
+    size?: ControlSize;
+    disabled?: boolean;
+    placeholder?: string;
+    className?: string;
+    /** The control's name when no Field labels it. In a settings form, a Field labels it ("Time zone"). */
+    "aria-label"?: string;
+}
+/**
+ * A time zone select (Sprint 25.17 A28, R28-51): every IANA zone the browser knows, each shown with its offset now
+ * (which follows daylight saving), searchable by city, region or offset, with the house keyboard (the Combobox's).
+ * UTC is always offered. A stored zone is matched by the browser's own name for it, and one the browser doesn't list
+ * is still shown, never a blank.
+ */
+declare function TimezoneSelect({ value, onChange, placeholder, ...rest }: TimezoneSelectProps): react_jsx_runtime.JSX.Element;
+
+/** A time: an ISO string, a Date, or milliseconds since the epoch. */
+type TimeValue = string | Date | number;
+/**
+ * A time as people read it (Sprint 25.17 A29, R28-48; date_time#1, #11 and #13): within `thresholdHours` of now,
+ * relative ("now", "5 minutes ago", "in 2 hours", "yesterday", counting days on the calendar), in the page's language;
+ * beyond it, the date and the time. The threshold is given: the project's is the shell's
+ * (dateTime.relativeThresholdHours), which RelativeTime and useRelativeTimeFormat read for you.
+ */
+declare function formatRelativeTime(time: TimeValue, options: {
+    thresholdHours: number;
+    now?: number;
+}): string;
+/**
+ * formatRelativeTime with the project's threshold, the shell's (dateTime.relativeThresholdHours), for a time drawn as
+ * text in a slot that takes a string: a Timeline item's `timestamp`, with the time itself as its `dateTime` so the exact
+ * time shows on hover. The text is read when the page renders; RelativeTime draws a time that refreshes as it ages.
+ */
+declare function useRelativeTimeFormat(): (time: TimeValue) => string;
+/** The full timestamp, as the tooltip and a screen reader give it: the date, the time and its zone, in the page's language. */
+declare function formatFullTime(time: TimeValue): string;
+interface RelativeTimeProps {
+    /** The time: an ISO string, a Date, or milliseconds since the epoch. */
+    time: TimeValue;
+    /** Within this many hours it reads relative, else the date and time. Leave it out: the project's (the shell's dateTime.relativeThresholdHours). */
+    thresholdHours?: number;
+    /** The time's own classes (its colour, its size); the tooltip keeps the library's. */
+    className?: string;
+}
+/**
+ * A time drawn as the project reads times (Sprint 25.17 A29, R28-48): relative within the project's threshold, the date
+ * and time beyond it, and the full timestamp, with its zone, on hover and, outside a collection's rows, on focus
+ * (date_time#1, #2, #13). Outside them it is a Tab stop; among a table's, a list's or a grid's rows it isn't (a stop per
+ * row would make the collection hard to cross, and nest a stop in a row that is a button), and a screen reader hears the
+ * full timestamp with the time everywhere. It refreshes as it ages, each minute in its first hour and each hour after,
+ * and becomes the date and time once past the threshold; a time that changes is read against the clock afresh. Drawn on a
+ * server, the browser's reading of the clock replaces the server's when the page hydrates, with no error for the moment
+ * between them. In a sortable Table column, pass the time itself as the column's sort value.
+ */
+declare function RelativeTime({ time, thresholdHours, className }: RelativeTimeProps): react_jsx_runtime.JSX.Element | null;
 
 type CheckboxSize = "sm" | "md";
 /** A Field passes its wiring (0.21.0): its label names the box, and its hint and error describe it. */
@@ -594,13 +677,19 @@ interface FormWrapperProps {
      */
     errorSummary?: boolean | ((errors: FormFieldError[]) => ReactNode);
     /**
-     * Classes for the form. In a SettingsLayout panel the form 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 here wins.
+     * The form takes the full width it is given, for the rare form whose fields need it: several columns side by side,
+     * line items. Without it the form, its buttons with it, keeps the narrow reading width wherever it sits.
+     */
+    fullWidth?: boolean;
+    /**
+     * Classes for the form. Wherever it sits — a page of its own, a card, beside a list, under a tab, a settings panel —
+     * the form keeps the narrow page's reading width however wide its box is (--ds-form-max, Sprint 25.9 A4; everywhere
+     * since Sprint 25.16 A8); in a Drawer or a Dialog it takes the overlay's width. A `max-w-*` class here wins.
      */
     className?: string;
     ref?: React.Ref<HTMLFormElement>;
 }
-declare function FormWrapper({ onSubmit, validationMode: validationModeProp, children, actions: actionsProp, actionsAlign: actionsAlignProp, onCancel, cancelLabel, focusFirstError, errorSummary, className, ref }: FormWrapperProps): react_jsx_runtime.JSX.Element;
+declare function FormWrapper({ onSubmit, validationMode: validationModeProp, children, actions: actionsProp, actionsAlign: actionsAlignProp, onCancel, cancelLabel, focusFirstError, errorSummary, fullWidth, 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. */
@@ -653,13 +742,7 @@ interface TransferListProps {
 }
 declare function TransferList({ available, selected, onChange: onChangeProp, availableTitle, selectedTitle, searchable, className, ref, }: TransferListProps): react_jsx_runtime.JSX.Element;
 
-interface MentionSuggestion {
-    id: string;
-    label: string;
-    avatar?: string;
-    description?: string;
-}
-interface MentionInputProps {
+interface MentionInputProps extends FieldControlWiring {
     value?: string;
     onChange?: (value: string) => void;
     suggestions: MentionSuggestion[];
@@ -667,8 +750,10 @@ interface MentionInputProps {
     placeholder?: string;
     disabled?: boolean;
     className?: string;
+    /** The field's name when no Field labels it. Inside a Field, the Field's label names it. */
+    "aria-label"?: string;
 }
-declare function MentionInput({ value: controlledValue, onChange: onChangeProp, suggestions, trigger, placeholder, disabled, className, }: MentionInputProps): react_jsx_runtime.JSX.Element;
+declare function MentionInput({ value: controlledValue, onChange: onChangeProp, suggestions, trigger, placeholder, disabled, className, error, "aria-label": ariaLabel, ...wiring }: MentionInputProps): react_jsx_runtime.JSX.Element;
 
 type CardVariant = "default" | "featured" | "interactive" | "outline" | "ghost";
 type CardSelectType = "radio" | "checkbox" | "toggle";
@@ -859,9 +944,11 @@ interface Column {
      * What the column sorts by, when its cells don't say (Sprint 25.13 A3): a column of elements (an avatar beside a name,
      * a badge, a time) gives each row's name, number or date here, `sortValue: (row) => row.actorName`, and a column of
      * sizes gives bytes. Without it a sortable column sorts by the cell itself, which works for text and numbers; a cell
-     * that is an element can't be compared, and the column warns in development (data_display#1).
+     * that is an element can't be compared, and the column warns in development (data_display#1). It may return any of a
+     * row's fields as they are (a row's values are typed for its cells): a string, a number or a Date sorts; an element
+     * doesn't.
      */
-    sortValue?: (row: TableRow) => string | number | Date | null | undefined;
+    sortValue?: (row: TableRow) => unknown;
     /**
      * Keep the column in view while the table scrolls sideways (Sprint 25.13 A35): "end" for the row's actions, pinned on
      * the right; "start" for the row's name, drawn first and pinned beside the selection while it leaves room. Without a
@@ -1091,9 +1178,11 @@ interface EmptyStateProps {
      * An icon name from the theme's pack ("inbox", "filter") or an element. A
      * name is the easy path: the state renders it at the frame's size. An `Icon`
      * element is resized to match; any other element is rendered as given. A
-     * string that is not an icon name is a type error, not a printed word.
-     * (The Sprint 22 bench saw builders pass names into a ReactNode prop and
-     * React print the word — 14 Sep 2026.)
+     * string is always read as a name, never printed as a word (the Sprint 22
+     * bench saw builders pass names into a ReactNode prop and React print the
+     * word — 14 Sep 2026). `IconName` takes any string, so a name the theme's
+     * pack lacks still type-checks: it draws nothing, and in development the Icon
+     * says so (Sprint 25.17 A26).
      */
     icon?: IconName | Exclude<ReactNode, string>;
     /** How the icon is framed: the neutral circle (default), or none when the icon element brings its own frame. */
@@ -1216,7 +1305,14 @@ declare function TableToolbar({ search, primaryFilter, filters, filtersOpen, onF
 interface TimelineItem {
     title: string;
     description?: string;
-    /** What the item shows for its time: "2 hours ago", "Mon 14:05". */
+    /**
+     * When it happened (an ISO string, a Date or milliseconds), drawn as the project reads times, with RelativeTime:
+     * relative within the shell's threshold, the date and time beyond it, the full timestamp on hover, refreshing as it
+     * ages (Sprint 25.17's second review: a time the page formatted itself read differently on a server and in the browser,
+     * and read the date twice to a screen reader). With `time`, leave timestamp and dateTime out.
+     */
+    time?: TimeValue;
+    /** What the item shows for its time, as text the page wrote: "Mon 14:05". For a time ago, pass `time`. */
     timestamp?: string;
     /**
      * The item's exact time (an ISO string or a Date). The timestamp is then a <time> element, with the exact date and
@@ -1224,8 +1320,11 @@ interface TimelineItem {
      * "2 hours ago" with no way to the date). Without a timestamp, the exact date is shown.
      */
     dateTime?: string | Date;
-    /** Takes the dot's place — the actor's Avatar (size="sm") on an activity feed, or an Icon. `variant` colours the dot only. */
-    icon?: ReactNode;
+    /**
+     * Takes the dot's place — the actor's Avatar (size="sm") on an activity feed, or an icon: its name ("upload"), drawn as
+     * the theme's icon at 16 px, or an element. `variant` colours the dot only.
+     */
+    icon?: IconSlot;
     variant?: "default" | "success" | "warning" | "error";
 }
 interface TimelineProps {
@@ -1309,12 +1408,18 @@ interface TreeViewProps {
     checkable?: boolean;
     defaultExpanded?: string[];
     defaultSelected?: string[];
+    /**
+     * The selected ids, when the app holds the selection: the address names the open item, or a crumb of its path
+     * selects a folder (Sprint 25.16 A19). `onSelect` reports a click and the app passes the new selection back.
+     * Without it the tree keeps its own, starting from `defaultSelected`.
+     */
+    selected?: string[];
     defaultChecked?: string[];
     onSelect?: (ids: string[]) => void;
     onCheck?: (ids: string[]) => void;
     className?: string;
 }
-declare function TreeView({ nodes, selectable, multiSelect, checkable, defaultExpanded, defaultSelected, defaultChecked, onSelect, onCheck, className, }: TreeViewProps): react_jsx_runtime.JSX.Element;
+declare function TreeView({ nodes, selectable, multiSelect, checkable, defaultExpanded, defaultSelected, selected: selectedProp, defaultChecked, onSelect, onCheck, className, }: TreeViewProps): react_jsx_runtime.JSX.Element;
 
 interface CarouselProps {
     children: ReactNode[];
@@ -1656,7 +1761,7 @@ interface TimeScaleOptions {
     today?: DateInput;
     /** Default 1 (Monday), as Calendar's. */
     weekStartsOn?: 0 | 1;
-    /** Default the browser's. */
+    /** Default the page's language (its `lang`, in the visitor's formats where they speak it: formatLocale). */
     locale?: string;
     /** Px per day at each level, where a view needs another density (the defaults fit each level's labels). */
     pxPerDay?: Partial<Record<TimeZoom, number>>;
@@ -2015,7 +2120,7 @@ interface GanttProps<T extends GanttItem = GanttItem> {
     today?: DateInput;
     /** Default 1 (Monday), as Calendar's. */
     weekStartsOn?: 0 | 1;
-    /** Default the browser's: the scale's labels and the items' dates. */
+    /** Default the page's language (its `lang`, in the visitor's formats where they speak it): the scale's labels and the items' dates. */
     locale?: string;
     /**
      * Beside the title in the name column (assignees' avatars): shown, not announced (say it in `describe`), and left out
@@ -2065,11 +2170,15 @@ interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
      * Render through a router link component instead of a plain anchor
      * (e.g. `component={RouterLink}` from react-router or next/link). The
      * component receives the same props; `href` is also passed as `to` for
-     * react-router compatibility.
+     * react-router compatibility. Any element type: a router's Link requires
+     * its own props (react-router's `to`), which a narrower type refused under
+     * strict TypeScript (Sprint 25.16 A19).
      */
-    component?: ComponentType<Record<string, unknown>>;
-    iconLeft?: ReactNode;
-    iconRight?: ReactNode;
+    component?: ElementType;
+    /** An icon name ("info"), drawn as the theme's icon at 14 px, or an element. Not text: use children. */
+    iconLeft?: IconSlot;
+    /** As iconLeft, after the label. */
+    iconRight?: IconSlot;
 }
 /**
  * Navigation link. Renders a real <a> (or a router link via `component`) so
@@ -2276,33 +2385,6 @@ interface SettingsLayoutProps {
  */
 declare function SettingsLayout({ sections, value, onChange, layout: layoutProp, railWidth, collapseBelow: collapseBelowProp, "aria-label": ariaLabel, children, className, }: SettingsLayoutProps): react_jsx_runtime.JSX.Element;
 
-interface BreadcrumbItem$1 {
-    label: string;
-    href?: string;
-    onClick?: () => void;
-    icon?: IconName;
-}
-type BreadcrumbsVariant = "inline" | "contained" | "pill";
-type BreadcrumbsSeparator = "slash" | "chevron" | "dot" | "arrow";
-type BreadcrumbsSize = "sm" | "md";
-interface BreadcrumbsProps {
-    items: BreadcrumbItem$1[];
-    separator?: BreadcrumbsSeparator;
-    variant?: BreadcrumbsVariant;
-    /** Visual treatment of individual breadcrumb items — independent of layout variant. */
-    itemVariant?: "default" | "pill";
-    size?: BreadcrumbsSize;
-    showIcons?: boolean;
-    maxItems?: number;
-    /** Full-bleed: contained background extends edge-to-edge, breaking out of parent padding. Text stays aligned with sibling content. */
-    bleed?: boolean;
-    /** Max-width for bleed content alignment. Defaults to --ds-bp-xl. */
-    contentMaxWidth?: string;
-    className?: string;
-    container?: Element | DocumentFragment;
-}
-declare const Breadcrumbs: react.ForwardRefExoticComponent<BreadcrumbsProps & react.RefAttributes<HTMLElement>>;
-
 interface PaginationProps {
     currentPage: number;
     totalPages: number;
@@ -2332,6 +2414,8 @@ interface Step {
     label: string;
     description?: string;
     status?: "complete" | "error" | "loading";
+    /** Not reached yet, so it can't be gone to: its circle can't be pressed (Sprint 25.16 A30, useFlowSteps' stepper). */
+    disabled?: boolean;
 }
 interface StepperProps {
     steps: Step[];
@@ -2894,7 +2978,8 @@ interface AlertAction {
     label: string;
     onClick: () => void;
     variant?: "secondary" | "outline";
-    iconLeft?: ReactNode;
+    /** An icon name ("refresh"), drawn as the theme's icon at 14 px, or an element. */
+    iconLeft?: IconSlot;
 }
 interface AlertProps {
     variant: AlertVariant;
@@ -3135,6 +3220,14 @@ interface AppShellContextValue {
     addUnsavedChanges: () => () => void;
     /** The width every Drawer in the app takes when it is given none (Sprint 25.14 A24): AppShell's drawerWidth, 520 px by default. */
     drawerWidth: string;
+    /** The app's router (AppShell's `navigate`), or null: the library's links in the shell (a breadcrumb's crumb) and a flow's steps go through it. */
+    navigate: ((href: string, options?: {
+        replace?: boolean;
+    }) => void) | null;
+    /** A page that has left the flow is showing (<FlowSaved>, Sprint 25.16 A30): focus mode draws no exit control. */
+    flowLeft: boolean;
+    /** Set by FlowSaved; not for pages to call. Returns the release. */
+    markFlowLeft: () => () => void;
 }
 /**
  * Focus mode (Sprint 25.7, C1): a task flow the user completes before or outside the app — setup, onboarding,
@@ -3206,6 +3299,16 @@ interface AppShellProps {
     currentPath?: string;
     /** The home page's path. Default "/". */
     homePath?: string;
+    /**
+     * The app's router: `(href, options) => navigate(href, options)` with React Router, `(href, options) =>
+     * (options?.replace ? router.replace(href) : router.push(href))` with Next.js. The library's links in the shell — a
+     * breadcrumb's crumb, a SplitView's path — go through it on a plain click, so the page changes with no reload, and so
+     * do a flow's steps (useFlowSteps), which replace an address that isn't a step reached (Sprint 25.16 A19, A30).
+     * Without it they are ordinary links. The generated layout passes it.
+     */
+    navigate?: (href: string, options?: {
+        replace?: boolean;
+    }) => void;
     /**
      * Focus mode for a flow outside the navigation (setup, onboarding, checkout). The sidebar, mobile menu and bottom
      * nav are not rendered, and the Navbar drops its links and search; the logo, the assistant (its launcher and its
@@ -3216,6 +3319,139 @@ interface AppShellProps {
 }
 declare const AppShell: react.ForwardRefExoticComponent<AppShellProps & react.RefAttributes<HTMLDivElement>>;
 
+interface FlowStep<A> {
+    /** The step's name in the Stepper ("Team size"). */
+    label: string;
+    /** The page's title on this step ("How big is your team?"). */
+    title: string;
+    /** The step is shown only while this holds, so the total follows the answers ("Just me" leaves out the team's step). */
+    when?: (answers: A) => boolean;
+}
+/**
+ * What a flow keeps between visits: the furthest step reached, the step the user was on, and the answers so far. The
+ * answers are kept as JSON: strings, numbers, booleans, arrays and plain objects (a Date comes back as its string).
+ */
+interface FlowProgress<A> {
+    furthest: number;
+    current?: number;
+    answers: A;
+}
+type FlowNavigate = (href: string, options?: {
+    replace?: boolean;
+}) => void;
+interface UseFlowStepsOptions<A, S extends FlowStep<A>> {
+    /** Every step, in order; a step with `when` is shown only while it holds. */
+    steps: readonly S[];
+    /** The step the address names: the flow's one `:step` route parameter ("3"). */
+    at: string | undefined;
+    /** Step n's address, counting the steps shown from 1: (n) => `/setup/${n}`. */
+    href: (step: number) => string;
+    /**
+     * The flow's name in the browser's storage, where its progress and answers are kept between visits. With sign-in,
+     * name it for the user (`setup:${userId}`), so the next person on the browser starts afresh; pass undefined until the
+     * user is known, and the flow waits (draws nothing, moves nothing, writes nothing).
+     */
+    storageKey: string | undefined;
+    /** The answers before the user has given any. */
+    initialAnswers: A;
+    /**
+     * Where saveAndExit goes with no sign-in: a page drawing <FlowSaved> (the shell's exit, "Save and continue later",
+     * goes there too). An app with sign-in leaves through the shell's "Save and log out" instead, and resumes on return.
+     */
+    exitTo: string;
+    /** Where Finish goes once the flow is done: the app's home. */
+    finishTo: string;
+    /** The app's router. Left out, the shell's (AppShell's navigate); with neither, a page load. */
+    navigate?: FlowNavigate;
+}
+interface FlowSteps<A, S extends FlowStep<A>> {
+    /**
+     * False until the flow's progress has been read and the address names a step reached. Draw nothing until then: an
+     * address not reached yet, past the last step or not a step at all is being moved to the furthest step reached.
+     */
+    ready: boolean;
+    /** This step, counting the steps shown from 1. */
+    step: number;
+    /** How many steps are shown, which follows the answers. */
+    total: number;
+    /** This step's own entry in `steps`: pick its form from it. */
+    current: S;
+    /** "Step 2 of 6": PageHeader's caption. */
+    caption: string;
+    /** This step's title: PageHeader's title. The browser tab's title follows it. */
+    title: string;
+    /** The answers so far, kept with the progress. */
+    answers: A;
+    /** Merges answers in. One that changes which steps follow this one means walking them again: they count as not reached. */
+    setAnswers: (patch: Partial<A>) => void;
+    /** The furthest step reached: any step up to it can be gone to. */
+    furthest: number;
+    isFirst: boolean;
+    isLast: boolean;
+    /** Goes on to the next step, which then counts as reached; answers given with it are kept in the same move. */
+    next: (patch?: Partial<A>) => void;
+    /** PageHeader's onBack: the step before, or undefined on the first step (no Back link there). */
+    back: (() => void) | undefined;
+    /** Goes to a step reached; any other is ignored. */
+    goTo: (step: number) => void;
+    /** The Stepper's props: the steps shown (done before the furthest, and a step past it can't be pressed), this one, and going to one. */
+    stepper: {
+        steps: {
+            label: string;
+            status?: "complete";
+            disabled?: boolean;
+        }[];
+        currentStep: number;
+        onStepChange: (index: number) => void;
+    };
+    /** Keeps the progress and leaves the flow, for exitTo. */
+    saveAndExit: () => void;
+    /** Ends the flow: its stored progress and answers go, and the user goes on to finishTo. */
+    finish: () => void;
+}
+/** A flow's stored progress: its record under the prefix, its answers merged over the initial ones. Null when none (or unreadable). */
+declare function readFlowProgress<A>(storageKey: string, initialAnswers: A): FlowProgress<A> | null;
+/**
+ * Sprint 25.16 A30 (R28-57, R28-58; P22): the library owns a flow's step. A flow with an address per step has one
+ * `:step` route, and this hook reads the step from it: the step and the total, next, back and go-to, never past the
+ * furthest step reached. An address not reached yet, past the last step or not a step at all ("/setup/9",
+ * "/setup/abc") goes to the furthest step reached, the address changing with it: a fresh "/setup/3" lands on
+ * "/setup/1". Steps can be conditional, so the total follows the answers. The progress (the furthest step, and the step
+ * on screen) and the answers are kept in the browser's storage under the flow's name, so a return resumes; they go once
+ * the flow finishes. Every caller with that name (a layout and its step, a page that mounts anew on each step, another
+ * tab) shares one flow: its progress, its finish, the focus after a move and the tab's title. Its save-and-exit leaves
+ * the flow (GOV.UK's save and return): with sign-in, the shell's "Save and log out", resumed after signing in; with
+ * none, a page drawing <FlowSaved>, whose Continue resumes at the step the user was on. The focus shell's PageHeader
+ * reads its caption, title, Stepper and Back from it; after a move the new step's heading takes focus and the browser
+ * tab names the step.
+ */
+declare function useFlowSteps<A, S extends FlowStep<A>>(options: UseFlowStepsOptions<A, S>): FlowSteps<A, S>;
+
+interface FlowSavedProps {
+    /** The flow's storageKey, as its useFlowSteps has it. */
+    storageKey: string;
+    /** The flow's step addresses, as its useFlowSteps has them: Continue goes to the step the user was on. */
+    href: (step: number) => string;
+    /** The page's one heading. Default "Your progress has been saved". */
+    title?: string;
+    /** What the user should know about coming back. Default: the answers are kept in this browser. */
+    children?: ReactNode;
+    /** The app's router. Left out, the shell's (AppShell's navigate). */
+    navigate?: (href: string, options?: {
+        replace?: boolean;
+    }) => void;
+}
+/**
+ * Sprint 25.16 A30 (R28-58): where a flow's "Save and continue later" goes when the app has no sign-in to leave to —
+ * save and return: a page saying the progress has been saved, whose Continue resumes at the step the user was on. It
+ * has left the flow, so the focus shell draws no exit while it shows; its heading takes focus, as the pressed exit has
+ * gone. A status page, as "Page not found" is: one centred message under the page's one heading. With nothing saved
+ * (a bookmark, cleared storage) it says so, and Continue starts the flow. Continue goes back to the step when the user
+ * has just left it for this page (so Back from the step doesn't show it twice), else replaces this page with it; the
+ * step's heading takes focus either way.
+ */
+declare function FlowSaved({ storageKey, href, title, children, navigate }: FlowSavedProps): react_jsx_runtime.JSX.Element;
+
 interface DestructiveActionOptions {
     /** The action's key as the preference lists name it ("remove_range"); derived from `title` when omitted. */
     action?: string;
@@ -3290,8 +3526,9 @@ interface PageContainerProps {
     maxWidth?: MaxWidth;
     /**
      * Caps the content under the header without narrowing the page: the header and tab strip keep the page's width, the
-     * content column below is capped at this width and left-aligned. For a form tab inside a tabbed area (round 17,
-     * 54.1) — `contentWidth="narrow"`; a layout pattern that wraps PageContainer passes it through. Never a hand-rolled
+     * content column below is capped at this width and left-aligned. For a tab whose content is a form (round 17, 54.1)
+     * — `contentWidth="narrow"`; a layout pattern that wraps PageContainer passes it through. A tab with lists or tables
+     * beside its form keeps the full width: FormWrapper caps the fields itself (Sprint 25.16 A8). Never a hand-rolled
      * `max-w-` wrapper around the form.
      */
     contentWidth?: PageContainerWidth;
@@ -3317,6 +3554,15 @@ interface PageContainerProps {
  * `useContentWidth("narrow")` at the top of the page; the cap lifts when the page unmounts.
  */
 declare function useContentWidth(width: PageContainerWidth): void;
+/**
+ * Sprint 25.16 A4 (R28-7): a page's own actions in the header its area layout draws ("Invite user" on Users, "Save" on
+ * Roles), beside useContentWidth. Put them anywhere in the page: they render in the layout's PageHeader, as the page's
+ * own live elements (its state and handlers, never a stale copy), and go when the page does. The layout passes no
+ * actions per tab. Outside a PageContainer with a header they render nothing.
+ */
+declare function PageActions({ children }: {
+    children: ReactNode;
+}): react.ReactPortal | null;
 /**
  * The page's width constraint, and — when a PageHeader is among its direct
  * children — the page's composition: the header is placed inside the column
@@ -3332,6 +3578,17 @@ declare const PageContainer: react.ForwardRefExoticComponent<PageContainerProps
 interface SectionHeadingProps {
     /** Wraps onto more lines rather than being cut (an insight above a chart); a pane's title keeps one line. */
     title: string;
+    /**
+     * Makes the title editable, for a view whose name the user changes in place (a document, a board): called with each
+     * new title as the user types. The title shows as a field at the title's size, filling the title's line. The actions
+     * stay beside it while it keeps about 20 characters, and move under it when it can't, as they always do on a phone,
+     * so a phone never squeezes the name to a few letters (the owner's review of 1 October: run 71's "Sys").
+     */
+    onTitleChange?: (title: string) => void;
+    /** The editable title's name for a screen reader, what it is the title of ("Document title"). Default "Title". */
+    titleLabel?: string;
+    /** The heading's id, for a section named by its heading (`aria-labelledby`). */
+    titleId?: string;
     description?: string;
     /** The section's buttons. Below sm they sit under the title, like PageHeader's actions. */
     actions?: ReactNode;
@@ -3345,7 +3602,8 @@ interface SectionHeadingProps {
      * "section" (default): a heading within a page, spaced below by --ds-heading-gap. "pane": the title block at the
      * top of a SplitView pane on a fill page (an inbox, a library), where there is no PageHeader — a 16 px inset that
      * matches the list rows under it, a rule at the bottom and no margin below (Sprint 25.4 C-9, folded in from
-     * PaneHeader on the owner's review).
+     * PaneHeader on the owner's review). At the top of the detail, an item's own header: there it insets at the page's
+     * gutter, as the item's path above it does.
      */
     variant?: "section" | "pane";
     className?: string;
@@ -3366,6 +3624,31 @@ interface ActionPanelGroupProps {
 }
 declare const ActionPanelGroup: react.ForwardRefExoticComponent<ActionPanelGroupProps & react.RefAttributes<HTMLDivElement>>;
 
+interface DangerZoneProps {
+    /** The section's heading. Default "Danger zone". */
+    title?: string;
+    /** A line under the heading ("Irreversible actions for this project"). */
+    description?: string;
+    /**
+     * One ActionPanel per action: what the action does and what it costs, and its destructive Button that opens the
+     * confirmation (destructive_actions#3).
+     */
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * A danger zone (Sprint 25.17 A39, R28-75; destructive_actions#7): the page's last section, holding its irreversible
+ * actions. Its heading, then a frame drawn as a Card is, in the error colour, with one row per action, divided:
+ *
+ *   <DangerZone>
+ *     <ActionPanel title="Delete project" description="Removes the project and its tasks. This can't be undone."
+ *       action={<Button variant="destructive" onClick={confirm}>Delete project</Button>} />
+ *   </DangerZone>
+ *
+ * The rows sit at a card's inset, so they line up with the cards above it.
+ */
+declare function DangerZone({ title, description, children, className }: DangerZoneProps): react_jsx_runtime.JSX.Element;
+
 interface TextOverflowProps {
     /** Max visible lines before truncation. 1 = single-line ellipsis, >1 = line-clamp-N. */
     lines?: number;
@@ -3410,4 +3693,4 @@ interface UseTextOverflowResult {
  */
 declare function useTextOverflow(options?: UseTextOverflowOptions): UseTextOverflowResult;
 
-export { Accordion, ActionPanel, ActionPanelGroup, AddAnother, type AddAnotherProps, Alert, type AlertPlacement, AppShell, type AppShellContextValue, type AppShellFocus, 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, Pager, Pagination, PinInput, Popover, Progress, type PromiseToastMessages, RadioGroup, Rating, 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, type SortDir, Spinner, StackedList, type StackedListVariant, StatsCard, StatusDot, type StatusDotVariant, Stepper, TIME_ZOOMS, type Tab, Table, type TableDensity, type TableProps, type TableRow, 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, timeExtent, useAppShell, useContentWidth, useDestructiveAction, useFittedLabels, useFormContext, useGridKeyboard, useSidebar, useTextMeasure, useTextOverflow, useTimeScale, useTimeViewport, useTimeViewportLayout, useToast, useToastOptional, useUnsavedChanges };
+export { Accordion, ActionPanel, ActionPanelGroup, AddAnother, type AddAnotherProps, Alert, type AlertPlacement, AppShell, type AppShellContextValue, type AppShellFocus, 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, 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, DangerZone, type DangerZoneProps, 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, type FlowNavigate, type FlowProgress, FlowSaved, type FlowSavedProps, type FlowStep, type FlowSteps, 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, type MentionInputProps, MentionSuggestion, MobileHeaderMenu, type MobileHeaderMenuItemData, type MobileHeaderMenuType, NavItem, type NavItemProps, type NavItemType, NavMenu, type NavMenuItem, Navbar, type NavbarSize, type NavbarType, type NavbarVariant, NotificationCenter, NumberInput, PageActions, PageContainer, type PageContainerWidth, PageHeader, type PageHeaderBehavior, type PageHeaderIntensity, type PageHeaderProps, type PageHeaderVariant, Pager, Pagination, PinInput, Popover, Progress, type PromiseToastMessages, RadioGroup, Rating, RelativeTime, type RelativeTimeProps, 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, type SortDir, Spinner, StackedList, type StackedListVariant, StatsCard, StatusDot, type StatusDotVariant, Stepper, TIME_ZOOMS, type Tab, Table, type TableDensity, type TableProps, type TableRow, 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, type TimeValue, TimeViewport, type TimeViewportHandle, type TimeViewportLayout, type TimeViewportProps, type TimeViewportState, type TimeZoom, Timeline, TimezoneSelect, type TimezoneSelectProps, Toast, type ToastAction, type ToastApi, type ToastOptions, type ToastPosition, ToastProvider, type ToastVariant, Toggle, Tooltip, Tour, TransferList, TreeView, type Trend, type UseFlowStepsOptions, type UseTextOverflowOptions, type UseTextOverflowResult, browserTimeZone, canonicalTimeZone, dateOfDay, dayOf, endDayOf, fitLabel, fitLabels, formatDateRange, formatFullTime, formatRelativeTime, readFlowProgress, timeExtent, timeZoneOffset, useAppShell, useContentWidth, useDestructiveAction, useFittedLabels, useFlowSteps, useFormContext, useGridKeyboard, useRelativeTimeFormat, useSidebar, useTextMeasure, useTextOverflow, useTimeScale, useTimeViewport, useTimeViewportLayout, useToast, useToastOptional, useUnsavedChanges };