@grampro/kit 2.4.4 → 2.6.0

package/source/components/dialog/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/api.ts",
       "core/dialog.ts",
@@ -23,7 +23,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:d087fe0d6b3c7069ea05892cbf27167e7b5aae79c9522503d2f92574c1158058"
+    "sourceHash": "sha256:f0b7d7683418b4981af453e5bf4dc08034a6d854dbca6e192283a555e77fdd0d"
   },
   "props": [
     {
@@ -31,7 +31,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The dismissing button's text. Defaults to Cancel.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "className",
@@ -52,7 +54,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The confirming button's text. Defaults to OK for an alert and Confirm\notherwise; naming the action (\"Delete project\") reads better than\neither.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "defaultValue",
@@ -67,7 +71,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The detail under the title - what is about to happen, and to what.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "dismissible",
@@ -100,7 +106,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Names the text field. Without it the field is named by the title.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "inputType",
@@ -116,7 +124,9 @@
       "typeText": "'number' | 'email' | 'tel' | 'text' | 'url' | 'password' | undefined",
       "required": false,
       "default": "text",
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The field's input type, which picks the on-screen keyboard on a phone.\nDefault `text`. The value still arrives as a string.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "intent",
@@ -189,7 +199,9 @@
       "type": "boolean",
       "typeText": "boolean",
       "required": true,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Whether the dialog is on screen. Required: this component is always\ncontrolled, so set it to false in `onClose`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "placeholder",
@@ -216,7 +228,9 @@
       "typeText": "DialogSize | undefined",
       "required": false,
       "default": "sm",
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Default `md`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "store",
@@ -334,9 +348,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 25,
-    "propsDescribed": 9,
-    "describedPct": 36,
+    "propsTotal": 21,
+    "propsDescribed": 16,
+    "describedPct": 76,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/dialog/react/Dialog.tsx

@@ -35,6 +35,10 @@ const INTENT_ICONS: Record<DialogIntent, ReactNode> = {
 export type DialogAction = "confirm" | "cancel";
 
 export interface DialogProps extends Omit<PromptOptions, "onConfirm"> {
+  /**
+   * Whether the dialog is on screen. Required: this component is always
+   * controlled, so set it to false in `onClose`.
+   */
   open: boolean;
   /** `alert` has one button, `confirm` two, `prompt` adds a text field. Default `confirm`. */
   kind?: DialogKind;

package/source/components/file-uploader/passport.json

@@ -13,7 +13,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/format.ts",
       "core/index.ts",
@@ -29,7 +29,7 @@
       "react/props.ts",
       "react/useFileUploader.ts"
     ],
-    "sourceHash": "sha256:07b69e816e869610850093764502d4da38bb450f2ab729b827e4f124f6125d63"
+    "sourceHash": "sha256:f77a12b14c2d24bc55a922a38f2f85dca85eafe89f63ffb28932e0dc4639d965"
   },
   "props": [
     {
@@ -46,7 +46,9 @@
       "type": "boolean",
       "typeText": "boolean | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Accept the same file twice. Default false, where a file matching one\r\nalready selected by name, size and last-modified time is rejected.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "autoUpload",
@@ -95,7 +97,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "A hint under the label, linked as the field's description. The place\r\nto say what is accepted and how large it may be.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "disabled",
@@ -137,7 +141,9 @@
       "type": "other",
       "typeText": "Partial<import(\"..\").ChunkFieldNames> | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Rename the form fields each chunk is sent under, for a server whose\r\ncontract you do not control.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "getFileId",
@@ -153,7 +159,9 @@
       "type": "other",
       "typeText": "Record<string, string> | ((request: import(\"..\").ChunkRequest) => Record<string, string> | Promise<Record<string, string>>) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Static headers, or a function - async allowed - called per chunk, which\r\nis what to use for a token that expires mid-upload.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "id",
@@ -167,7 +175,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The field's name, shown above the drop zone and linked to it.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "locale",
@@ -213,7 +223,9 @@
       ],
       "typeText": "'POST' | 'PUT' | 'PATCH' | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "HTTP method for each chunk. Default `POST`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "minSize",
@@ -257,28 +269,36 @@
       "type": "function",
       "signature": "((item: UploadItem, error: unknown) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "One file failed, after its retries were used up. `error` is an\r\n`UploadHttpError` carrying `status` and the parsed `body` when the\r\nserver answered, and whatever was thrown otherwise.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onFileSuccess",
       "type": "function",
       "signature": "((item: UploadItem) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "One file finished uploading. Fires per file, not once at the end.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onRejected",
       "type": "function",
       "signature": "((rejections: FileRejection[]) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Files that never made it in - wrong type, too large, a duplicate, or\r\nrefused by `validate`. Each rejection carries the file and the reason,\r\nso this is the hook for reporting why.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onRemoveExisting",
       "type": "function",
       "signature": "((file: ExistingFile) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Someone removed one of the already-stored files. Removing it for real\r\nis yours to do; the component only reports it.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onUploadComplete",
@@ -303,7 +323,9 @@
       "type": "function",
       "signature": "((body: string, xhr: XMLHttpRequest) => unknown) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Turn the response body into the value stored on the item, which is\r\nwhere `getFileId` then looks. Default: JSON, falling back to text.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "preview",
@@ -369,7 +391,9 @@
       "typeText": "UploaderSize | undefined",
       "required": false,
       "default": "md",
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Default `md`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "style",
@@ -401,7 +425,9 @@
       "type": "boolean",
       "typeText": "boolean | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Send cookies on cross-origin requests. Default false.",
+      "descriptionOrigin": "jsdoc"
     }
   ],
   "events": [
@@ -508,9 +534,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 44,
-    "propsDescribed": 23,
-    "describedPct": 52,
+    "propsTotal": 39,
+    "propsDescribed": 36,
+    "describedPct": 92,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/file-uploader/react/FileUploader.tsx

@@ -45,17 +45,35 @@ export interface FileUploaderProps {
   minSize?: number;
   /** Return a message to reject a file. */
   validate?(file: File): string | null | undefined;
+  /**
+   * Accept the same file twice. Default false, where a file matching one
+   * already selected by name, size and last-modified time is rejected.
+   */
   allowDuplicates?: boolean;
 
   /* ------------------------------------------------------------- upload */
   /** Where chunks are POSTed. Without `endpoint` or `transport`, files are only selected. */
   endpoint?: HttpTransportOptions["endpoint"];
+  /** HTTP method for each chunk. Default `POST`. */
   method?: HttpTransportOptions["method"];
+  /**
+   * Static headers, or a function - async allowed - called per chunk, which
+   * is what to use for a token that expires mid-upload.
+   */
   headers?: HttpTransportOptions["headers"];
+  /** Send cookies on cross-origin requests. Default false. */
   withCredentials?: boolean;
   /** Extra data sent as JSON with every chunk. */
   params?: HttpTransportOptions["params"];
+  /**
+   * Rename the form fields each chunk is sent under, for a server whose
+   * contract you do not control.
+   */
   fieldNames?: HttpTransportOptions["fieldNames"];
+  /**
+   * Turn the response body into the value stored on the item, which is
+   * where `getFileId` then looks. Default: JSON, falling back to text.
+   */
   parseResponse?: HttpTransportOptions["parseResponse"];
   /** Replaces the built-in HTTP transport, e.g. for presigned URLs or an SDK. */
   transport?: Transport;
@@ -77,15 +95,25 @@ export interface FileUploaderProps {
   preview?: boolean;
   /** Files already stored, shown above new ones. */
   existingFiles?: readonly ExistingFile[];
+  /**
+   * Someone removed one of the already-stored files. Removing it for real
+   * is yours to do; the component only reports it.
+   */
   onRemoveExisting?(file: ExistingFile): void;
   /** Show remove buttons. Default true. */
   removable?: boolean;
+  /** The field's name, shown above the drop zone and linked to it. */
   label?: ReactNode;
+  /**
+   * A hint under the label, linked as the field's description. The place
+   * to say what is accepted and how large it may be.
+   */
   description?: ReactNode;
   /** Message below the drop zone; also marks it invalid. */
   error?: ReactNode;
   required?: boolean;
   disabled?: boolean;
+  /** Default `md`. */
   size?: UploaderSize;
   /**
    * Form field name. With an endpoint, the stored file ids are posted; without
@@ -103,8 +131,19 @@ export interface FileUploaderProps {
   /* ------------------------------------------------------------- events */
   /** Selected files changed. */
   onChange?(files: File[]): void;
+  /**
+   * Files that never made it in - wrong type, too large, a duplicate, or
+   * refused by `validate`. Each rejection carries the file and the reason,
+   * so this is the hook for reporting why.
+   */
   onRejected?(rejections: FileRejection[]): void;
+  /** One file finished uploading. Fires per file, not once at the end. */
   onFileSuccess?(item: UploadItem): void;
+  /**
+   * One file failed, after its retries were used up. `error` is an
+   * `UploadHttpError` carrying `status` and the parsed `body` when the
+   * server answered, and whatever was thrown otherwise.
+   */
   onFileError?(item: UploadItem, error: unknown): void;
   /** Every file in an upload run has stopped (uploaded, failed, paused or canceled). */
   onUploadComplete?(items: UploadItem[]): void;

package/source/components/input/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/count.ts",
       "core/index.ts",
@@ -23,7 +23,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:8059fadd4e1670ffcf97afe2f729758855d04389b0ccbe91edfc9d2a2975ee75"
+    "sourceHash": "sha256:50ff11f4a9255189704b330123d35d4f4e3550bd4cf2eed2d0735c92ba876b03"
   },
   "props": [
     {
@@ -112,7 +112,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",
@@ -182,7 +184,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": "leading",
@@ -363,7 +367,9 @@
       "typeText": "FieldSize | undefined",
       "required": false,
       "default": "md",
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Default `md`.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "step",
@@ -526,9 +532,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 49,
-    "propsDescribed": 14,
-    "describedPct": 29,
+    "propsTotal": 18,
+    "propsDescribed": 16,
+    "describedPct": 89,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/input/react/Input.tsx

@@ -26,10 +26,13 @@ export interface InputProps
   defaultValue?: string;
   /** The new text on every change. The native `onChange` fires as well. */
   onValueChange?(value: string): void;
+  /** 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;
   /** Message below the field; also marks it invalid. */
   error?: ReactNode;
+  /** Default `md`. */
   size?: FieldSize;
   /** Content before the text, e.g. an icon or "https://". */
   leading?: ReactNode;

package/source/components/menu/passport.json

@@ -16,7 +16,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/index.ts",
       "core/navigation.ts",
@@ -29,7 +29,7 @@
       "react/props.ts",
       "react/useMenuKeys.ts"
     ],
-    "sourceHash": "sha256:7613198a66407cdf4fa284f093ae35f5596e79cf1242097d09cdc3172c2f79d7"
+    "sourceHash": "sha256:9a6248a4986051f6506746c084b9e89728fecd0a0b430d1962f5f3ed544ce1e5"
   },
   "props": [
     {
@@ -52,7 +52,9 @@
       "typeText": "boolean | undefined",
       "required": false,
       "default": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Ticked (controlled).",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "children",
@@ -91,7 +93,9 @@
       "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": "destructive",
@@ -126,7 +130,9 @@
       "type": "other",
       "typeText": "ReactNode",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Drawn before the submenu's label, at the size of the text.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "id",
@@ -156,14 +162,18 @@
       "type": "function",
       "signature": "((checked: boolean) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The state after a toggle, as a plain boolean.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onOpenChange",
       "type": "function",
       "signature": "((open: boolean, reason?: MenuCloseReason) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "`reason` says what closed it - `escape`, `outside`, `trigger`,\r\n`select` or `api` - and is undefined when opening.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "onSelect",
@@ -179,14 +189,18 @@
       "type": "function",
       "signature": "((value: string) => void) | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The newly chosen value.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "open",
       "type": "boolean",
       "typeText": "boolean | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "Controlled open state.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "ref",
@@ -241,7 +255,9 @@
       "type": "string",
       "typeText": "string | undefined",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The chosen value (controlled).",
+      "descriptionOrigin": "jsdoc"
     }
   ],
   "events": [
@@ -312,9 +328,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 25,
-    "propsDescribed": 9,
-    "describedPct": 36,
+    "propsTotal": 20,
+    "propsDescribed": 17,
+    "describedPct": 85,
     "authoredSections": [
       "accessibility"
     ]

package/source/components/menu/react/Menu.tsx

@@ -46,8 +46,14 @@ export interface MenuProps {
    */
   trigger: ReactElement<{ [attribute: string]: unknown }>;
   children: 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`,
+   * `select` or `api` - and is undefined when opening.
+   */
   onOpenChange?(open: boolean, reason?: MenuCloseReason): void;
   /** Names the menu for screen readers. Defaults to the locale text. */
   label?: string;
@@ -257,6 +263,7 @@ export interface MenuSubProps {
   /** The label of the item that opens the submenu. */
   label: ReactNode;
   children: ReactNode;
+  /** Drawn before the submenu's label, at the size of the text. */
   icon?: ReactNode;
   disabled?: boolean;
   className?: string;

package/source/components/menu/react/items.tsx

@@ -96,7 +96,9 @@ export function MenuItem(props: MenuItemProps) {
 }
 
 export interface MenuCheckboxItemProps extends BaseItemProps {
+  /** Ticked (controlled). */
   checked?: boolean;
+  /** The state after a toggle, as a plain boolean. */
   onCheckedChange?(checked: boolean): void;
   /** Default false: toggling several options in a row is the usual case. */
   closeOnSelect?: boolean;
@@ -147,7 +149,9 @@ export function MenuCheckboxItem(props: MenuCheckboxItemProps) {
 }
 
 export interface MenuRadioGroupProps {
+  /** The chosen value (controlled). */
   value?: string;
+  /** The newly chosen value. */
   onValueChange?(value: string): void;
   /** Names the group, and is shown above it when it is a string. */
   label?: ReactNode;

package/source/components/modal/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.4",
+    "libraryVersion": "2.6.0",
     "files": [
       "core/dismiss.ts",
       "core/index.ts",
@@ -19,7 +19,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:65249a3a5ade72848c6db3224858922d8c2b8f7c6bcce0f421275835398fb6c7"
+    "sourceHash": "sha256:078ceea5f6cf953d95a999fd958a6b2ed8a61e3c9060665eeca4efd53fb70413"
   },
   "props": [
     {
@@ -88,21 +88,27 @@
       "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 dialog's description.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "footer",
       "type": "other",
       "typeText": "Renderable",
       "required": false,
-      "origin": "derived"
+      "origin": "derived",
+      "description": "The actions row, pinned below the scrolling content so it stays\r\nreachable however long the body is.",
+      "descriptionOrigin": "jsdoc"
     },
     {
       "name": "id",
@@ -279,9 +285,9 @@
   "safeMutations": {},
   "examples": [],
   "coverage": {
-    "propsTotal": 22,
-    "propsDescribed": 11,
-    "describedPct": 50,
+    "propsTotal": 17,
+    "propsDescribed": 14,
+    "describedPct": 82,
     "authoredSections": [
       "accessibility"
     ]