gridsmith-ui 0.17.1 → 0.17.3

package/dist/index.d.ts

@@ -294,8 +294,13 @@ interface SliderRangeProps {
      * accent fill is hidden so the custom track stays fully visible.
      */
     trackStyle?: CSSProperties;
+    /**
+     * The value in words, for a slider whose number alone means nothing ("Weekly" for 2): each thumb's aria-valuetext and
+     * the value shown beside the label (Sprint 25.9, A7; APG slider pattern). Leave it out and the number is shown and read.
+     */
+    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 }: 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, formatValue }: SliderRangeProps): react_jsx_runtime.JSX.Element;
 
 interface TimePickerProps {
     value: string;
@@ -422,6 +427,9 @@ interface FieldProps {
  * (aria-describedby), that the control is marked invalid, and that the error
  * sits directly below the field (forms-002/006/009/010). Use one Field per
  * control; do not add a separate <Label> or a label prop on the child.
+ *
+ * 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, className }: FieldProps): react_jsx_runtime.JSX.Element;
 
@@ -469,6 +477,10 @@ interface FormWrapperProps {
      * A function renders your own from the list.
      */
     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.
+     */
     className?: string;
     ref?: React.Ref<HTMLFormElement>;
 }
@@ -588,7 +600,12 @@ interface DescriptionListProps {
     columns?: 1 | 2 | 3 | 4;
     size?: DescriptionListSize;
     dividers?: boolean;
-    /** Below this breakpoint a multi-column list becomes one column. Default "sm" when columns > 1 (a phone never shows two columns of pairs); "none" keeps the columns at every width. */
+    /**
+     * A multi-column list re-flows by its own width (Sprint 25.9, A5): a column never gets narrower than a pair needs
+     * (20rem beside, 8rem stacked), so in a drawer, a pane or a settings panel it shows fewer columns, and one when a
+     * second will not fit. `stackBelow` adds a viewport rule on top: below this breakpoint the list is one column.
+     * Default "sm" when columns > 1 (a phone never shows two columns of pairs); "none" keeps the columns at every width.
+     */
     stackBelow?: "sm" | "md" | "lg" | "none";
     className?: string;
 }
@@ -661,9 +678,20 @@ interface TableProps {
     onRowClick?: (row: Record<string, string | number | ReactNode>, index: number) => void;
     /** Breakpoint at which the table switches to card layout. Defaults to "md" (768px). */
     mobileBreakpoint?: BreakpointKey;
+    /**
+     * The table's title inside its frame (Sprint 25.9, A1): a heading in CardTitle's style at CardHeader's inset, in a band
+     * above the scroll area that never scrolls sideways, and the `<table>`'s name. Title a table this way or with a
+     * SectionHeading above it — the same way as the blocks beside it (page_composition#45). In card mode, and while it
+     * loads or is empty there, the same heading sits above the cards. Without a title the table renders as before.
+     */
+    title?: string;
+    /** A line under the title, which also describes the `<table>` (aria-describedby). Needs `title`. */
+    description?: string;
+    /** The table's buttons, at the end of the title band as in a CardHeader. Needs `title`. */
+    actions?: ReactNode;
     ref?: Ref<HTMLDivElement>;
 }
-declare function Table({ columns, data, className, sortable, sortKey: controlledSortKey, sortDir: controlledSortDir, onSortChange, selectable, selectedRows, onSelectionChange, expandable, renderExpanded, density, stickyHeader, striped, loading, emptyState, onRowClick, mobileBreakpoint: mobileBreakpointProp, ref, }: TableProps): react_jsx_runtime.JSX.Element;
+declare function Table({ columns, data, className, sortable, sortKey: controlledSortKey, sortDir: controlledSortDir, onSortChange, selectable, selectedRows, onSelectionChange, expandable, renderExpanded, density, stickyHeader, striped, loading, emptyState, onRowClick, mobileBreakpoint: mobileBreakpointProp, title, description, actions, ref, }: TableProps): react_jsx_runtime.JSX.Element;
 
 interface CalendarEvent {
     id: string;
@@ -1257,16 +1285,18 @@ type TimeZoom = "day" | "week" | "month" | "quarter";
 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.
+ * day plus the fraction of the day its local clock shows (a day's first instant is the whole day); a number is a day
+ * index already, as the scale's own functions take it. NaN for anything else: null from JSON, a string that is no date.
  */
-declare function dayOf(value: DateInput): number;
+declare function dayOf(value: DateInput | number): 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.
+ * as the date pickers give) → the start of 15 March. A date-time end is half-open: it stops at that moment, as a day
+ * index does. A range's start can make a midnight Date half-open too (scale.span, formatDateRange, timeExtent).
  */
-declare function endDayOf(value: DateInput): number;
+declare function endDayOf(value: DateInput | number): 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;
@@ -1278,7 +1308,10 @@ interface TimeTick {
     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"]. */
+    /**
+     * Longest first, from Intl in the locale: ["September", "Sept", "S"], ["Mon 7", "7"], ["2026", "26"]. Every tick in a
+     * row has one form per level, so a form can repeat ("May", "May", "M").
+     */
     labels: string[];
 }
 /** A calendar day, as shadeDays sees it: its index, its weekday (0 is Sunday) and its "YYYY-MM-DD" key. */
@@ -1299,7 +1332,8 @@ interface TimeScale {
     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.
+     * (so a day's bar is never a day short), but a Date at midnight after a time-of-day start is where the range stops
+     * (an evening shift); a day index is where the range stops. Default: the start's own day.
      */
     span(start: DateInput | number, end?: DateInput | number): {
         x: number;
@@ -1324,7 +1358,10 @@ interface TimeScaleOptions {
     /** 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"). */
+    /**
+     * Default: the moment the view mounted, on the device that shows it. The server's render, and the render that
+     * hydrates its HTML, draw no today. 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;
@@ -1343,7 +1380,7 @@ declare function useTimeScale({ start, end, zoom, today, weekStartsOn, locale, p
 /**
  * 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.
+ * NaN for no dated range, which the scale shows as today. A range, a start or an end that is null is skipped.
  */
 declare function timeExtent(ranges: Iterable<{
     start: DateInput;
@@ -1363,12 +1400,13 @@ interface DateRangeWords {
 }
 /**
  * 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
+ * for one day. The end is inclusive for a whole day, as scale.span (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.
+ * the year shows when the two ends are in different years. A null end is the start's own day; a start that is no date
+ * gives "".
  */
-declare function formatDateRange(start: DateInput | number, end?: DateInput | number, { locale, to, day, time }?: DateRangeWords): string;
+declare function formatDateRange(start: DateInput | number, end?: DateInput | number, words?: DateRangeWords): string;
 
 /**
  * What a TimeViewport gives the things drawn inside it (Sprint 25.7, Part D). The scroll position lives in a store of
@@ -1377,7 +1415,10 @@ declare function formatDateRange(start: DateInput | number, end?: DateInput | nu
 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. */
+    /**
+     * One visible width back or on (the previous and next period), ending on the minor tick nearest there when one is
+     * within half a view of it. It always moves: where a period is wider than the view it moves by the view's width.
+     */
     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
@@ -1634,10 +1675,13 @@ 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 Date, or "YYYY-MM-DD" for a calendar day in the user's zone. Null for a task with no dates yet: like a date that
+     * does not parse, its row says "no dates", it has no bar and no arrows, and it has no part in the scale.
+     */
+    start: DateInput | null;
+    /** Inclusive for a whole day ("3 to 14 March" covers the 14th). Left out, the task is its start's day; a milestone uses its start alone. */
+    end?: DateInput | null;
     /** A GanttGroup's id. */
     group?: string;
     /** A key of `statuses`. */
@@ -1655,17 +1699,23 @@ interface GanttGroup {
 interface GanttStatus {
     label: string;
     tone: GanttTone;
+    /** The cue beside the colour, on its bars and in the legend (colour is never the only one). Default the tone's own. */
+    icon?: IconName;
 }
-interface GanttProps {
-    items: GanttItem[];
+interface GanttProps<T extends GanttItem = GanttItem> {
+    items: T[];
     /** 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. */
+    /**
+     * The selected item's id. The selection is controlled once this has held a value, and from then on undefined means
+     * none too, so selectedId={task?.id} works. 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. */
+    onSelect?: (item: T | null) => void;
+    /** The bars' colours and cues, and the legend; an item with no known status is neutral. */
     statuses?: Record<string, GanttStatus>;
+    /** Controlled. With no onZoomChange it is fixed, and there are no zoom controls. */
     zoom?: TimeZoom;
     /** Default "week". */
     defaultZoom?: TimeZoom;
@@ -1677,13 +1727,18 @@ interface GanttProps {
     /** 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.
+     * Beside the title in the name column (assignees' avatars): shown, not announced (say it in `describe`), and left out
+     * when the column is too narrow for it and the title (a phone). Nothing in it may take focus.
+     */
+    renderLabel?: (item: T) => ReactNode;
+    /**
+     * Words added to an item's accessible name after its title, dates, status and dependencies: what renderLabel shows
+     * ("assigned to Amara Haddad"). Called as the rows render, so an inline function is fine.
      */
-    renderLabel?: (item: GanttItem) => ReactNode;
+    describe?: (item: T) => string;
     /** 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. */
+    labelHeader?: ReactNode;
+    /** Controls after the built-in zoom, period and Today buttons, before the legend; false hides the bar (the legend stays). */
     toolbar?: ReactNode | false;
     "aria-label": string;
     className?: string;
@@ -1693,15 +1748,16 @@ interface GanttProps {
  * 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.
+ * of its own. A task whose dates do not parse keeps its row, marked "no dates".
  *
- * 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.
+ * Keyboard (APG tree view): the chart is one Tab stop, the selected row when focus comes in from outside. 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. When the focused row goes (a deletion, a
+ * filter), focus moves to the row before it. 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;
+declare function Gantt<T extends GanttItem = GanttItem>({ items, groups, selectedId, onSelect, statuses, zoom: zoomProp, defaultZoom, onZoomChange, today, weekStartsOn, locale, renderLabel, describe, labelHeader, toolbar, "aria-label": ariaLabel, className, }: GanttProps<T>): react_jsx_runtime.JSX.Element;
 
 type LinkUnderline = "hover" | "always" | "none";
 type LinkTone = "accent" | "muted" | "inherit";
@@ -1903,8 +1959,10 @@ interface SettingsLayoutProps {
     /** Width of the rail in px (sidebar layout). */
     railWidth?: number;
     /**
-     * Below this width of the layout itself (not the viewport) the rail becomes a Dropdown. Default: the rail plus a
-     * usable panel (railWidth + 480). Measured on the layout, so a narrow PageContainer or a sidebar shell counts.
+     * Below this width of the layout itself (not the viewport) the rail becomes a Dropdown. Default: the rail, the gap
+     * beside it and a usable panel (railWidth + gap + 560). Measured on the layout, so a narrow PageContainer or a
+     * sidebar shell counts. A narrow page holding the rail is wider by the rail and its gap, so the panel keeps the narrow
+     * width (roots.css, Sprint 25.9).
      */
     collapseBelow?: number;
     /** Accessible name of the section navigation. */
@@ -1925,7 +1983,7 @@ interface SettingsLayoutProps {
  * The rail is a Tabs (vertical) styled by the theme's in-page vertical style;
  * the page assembles the sections' contents and nothing else.
  */
-declare function SettingsLayout({ sections, value, onChange, layout: layoutProp, railWidth, collapseBelow, "aria-label": ariaLabel, children, className, }: SettingsLayoutProps): react_jsx_runtime.JSX.Element;
+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;
@@ -2988,7 +3046,10 @@ type PageContainerWidth = "constrained" | "full" | "narrow";
 type Padding = "none" | "default" | "wide";
 type VerticalPadding = "none" | "default" | "spacious";
 interface PageContainerProps {
-    /** Semantic width — maps to maxWidth internally. Takes precedence over maxWidth when both are set. */
+    /**
+     * Semantic width — maps to maxWidth internally. Takes precedence over maxWidth when both are set. A narrow page that
+     * holds a SettingsLayout rail is wider by the rail and its gap, so the panel keeps the narrow width (Sprint 25.9).
+     */
     width?: PageContainerWidth;
     /** Lower-level max-width escape hatch. Use `width` for standard cases. */
     maxWidth?: MaxWidth;
@@ -3034,6 +3095,7 @@ declare function useContentWidth(width: PageContainerWidth): void;
 declare const PageContainer: react.ForwardRefExoticComponent<PageContainerProps & react.RefAttributes<HTMLDivElement>>;
 
 interface SectionHeadingProps {
+    /** Wraps onto more lines rather than being cut (an insight above a chart); a pane's title keeps one line. */
     title: string;
     description?: string;
     /** The section's buttons. Below sm they sit under the title, like PageHeader's actions. */