@grampro/kit 2.4.4 → 2.5.0

package/source/components/checkbox/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/group.ts",
       "core/index.ts",
@@ -22,7 +22,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:5b132e0d372a16b0536b1e8a6fb8809dbcbfb00e1282d406a0a474090f4a72f5"
+    "sourceHash": "sha256:ddf0907b2b6377c5d134ed140d8a4f47b0dc5ef39ec984c21ec33370c6d9815f"
   },
   "props": [
     {
@@ -96,21 +96,27 @@
       "typeText": "CheckedState | undefined",
       "required": false,
       "default": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The starting state when you are not controlling `checked`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "defaultValue",
       "type": "other",
       "typeText": "string[] | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The values checked to begin with, when you are not controlling `value`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "description",
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "A hint under the label, linked as the box's description.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "disabled",
@@ -125,7 +131,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The validation message. Setting it is enough on its own: the box reads as\r\ninvalid to assistive technology and the message is announced, so no extra\r\n`aria-invalid` is needed.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "form",
@@ -170,7 +178,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The text beside the box. Clicking it toggles the box.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "localeText",
@@ -221,21 +231,27 @@
       "type": "function",
       "signature": "ChangeEventHandler<HTMLInputElement> | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The underlying DOM event, for form libraries that want the native\r\nhandler. For reading the new state, `onCheckedChange` is simpler.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onCheckedChange",
       "type": "function",
       "signature": "((checked: boolean) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The state after a change, as a plain boolean — the handler to reach for.\r\nNever fires with `\"indeterminate\"`: clicking a mixed box resolves it.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onValueChange",
       "type": "function",
       "signature": "((values: string[]) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The checked values after a change. They accumulate in the order they were\nchecked, not the order the options are declared, so sort before comparing\ntwo selections for equality.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "options",
@@ -324,7 +340,9 @@
       ],
       "typeText": "CheckboxSize | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Default `md`, or the size of the CheckboxGroup it sits in.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "step",
@@ -446,9 +464,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 43,
-    "propsDescribed": 7,
-    "describedPct": 16,
+    "propsTotal": 19,
+    "propsDescribed": 15,
+    "describedPct": 79,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/checkbox/react/Checkbox.tsx

@@ -25,14 +25,31 @@ export interface CheckboxProps
   > {
   /** `true`, `false` or `"indeterminate"` (controlled). */
   checked?: CheckedState;
+  /** The starting state when you are not controlling `checked`. */
   defaultChecked?: CheckedState;
+  /**
+   * The state after a change, as a plain boolean — the handler to reach for.
+   * Never fires with `"indeterminate"`: clicking a mixed box resolves it.
+   */
   onCheckedChange?(checked: boolean): void;
+  /**
+   * The underlying DOM event, for form libraries that want the native
+   * handler. For reading the new state, `onCheckedChange` is simpler.
+   */
   onChange?: ChangeEventHandler<HTMLInputElement>;
   /** Posted with the form when checked. Inside a CheckboxGroup, the value this box adds. */
   value?: string;
+  /** The text beside the box. Clicking it toggles the box. */
   label?: ReactNode;
+  /** A hint under the label, linked as the box's description. */
   description?: ReactNode;
+  /**
+   * The validation message. Setting it is enough on its own: the box reads as
+   * invalid to assistive technology and the message is announced, so no extra
+   * `aria-invalid` is needed.
+   */
   error?: ReactNode;
+  /** Default `md`, or the size of the CheckboxGroup it sits in. */
   size?: CheckboxSize;
   classNames?: Partial<Record<CheckboxSlot, string>>;
   /** The `<input>` element. */

package/source/components/checkbox/react/CheckboxGroup.tsx

@@ -13,7 +13,13 @@ import { cx, type CheckboxGroupSlot } from "./props";
 export interface CheckboxGroupProps {
   /** Checked values (controlled). */
   value?: string[];
+  /** The values checked to begin with, when you are not controlling `value`. */
   defaultValue?: string[];
+  /**
+   * The checked values after a change. They accumulate in the order they were
+   * checked, not the order the options are declared, so sort before comparing
+   * two selections for equality.
+   */
   onValueChange?(values: string[]): void;
   /** Render these options, or pass `<Checkbox value="…">` children. */
   options?: readonly CheckboxOption[];

package/source/components/combobox/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/filter.ts",
       "core/index.ts",
@@ -25,7 +25,7 @@
       "react/props.ts",
       "react/useCombobox.ts"
     ],
-    "sourceHash": "sha256:39aa629ae5088777b3a2b8e89036701d9a100c214986912d233bbb6f4fd4f72a"
+    "sourceHash": "sha256:9cd7b0e88a1ee4b9bd83cab6ad6d55613476a35e4d7ea70be9fc7ac9fe2a58e7"
   },
   "props": [
     {
@@ -77,7 +77,7 @@
       "required": false,
       "default": true,
       "origin": "derived",
-      "description": "Keep the list open after choosing. Default false.",
+      "description": "Close the list after choosing. Default true; `false` keeps it open.",
       "descriptionOrigin": "jsdoc"
     },
     {
@@ -92,7 +92,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",
@@ -107,7 +109,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Shown when nothing matches the search. Defaults to the locale text.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "error",
@@ -148,7 +152,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": "loading",
@@ -223,28 +229,36 @@
       "type": "function",
       "signature": "((value: NoInfer<V> | null, option: ComboboxOption<NoInfer<V>> | null) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The chosen value, and the whole option beside it so the label and\r\nanything else it carries need not be looked up again. Both are\r\n`null` once the control is cleared.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onCreate",
       "type": "function",
       "signature": "((label: string) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The text someone typed when they chose \"Create ...\". Adding it to\n`options` and selecting it is yours to do.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onLoadMore",
       "type": "function",
       "signature": "(() => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Fetch the next page. Called once as the list nears its end, while\n`hasMore` is true - so it must not fire again until the new options\nhave arrived.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onOpenChange",
       "type": "function",
       "signature": "((open: boolean) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The list opened or closed.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onSearchChange",
@@ -260,7 +274,9 @@
       "type": "other",
       "typeText": "readonly ComboboxOption<V>[]",
       "required": true,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The choices. Each needs a `value` and a `label`, and may carry a\n`description`, a `group` heading, an icon or `disabled`. In `server`\nmode these are the current results rather than the whole set.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "placeholder",
@@ -282,7 +298,9 @@
       "type": "function",
       "signature": "((option: ComboboxOption<NoInfer<V>>, state: OptionState) => ReactNode) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Draw each row yourself. `state` carries whether the option is\nselected, active or disabled, so the row can reflect them.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "required",
@@ -332,7 +350,9 @@
       "typeText": "ComboboxSize | undefined",
       "required": false,
       "default": "md",
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Default `md`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "style",
@@ -446,9 +466,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 39,
-    "propsDescribed": 18,
-    "describedPct": 46,
+    "propsTotal": 34,
+    "propsDescribed": 28,
+    "describedPct": 82,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/combobox/react/Select.tsx

@@ -13,8 +13,13 @@ import { useCombobox } from "./useCombobox";
 export interface SelectProps<V extends OptionValue = string> extends ComboboxSharedProps<V> {
   value?: V | null;
   defaultValue?: V | null;
+  /**
+   * The chosen value, and the whole option beside it so the label and
+   * anything else it carries need not be looked up again. Both are
+   * `null` once the control is cleared.
+   */
   onChange?(value: NoInfer<V> | null, option: ComboboxOption<NoInfer<V>> | null): void;
-  /** Keep the list open after choosing. Default false. */
+  /** Close the list after choosing. Default true; `false` keeps it open. */
   closeOnSelect?: boolean;
   ref?: Ref<ComboboxHandle<V>>;
 }

package/source/components/combobox/react/props.ts

@@ -34,6 +34,11 @@ export interface OptionState {
 }
 
 export interface ComboboxSharedProps<V extends OptionValue = string> {
+  /**
+   * The choices. Each needs a `value` and a `label`, and may carry a
+   * `description`, a `group` heading, an icon or `disabled`. In `server`
+   * mode these are the current results rather than the whole set.
+   */
   options: readonly ComboboxOption<V>[];
   /** `client` filters `options` locally; `server` expects `options` to be the current results. */
   mode?: "client" | "server";
@@ -47,18 +52,33 @@ export interface ComboboxSharedProps<V extends OptionValue = string> {
   searchable?: boolean;
   /** More results are available; the list calls `onLoadMore` when scrolled near the end. */
   hasMore?: boolean;
+  /**
+   * Fetch the next page. Called once as the list nears its end, while
+   * `hasMore` is true - so it must not fire again until the new options
+   * have arrived.
+   */
   onLoadMore?(): void;
   /**
    * Replaces the built-in search matching (client mode).
    * `NoInfer` keeps the option type coming from `options` and `value` only.
    */
   filterFn?(option: ComboboxOption<NoInfer<V>>, search: string): boolean;
+  /**
+   * Draw each row yourself. `state` carries whether the option is
+   * selected, active or disabled, so the row can reflect them.
+   */
   renderOption?(option: ComboboxOption<NoInfer<V>>, state: OptionState): ReactNode;
   /** Offers "Create …" when the search matches no option. */
   allowCreate?: boolean;
+  /**
+   * The text someone typed when they chose "Create ...". Adding it to
+   * `options` and selecting it is yours to do.
+   */
   onCreate?(label: string): void;
+  /** The control's name, shown above it and linked to it. */
   label?: ReactNode;
   placeholder?: string;
+  /** 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;
@@ -66,6 +86,7 @@ export interface ComboboxSharedProps<V extends OptionValue = string> {
   disabled?: boolean;
   /** Show the clear button. Default true. */
   clearable?: boolean;
+  /** Default `md`. */
   size?: ComboboxSize;
   /** Name for the hidden form input. */
   name?: string;
@@ -74,11 +95,13 @@ export interface ComboboxSharedProps<V extends OptionValue = string> {
   maxHeight?: number;
   /** `true` / `false` to force, or a count above which virtualization turns on (default 80). */
   virtualize?: boolean | number;
+  /** Shown when nothing matches the search. Defaults to the locale text. */
   emptyMessage?: ReactNode;
   className?: string;
   classNames?: Partial<Record<ComboboxSlot, string>>;
   style?: CSSProperties;
   localeText?: Partial<ComboboxLocaleText>;
+  /** The list opened or closed. */
   onOpenChange?(open: boolean): void;
   /** Names the control when there is no visible `label`. */
   "aria-label"?: string;

package/source/components/data-grid/core/types.ts

@@ -268,7 +268,17 @@ export interface PdfExportOptions<T> extends PrintExportOptions<T> {
 }
 
 export interface GridOptions<T> {
+  /**
+   * The rows to show. One object per row, in whatever shape your data already
+   * has — columns reach into it rather than the other way round. In `server`
+   * mode this is the current page, not the whole set.
+   */
   data: readonly T[];
+  /**
+   * One definition per column, and the order here is the initial column order.
+   * A definition says where a column's value comes from and how to render it;
+   * everything else about the grid is driven from these.
+   */
   columns: readonly ColumnDef<T>[];
   /**
    * Stable row id: a property name (recommended) or a function.
@@ -279,24 +289,67 @@ export interface GridOptions<T> {
   mode?: "client" | "server";
   /** Total rows on the server (server mode). */
   rowCount?: number;
+  /**
+   * Drive the grid from outside. Whatever you pass here the grid obeys rather
+   * than deciding for itself, so pair it with `onStateChange` or the grid
+   * stops responding. Pass only the slices you want to own; the rest stay
+   * internal. For a starting point you do not intend to control, use
+   * `initialState`.
+   */
   state?: Partial<GridState>;
+  /**
+   * Where the grid starts — a default sort, a page size, hidden columns. Read
+   * once on mount and then owned by the grid, so later changes are ignored.
+   */
   initialState?: Partial<GridState>;
+  /**
+   * Every change to sorting, filters, search, pagination, selection, column
+   * layout or density, with the state before it for comparison. This is the
+   * hook for persisting a user's view.
+   */
   onStateChange?(next: GridState, prev: GridState): void;
   /** Fires when sorting, filters, search or pagination change. */
   onQueryChange?(query: GridQuery): void;
+  /** Page the rows instead of scrolling the whole set. Default `true`. */
   enablePagination?: boolean;
+  /** Let a header click sort the column. Default `true`. */
   enableSorting?: boolean;
+  /**
+   * Let a shift-click add a column to the sort rather than replacing it.
+   * Default `true`, and inert while `enableSorting` is off.
+   */
   enableMultiSort?: boolean;
+  /** Per-column filters and the toolbar's search box. Default `true`. */
   enableFiltering?: boolean;
+  /** Let a header edge be dragged to resize. Default `true`. */
   enableColumnResizing?: boolean;
+  /** Let a header be dragged to move the column. Default `true`. */
   enableColumnReordering?: boolean;
+  /** Let a column be pinned to the left or right edge. Default `true`. */
   enableColumnPinning?: boolean;
+  /** Let columns be shown and hidden from the toolbar. Default `true`. */
   enableColumnHiding?: boolean;
+  /**
+   * Add the selection column. Default `false`. A function selects per row —
+   * return `false` and that row's checkbox is disabled, which is how to stop
+   * someone picking a record their role does not cover.
+   */
   enableRowSelection?: boolean | ((row: T) => boolean);
+  /** `single` leaves one row selected at a time. Default `multiple`. */
   selectionMode?: "single" | "multiple";
+  /**
+   * A cell was edited. Fires only when the value actually changed.
+   *
+   * Return a promise to make the edit optimistic: the new value shows while
+   * it is in flight, and if the promise rejects the cell reverts to the
+   * underlying data and shows the rejection's message as the cell's error.
+   * So reject with the reason you want the user to read.
+   */
   onCellEdit?(event: CellEditEvent<T>): void | Promise<void>;
   /** Not fired for clicks on interactive content (buttons, inputs, links, checkboxes). */
   onRowClick?(row: T, event: MouseEvent<HTMLElement>): void;
+  /** Same exclusions as `onRowClick`: interactive content does not reach it. */
   onRowDoubleClick?(row: T, event: MouseEvent<HTMLElement>): void;
+  /** Base name for an exported file, without the extension. */
   exportFileName?: string;
 }