@grampro/kit 2.4.3 → 2.5.0

package/source/components/data-grid/passport.json

@@ -14,7 +14,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.5.0",
     "files": [
       "agent/coerce.ts",
       "agent/contract.ts",
@@ -64,7 +64,7 @@
       "react/keyboard.ts",
       "react/locale.ts"
     ],
-    "sourceHash": "sha256:85285e939d717fa498f6aa038e225d9f488eef52e3e530f214e51e6ae34aaa79"
+    "sourceHash": "sha256:b3fa605b7c7ae2fbb4d9ccd3900b69472665508c0c92b5a218767d4c387d20a3"
   },
   "purpose": "Display and operate on tabular data. Virtualized; holds its own sort, filter, search, selection, column and pagination state in an external store exposed through GridApi.",
   "props": [
@@ -73,7 +73,9 @@
       "type": "other",
       "typeText": "GridAgent<T> | null",
       "required": true,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The agent that turns a sentence into grid operations, from\n`useGridAgent`. `null` while none is in scope, and the box renders\nnothing rather than offering something that cannot answer.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "agentPolicy",
@@ -131,21 +133,27 @@
       "type": "other",
       "typeText": "readonly ColumnDef<T, unknown>[]",
       "required": true,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "One definition per column, and the order here is the initial column order.\nA definition says where a column's value comes from and how to render it;\neverything else about the grid is driven from these.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "data",
       "type": "other",
       "typeText": "readonly T[]",
       "required": true,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The rows to show. One object per row, in whatever shape your data already\nhas — columns reach into it rather than the other way round. In `server`\nmode this is the current page, not the whole set.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "emptyState",
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Shown in place of rows when there are none. Worth distinguishing \"nothing\r\nhere yet\" from \"nothing matched your filters\", which the default does not.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "enableColumnHiding",
@@ -153,7 +161,9 @@
       "typeText": "boolean | undefined",
       "required": false,
       "default": true,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Let columns be shown and hidden from the toolbar. Default `true`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "enableColumnPinning",
@@ -161,7 +171,9 @@
       "typeText": "boolean | undefined",
       "required": false,
       "default": true,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Let a column be pinned to the left or right edge. Default `true`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "enableColumnReordering",
@@ -169,7 +181,9 @@
       "typeText": "boolean | undefined",
       "required": false,
       "default": true,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Let a header be dragged to move the column. Default `true`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "enableColumnResizing",
@@ -177,7 +191,9 @@
       "typeText": "boolean | undefined",
       "required": false,
       "default": true,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Let a header edge be dragged to resize. Default `true`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "enableFiltering",
@@ -185,14 +201,18 @@
       "typeText": "boolean | undefined",
       "required": false,
       "default": true,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Per-column filters and the toolbar's search box. Default `true`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "enableMultiSort",
       "type": "boolean",
       "typeText": "boolean | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Let a shift-click add a column to the sort rather than replacing it.\nDefault `true`, and inert while `enableSorting` is off.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "enablePagination",
@@ -200,7 +220,9 @@
       "typeText": "boolean | undefined",
       "required": false,
       "default": true,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Page the rows instead of scrolling the whole set. Default `true`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "enableRowSelection",
@@ -208,7 +230,9 @@
       "typeText": "boolean | ((row: T) => boolean) | undefined",
       "required": false,
       "default": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Add the selection column. Default `false`. A function selects per row —\nreturn `false` and that row's checkbox is disabled, which is how to stop\nsomeone picking a record their role does not cover.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "enableSorting",
@@ -216,21 +240,27 @@
       "typeText": "boolean | undefined",
       "required": false,
       "default": true,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Let a header click sort the column. Default `true`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "exportFileName",
       "type": "string",
       "typeText": "string | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Base name for an exported file, without the extension.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "getRowClassName",
       "type": "function",
       "signature": "((row: T, rowIndex: number) => string | undefined) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "A class per row, for status colouring. Return undefined for no class.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "getRowId",
@@ -246,7 +276,9 @@
       "type": "number",
       "typeText": "number | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Fixed header height in px. Defaults to the density's row height.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "height",
@@ -263,7 +295,9 @@
       "type": "other",
       "typeText": "Partial<GridState> | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Where the grid starts — a default sort, a page size, hidden columns. Read\nonce on mount and then owned by the grid, so later changes are ignored.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "loading",
@@ -271,7 +305,9 @@
       "typeText": "boolean | undefined",
       "required": false,
       "default": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Show the loading treatment over the grid. The existing rows stay in place\r\nunderneath, so a refresh does not empty the screen.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "locale",
@@ -309,7 +345,9 @@
       "type": "function",
       "signature": "((event: CellEditEvent<T>) => void | Promise<void>) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "A cell was edited. Fires only when the value actually changed.\n\nReturn a promise to make the edit optimistic: the new value shows while\nit is in flight, and if the promise rejects the cell reverts to the\nunderlying data and shows the rejection's message as the cell's error.\nSo reject with the reason you want the user to read.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onQueryChange",
@@ -334,14 +372,18 @@
       "type": "function",
       "signature": "((row: T, event: MouseEvent<HTMLElement>) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Same exclusions as `onRowClick`: interactive content does not reach it.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onStateChange",
       "type": "function",
       "signature": "((next: GridState, prev: GridState) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Every change to sorting, filters, search, pagination, selection, column\nlayout or density, with the state before it for comparison. This is the\nhook for persisting a user's view.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "pageSizeOptions",
@@ -349,7 +391,9 @@
       "typeText": "number[] | undefined",
       "required": false,
       "default": "DEFAULT_PAGE_SIZES",
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Page sizes offered in the pager. Default `[25, 50, 100, 250]`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "placeholder",
@@ -393,7 +437,9 @@
       "typeText": "'multiple' | 'single' | undefined",
       "required": false,
       "default": "multiple",
-      "origin": "derived"
+      "origin": "derived",
+      "description": "`single` leaves one row selected at a time. Default `multiple`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "semantics",
@@ -410,6 +456,8 @@
       "typeText": "Partial<GridState> | undefined",
       "required": false,
       "origin": "derived",
+      "description": "Drive the grid from outside. Whatever you pass here the grid obeys rather\nthan deciding for itself, so pair it with `onStateChange` or the grid\nstops responding. Pass only the slices you want to own; the rest stay\ninternal. For a starting point you do not intend to control, use\n`initialState`.",
+      "descriptionOrigin": "jsdoc",
       "note": "Makes the grid controlled. Prefer `initialState` unless the host genuinely owns the state."
     },
     {
@@ -424,7 +472,9 @@
       "type": "other",
       "typeText": "readonly string[] | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Example questions offered before anyone types. Worth setting to the\nphrasings this data actually supports — they teach the shape of a good\nquestion faster than placeholder text does.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "toolbar",
@@ -432,7 +482,9 @@
       "typeText": "boolean | ToolbarOptions | undefined",
       "required": false,
       "default": true,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The toolbar above the grid. `true` for all of it, `false` for none, or an\r\nobject to choose parts — `{ search: true, export: false }` — and to put\r\nyour own controls at its `start` or `end`.",
+      "descriptionOrigin": "jsdoc"
     }
   ],
   "events": [
@@ -1029,9 +1081,9 @@
   },
   "examples": [],
   "coverage": {
-    "propsTotal": 45,
-    "propsDescribed": 12,
-    "describedPct": 27,
+    "propsTotal": 40,
+    "propsDescribed": 38,
+    "describedPct": 95,
     "authoredSections": [
       "accessibility",
       "composition",

package/source/components/data-grid/react/AskGrid.tsx

@@ -20,8 +20,18 @@ import type { GridAgent } from "../agent/engine";
  */
 
 export interface AskGridProps<T> {
+  /**
+   * The agent that turns a sentence into grid operations, from
+   * `useGridAgent`. `null` while none is in scope, and the box renders
+   * nothing rather than offering something that cannot answer.
+   */
   agent: GridAgent<T> | null;
   placeholder?: string;
+  /**
+   * Example questions offered before anyone types. Worth setting to the
+   * phrasings this data actually supports — they teach the shape of a good
+   * question faster than placeholder text does.
+   */
   suggestions?: readonly string[];
   className?: string;
   "aria-label"?: string;

package/source/components/data-grid/react/DataGrid.tsx

@@ -38,11 +38,27 @@ export interface DataGridProps<T> extends GridOptions<T> {
   autoHeight?: boolean;
   /** Fixed row height in px. Defaults to the density's height. */
   rowHeight?: number;
+  /** Fixed header height in px. Defaults to the density's row height. */
   headerHeight?: number;
+  /**
+   * Show the loading treatment over the grid. The existing rows stay in place
+   * underneath, so a refresh does not empty the screen.
+   */
   loading?: boolean;
+  /**
+   * The toolbar above the grid. `true` for all of it, `false` for none, or an
+   * object to choose parts — `{ search: true, export: false }` — and to put
+   * your own controls at its `start` or `end`.
+   */
   toolbar?: boolean | ToolbarOptions;
+  /** Page sizes offered in the pager. Default `[25, 50, 100, 250]`. */
   pageSizeOptions?: number[];
+  /**
+   * Shown in place of rows when there are none. Worth distinguishing "nothing
+   * here yet" from "nothing matched your filters", which the default does not.
+   */
   emptyState?: ReactNode;
+  /** A class per row, for status colouring. Return undefined for no class. */
   getRowClassName?(row: T, rowIndex: number): string | undefined;
   classNames?: Partial<Record<GridSlot, string>>;
   className?: string;

package/source/components/date-picker/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/calendar.ts",
       "core/format.ts",
@@ -29,7 +29,7 @@
       "react/props.ts",
       "react/useDatePicker.ts"
     ],
-    "sourceHash": "sha256:1d3862b23e2bb13fb234af1b85344691a92f9282dae1052fa8eebd19414452bb"
+    "sourceHash": "sha256:2370299b9b495fd18671fb31106c1ba88e834227e3b9632207c048da66982370"
   },
   "props": [
     {
@@ -88,7 +88,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "A hint under the label, linked as the control's description.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "disabled",
@@ -122,7 +124,9 @@
       "type": "other",
       "typeText": "DateFormat | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "How the chosen date is displayed. `Intl.DateTimeFormatOptions` for the\nusual cases, or a function for a shape Intl cannot express. Left out,\nthe locale's own date format is used - which is the right default far\nmore often than a hand-written one.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "id",
@@ -145,7 +149,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The control's name, shown above it and linked to it.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "locale",
@@ -168,7 +174,9 @@
       "type": "other",
       "typeText": "DateInput | null | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Latest selectable day. Later days are shown but cannot be picked.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "min",
@@ -176,7 +184,7 @@
       "typeText": "DateInput | null | undefined",
       "required": false,
       "origin": "derived",
-      "description": "Earliest and latest selectable day.",
+      "description": "Earliest selectable day. Earlier days are shown but cannot be picked.",
       "descriptionOrigin": "jsdoc"
     },
     {
@@ -203,14 +211,18 @@
       "type": "function",
       "signature": "((date: Date | null) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The chosen day as a `Date` at local midnight, or `null` once cleared.\r\nAccepts a string or a number in `value`, but always hands back a\r\n`Date`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onOpenChange",
       "type": "function",
       "signature": "((open: boolean) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The calendar opened or closed.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "placeholder",
@@ -269,7 +281,9 @@
       "typeText": "boolean | undefined",
       "required": false,
       "default": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Number each week down the left of the calendar. Default false.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "size",
@@ -282,7 +296,9 @@
       "typeText": "DatePickerSize | undefined",
       "required": false,
       "default": "md",
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Default `md`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "style",
@@ -397,9 +413,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 33,
-    "propsDescribed": 14,
-    "describedPct": 42,
+    "propsTotal": 28,
+    "propsDescribed": 22,
+    "describedPct": 79,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/date-picker/react/DatePicker.tsx

@@ -23,6 +23,11 @@ import { useDatePicker } from "./useDatePicker";
 export interface DatePickerProps extends DatePickerSharedProps {
   value?: DateInput | null;
   defaultValue?: DateInput | null;
+  /**
+   * The chosen day as a `Date` at local midnight, or `null` once cleared.
+   * Accepts a string or a number in `value`, but always hands back a
+   * `Date`.
+   */
   onChange?(date: Date | null): void;
   /** Close the calendar after choosing a date. Default true. */
   closeOnSelect?: boolean;

package/source/components/date-picker/react/props.ts

@@ -27,8 +27,9 @@ export type DateFormat =
   | ((date: Date, locale: string | undefined) => string);
 
 export interface DatePickerSharedProps {
-  /** Earliest and latest selectable day. */
+  /** Earliest selectable day. Earlier days are shown but cannot be picked. */
   min?: DateInput | null;
+  /** Latest selectable day. Later days are shown but cannot be picked. */
   max?: DateInput | null;
   /** Called for every rendered day; return true to block it (weekends, holidays). */
   isDateDisabled?(date: Date): boolean;
@@ -40,9 +41,16 @@ export interface DatePickerSharedProps {
   locale?: string;
   /** 0 = Sunday. Defaults to the locale's first day of the week. */
   weekStartsOn?: number;
+  /**
+   * How the chosen date is displayed. `Intl.DateTimeFormatOptions` for the
+   * usual cases, or a function for a shape Intl cannot express. Left out,
+   * the locale's own date format is used - which is the right default far
+   * more often than a hand-written one.
+   */
   format?: DateFormat;
   /** Months shown side by side. Default 1, or 2 for the range picker. */
   numberOfMonths?: number;
+  /** Number each week down the left of the calendar. Default false. */
   showWeekNumbers?: boolean;
   /** Show the "Today" shortcut in the footer. Default true. */
   showToday?: boolean;
@@ -50,7 +58,9 @@ export interface DatePickerSharedProps {
   allowInput?: boolean;
   /** Always six week rows, so the popover never changes height. Default true. */
   fixedWeeks?: boolean;
+  /** The control's name, shown above it and linked to it. */
   label?: ReactNode;
+  /** A hint under the label, linked as the control's description. */
   description?: ReactNode;
   /** Message shown below the control; also marks the control invalid. */
   error?: ReactNode;
@@ -61,6 +71,7 @@ export interface DatePickerSharedProps {
   readOnly?: boolean;
   /** Show the clear button. Default true. */
   clearable?: boolean;
+  /** Default `md`. */
   size?: DatePickerSize;
   /** Posts the value as `yyyy-mm-dd` in a hidden input. */
   name?: string;
@@ -69,6 +80,7 @@ export interface DatePickerSharedProps {
   classNames?: Partial<Record<DatePickerSlot, string>>;
   style?: CSSProperties;
   localeText?: Partial<DatePickerLocaleText>;
+  /** The calendar opened or closed. */
   onOpenChange?(open: boolean): void;
 }
 

package/source/components/dialog/core/types.ts

@@ -6,14 +6,21 @@ export type DialogSize = "sm" | "md";
 
 export interface DialogBaseOptions {
   title: ReactNode;
+  /** The detail under the title - what is about to happen, and to what. */
   description?: ReactNode;
   /** Sets the icon and the confirm button's color. `danger` also focuses Cancel first. */
   intent?: DialogIntent;
   /** Replaces the intent's icon; `null` hides it. */
   icon?: ReactNode;
+  /**
+   * The confirming button's text. Defaults to OK for an alert and Confirm
+   * otherwise; naming the action ("Delete project") reads better than
+   * either.
+   */
   confirmLabel?: ReactNode;
   /** Escape and a backdrop click count as Cancel. Default true. */
   dismissible?: boolean;
+  /** Default `md`. */
   size?: DialogSize;
 }
 
@@ -23,16 +30,23 @@ export interface AlertOptions extends DialogBaseOptions {
 }
 
 export interface ConfirmOptions extends DialogBaseOptions {
+  /** The dismissing button's text. Defaults to Cancel. */
   cancelLabel?: ReactNode;
   /** Runs on Confirm. The dialog waits while it runs and shows its error if it throws. */
   onConfirm?(): void | Promise<void>;
 }
 
 export interface PromptOptions extends DialogBaseOptions {
+  /** The dismissing button's text. Defaults to Cancel. */
   cancelLabel?: ReactNode;
   defaultValue?: string;
   placeholder?: string;
+  /** Names the text field. Without it the field is named by the title. */
   inputLabel?: ReactNode;
+  /**
+   * The field's input type, which picks the on-screen keyboard on a phone.
+   * Default `text`. The value still arrives as a string.
+   */
   inputType?: "text" | "email" | "password" | "number" | "url" | "tel";
   required?: boolean;
   /** Return a message to block confirming. */