gridsmith-ui 0.17.0 → 0.17.2

package/dist/index.d.ts

@@ -1257,16 +1257,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 +1280,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 +1304,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 +1330,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 +1352,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 +1372,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 +1387,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 +1647,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 +1671,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 +1699,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 +1720,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";