@grampro/kit 2.7.1 → 2.7.3

package/source/components/date-picker/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/agent.ts",
       "core/calendar.ts",
@@ -28,9 +28,10 @@
       "react/icons.tsx",
       "react/locale.ts",
       "react/props.ts",
+      "react/surface.ts",
       "react/useDatePicker.ts"
     ],
-    "sourceHash": "sha256:abe15583c9bca1d5cce8aa9a3cbbcfcfd29ad44b7e63a3b66956089dc2d18f72"
+    "sourceHash": "sha256:3e136ee827a03bb66165debb1fd40926d6265f0fb017ef3b7cff60588140d741"
   },
   "purpose": "DatePicker and DateRangePicker: a text field people can type dates into, plus a calendar, both honouring the locale's order and separators.",
   "props": [

package/source/components/date-picker/passport.manual.json

@@ -6,7 +6,7 @@
     "TemporalInterpretation",
     "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/date-picker/react/DatePicker.tsx

@@ -18,6 +18,7 @@ import { CalendarIcon, XIcon } from "./icons";
 import { defaultDatePickerText } from "./locale";
 import { DatePickerPopover } from "./Popover";
 import { cx, type DatePickerHandle, type DatePickerSharedProps } from "./props";
+import { useDateSurface } from "./surface";
 import { useDatePicker } from "./useDatePicker";
 
 export interface DatePickerProps extends DatePickerSharedProps {
@@ -116,8 +117,8 @@ export function DatePicker(props: DatePickerProps) {
   const message = error ?? picker.inputError;
   const invalid = Boolean(message);
 
-  useImperativeHandle(
-    ref,
+  // One handle, for the ref and for an <AgentSurface>.
+  const handle = useMemo<DatePickerHandle<Date | null>>(
     () => ({
       open: () => picker.setOpen(true),
       close: () => picker.setOpen(false),
@@ -134,6 +135,19 @@ export function DatePicker(props: DatePickerProps) {
     }),
     [picker],
   );
+  useImperativeHandle(ref, () => handle, [handle]);
+  useDateSurface({
+    component: "DatePicker",
+    label,
+    name,
+    required,
+    disabled,
+    readOnly,
+    min: minDate,
+    max: maxDate,
+    isDateDisabled,
+    handle,
+  });
 
   const onInputKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
     if (event.key === "ArrowDown" || (event.key === "Enter" && !picker.open)) {

package/source/components/date-picker/react/DateRangePicker.tsx

@@ -18,6 +18,7 @@ import { CalendarIcon, XIcon } from "./icons";
 import { defaultDatePickerText } from "./locale";
 import { DatePickerPopover } from "./Popover";
 import { cx, type DatePickerHandle, type DatePickerSharedProps } from "./props";
+import { useDateSurface } from "./surface";
 import { useDatePicker, type RangeField } from "./useDatePicker";
 
 /** A range as it comes in from props: each end may be a Date, an ISO string or a timestamp. */
@@ -128,8 +129,8 @@ export function DateRangePicker(props: DateRangePickerProps) {
   const invalid = Boolean(message);
   const hasValue = start !== null || end !== null;
 
-  useImperativeHandle(
-    ref,
+  // One handle, for the ref and for an <AgentSurface>.
+  const handle = useMemo<DatePickerHandle<DateRange>>(
     () => ({
       open: () => picker.setOpen(true),
       close: () => picker.setOpen(false),
@@ -144,6 +145,19 @@ export function DateRangePicker(props: DateRangePickerProps) {
     }),
     [picker],
   );
+  useImperativeHandle(ref, () => handle, [handle]);
+  useDateSurface({
+    component: "DateRangePicker",
+    label,
+    name,
+    required,
+    disabled,
+    readOnly,
+    min: minDate,
+    max: maxDate,
+    isDateDisabled,
+    handle,
+  });
 
   const onInputKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
     if (event.key === "ArrowDown" || (event.key === "Enter" && !picker.open)) {

package/source/components/date-picker/react/surface.ts

@@ -0,0 +1,68 @@
+"use client";
+
+import { labelText, useAgentSurfaceField } from "../../shared/react/agentSurfaceContext";
+import { toDate, toISODate } from "../core/calendar";
+import type { DateInput } from "../core/types";
+
+interface DateSurfaceParams {
+  component: "DatePicker" | "DateRangePicker";
+  label: unknown;
+  name?: string;
+  required: boolean;
+  disabled: boolean;
+  readOnly: boolean;
+  min: Date | null;
+  max: Date | null;
+  isDateDisabled?: (date: Date) => boolean;
+  handle: {
+    setValue(value: unknown): void;
+    clear(): void;
+    focus(): void;
+    open(): void;
+    close(): void;
+  };
+}
+
+/**
+ * Inside an <AgentSurface>, offer a date or range field with its bounds.
+ *
+ * `min` and `max` go in the contract, where the validator refuses an
+ * out-of-range day with the reason. `isDateDisabled` is a function and cannot
+ * be described, so it is checked at the write instead: a disabled day is
+ * refused there rather than quietly chosen.
+ */
+export function useDateSurface(params: DateSurfaceParams): void {
+  useAgentSurfaceField(() => {
+    const { component, handle, isDateDisabled } = params;
+    const refuseDisabled = (value: DateInput | null | undefined) => {
+      const date = toDate(value ?? null);
+      if (date && isDateDisabled?.(date)) throw new Error(`${toISODate(date)} is not available in this field.`);
+    };
+    return {
+      contract: {
+        component,
+        kind: component === "DateRangePicker" ? "dateRange" : "date",
+        label: labelText(params.label, params.name),
+        disabled: params.disabled,
+        readOnly: params.readOnly,
+        required: params.required,
+        ...(params.min ? { min: toISODate(params.min) } : {}),
+        ...(params.max ? { max: toISODate(params.max) } : {}),
+        operations: ["setValue", "clear", "focus", "open", "close"],
+      },
+      target: () => ({
+        ...handle,
+        setValue: (next) => {
+          if (next && typeof next === "object") {
+            const range = next as { start?: DateInput; end?: DateInput };
+            refuseDisabled(range.start);
+            refuseDisabled(range.end);
+          } else {
+            refuseDisabled(next as DateInput);
+          }
+          handle.setValue(next);
+        },
+      }),
+    };
+  });
+}

package/source/components/dialog/passport.json

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

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

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

package/source/components/input/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/agent.ts",
       "core/count.ts",
@@ -24,7 +24,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:6d1ef1229a82962e2bd3bf32a15de6f7d9e43c2270e65df9f7303cd74dd479d4"
+    "sourceHash": "sha256:747f35b5f70457677fbc0a0ce1b8c47404e45b4e30a37c4567871fa3b21e16f6"
   },
   "purpose": "A single-line text field with its label, hint and error wired together. OtpInput is the same field split into one box per character for a one-time code.",
   "props": [

package/source/components/input/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/input/react/Input.tsx

@@ -13,6 +13,7 @@ import {
 } from "react";
 import { useControllableState } from "../../shared/react/useControllableState";
 import { describeField } from "../../shared/core/field";
+import { labelText, useAgentSurfaceField } from "../../shared/react/agentSurfaceContext";
 import { countCharacters } from "../core/count";
 import type { FieldSize, InputLocaleText } from "../core/types";
 import { setNativeValue } from "./dom";
@@ -95,6 +96,26 @@ export function Input(props: InputProps) {
   const [current, setCurrent] = useControllableState(valueProp, defaultValue ?? "");
   const [revealed, setRevealed] = useState(false);
 
+  // Inside an <AgentSurface>, offered to an agent with what it accepts now.
+  // A password, a hidden or a file input never is.
+  useAgentSurfaceField(
+    () => ({
+      contract: {
+        component: "Input",
+        kind: "text",
+        label: labelText(label, inputProps["aria-label"], inputProps.name, inputProps.placeholder),
+        disabled,
+        readOnly,
+        required,
+        maxLength,
+        pattern: inputProps.pattern,
+        operations: ["setValue", "clear", "focus"],
+      },
+      target: () => inputRef.current,
+    }),
+    type !== "password" && type !== "hidden" && type !== "file",
+  );
+
   const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
     setCurrent(event.target.value);
     onChange?.(event);

package/source/components/menu/passport.json

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

package/source/components/modal/passport.json

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

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

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/agent.ts",
       "core/format.ts",
@@ -22,7 +22,7 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:b62e20ffb71a95c6e30e7c55f895750de1015364734a3cceacea972e3dc89e6a"
+    "sourceHash": "sha256:e29f16b8317ad5e1ce54a08a1705e24fd0be033344ba8509048b4c168d2f64a4"
   },
   "purpose": "A numeric field that reads and writes numbers the way the locale does, with a stepper, clamping and currency formatting.",
   "props": [

package/source/components/number-input/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/number-input/react/NumberInput.tsx

@@ -16,6 +16,7 @@ import {
   type Ref,
 } from "react";
 import { describeField } from "../../shared/core/field";
+import { labelText, useAgentSurfaceField } from "../../shared/react/agentSurfaceContext";
 import { formatNumber } from "../core/format";
 import { parseNumber, toEditText } from "../core/parse";
 import { clamp, round, snapToStep, stepBy } from "../core/step";
@@ -195,6 +196,35 @@ export function NumberInput(props: NumberInputProps) {
     [decimals, snap, step, min, max, clampBehavior],
   );
 
+  // Inside an <AgentSurface>, offered to an agent as a number with its bounds.
+  // Written as a number through `commit`, not as text into the element: text
+  // would be read in this field's locale, where "1.5" may mean fifteen.
+  useAgentSurfaceField(() => ({
+    contract: {
+      component: "NumberInput",
+      kind: "number",
+      label: labelText(label, inputProps["aria-label"], inputProps.name, placeholder),
+      disabled,
+      readOnly,
+      required,
+      min,
+      max,
+      ...(snap ? { step } : {}),
+      operations: ["setValue", "clear", "focus"],
+    },
+    target: () => ({
+      setValue: (next) => {
+        setDraft(null);
+        commit(next === null || next === undefined ? null : settle(Number(next)));
+      },
+      clear: () => {
+        setDraft(null);
+        commit(null);
+      },
+      focus: () => inputRef.current?.focus(),
+    }),
+  }));
+
   const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
     const typed = event.target.value;
     setDraft(typed);

package/source/components/popover/passport.json

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

package/source/components/progress/passport.json

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

package/source/components/radio-group/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:8630723accbd754b823c4f2d7f5c1c0da02252d3a51f87b8abeaad117bd75064"
+    "sourceHash": "sha256:bcc1323c5e328b91461ef96c6901d41bf0eca3ec6dcf7b96c6ec45a9efa2a155"
   },
   "purpose": "One choice out of a few, on native radios: a single tab stop, arrow keys between the choices, and a card variant for richer options.",
   "props": [

package/source/components/radio-group/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/radio-group/react/RadioGroup.tsx

@@ -3,6 +3,7 @@
 import { useCallback, useId, useMemo, type CSSProperties, type ReactNode } from "react";
 import { useControllableState } from "../../shared/react/useControllableState";
 import { describeField } from "../../shared/core/field";
+import { labelText, useAgentSurfaceField } from "../../shared/react/agentSurfaceContext";
 import { hasEnabledOption, normalizeOptions, resolveValue } from "../core/group";
 import type {
   RadioGroupLocaleText,
@@ -109,6 +110,38 @@ export function RadioGroup(props: RadioGroupProps) {
     [setCurrent, onValueChange],
   );
 
+  // Inside an <AgentSurface>, offered to an agent as one choice among the
+  // options. Written through `commit`, as a click is: a radio element would be
+  // only one of the choices.
+  useAgentSurfaceField(() => ({
+    contract: {
+      component: "RadioGroup",
+      kind: "choice",
+      label: labelText(label, nameProp),
+      disabled,
+      required,
+      ...(items
+        ? {
+            options: items.map((option) => ({
+              value: option.value,
+              label: labelText(option.label) ?? option.value,
+              ...(option.disabled ? { disabled: true } : {}),
+            })),
+          }
+        : {}),
+      operations: ["setValue", "clear", "focus"],
+    },
+    target: () => ({
+      setValue: (next) => commit(next === null || next === undefined ? null : String(next)),
+      clear: () => commit(null),
+      focus: () => {
+        const group = document.getElementById(id);
+        const radio = group?.querySelector<HTMLInputElement>("input:checked") ?? group?.querySelector("input");
+        radio?.focus();
+      },
+    }),
+  }));
+
   const context = useMemo<RadioGroupContextValue>(
     () => ({
       value: selected,