@grampro/kit 2.4.4 → 2.5.0

package/source/components/modal/react/Modal.tsx

@@ -34,14 +34,20 @@ type Renderable = ReactNode | ((props: ModalRenderProps) => ReactNode);
 export interface ModalProps {
   /** Controlled open state. */
   open?: boolean;
+  /** Open to begin with, when you are not controlling `open`. */
   defaultOpen?: boolean;
   /** `reason` says what closed it; it is undefined when opening. */
   onOpenChange?(open: boolean, reason?: CloseReason): void;
   title?: ReactNode;
+  /** A line under the title, linked as the dialog's description. */
   description?: ReactNode;
   /** Accessible name when there is no `title`. */
   "aria-label"?: string;
   children?: Renderable;
+  /**
+   * The actions row, pinned below the scrolling content so it stays
+   * reachable however long the body is.
+   */
   footer?: Renderable;
   /** Width for dialogs; for drawers, the width (left/right) or height (bottom). Default `md`. */
   size?: ModalSize;

package/source/components/number-input/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/format.ts",
       "core/index.ts",
@@ -21,7 +21,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:45120dc11be8aafca638f8f6248f83deeb9f98c809140f80fd8c2d2610306371"
+    "sourceHash": "sha256:0cb6347602f25bd7c77b8738d9d1ac5216ee1a6ef50b5bf54f34deeb2d914f7b"
   },
   "props": [
     {
@@ -143,7 +143,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "A hint under the label, linked as the field's description.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "disabled",
@@ -157,7 +159,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The validation message. Setting it is enough on its own: the field\r\nreads as invalid to assistive technology and the message is announced.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "form",
@@ -217,7 +221,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The field's name, shown above it and linked to it.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "largeStep",
@@ -259,7 +265,9 @@
       "type": "number",
       "typeText": "number | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Largest accepted value, applied the same way as `min`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "maxLength",
@@ -273,7 +281,9 @@
       "type": "number",
       "typeText": "number | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Smallest accepted value. By default it is applied on blur rather than on\r\neach keystroke, so the field does not fight someone mid-number — see\r\n`clampBehavior` for `strict` or `none`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "minLength",
@@ -356,7 +366,9 @@
       "typeText": "NumberSize | undefined",
       "required": false,
       "default": "md",
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Default `md`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "snapToStep",
@@ -531,9 +543,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 50,
-    "propsDescribed": 18,
-    "describedPct": 36,
+    "propsTotal": 24,
+    "propsDescribed": 23,
+    "describedPct": 96,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/number-input/react/NumberInput.tsx

@@ -43,7 +43,13 @@ export interface NumberInputProps
   defaultValue?: number | null;
   /** Fires with the parsed number, or `null` when the field is emptied. */
   onValueChange?(value: number | null): void;
+  /**
+   * Smallest accepted value. By default it is applied on blur rather than on
+   * each keystroke, so the field does not fight someone mid-number — see
+   * `clampBehavior` for `strict` or `none`.
+   */
   min?: number;
+  /** Largest accepted value, applied the same way as `min`. */
   max?: number;
   /** How much one arrow press or stepper button moves. Default 1. */
   step?: number;
@@ -75,9 +81,16 @@ export interface NumberInputProps
   selectOnFocus?: boolean;
   /** A button that empties the field. */
   clearable?: boolean;
+  /** The field's name, shown above it and linked to it. */
   label?: ReactNode;
+  /** A hint under the label, linked as the field's description. */
   description?: ReactNode;
+  /**
+   * The validation message. Setting it is enough on its own: the field
+   * reads as invalid to assistive technology and the message is announced.
+   */
   error?: ReactNode;
+  /** Default `md`. */
   size?: NumberSize;
   /** Before the number: a currency symbol, a unit. */
   leading?: ReactNode;

package/source/components/popover/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/index.ts",
       "core/types.ts",
@@ -17,7 +17,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:ac04de47fed41d6ef646920b241371395154173d148a5c5f9a6440ef2f589f6a"
+    "sourceHash": "sha256:71722134c43ba8dec7c9139a8c2c84ab4009247f7b8e1699308f6abbc634f278"
   },
   "props": [
     {
@@ -80,14 +80,18 @@
       "typeText": "boolean | undefined",
       "required": false,
       "default": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Open to begin with, when you are not controlling `open`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "description",
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "A line under the title, linked as the panel's description.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "gap",
@@ -118,14 +122,18 @@
       "type": "function",
       "signature": "((open: boolean, reason?: PopoverCloseReason) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "`reason` says what closed it - `escape`, `outside`, `trigger` or\r\n`api` - and is undefined when opening.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "open",
       "type": "boolean",
       "typeText": "boolean | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Controlled open state.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "ref",
@@ -228,9 +236,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 19,
-    "propsDescribed": 8,
-    "describedPct": 42,
+    "propsTotal": 14,
+    "propsDescribed": 12,
+    "describedPct": 86,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/popover/react/Popover.tsx

@@ -47,11 +47,18 @@ export interface PopoverProps {
    */
   trigger: ReactElement<{ ref?: Ref<HTMLElement>; [attribute: string]: unknown }>;
   children?: ReactNode | ((props: PopoverRenderProps) => ReactNode);
+  /** Controlled open state. */
   open?: boolean;
+  /** Open to begin with, when you are not controlling `open`. */
   defaultOpen?: boolean;
+  /**
+   * `reason` says what closed it - `escape`, `outside`, `trigger` or
+   * `api` - and is undefined when opening.
+   */
   onOpenChange?(open: boolean, reason?: PopoverCloseReason): void;
   /** Heading inside the panel, which also names it. */
   title?: ReactNode;
+  /** A line under the title, linked as the panel's description. */
   description?: ReactNode;
   /** Names the panel when there is no `title`. */
   "aria-label"?: string;

package/source/components/progress/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/index.ts",
       "core/progress.ts",
@@ -260,9 +260,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 21,
+    "propsTotal": 9,
     "propsDescribed": 8,
-    "describedPct": 38,
+    "describedPct": 89,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/radio-group/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:cd5f36365c184346538fb461f4c4cd8014723621fd4d312cd5f00c415df20618"
+    "sourceHash": "sha256:7e13b8cd8a2bab1ee7a89cf691c1dc388951723939ca4a87def57d6301d8aa33"
   },
   "props": [
     {
@@ -106,21 +106,27 @@
       "typeText": "boolean | undefined",
       "required": false,
       "default": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Selected to begin with, for a standalone radio you are not controlling.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "defaultValue",
       "type": "string",
       "typeText": "string | null | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The choice selected 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 this choice's description.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "disabled",
@@ -135,7 +141,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The validation message for this one choice. A message that applies to the\nwhole question belongs on the RadioGroup instead.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "form",
@@ -180,7 +188,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The text beside the radio. Clicking it selects this choice.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "localeText",
@@ -231,21 +241,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\nhandler.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onCheckedChange",
       "type": "function",
       "signature": "((checked: boolean) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "This radio was chosen. Only ever fires with `true`, since choosing\nanother radio deselects this one rather than firing on it — to follow a\ngroup's choice, use `onValueChange` on the RadioGroup.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onValueChange",
       "type": "function",
       "signature": "((value: string | null) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The chosen value, or `null` when the group was emptied with `clearable`.\r\nThis is the handler to use for a group; the individual radios do not need\r\none.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "options",
@@ -325,7 +341,9 @@
       ],
       "typeText": "RadioSize | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Default `md`, or the size of the RadioGroup it sits in.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "step",
@@ -467,9 +485,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 44,
-    "propsDescribed": 8,
-    "describedPct": 18,
+    "propsTotal": 20,
+    "propsDescribed": 16,
+    "describedPct": 80,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/radio-group/react/Radio.tsx

@@ -26,12 +26,29 @@ export interface RadioProps
   value: string;
   /** Selected (controlled). Inside a RadioGroup the group decides instead. */
   checked?: boolean;
+  /** Selected to begin with, for a standalone radio you are not controlling. */
   defaultChecked?: boolean;
+  /**
+   * This radio was chosen. Only ever fires with `true`, since choosing
+   * another radio deselects this one rather than firing on it — to follow a
+   * group's choice, use `onValueChange` on the RadioGroup.
+   */
   onCheckedChange?(checked: boolean): void;
+  /**
+   * The underlying DOM event, for form libraries that want the native
+   * handler.
+   */
   onChange?: ChangeEventHandler<HTMLInputElement>;
+  /** The text beside the radio. Clicking it selects this choice. */
   label?: ReactNode;
+  /** A hint under the label, linked as this choice's description. */
   description?: ReactNode;
+  /**
+   * The validation message for this one choice. A message that applies to the
+   * whole question belongs on the RadioGroup instead.
+   */
   error?: ReactNode;
+  /** Default `md`, or the size of the RadioGroup it sits in. */
   size?: RadioSize;
   classNames?: Partial<Record<RadioSlot, string>>;
   /** The `<input>` element. */

package/source/components/radio-group/react/RadioGroup.tsx

@@ -19,19 +19,32 @@ import { cx, type RadioGroupSlot } from "./props";
 export interface RadioGroupProps {
   /** The chosen value (controlled). `null` for nothing chosen. */
   value?: string | null;
+  /** The choice selected to begin with, when you are not controlling `value`. */
   defaultValue?: string | null;
+  /**
+   * The chosen value, or `null` when the group was emptied with `clearable`.
+   * This is the handler to use for a group; the individual radios do not need
+   * one.
+   */
   onValueChange?(value: string | null): void;
   /** Render these choices, or pass `<Radio value="…">` children. Plain strings work too. */
   options?: readonly (string | RadioOption)[];
   children?: ReactNode;
   /** The question the choices answer, shown as the group's legend. */
   label?: ReactNode;
+  /** A hint under the legend, explaining the question rather than one choice. */
   description?: ReactNode;
+  /**
+   * The validation message for the question — "choose a plan". Setting it
+   * marks every radio in the group invalid and announces the message, so no
+   * extra `aria-invalid` is needed.
+   */
   error?: ReactNode;
   required?: boolean;
   disabled?: boolean;
   /** Form field name shared by every radio. One is generated when it is left out. */
   name?: string;
+  /** Default `md`. Each radio inherits it unless it sets its own. */
   size?: RadioSize;
   /** Default `vertical`. */
   orientation?: RadioOrientation;

package/source/components/skeleton/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/index.ts",
       "core/lines.ts",
@@ -19,7 +19,7 @@
       "react/Skeleton.tsx",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:e5c3bcb487c25092a77daec5c55f726d39ac8cf4f3628141cb6777053af6b01f"
+    "sourceHash": "sha256:c43f854a600cef0e2704513508c60910dbe3938df4b33ec6f2f614b8743055b3"
   },
   "props": [
     {
@@ -74,7 +74,9 @@
       "type": "other",
       "typeText": "string | number | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "A number is pixels; a string is used as given. Left out, each variant\nuses its own height, which is what keeps a skeleton the size of the\nthing it stands in for.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "icon",
@@ -241,9 +243,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 17,
-    "propsDescribed": 12,
-    "describedPct": 71,
+    "propsTotal": 13,
+    "propsDescribed": 13,
+    "describedPct": 100,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/skeleton/react/Skeleton.tsx

@@ -14,6 +14,11 @@ export interface SkeletonProps {
   lastLineWidth?: number;
   /** A number is pixels; a string is used as given. */
   width?: number | string;
+  /**
+   * A number is pixels; a string is used as given. Left out, each variant
+   * uses its own height, which is what keeps a skeleton the size of the
+   * thing it stands in for.
+   */
   height?: number | string;
   /** Corner radius for `rect`. */
   radius?: number | string;

package/source/components/spinner/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/index.ts",
       "core/types.ts",
@@ -235,9 +235,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 20,
+    "propsTotal": 8,
     "propsDescribed": 8,
-    "describedPct": 40,
+    "describedPct": 100,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/switch/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.5.0",
     "files": [
       "core/index.ts",
       "core/toggle.ts",
@@ -18,7 +18,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:d96a8af61a18c077beccad85f49d1a25f1e20091aede0182c852f7f36ee9254a"
+    "sourceHash": "sha256:b2007da7ec91cbad6bd7697048cc205d22e8b94035482a9f631a75e9dabfd0e4"
   },
   "props": [
     {
@@ -85,7 +85,9 @@
       "typeText": "boolean | undefined",
       "required": false,
       "default": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The starting state when you are not controlling `checked`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "defaultValue",
@@ -99,7 +101,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "A hint under the label, linked as the switch's description.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "disabled",
@@ -113,7 +117,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The validation message. Setting it is enough on its own: the switch reads\r\nas invalid to assistive technology and the message is announced, so no\r\nextra `aria-invalid` is needed.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "form",
@@ -158,7 +164,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The text beside the track. Clicking it flips the switch.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "labelPosition",
@@ -231,7 +239,9 @@
       "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 the new state, and for the async behaviour above, use\r\n`onCheckedChange`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onCheckedChange",
@@ -290,7 +300,9 @@
       "typeText": "SwitchSize | undefined",
       "required": false,
       "default": "md",
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Default `md`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "step",
@@ -411,9 +423,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 39,
-    "propsDescribed": 6,
-    "describedPct": 15,
+    "propsTotal": 11,
+    "propsDescribed": 11,
+    "describedPct": 100,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/switch/react/Switch.tsx

@@ -27,6 +27,7 @@ export interface SwitchProps
   > {
   /** On or off (controlled). */
   checked?: boolean;
+  /** The starting state when you are not controlling `checked`. */
   defaultChecked?: boolean;
   /**
    * Fires with the new state. Return a promise and the switch stays on the new
@@ -34,12 +35,25 @@ export interface SwitchProps
    * it rejects — see [Saving](#saving).
    */
   onCheckedChange?(checked: boolean): void | Promise<unknown>;
+  /**
+   * The underlying DOM event, for form libraries that want the native
+   * handler. For the new state, and for the async behaviour above, use
+   * `onCheckedChange`.
+   */
   onChange?: ChangeEventHandler<HTMLInputElement>;
   /** Posted with the form when the switch is on. Default `"on"`, as for a checkbox. */
   value?: string;
+  /** The text beside the track. Clicking it flips the switch. */
   label?: ReactNode;
+  /** A hint under the label, linked as the switch's description. */
   description?: ReactNode;
+  /**
+   * The validation message. Setting it is enough on its own: the switch reads
+   * as invalid to assistive technology and the message is announced, so no
+   * extra `aria-invalid` is needed.
+   */
   error?: ReactNode;
+  /** Default `md`. */
   size?: SwitchSize;
   /** Default `end`: the label after the track. `start` puts the track on the right, for settings rows. */
   labelPosition?: SwitchLabelPosition;