@grampro/kit 2.6.3 → 2.7.0

package/source/components/checkbox/passport.json

@@ -10,8 +10,9 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.0",
     "files": [
+      "core/agent.ts",
       "core/group.ts",
       "core/index.ts",
       "core/types.ts",
@@ -22,8 +23,9 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:ddf0907b2b6377c5d134ed140d8a4f47b0dc5ef39ec984c21ec33370c6d9815f"
+    "sourceHash": "sha256:864a782462120954cea168efe6df111474541556f8518107677c1098cceaa035"
   },
+  "purpose": "A single native checkbox, and CheckboxGroup for several that share a name, with mixed state, a select-all and group-level validation.",
   "props": [
     {
       "name": "aria-describedby",
@@ -260,7 +262,8 @@
       "required": false,
       "origin": "derived",
       "description": "Render these options, or pass `<Checkbox value=\"…\">` children.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "The declarative form of the group's children. Supply this or Checkbox children, never both."
     },
     {
       "name": "orientation",
@@ -455,20 +458,90 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "native <input type=checkbox> semantics, including Space to toggle",
+      "the indeterminate state is set as a DOM property, which is the only way it exists",
+      "CheckboxGroup renders a fieldset with the group label as its legend",
+      "description and error linked by aria-describedby"
+    ],
+    "required": [
+      "a `label` on every checkbox — an unlabelled one is unusable by anything but sight",
+      "`name` when the value is submitted with a form"
+    ]
+  },
+  "composition": {
+    "allowedChildren": [
+      "Checkbox"
+    ],
+    "mustNotContain": [
+      "label"
+    ],
+    "notes": "CheckboxGroup expects Checkbox children or an `options` array, not both. The component supplies its own label element."
+  },
+  "operations": {
+    "setValue": {
+      "summary": "Write a value into the field, as though a person had entered it.",
+      "effects": [
+        "replaces the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "clear": {
+      "summary": "Empty the field.",
+      "effects": [
+        "discards the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "focus": {
+      "summary": "Move keyboard focus to the field.",
+      "effects": [
+        "moves focus"
+      ],
+      "reversible": false
+    }
+  },
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "orientation",
+      "description",
+      "selectAll"
+    ],
+    "forbidden": [
+      "checked",
+      "defaultChecked",
+      "value",
+      "defaultValue",
+      "name",
+      "options",
+      "required",
+      "disabled",
+      "readOnly",
+      "onChange",
+      "onCheckedChange",
+      "onValueChange",
+      "error"
+    ],
+    "rationale": "Layout is safe. The checked state is the user's answer and `options` is the question; an agent that edits either is answering on their behalf."
   },
-  "composition": {},
-  "operations": {},
-  "intentDomains": [],
-  "safeMutations": {},
   "examples": [],
   "coverage": {
     "propsTotal": 19,
     "propsDescribed": 15,
     "describedPct": 79,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "operations",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

package/source/components/checkbox/passport.manual.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Checkbox",
+  "purpose": "A single native checkbox, and CheckboxGroup for several that share a name, with mixed state, a select-all and group-level validation.",
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "$operationsNote": "Mirrors shared/core/agent/field.ts, which is what the runtime dispatches on. source/components/shared/core/agent/__tests__/field-passport.test.ts fails if the two drift. No `apiMethod`: a field is written through its ref — the element for most of these, a handle for Combobox and DatePicker — and that is a normal case, not a gap.",
+  "operations": {
+    "setValue": {
+      "summary": "Write a value into the field, as though a person had entered it.",
+      "effects": [
+        "replaces the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "clear": {
+      "summary": "Empty the field.",
+      "effects": [
+        "discards the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "focus": {
+      "summary": "Move keyboard focus to the field.",
+      "effects": [
+        "moves focus"
+      ],
+      "reversible": false
+    }
+  },
+  "accessibility": {
+    "supplied": [
+      "native <input type=checkbox> semantics, including Space to toggle",
+      "the indeterminate state is set as a DOM property, which is the only way it exists",
+      "CheckboxGroup renders a fieldset with the group label as its legend",
+      "description and error linked by aria-describedby"
+    ],
+    "required": [
+      "a `label` on every checkbox — an unlabelled one is unusable by anything but sight",
+      "`name` when the value is submitted with a form"
+    ]
+  },
+  "composition": {
+    "allowedChildren": [
+      "Checkbox"
+    ],
+    "mustNotContain": [
+      "label"
+    ],
+    "notes": "CheckboxGroup expects Checkbox children or an `options` array, not both. The component supplies its own label element."
+  },
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "orientation",
+      "description",
+      "selectAll"
+    ],
+    "forbidden": [
+      "checked",
+      "defaultChecked",
+      "value",
+      "defaultValue",
+      "name",
+      "options",
+      "required",
+      "disabled",
+      "readOnly",
+      "onChange",
+      "onCheckedChange",
+      "onValueChange",
+      "error"
+    ],
+    "rationale": "Layout is safe. The checked state is the user's answer and `options` is the question; an agent that edits either is answering on their behalf."
+  },
+  "propNotes": {
+    "options": "The declarative form of the group's children. Supply this or Checkbox children, never both."
+  }
+}

package/source/components/combobox/core/agent.ts

@@ -0,0 +1,38 @@
+/*
+ * Combobox's agent contract.
+ *
+ * The first of the two components whose ref is a handle rather than an
+ * element. `open` and `close` join the operation set because it has a list to
+ * disclose, and `mode` decides whether the value is one option or several.
+ *
+ * Pure: no React, no DOM. The contract is what this instance will accept, and
+ * the validator in shared/core/agent decides everything from it. Build it from
+ * props on every render so that a field which has just become read-only stops
+ * accepting writes immediately.
+ */
+
+import type { FieldContract } from "../../shared/core/agent";
+
+export interface ComboboxAgentProps {
+  label?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  multiple?: boolean;
+  max?: number;
+  options?: readonly { value: string; label: string; disabled?: boolean }[];
+}
+
+export function comboboxContract(props: ComboboxAgentProps = {}): FieldContract {
+  return {
+    component: props.multiple ? "MultiSelect" : "Select",
+    kind: props.multiple ? "multiChoice" : "choice",
+    operations: ["setValue", "clear", "focus", "open", "close"],
+    label: props.label,
+    disabled: props.disabled,
+    readOnly: props.readOnly,
+    required: props.required,
+    options: props.options,
+    maxSelected: props.multiple ? props.max : undefined,
+  };
+}

package/source/components/combobox/core/index.ts

@@ -14,3 +14,5 @@ export {
 export { getVisibleRange, measureItems, scrollToItem } from "./virtual";
 export type { ItemSizes, ListMetrics, Range } from "./virtual";
 export type * from "./types";
+// The agent contract: what a model may ask this field to do.
+export { comboboxContract, type ComboboxAgentProps } from "./agent";

package/source/components/combobox/passport.json

@@ -9,8 +9,9 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.0",
     "files": [
+      "core/agent.ts",
       "core/filter.ts",
       "core/index.ts",
       "core/types.ts",
@@ -25,8 +26,9 @@
       "react/props.ts",
       "react/useCombobox.ts"
     ],
-    "sourceHash": "sha256:9cd7b0e88a1ee4b9bd83cab6ad6d55613476a35e4d7ea70be9fc7ac9fe2a58e7"
+    "sourceHash": "sha256:5243c2cc6863f8c2dcd248c2fd46417390fec66a8d5b0d405177a372e9c0566f"
   },
+  "purpose": "Select and MultiSelect: a searchable combobox for one or many values, with options in the browser's top layer, optional virtualisation and create-on-type.",
   "props": [
     {
       "name": "allowCreate",
@@ -213,7 +215,8 @@
       "required": false,
       "origin": "derived",
       "description": "`client` filters `options` locally; `server` expects `options` to be the current results.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Single or multiple. Changing it changes the shape of `value`, so it cannot be toggled on a live field."
     },
     {
       "name": "name",
@@ -376,7 +379,8 @@
       "default": true,
       "origin": "derived",
       "description": "`true` / `false` to force, or a count above which virtualization turns on (default 80).",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Worth turning on past a few hundred options; it changes nothing a user can observe."
     }
   ],
   "events": [
@@ -457,20 +461,108 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "the combobox pattern: aria-expanded, aria-controls, aria-activedescendant on the control",
+      "arrow keys move the active option, Enter selects, Escape closes and returns focus",
+      "the listbox renders in the top layer, so it is never clipped by an ancestor's overflow",
+      "the empty and loading states are announced rather than leaving silence"
+    ],
+    "required": [
+      "a `label`, or `aria-label` when the control is visually unlabelled",
+      "an `emptyMessage` that says what to do next, not just that nothing matched"
+    ]
+  },
+  "composition": {
+    "notes": "Options come from the `options` array, not from children. `renderOption` changes how one is drawn but must not introduce its own focusable elements — the listbox owns focus."
+  },
+  "operations": {
+    "setValue": {
+      "summary": "Write a value into the field, as though a person had entered it.",
+      "effects": [
+        "replaces the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "clear": {
+      "summary": "Empty the field.",
+      "effects": [
+        "discards the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "focus": {
+      "summary": "Move keyboard focus to the field.",
+      "effects": [
+        "moves focus"
+      ],
+      "reversible": false
+    },
+    "open": {
+      "summary": "Open the field's calendar or option list.",
+      "effects": [
+        "shows the overlay"
+      ],
+      "reversible": true
+    },
+    "close": {
+      "summary": "Close the field's calendar or option list.",
+      "effects": [
+        "hides the overlay"
+      ],
+      "reversible": true
+    }
+  },
+  "intentDomains": [
+    "ActionIntent",
+    "Recommendation",
+    "Classification"
+  ],
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "placeholder",
+      "description",
+      "emptyMessage",
+      "maxHeight",
+      "maxVisibleTags",
+      "searchable",
+      "clearable",
+      "closeOnSelect",
+      "showSelectAll",
+      "virtualize"
+    ],
+    "forbidden": [
+      "value",
+      "defaultValue",
+      "name",
+      "options",
+      "mode",
+      "max",
+      "required",
+      "disabled",
+      "allowCreate",
+      "onChange",
+      "onCreate",
+      "onLoadMore",
+      "filterFn",
+      "error"
+    ],
+    "rationale": "Presentation and affordances are safe. `options` is the domain, `mode` decides single or multiple, and `allowCreate` lets a user invent values the backend may not accept."
   },
-  "composition": {},
-  "operations": {},
-  "intentDomains": [],
-  "safeMutations": {},
   "examples": [],
   "coverage": {
     "propsTotal": 34,
     "propsDescribed": 28,
     "describedPct": 82,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "operations",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

package/source/components/combobox/passport.manual.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Combobox",
+  "purpose": "Select and MultiSelect: a searchable combobox for one or many values, with options in the browser's top layer, optional virtualisation and create-on-type.",
+  "intentDomains": [
+    "ActionIntent",
+    "Recommendation",
+    "Classification"
+  ],
+  "$operationsNote": "Mirrors shared/core/agent/field.ts, which is what the runtime dispatches on. source/components/shared/core/agent/__tests__/field-passport.test.ts fails if the two drift. No `apiMethod`: a field is written through its ref — the element for most of these, a handle for Combobox and DatePicker — and that is a normal case, not a gap.",
+  "operations": {
+    "setValue": {
+      "summary": "Write a value into the field, as though a person had entered it.",
+      "effects": [
+        "replaces the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "clear": {
+      "summary": "Empty the field.",
+      "effects": [
+        "discards the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "focus": {
+      "summary": "Move keyboard focus to the field.",
+      "effects": [
+        "moves focus"
+      ],
+      "reversible": false
+    },
+    "open": {
+      "summary": "Open the field's calendar or option list.",
+      "effects": [
+        "shows the overlay"
+      ],
+      "reversible": true
+    },
+    "close": {
+      "summary": "Close the field's calendar or option list.",
+      "effects": [
+        "hides the overlay"
+      ],
+      "reversible": true
+    }
+  },
+  "accessibility": {
+    "supplied": [
+      "the combobox pattern: aria-expanded, aria-controls, aria-activedescendant on the control",
+      "arrow keys move the active option, Enter selects, Escape closes and returns focus",
+      "the listbox renders in the top layer, so it is never clipped by an ancestor's overflow",
+      "the empty and loading states are announced rather than leaving silence"
+    ],
+    "required": [
+      "a `label`, or `aria-label` when the control is visually unlabelled",
+      "an `emptyMessage` that says what to do next, not just that nothing matched"
+    ]
+  },
+  "composition": {
+    "notes": "Options come from the `options` array, not from children. `renderOption` changes how one is drawn but must not introduce its own focusable elements — the listbox owns focus."
+  },
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "placeholder",
+      "description",
+      "emptyMessage",
+      "maxHeight",
+      "maxVisibleTags",
+      "searchable",
+      "clearable",
+      "closeOnSelect",
+      "showSelectAll",
+      "virtualize"
+    ],
+    "forbidden": [
+      "value",
+      "defaultValue",
+      "name",
+      "options",
+      "mode",
+      "max",
+      "required",
+      "disabled",
+      "allowCreate",
+      "onChange",
+      "onCreate",
+      "onLoadMore",
+      "filterFn",
+      "error"
+    ],
+    "rationale": "Presentation and affordances are safe. `options` is the domain, `mode` decides single or multiple, and `allowCreate` lets a user invent values the backend may not accept."
+  },
+  "propNotes": {
+    "mode": "Single or multiple. Changing it changes the shape of `value`, so it cannot be toggled on a live field.",
+    "virtualize": "Worth turning on past a few hundred options; it changes nothing a user can observe."
+  }
+}

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

@@ -24,6 +24,20 @@ export interface ComboboxHandle<V extends OptionValue = string> {
   toggle(): void;
   focus(): void;
   clear(): void;
+  /**
+   * Replace the selection, as choosing from the list would: the change
+   * handler fires, and an uncontrolled combobox updates itself.
+   *
+   * `null` clears. A single value is accepted in either mode; a list given to
+   * a single-select combobox keeps the first entry, and one longer than `max`
+   * is truncated rather than silently rejected. Values that are not in
+   * `options` are still committed — the component does not own the option set
+   * and a `server`-mode combobox legitimately holds a value whose option is
+   * not currently loaded. Code that needs values checked against the list
+   * should go through the agent runtime, whose reference layer does exactly
+   * that.
+   */
+  setValue(next: V | readonly V[] | null): void;
   getValue(): V[];
   getSelectedOptions(): ComboboxOption<V>[];
 }

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

@@ -373,10 +373,16 @@ export function useCombobox<V extends OptionValue>(params: UseComboboxParams<V>)
       toggle: () => setOpen(!open),
       focus: () => controlRef.current?.focus(),
       clear: () => commit([]),
+      // `clear` was always a write; this is the same write with a value in it.
+      setValue: (next) => {
+        const list = next == null ? [] : Array.isArray(next) ? [...next] : [next as V];
+        if (!multiple) return commit(list.slice(0, 1));
+        commit(max === undefined ? list : list.slice(0, max));
+      },
       getValue: () => [...values],
       getSelectedOptions: () => selectedOptions,
     }),
-    [setOpen, open, commit, values, selectedOptions, controlRef],
+    [setOpen, open, commit, values, selectedOptions, controlRef, multiple, max],
   );
 
   return {

package/source/components/data-grid/export/xlsx.ts

@@ -7,8 +7,15 @@ const MAIN_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
 const REL_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
 const PKG_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships";
 
-/** Characters XML 1.0 does not allow at all. */
-const INVALID_XML_CHARS = /[^\t\n\r -퟿-�\u{10000}-\u{10FFFF}]/gu;
+/**
+ * Characters XML 1.0 does not allow at all.
+ *
+ * Written as escapes rather than as the characters themselves. The bounds
+ * here are U+D7FF, U+E000 and U+FFFD, which are invisible in an editor, do
+ * not survive every copy and paste, and made this line depend on the file
+ * being read back as UTF-8. TypeScript 7 also rejected the literal form.
+ */
+const INVALID_XML_CHARS = /[^\t\n\r\u0020-\uD7FF\uE000-\uFFFD\u{10000}-\u{10FFFF}]/gu;
 
 const XML_ENTITIES: Record<string, string> = {
   "&": "&amp;",

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

@@ -14,7 +14,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.0",
     "files": [
       "agent/coerce.ts",
       "agent/contract.ts",
@@ -64,7 +64,7 @@
       "react/keyboard.ts",
       "react/locale.ts"
     ],
-    "sourceHash": "sha256:b3fa605b7c7ae2fbb4d9ccd3900b69472665508c0c92b5a218767d4c387d20a3"
+    "sourceHash": "sha256:66dfc75f60791c6e4397d3438ec3ad19ce47f9e5ea51677024200d1f75bd5d44"
   },
   "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": [

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

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../../schema/passport-v1.schema.json",
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
   "component": "DataGrid",
   "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.",
   "intentDomains": ["Query", "ActionIntent", "Extraction"],

package/source/components/date-picker/core/agent.ts

@@ -0,0 +1,42 @@
+/*
+ * DatePicker's agent contract.
+ *
+ * Dates arrive as ISO yyyy-mm-dd and are checked against `min` and `max`
+ * before anything is written. Anything relative — "last Friday", "end of the
+ * quarter" — is the adapter's to resolve: this layer refuses what it cannot read
+ * rather than guessing, because guessing a date wrong is indistinguishable from
+ * being told the wrong date.
+ *
+ * Pure: no React, no DOM. The contract is what this instance will accept, and
+ * the validator in shared/core/agent decides everything from it. Build it from
+ * props on every render so that a field which has just become read-only stops
+ * accepting writes immediately.
+ */
+
+import type { FieldContract } from "../../shared/core/agent";
+
+export interface DatePickerAgentProps {
+  label?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  /** ISO yyyy-mm-dd. */
+  min?: string;
+  /** ISO yyyy-mm-dd. */
+  max?: string;
+  range?: boolean;
+}
+
+export function datePickerContract(props: DatePickerAgentProps = {}): FieldContract {
+  return {
+    component: props.range ? "DateRangePicker" : "DatePicker",
+    kind: props.range ? "dateRange" : "date",
+    operations: ["setValue", "clear", "focus", "open", "close"],
+    label: props.label,
+    disabled: props.disabled,
+    readOnly: props.readOnly,
+    required: props.required,
+    min: props.min,
+    max: props.max,
+  };
+}

package/source/components/date-picker/core/index.ts

@@ -39,3 +39,5 @@ export {
 export type { DateField, WeekdayName } from "./format";
 export { getServerToday, getToday, subscribeToToday } from "./today";
 export type * from "./types";
+// The agent contract: what a model may ask this field to do.
+export { datePickerContract, type DatePickerAgentProps } from "./agent";