gridsmith-ui 0.15.0 → 0.17.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ReactNode, InputHTMLAttributes, LabelHTMLAttributes, TextareaHTMLAttributes, Ref, CSSProperties, ReactElement, HTMLAttributes, AnchorHTMLAttributes, ComponentType } from 'react';
+import { ButtonHTMLAttributes, ReactNode, InputHTMLAttributes, LabelHTMLAttributes, TextareaHTMLAttributes, Ref, CSSProperties, ReactElement, HTMLAttributes, RefObject, KeyboardEvent, AnchorHTMLAttributes, ComponentType } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { IconName } from './icons.js';
 import { C as ColumnKind, B as BreakpointKey } from './table-utils-GounRE6s.js';
@@ -247,18 +247,38 @@ declare function DateRangePicker({ value, onChange, placeholder, disabled, error
 
 interface FileUploadProps {
     onFiles: (files: File[]) => 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.
+     */
     accept?: string;
+    /** false: the zone takes one file, a new one replaces it, and its copy says "a file". */
     multiple?: boolean;
+    /** The largest file, in bytes. The zone says it ("up to 5 MB"), and a bigger file gets a message instead of reaching onFiles. */
     maxSize?: number;
     className?: string;
     error?: boolean;
+    /**
+     * The zone's label, shown above it: what the file is ("Project list"), never how to upload it — the zone says that.
+     * Inside a Field, leave it out: the zone takes the Field's label (Sprint 25.7, C6) and shows none of its own.
+     */
     label?: string;
+    /** 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 }: FileUploadProps): react_jsx_runtime.JSX.Element;
+declare function FileUpload({ onFiles, accept, multiple, maxSize, className, error, label, id }: FileUploadProps): react_jsx_runtime.JSX.Element;
 
 interface SliderRangeProps {
-    /** Accessible name for the slider thumb(s); range sliders announce "<label> minimum" / "<label> maximum". Default "Value". */
+    /**
+     * The slider's label, shown above it and used as its name (Sprint 25.7, C5: it used to be an invisible aria-label with
+     * a "Value" default). Inside a Field, leave it out: the slider takes the Field's label (aria-labelledby) and shows no
+     * label of its own. Range sliders announce "<label> minimum" / "<label> maximum".
+     */
     label?: string;
+    /** The slider's name when its visible label is drawn elsewhere (a compact settings row): no label is shown. */
+    "aria-label"?: string;
+    /** Extra description ids; inside a Field its hint and error are linked already. */
+    "aria-describedby"?: string;
     value: number | [number, number];
     onChange: (value: number | [number, number]) => void;
     min?: number;
@@ -275,7 +295,7 @@ interface SliderRangeProps {
      */
     trackStyle?: CSSProperties;
 }
-declare function SliderRange({ value, onChange, min, max, step, disabled, showValue, className, ref, error, label, trackStyle }: SliderRangeProps): react_jsx_runtime.JSX.Element;
+declare function SliderRange({ value, onChange, min, max, step, disabled, showValue, className, ref, error, label, "aria-label": ariaLabel, "aria-describedby": describedByProp, trackStyle }: SliderRangeProps): react_jsx_runtime.JSX.Element;
 
 interface TimePickerProps {
     value: string;
@@ -1224,6 +1244,465 @@ interface StackedListProps {
 }
 declare const StackedList: react.ForwardRefExoticComponent<StackedListProps & react.RefAttributes<HTMLUListElement>>;
 
+/**
+ * Dates on a time axis (Sprint 25.7, Part D). A calendar day is a whole-number day index: days since 1970-01-01,
+ * counted on UTC day boundaries, so every day is the same width and a clock change never stretches or shrinks one.
+ * A "YYYY-MM-DD" string is a calendar day in the user's zone and is never parsed as UTC (new Date("2026-03-03") is
+ * 2 March, 19:00 in New York). Tick labels come from Intl in the locale, longest form first.
+ */
+/** A Date, or a string: "YYYY-MM-DD" is a calendar day; any other string is a date-time. */
+type DateInput = Date | string;
+type TimeZoom = "day" | "week" | "month" | "quarter";
+/** Narrow to wide. */
+declare const TIME_ZOOMS: readonly TimeZoom[];
+/**
+ * The day index of a date: "2026-03-03" → that calendar day's index; a Date or a date-time string → its local calendar
+ * day plus the fraction of the day its local clock shows. NaN for anything that is not a date.
+ */
+declare function dayOf(value: DateInput): number;
+/** Local midnight of that calendar day; a fraction adds that much of the day on the local clock. */
+declare function dateOfDay(day: number): Date;
+/**
+ * Where a range that ends at `value` stops. A whole-day end is inclusive: "2026-03-14" (or a Date at local midnight,
+ * as the date pickers give) → the start of 15 March. A date-time end is half-open: it stops at that moment.
+ */
+declare function endDayOf(value: DateInput): number;
+interface TimeTick {
+    /** Stable: "2026-09" for September 2026, "2026-09-07" for a day or the week starting on it, "2026-Q3", "2026". */
+    key: string;
+    /** The day index it starts on (the scale's start, for a period the scale cuts). */
+    day: number;
+    /** Px from the scale's start. */
+    x: number;
+    /** Px it spans: its label's room. */
+    width: number;
+    /** The weekday of the day it starts on: 0 is Sunday, as Date's getDay. */
+    weekday: number;
+    /** Longest first, from Intl in the locale: ["September", "Sept", "S"], ["Mon 7", "7"], ["2026", "26"]. */
+    labels: string[];
+}
+/** A calendar day, as shadeDays sees it: its index, its weekday (0 is Sunday) and its "YYYY-MM-DD" key. */
+interface CalendarDay {
+    day: number;
+    weekday: number;
+    key: string;
+}
+interface TimeScale {
+    zoom: TimeZoom;
+    /** The whole days shown, end exclusive: the range padded to whole minor periods. */
+    startDay: number;
+    endDay: number;
+    pxPerDay: number;
+    /** (endDay − startDay) × pxPerDay. */
+    width: number;
+    /** A date or a day index → px from the scale's start. */
+    x(value: DateInput | number): number;
+    /**
+     * Where a range sits: px from the scale's start and its width. The end is inclusive for a whole day, as endDayOf
+     * (so a day's bar is never a day short); a day index is where the range stops. Default: the start's own day.
+     */
+    span(start: DateInput | number, end?: DateInput | number): {
+        x: number;
+        width: number;
+    };
+    /** Px → the fractional day index there. */
+    dayAt(x: number): number;
+    /** The top row: months at day and week zoom, years at month and quarter zoom. */
+    major: TimeTick[];
+    /** The bottom row: days, weeks, months or quarters. */
+    minor: TimeTick[];
+    /** Today's day index when the scale shows it, else null. */
+    today: number | null;
+    /** The moment `today` names, as a fractional day index (its time of day), when the scale shows it: an hourly view's "now". */
+    now: number | null;
+    weekStartsOn: 0 | 1;
+    locale?: string;
+}
+interface TimeScaleOptions {
+    /** The extent to show (the data's first start to its last end, or timeExtent's); the scale pads it to whole minor periods. */
+    start: DateInput | number;
+    /** Inclusive for a whole day, as endDayOf. A day index is where the range stops. */
+    end: DateInput | number;
+    zoom: TimeZoom;
+    /** Default now; demos and tests pass a fixed date (a date-time gives an hourly view its "now"). */
+    today?: DateInput;
+    /** Default 1 (Monday), as Calendar's. */
+    weekStartsOn?: 0 | 1;
+    /** Default the browser's. */
+    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>>;
+    /** Whole minor periods of room before the start and after the end (default 0), so nothing sits against an edge. */
+    pad?: number;
+}
+/**
+ * Maps dates to pixels and back in calendar days, and makes the major and minor ticks for the zoom level. The scale
+ * is the same object while its inputs mean the same days, so a Date made on every render does not rebuild it.
+ */
+declare function useTimeScale({ start, end, zoom, today, weekStartsOn, locale, pxPerDay, pad }: TimeScaleOptions): TimeScale;
+/**
+ * The earliest start and the latest end of some ranges, as day indices for useTimeScale: the end is where the last
+ * range stops (inclusive for a whole day, as endDayOf), and a range with no end ends where it starts (a milestone).
+ * NaN for no dated range, which the scale shows as today.
+ */
+declare function timeExtent(ranges: Iterable<{
+    start: DateInput;
+    end?: DateInput;
+}>): {
+    start: number;
+    end: number;
+};
+interface DateRangeWords {
+    locale?: string;
+    /** Joins the two ends in place of Intl's separator. Default " to " in English, and Intl's own separator elsewhere. */
+    to?: string;
+    /** Intl options for the days. Default { day: "numeric", month: "long" }; the year is added when the ends' years differ. */
+    day?: Intl.DateTimeFormatOptions;
+    /** Intl options for the times of a date-time range. Default { hour: "2-digit", minute: "2-digit" }. */
+    time?: Intl.DateTimeFormatOptions;
+}
+/**
+ * A range in words, in the locale, for accessible names: "3 to 14 March", "28 September to 3 October", "16 September"
+ * for one day. The end is inclusive for a whole day, as endDayOf (a day index is where the range stops). A date-time
+ * range is named by its times, and the end's day only when it differs: "Friday 23 October, 06:00 to 14:00". Intl
+ * joins each day and time in the locale's own way, and outside English the two ends too ("10/31(土曜日)～11/01(日曜日)");
+ * the year shows when the two ends are in different years.
+ */
+declare function formatDateRange(start: DateInput | number, end?: DateInput | number, { locale, to, day, time }?: DateRangeWords): string;
+
+/**
+ * What a TimeViewport gives the things drawn inside it (Sprint 25.7, Part D). The scroll position lives in a store of
+ * its own, so rows that only need the scale do not re-render while the view scrolls; useTimeViewport() does.
+ */
+interface TimeViewportApi {
+    /** Scroll so the date (or day index) sits a little clear of the pinned column ("start"), or in the middle of the view. */
+    scrollToDate(value: DateInput | number, align?: "start" | "center"): void;
+    /** One visible width back or on (the previous and next period), ending on a minor tick. */
+    page(direction: -1 | 1): void;
+    /**
+     * Scroll the least to show [x0, x1] (px on the scale) clear of the pinned column. A range wider than the view is
+     * left alone while part of it shows, else brought in at its start.
+     */
+    ensureVisible(x0: number, x1: number): void;
+    /** Scroll the least to show an element inside the rows clear of the pinned column and the sticky scale (a focused bar). */
+    reveal(el: Element): void;
+}
+interface TimeViewportLayout extends TimeViewportApi {
+    /** The scale the viewport draws: the one it was given, continued at its end to fill the viewport's width. */
+    scale: TimeScale;
+    /** The pinned label column's width, px (narrower on a phone). */
+    labelWidth: number;
+    /** Whether the Today marker (the line and its label) is drawn. */
+    showToday: boolean;
+    /** Px on the scale where the Today line and its label sit (todayAt), or null when they are not drawn. */
+    todayX: number | null;
+    /** The phone layout: the viewport is narrower than 640 px and its label column has narrowed (data-compact). */
+    compact: boolean;
+}
+interface TimeViewportScroll {
+    /** Px of the scale scrolled out of view behind the pinned column. */
+    scrollLeft: number;
+    /** Px of the scale in view, clear of the pinned column. */
+    visibleWidth: number;
+}
+type TimeViewportState = TimeViewportLayout & TimeViewportScroll;
+/**
+ * The viewport's scale (continued to fill it), its label width, compact flag, Today position and scrolling API, for
+ * rows and the items in them. Unlike useTimeViewport(), it does not re-render as the view scrolls.
+ */
+declare function useTimeViewportLayout(): TimeViewportLayout;
+/**
+ * For anything drawn inside a TimeViewport (a Gantt's arrows, a marker, a header): the scale, what is in view now and
+ * the viewport's scrolling. It re-renders as the view scrolls.
+ */
+declare function useTimeViewport(): TimeViewportState;
+
+interface TimeViewportProps {
+    /** Controlled: what useTimeScale returns. The viewport shows it and asks for another zoom through onZoomChange. */
+    scale: TimeScale;
+    /** The toolbar's zoom buttons, + and − (and =), and Ctrl or ⌘ with the wheel. Without it there is no zoom. */
+    onZoomChange?: (zoom: TimeZoom) => void;
+    /** The levels offered, default TIME_ZOOMS. */
+    zooms?: readonly TimeZoom[];
+    /** The pinned label column, px (default 240). Narrower on a phone, never below a readable width. */
+    labelWidth?: number;
+    /** The corner cell above the labels ("Task"). */
+    labelHeader?: ReactNode;
+    /** The scale above the rows, default <TimeScaleHeader />; null for none. */
+    header?: ReactNode;
+    /** Controls after the built-in zoom out, zoom in and Today; they can call useTimeViewport(). False hides the bar. */
+    toolbar?: ReactNode | false;
+    /** Scrolled into the middle of the view on mount. Default today when the scale shows it, else the start. */
+    initialDate?: DateInput;
+    /** The Today line across the rows (default true). */
+    showToday?: boolean;
+    /**
+     * Where the Today line and its label sit: the middle of today (default, for day-long items), or "now", the time of
+     * day `today` gives the scale, for an hourly view (a rota's shifts).
+     */
+    todayAt?: "day" | "now";
+    /**
+     * Days to shade under the rows (weekends, holidays), by their weekday (0 is Sunday) or "YYYY-MM-DD" key: no date
+     * maths for the caller. Drawn where a day is at least 4 px wide; narrower, the bands would only be stripes.
+     */
+    shadeDays?: (day: CalendarDay) => boolean;
+    /**
+     * The scroll region is a Tab stop (default true), so the view can be scrolled by keyboard. Pass false when the rows
+     * hold a keyboard of their own with one Tab stop (a tree, a grid), which scrolls the view as focus moves.
+     */
+    tabStop?: boolean;
+    /** <TimeRow> elements, or one element holding them (a role="grid" or role="tree" with the rows' keyboard). */
+    children?: ReactNode;
+    /** Names the scroll region. */
+    "aria-label": string;
+    className?: string;
+}
+type TimeViewportHandle = TimeViewportApi;
+interface TimeRowProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** The row's cell in the pinned column: a name, an avatar and a name, a group's toggle. */
+    label: ReactNode;
+    /** Drawn on the row's track, which is as wide as the scale: place them with scale.x() from useTimeViewport(). */
+    children?: ReactNode;
+    /** Px, default 40. */
+    height?: number;
+    /** Classes for the pinned label cell (a selected row's tint). Its background stays opaque under them. */
+    labelClassName?: string;
+    "data-row-key"?: string;
+}
+interface TimeBarProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** Where it starts: a Date, "YYYY-MM-DD" or a date-time string, or a day index. */
+    start: DateInput | number;
+    /** Where it ends: inclusive for a whole day, as endDayOf; a day index is where it stops. Default its start's day. */
+    end?: DateInput | number;
+    /** Px it is never drawn narrower than (default 0). */
+    minWidth?: number;
+    /**
+     * Its label's forms, longest first (["Early", "E"]). The bar shows the longest that fits the part of itself in view
+     * inside its own padding, which narrows on a short bar, and moves to a shorter form (never an ellipsis) as it slides
+     * under the pinned column or past the view's end; none when even the shortest does not fit. The forms are for sight;
+     * assistive technology reads the longest, or the bar's own name when it has one (aria-label, aria-labelledby).
+     */
+    labels?: readonly string[];
+    /**
+     * Custom content in place of `labels` (an icon and a title): kept in view beside the pinned column the same way,
+     * never wider than the part of the bar in view (put text in a `truncate` span, which ends it with an ellipsis).
+     */
+    children?: ReactNode;
+    "data-grid-key"?: string;
+}
+/**
+ * The one scrolling area for anything on a time axis (Sprint 25.7, Part D): a Gantt, a roadmap, a resource scheduler.
+ * One scroll container, so the scale sticks at the top and the label column at the start while the rows scroll under
+ * both; it fills a frame of definite height (page_composition#17: no nested scroll containers). It draws the scale it
+ * is given, continued to fill its width, and asks for another zoom: its toolbar, + and − (and =), and Ctrl or ⌘ with
+ * the wheel step between the levels, keeping the date at the pointer or at the centre in place. It pans by scrolling,
+ * by dragging on the scale and with Shift+Left and Right (one minor period). The scroll region is a named Tab stop,
+ * so the view can be scrolled by keyboard with nothing focusable inside it.
+ */
+declare const TimeViewport: react.ForwardRefExoticComponent<TimeViewportProps & react.RefAttributes<TimeViewportApi>>;
+/**
+ * A row of a TimeViewport: its label pinned at the start, and a track as wide as the scale where its children lay
+ * themselves out with scale.x(). Other attributes (role, aria-*, handlers) go on the row.
+ */
+declare function TimeRow({ label, children, height, labelClassName, className, style, ...props }: TimeRowProps): react_jsx_runtime.JSX.Element;
+/**
+ * An item on a TimeRow's track (a task, a shift): placed by the viewport's scale from its start to its end (through
+ * scale.span, so a whole-day end is never a day short), with its content clipped and the focus ring. Its label is kept
+ * in view beside the pinned column while its start is scrolled away, and fitted to the part of the bar in view: the
+ * longest of `labels` that fits, or `children` shortened with an ellipsis. Other attributes (role, aria-*,
+ * data-grid-key, tabIndex, handlers, className, style) go on the bar; the caller gives the fill and the insets.
+ */
+declare function TimeBar({ start, end, minWidth, labels, children, className, style, ...props }: TimeBarProps): react_jsx_runtime.JSX.Element;
+
+interface TimeScaleHeaderProps {
+    /** The Today marker's label. Default "Today". */
+    todayLabel?: string;
+    className?: string;
+}
+/**
+ * The two-row scale of a TimeViewport (Sprint 25.7, Part D): months over days or weeks, years over months or
+ * quarters. Each row's labels take the longest form that fits and thin out rather than overlap; a month that starts
+ * before the view keeps its label in view, as a sticky heading does. The Today marker's label sits in the lower row
+ * on the Today line, never inside the thin line itself, and is clamped inside the visible area so it never clips
+ * (round 23's Today badge). The scale is drawn for sight only: the dates it shows are in the items' accessible names.
+ */
+declare function TimeScaleHeader({ todayLabel, className }: TimeScaleHeaderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Labels along a scale that never overlap (Sprint 25.7, Part D; data-visualisation#7). Each label gets the longest form
+ * that fits its box ("September" → "Sept" → "S"), one form along the row; when even the shortest does not fit, the row
+ * thins to every second, third … label, and each label left has the room of the boxes up to the next. No label is
+ * reachable only by hover: a date a label drops stays in the items' own accessible names. The maths takes the measure
+ * function, so it runs in jsdom; useFittedLabels measures in the element's own font.
+ */
+interface LabelBox {
+    key: string;
+    /** Px from the row's start. */
+    x: number;
+    width: number;
+    /** Longest first. A TimeTick is a LabelBox. */
+    labels: readonly string[];
+}
+interface FittedLabel {
+    key: string;
+    /** Where the text starts, px from the row's start. */
+    x: number;
+    /** The text's measured width (0 when thinned out). */
+    width: number;
+    /** Null: thinned out, or no form fits. */
+    text: string | null;
+}
+interface FitLabelsOptions {
+    /** The least space between two labels; each keeps half of it from the edges of its room. Default 8. */
+    gap?: number;
+    /** In its own box: "start" (default) or "center". */
+    align?: "start" | "center";
+    /**
+     * The part of the row in view. A label is only ever shown whole in it: a start-aligned label slides along its room
+     * to stay in view, as a sticky heading does (the month the view starts halfway through); a centred one centres on
+     * the part of its box in view. Near an edge a label takes a shorter form that fits, or none.
+     */
+    visible?: {
+        start: number;
+        end: number;
+    };
+}
+declare function fitLabels(boxes: readonly LabelBox[], measure: (text: string) => number, { gap, align, visible }?: FitLabelsOptions): FittedLabel[];
+/**
+ * The longest of `labels` that fits one box `width` px wide with `gap` shared either side of it, or null: a label
+ * inside a bar or a block, where fitLabels' row-wide form and thinning do not apply.
+ */
+declare function fitLabel(labels: readonly string[], width: number, measure: (text: string) => number, { gap }?: {
+    gap?: number;
+}): string | null;
+/**
+ * Measures text in `ref`'s computed font. Read after the element mounts (before paint), again when it resizes and when
+ * web fonts finish loading. Give it an element whose size follows its text (a span holding a character, out of sight),
+ * not a box of fixed size: its resize is how a change of text size (the theme's base size, a class up the tree) is seen.
+ */
+declare function useTextMeasure(ref: RefObject<HTMLElement | null>): (text: string) => number;
+/** fitLabels in the computed font of `ref`, the row the labels are drawn in. */
+declare function useFittedLabels(boxes: readonly LabelBox[], ref: RefObject<HTMLElement | null>, options?: FitLabelsOptions): FittedLabel[];
+
+interface GridKeyboardOptions<K> {
+    /** Holds the items, which carry `data-grid-key={keyOf(item)}`. */
+    container: RefObject<HTMLElement | null>;
+    /** The item that is the Tab stop. Keep it in step with focus (setActive from the item's onFocus). */
+    active: K;
+    setActive: (item: K) => void;
+    keyOf: (item: K) => string;
+    /** Where a key moves focus from `from` (arrows, Home, End: the caller's geometry), or null for a key it leaves alone. */
+    move: (from: K, e: KeyboardEvent) => K | null;
+    /** Enter and Space on an item. */
+    onActivate?: (item: K, e: KeyboardEvent) => void;
+    /**
+     * Printable keys go to the next item whose label starts with what was typed in the last 500 ms (the same letter
+     * again cycles). Never the zoom keys (+, = and −), never with Ctrl, ⌘ or Alt.
+     */
+    typeahead?: {
+        items: readonly K[];
+        labelOf: (item: K) => string;
+    };
+    /** Runs after focus moves to an item, in place of the browser's own scrolling (a time view keeps the item clear of its pinned column). */
+    scrollIntoView?: (key: string, el: HTMLElement) => void;
+    /**
+     * Keys held with Ctrl, ⌘ or Alt go to `move` too: an APG grid's Ctrl+Home and Ctrl+End. Typeahead and activation
+     * still ignore them. Off by default, so the browser keeps its own (Alt+Left is Back).
+     */
+    modifierKeys?: boolean;
+}
+interface GridKeyboard<K> {
+    /** On the container. */
+    onKeyDown: (e: KeyboardEvent) => void;
+    tabIndexOf: (item: K) => 0 | -1;
+    /** Focus the active item (after the next render when it is not in the DOM yet). */
+    focusActive: () => void;
+    /** Focus an item, as a key would (after the next render when it is not in the DOM yet); keep `active` in step. */
+    focus: (item: K) => void;
+}
+/**
+ * One Tab stop over a grid or rows of items (APG grid and tree patterns): the caller says where each key moves
+ * (`move`), and the hook keeps the roving tabindex and puts focus on the new item — after the next render when the
+ * item is not in the DOM yet (a date grid moving into the next month). Enter and Space activate, typeahead jumps by
+ * label, and `scrollIntoView` places the item. It works by key, not DOM position, so a virtualised list can use it.
+ * Keys typed in a field inside the container are left alone. Built for the date pickers, extended in Part D for
+ * time-axis rows (it is Sprint 2X.3's `useGridNavigation`).
+ */
+declare function useGridKeyboard<K>({ container, active, setActive, keyOf, move, onActivate, typeahead, scrollIntoView, modifierKeys }: GridKeyboardOptions<K>): GridKeyboard<K>;
+
+type GanttTone = "neutral" | "info" | "success" | "warning" | "error" | "accent";
+interface GanttItem {
+    id: string;
+    title: string;
+    /** A Date, or "YYYY-MM-DD" for a calendar day in the user's zone. */
+    start: DateInput;
+    /** Inclusive for a whole day ("3 to 14 March" covers the 14th); required unless `milestone`. */
+    end?: DateInput;
+    /** A GanttGroup's id. */
+    group?: string;
+    /** A key of `statuses`. */
+    status?: string;
+    /** A diamond on its start. */
+    milestone?: boolean;
+    /** The ids it waits for: finish-to-start. */
+    dependsOn?: string[];
+}
+interface GanttGroup {
+    id: string;
+    title: string;
+    defaultCollapsed?: boolean;
+}
+interface GanttStatus {
+    label: string;
+    tone: GanttTone;
+}
+interface GanttProps {
+    items: GanttItem[];
+    /** Rows grouped under collapsible headers, in this order; items with no group come last. A group with no items is left out. */
+    groups?: GanttGroup[];
+    /** Controlled selection; leave it out for the Gantt to keep its own. */
+    selectedId?: string | null;
+    /** Enter, Space or a click: the item. Escape, or a click on the selected item: null. */
+    onSelect?: (item: GanttItem | null) => void;
+    /** The bars' colours and the legend; an item with no known status is neutral. */
+    statuses?: Record<string, GanttStatus>;
+    zoom?: TimeZoom;
+    /** Default "week". */
+    defaultZoom?: TimeZoom;
+    onZoomChange?: (zoom: TimeZoom) => void;
+    /** Default now; demos and tests pass a fixed date. */
+    today?: DateInput;
+    /** Default 1 (Monday), as Calendar's. */
+    weekStartsOn?: 0 | 1;
+    /** Default the browser's: the scale's labels and the items' dates. */
+    locale?: string;
+    /**
+     * Beside the title in the name column (assignees' avatars): shown, not announced, and left out when the column is
+     * too narrow for it and the title (a phone). Nothing in it may take focus.
+     */
+    renderLabel?: (item: GanttItem) => ReactNode;
+    /** The name column's heading. Default "Task". */
+    labelHeader?: string;
+    /** Controls after the built-in zoom, period and Today buttons, before the legend; false hides the bar. */
+    toolbar?: ReactNode | false;
+    "aria-label": string;
+    className?: string;
+}
+/**
+ * A plan on a time axis (Sprint 25.7, Part D2): tasks as bars on a date scale, grouped under collapsible headers, with
+ * milestones and finish-to-start dependencies. Assembled from the time blocks: the scale and date model
+ * (useTimeScale), the viewport with its pinned name column, sticky scale, zoom, pan and Today (TimeViewport), labels
+ * that fit (TimeScaleHeader) and the one-Tab-stop keyboard (useGridKeyboard). It does no date maths and no scrolling
+ * of its own.
+ *
+ * Keyboard (APG tree view): the chart is one Tab stop. Up and Down move between rows; Right opens a group, or moves
+ * into it; Left closes it, or moves to it; Home and End go to the first and last row; typing jumps by title. Enter or
+ * Space selects, and opens or closes a group; Escape clears the selection. + and − zoom and Shift+Left and Right pan,
+ * from the viewport. Each item's accessible name carries its title, dates, status and dependencies; the arrows and
+ * the scale are for sight only.
+ */
+declare function Gantt({ items, groups, selectedId, onSelect, statuses, zoom: zoomProp, defaultZoom, onZoomChange, today, weekStartsOn, locale, renderLabel, labelHeader, toolbar, "aria-label": ariaLabel, className, }: GanttProps): react_jsx_runtime.JSX.Element;
+
 type LinkUnderline = "hover" | "always" | "none";
 type LinkTone = "accent" | "muted" | "inherit";
 interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
@@ -1652,6 +2131,11 @@ type PageHeaderIntensity = "subtle" | "bold";
 interface PageHeaderProps {
     title: string;
     description?: string;
+    /**
+     * A short line above the title: the section the page belongs to, or its place in a flow ("Step 2 of 6") — GOV.UK's
+     * heading caption. Drawn in every variant (Sprint 25.7, C1).
+     */
+    caption?: ReactNode;
     badge?: ReactNode;
     breadcrumbs?: BreadcrumbItem[];
     onBack?: () => void;
@@ -1676,7 +2160,10 @@ interface PageHeaderProps {
     pinned?: boolean;
     /** Constrain inner content to this max-width while the header background spans full width. Used by colourful and snapping variants to align header content with PageContainer body. Defaults to --ds-bp-xl. */
     contentMaxWidth?: string;
-    /** Tabs-integrated: render a Tabs component at the header bottom edge */
+    /**
+     * A row at the header's bottom edge: Tabs, or a Stepper for a flow's steps. Drawn in every variant (Sprint 25.7, C1:
+     * the default, minimal and colourful headers used to drop it). A Stepper here lines its first step up with the title.
+     */
     tabs?: ReactNode;
     /** Visual style of inline breadcrumbs */
     breadcrumbStyle?: "default" | "pill";
@@ -2307,8 +2794,36 @@ interface AppShellContextValue {
     /** The shell renders an app footer under the page. Its children sit in a wrapper whose height is not definite, so a
      *  `fill` SplitView reads `--ds-main-height` (published on the shell element) instead of `h-full`. */
     hasFooter: boolean;
+    /** The flow this shell is in focus mode for (Sprint 25.7, C1), or null. The Navbar and PageHeader read it. */
+    focus: AppShellFocus | null;
+    /** A page inside the shell has unsaved changes (useUnsavedChanges): focus mode's Exit asks before it leaves. */
+    hasUnsavedChanges: boolean;
+    /** Set by useUnsavedChanges; not for pages to call. Returns the release. */
+    addUnsavedChanges: () => () => void;
+}
+/**
+ * Focus mode (Sprint 25.7, C1): a task flow the user completes before or outside the app — setup, onboarding,
+ * checkout, an import — renders in the same shell with the navigation taken away. The header keeps the logo and the
+ * assistant, and its one way out is the exit control.
+ */
+interface AppShellFocus {
+    /**
+     * `before-app`: a flow before the app (setup, onboarding). The exit control, "Save and log out", takes the user
+     * menu's place. `in-app`: a flow inside the app (checkout, an import). "Exit" goes back to where the user came from,
+     * asks first while the page has unsaved changes, and the user menu stays.
+     */
+    kind: "before-app" | "in-app";
+    /** The exit control's label. Default "Save and log out" before the app, "Exit" inside it. */
+    exitLabel?: string;
+    /** What the exit control does: save and log out, or return to where the user came from. */
+    onExit?: () => void;
 }
 declare function useAppShell(): AppShellContextValue | null;
+/**
+ * Tells the shell this page has unsaved changes, so focus mode's Exit asks before it leaves (Sprint 25.7, C1). Pass the
+ * same `dirty` a Drawer takes; outside a shell it does nothing.
+ */
+declare function useUnsavedChanges(dirty: boolean): void;
 type AppShellLayout = "sidebar" | "stacked" | "sidebar-header" | "multi-column";
 interface AppShellProps {
     layout?: AppShellLayout;
@@ -2351,6 +2866,13 @@ interface AppShellProps {
     currentPath?: string;
     /** The home page's path. Default "/". */
     homePath?: string;
+    /**
+     * 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
+     * docked panel in the aside slot), the skip link, the theme, the preferences and the page spacing stay. The
+     * generated layout passes it; a page never does.
+     */
+    focus?: AppShellFocus;
 }
 declare const AppShell: react.ForwardRefExoticComponent<AppShellProps & react.RefAttributes<HTMLDivElement>>;
 
@@ -2591,4 +3113,4 @@ interface UseTextOverflowResult {
  */
 declare function useTextOverflow(options?: UseTextOverflowOptions): UseTextOverflowResult;
 
-export { Accordion, ActionPanel, ActionPanelGroup, Alert, type AlertPlacement, AppShell, type AppShellContextValue, 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, Card, CardContent, CardDescription, CardFooter, 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, DatePicker, type DateRange, DateRangePicker, type DateRangePickerProps, type DateRangePreset, 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, FormWrapper, HoverCard, InlineFieldError, Input, Kbd, Label, 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, type Tab, Table, type TableDensity, type TableProps, TableToolbar, type TableToolbarActiveFilter, type TableToolbarFilterOption, Tabs, Tag, TagInput, type TagPaletteColor, type TagVariant, TextOverflow, type TextOverflowProps, Textarea, TimePicker, Timeline, Toast, type ToastAction, type ToastApi, type ToastOptions, type ToastPosition, ToastProvider, type ToastVariant, Toggle, Tooltip, Tour, TransferList, TreeView, type Trend, type UseTextOverflowOptions, type UseTextOverflowResult, preferenceActionKey, useAppShell, useContentWidth, useDestructiveAction, useFormContext, usePagination, usePreferences, useSidebar, useTextOverflow, useToast, useToastOptional };
+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, 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 };