@grampro/kit 2.7.1 → 2.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grampro/kit",
-  "version": "2.7.1",
+  "version": "2.7.3",
   "description": "GramproKit — an agent-native UI runtime for React. Copy-in components you own, each publishing a contract that software can read.",
   "type": "module",
   "files": [

package/source/components/accordion/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/index.ts",
       "core/open.ts",

package/source/components/alert/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/index.ts",
       "core/live.ts",

package/source/components/avatar/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/identity.ts",
       "core/index.ts",

package/source/components/badge/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/count.ts",
       "core/index.ts",

package/source/components/breadcrumb/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/index.ts",
       "core/trail.ts",

package/source/components/button/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/index.ts",
       "core/state.ts",

package/source/components/card/passport.json

@@ -12,7 +12,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/index.ts",
       "core/trend.ts",

package/source/components/checkbox/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/agent.ts",
       "core/group.ts",
@@ -23,7 +23,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:864a782462120954cea168efe6df111474541556f8518107677c1098cceaa035"
+    "sourceHash": "sha256:3bb3c0d76ef4b8d42f6b3bc0a3cdd203a90a1662175ec62ae40eba49ce7ad423"
   },
   "purpose": "A single native checkbox, and CheckboxGroup for several that share a name, with mixed state, a select-all and group-level validation.",
   "props": [

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

@@ -5,7 +5,7 @@
   "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.",
+  "$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. Inside an <AgentSurface> the component registers itself with these operations; NumberInput and RadioGroup are then written through their own commit path rather than the element.",
   "operations": {
     "setValue": {
       "summary": "Write a value into the field, as though a person had entered it.",

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

@@ -14,6 +14,7 @@ import {
 } from "react";
 import { useControllableState } from "../../shared/react/useControllableState";
 import { describeField } from "../../shared/core/field";
+import { labelText, useAgentSurfaceField } from "../../shared/react/agentSurfaceContext";
 import type { CheckboxSize, CheckedState } from "../core/types";
 import { CheckboxGroupContext } from "./context";
 import { cx, type CheckboxSlot } from "./props";
@@ -107,6 +108,19 @@ export function Checkbox(props: CheckboxProps) {
     onCheckedChange?.(next);
   };
 
+  // Inside an <AgentSurface>, offered to an agent as a yes/no it can set.
+  useAgentSurfaceField(() => ({
+    contract: {
+      component: "Checkbox",
+      kind: "boolean",
+      label: labelText(label, inputProps["aria-label"], name, value),
+      disabled: disabled || group?.disabled,
+      required,
+      operations: ["setValue", "clear", "focus"],
+    },
+    target: () => inputRef.current,
+  }));
+
   const invalid = Boolean(error) || (group?.invalid ?? false);
   const describedBy = describeField(id, { extra: describedByProp, description, error });
 

package/source/components/combobox/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/agent.ts",
       "core/filter.ts",
@@ -24,9 +24,10 @@
       "react/icons.tsx",
       "react/locale.ts",
       "react/props.ts",
+      "react/surface.ts",
       "react/useCombobox.ts"
     ],
-    "sourceHash": "sha256:5243c2cc6863f8c2dcd248c2fd46417390fec66a8d5b0d405177a372e9c0566f"
+    "sourceHash": "sha256:c8001ea7c65beeed1b50d9f35cb0fcc447d01cea88128dda3d8b3584bd542496"
   },
   "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": [

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

@@ -7,7 +7,7 @@
     "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.",
+  "$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. Inside an <AgentSurface> the component registers itself with these operations; NumberInput and RadioGroup are then written through their own commit path rather than the element.",
   "operations": {
     "setValue": {
       "summary": "Write a value into the field, as though a person had entered it.",

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

@@ -8,6 +8,7 @@ import { Listbox } from "./Listbox";
 import { defaultComboboxText } from "./locale";
 import { ComboboxPopover } from "./Popover";
 import { cx, type ComboboxHandle, type ComboboxSharedProps } from "./props";
+import { useComboboxSurface } from "./surface";
 import { useCombobox } from "./useCombobox";
 
 export interface MultiSelectProps<V extends OptionValue = string> extends ComboboxSharedProps<V> {
@@ -89,6 +90,18 @@ export function MultiSelect<V extends OptionValue = string>(props: MultiSelectPr
   const visibleTags = hidden > 0 ? selectedOptions.slice(0, maxVisibleTags) : selectedOptions;
 
   useImperativeHandle(ref, () => combobox.handle, [combobox.handle]);
+  useComboboxSurface({
+    component: "MultiSelect",
+    label,
+    ariaLabel: props["aria-label"],
+    name,
+    required,
+    disabled,
+    options,
+    mode: props.mode,
+    max: max,
+    handle: combobox.handle,
+  });
 
   const selectableVisible = combobox.entries.filter(
     (entry) => !entry.option.disabled && !combobox.isSelected(entry.option.value),

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

@@ -8,6 +8,7 @@ import { ChevronIcon, XIcon } from "./icons";
 import { Listbox } from "./Listbox";
 import { ComboboxPopover } from "./Popover";
 import { cx, type ComboboxHandle, type ComboboxSharedProps } from "./props";
+import { useComboboxSurface } from "./surface";
 import { useCombobox } from "./useCombobox";
 
 export interface SelectProps<V extends OptionValue = string> extends ComboboxSharedProps<V> {
@@ -83,6 +84,18 @@ export function Select<V extends OptionValue = string>(props: SelectProps<V>) {
   const selected = combobox.selectedOptions[0];
 
   useImperativeHandle(ref, () => combobox.handle, [combobox.handle]);
+  useComboboxSurface({
+    component: "Select",
+    label,
+    ariaLabel: props["aria-label"],
+    name,
+    required,
+    disabled,
+    options,
+    mode: props.mode,
+    max: undefined,
+    handle: combobox.handle,
+  });
 
   return (
     <div

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

@@ -0,0 +1,70 @@
+"use client";
+
+import { labelText, useAgentSurfaceField } from "../../shared/react/agentSurfaceContext";
+import type { ComboboxOption, OptionValue } from "../core/types";
+import type { ComboboxHandle } from "./props";
+
+interface ComboboxSurfaceParams<V extends OptionValue> {
+  component: "Select" | "MultiSelect";
+  label: unknown;
+  ariaLabel: unknown;
+  name?: string;
+  required: boolean;
+  disabled: boolean;
+  options: readonly ComboboxOption<V>[];
+  mode?: "client" | "server";
+  max?: number;
+  handle: ComboboxHandle<V>;
+}
+
+/**
+ * Inside an <AgentSurface>, offer a Select or MultiSelect with its options.
+ *
+ * An agent speaks in strings and an option's value may be a number, so values
+ * are offered as text and mapped back to the option they came from before the
+ * write. In server mode the options are only the current results, so none are
+ * enumerated: the set is the server's, not the component's.
+ */
+export function useComboboxSurface<V extends OptionValue>(params: ComboboxSurfaceParams<V>): void {
+  useAgentSurfaceField(() => {
+    const { component, options, handle } = params;
+    const multiple = component === "MultiSelect";
+    const enumerate = params.mode !== "server";
+    const back = (value: unknown): V => {
+      const text = String(value);
+      return (options.find((option) => String(option.value) === text)?.value ?? text) as V;
+    };
+    return {
+      contract: {
+        component,
+        kind: multiple ? "multiChoice" : "choice",
+        label: labelText(params.label, params.ariaLabel, params.name),
+        disabled: params.disabled,
+        required: params.required,
+        ...(enumerate
+          ? {
+              options: options.map((option) => ({
+                value: String(option.value),
+                label: option.label,
+                ...(option.disabled ? { disabled: true } : {}),
+              })),
+            }
+          : {}),
+        ...(multiple && params.max !== undefined ? { maxSelected: params.max } : {}),
+        operations: ["setValue", "clear", "focus", "open", "close"],
+      },
+      target: () => ({
+        setValue: (next) =>
+          handle.setValue(
+            (next == null ? null : Array.isArray(next) ? next.map(back) : back(next)) as Parameters<
+              ComboboxHandle<V>["setValue"]
+            >[0],
+          ),
+        clear: handle.clear,
+        focus: handle.focus,
+        open: handle.open,
+        close: handle.close,
+      }),
+    };
+  });
+}

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

@@ -14,7 +14,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.3",
     "files": [
       "agent/coerce.ts",
       "agent/contract.ts",
@@ -64,7 +64,7 @@
       "react/keyboard.ts",
       "react/locale.ts"
     ],
-    "sourceHash": "sha256:66dfc75f60791c6e4397d3438ec3ad19ce47f9e5ea51677024200d1f75bd5d44"
+    "sourceHash": "sha256:1047a3723ee462533fa5b82741d89309723cecedc71ea4b1339176a50ced0545"
   },
   "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": [
@@ -93,7 +93,7 @@
       "required": false,
       "default": false,
       "origin": "derived",
-      "description": "Render a natural-language box above the grid.\r\n\r\nNeeds a `<GramproAIProvider>` above it supplying an adapter; without one\r\nthis renders nothing and the grid is unchanged. No model is bundled or\r\ndownloaded — the application brings its own.",
+      "description": "Render a natural-language box above the grid.\n\nNeeds a `<GramproAIProvider>` above it supplying an adapter; without one\nthis renders nothing and the grid is unchanged. No model is bundled or\ndownloaded — the application brings its own.",
       "descriptionOrigin": "jsdoc"
     },
     {
@@ -152,7 +152,7 @@
       "typeText": "ReactNode",
       "required": false,
       "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.",
+      "description": "Shown in place of rows when there are none. Worth distinguishing \"nothing\nhere yet\" from \"nothing matched your filters\", which the default does not.",
       "descriptionOrigin": "jsdoc"
     },
     {
@@ -306,7 +306,7 @@
       "required": false,
       "default": false,
       "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.",
+      "description": "Show the loading treatment over the grid. The existing rows stay in place\nunderneath, so a refresh does not empty the screen.",
       "descriptionOrigin": "jsdoc"
     },
     {
@@ -483,7 +483,7 @@
       "required": false,
       "default": true,
       "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`.",
+      "description": "The toolbar above the grid. `true` for all of it, `false` for none, or an\nobject to choose parts — `{ search: true, export: false }` — and to put\nyour own controls at its `start` or `end`.",
       "descriptionOrigin": "jsdoc"
     }
   ],