@grampro/kit 2.6.2 → 2.7.0

package/source/components/shared/core/agent/write.ts

@@ -0,0 +1,58 @@
+/*
+ * Writing to a field the way a person does.
+ *
+ * This is the one file under `agent/` that needs a browser. Everything else
+ * here validates, and validation runs anywhere; executing has to touch
+ * something real. It is kept separate so the split is visible rather than
+ * discovered when a server build fails.
+ *
+ * Why not simply assign `input.value = x`: React tracks the last value it
+ * wrote on the DOM node, and an assignment that bypasses the prototype setter
+ * leaves that tracker in step with the new value. React then concludes nothing
+ * changed and never fires `onChange`, so a controlled field snaps back on the
+ * next render. Going through the prototype setter and dispatching a real
+ * bubbling event is what makes the change indistinguishable from typing — to
+ * React, to form libraries, and to any plain listener.
+ *
+ * `Input.clear()` has worked this way since before there was an agent runtime.
+ * This is the same technique, generalised to textareas and to checkedness.
+ */
+
+type Writable = HTMLInputElement | HTMLTextAreaElement;
+
+/** The prototype that owns the real setter for this element. */
+const prototypeOf = (element: Writable) =>
+  element instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+
+function nativeSetter(element: Writable, property: "value" | "checked") {
+  return Object.getOwnPropertyDescriptor(prototypeOf(element), property)?.set;
+}
+
+/**
+ * Set a field's text through the prototype setter, then fire the events a
+ * person typing would have fired.
+ */
+export function writeValue(element: Writable, value: string): void {
+  nativeSetter(element, "value")?.call(element, value);
+  element.dispatchEvent(new Event("input", { bubbles: true }));
+  element.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
+/**
+ * Set a checkbox or radio, as a click would.
+ *
+ * `checked` rather than `value`, and a `click` is not used: clicking a radio
+ * that is already selected does nothing, and clicking a disabled one is
+ * silently dropped. Setting the property and announcing it is both more
+ * predictable and easier to reason about from a validator's point of view —
+ * by the time this runs, the policy layer has already decided it is allowed.
+ */
+export function writeChecked(element: HTMLInputElement, checked: boolean): void {
+  nativeSetter(element, "checked")?.call(element, checked);
+  element.dispatchEvent(new Event("input", { bubbles: true }));
+  element.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
+/** True when the element can still be written to at all. */
+export const writable = (element: Writable | null | undefined): element is Writable =>
+  Boolean(element) && !(element as Writable).disabled && !(element as Writable).readOnly;

package/source/components/shared/react/useFieldAgent.ts

@@ -0,0 +1,88 @@
+"use client";
+
+/*
+ * Make a field agent-operable without changing the field.
+ *
+ * The DataGrid takes an `agent` prop because a grid's runtime needs to see the
+ * data, the columns and the live state to say anything useful. A field needs
+ * none of that: its contract is its own props, and its executor is the ref the
+ * caller already holds. So this is a hook rather than a prop, and no component
+ * had to grow an API to support it.
+ *
+ *   const ref = useRef<HTMLInputElement>(null);
+ *   const agent = useFieldAgent({
+ *     contract: { component: "Input", kind: "text", operations: ["setValue", "clear", "focus"], maxLength: 80 },
+ *     target: ref,
+ *   });
+ *
+ *   await agent.run({ action: "setValue", value: "Ada Lovelace" });
+ *
+ * `target` is whatever that component's ref gives you. Input, Textarea,
+ * NumberInput, Checkbox, Switch and Radio hand back the DOM element; Combobox
+ * and DatePicker hand back a handle. The hook tells them apart and nothing
+ * above it has to care.
+ */
+
+import { useMemo, useRef } from "react";
+import {
+  createFieldAgent,
+  domFieldExecutors,
+  handleFieldExecutors,
+  type FieldAgent,
+  type FieldContract,
+  type FieldHandleTarget,
+  type RegisteredExecutor,
+} from "../core/agent";
+
+type Target =
+  | { readonly current: HTMLInputElement | HTMLTextAreaElement | null }
+  | { readonly current: FieldHandleTarget | null };
+
+export interface UseFieldAgentOptions {
+  /** What this instance will accept. Rebuild it from props as they change. */
+  readonly contract: FieldContract;
+  /** The component's ref: a DOM element for most fields, a handle for some. */
+  readonly target: Target;
+}
+
+/** A handle, as opposed to a DOM node. Checked by capability, not by instanceof. */
+const isHandle = (value: unknown): value is FieldHandleTarget =>
+  Boolean(value) && typeof (value as FieldHandleTarget).setValue === "function";
+
+export function useFieldAgent({ contract, target }: UseFieldAgentOptions): FieldAgent {
+  // The ref object is stable; its contents are not, and the executors read
+  // them at call time rather than closing over whatever was there on mount.
+  const latest = useRef(target);
+  latest.current = target;
+
+  return useMemo(() => {
+    const read = () => latest.current.current as unknown;
+
+    /*
+     * Which kind of target this is cannot be decided here: a ref is null on
+     * the first render, and deciding then would type every component as a DOM
+     * field and never revisit it. Both registries are built, and the choice is
+     * made inside `execute`, by which point the ref is populated.
+     */
+    const dom = domFieldExecutors(() => read() as HTMLInputElement | HTMLTextAreaElement | null, {
+      checkable: contract.kind === "boolean",
+    });
+    const handle = handleFieldExecutors(() => read() as FieldHandleTarget | null);
+
+    const executors = new Map<string, RegisteredExecutor<FieldContract>>();
+    for (const name of new Set([...dom.keys(), ...handle.keys()])) {
+      executors.set(name, {
+        operation: name,
+        execute: (input, context) => {
+          const chosen = isHandle(read()) ? handle.get(name) : dom.get(name);
+          if (!chosen) throw new Error(`${contract.component} cannot ${name}.`);
+          return chosen.execute(input, context);
+        },
+      } as RegisteredExecutor<FieldContract>);
+    }
+
+    return createFieldAgent({ contract, executors });
+    // The contract is the dependency that matters: a field that has just
+    // become read-only must stop accepting writes on the very next render.
+  }, [contract]);
+}

package/source/components/skeleton/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.2",
+    "libraryVersion": "2.7.0",
     "files": [
       "core/index.ts",
       "core/lines.ts",
@@ -21,6 +21,7 @@
     ],
     "sourceHash": "sha256:c43f854a600cef0e2704513508c60910dbe3938df4b33ec6f2f614b8743055b3"
   },
+  "purpose": "Placeholders in the shape of the content that is loading, plus an Empty state for when there turns out to be nothing.",
   "props": [
     {
       "name": "actions",
@@ -234,20 +235,50 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "placeholders are hidden from assistive technology, so a screen reader is not read a wall of meaningless boxes",
+      "the loading condition is announced once by the region that owns it, rather than by every bar",
+      "Empty renders a heading and an action, not just an illustration"
+    ],
+    "required": [
+      "announce loading on the container, since the skeletons themselves are silent by design",
+      "an Empty state that says what to do next, not only that there is nothing"
+    ]
+  },
+  "composition": {
+    "notes": "Skeletons should match the shape of what replaces them. A layout that jumps when the content arrives is worse than a spinner."
   },
-  "composition": {},
   "operations": {},
   "intentDomains": [],
-  "safeMutations": {},
+  "safeMutations": {
+    "allowed": [
+      "variant",
+      "animation",
+      "width",
+      "height",
+      "radius",
+      "lines",
+      "lastLineWidth",
+      "size",
+      "icon"
+    ],
+    "forbidden": [
+      "label",
+      "description",
+      "actions"
+    ],
+    "rationale": "Shape and animation are entirely presentational, which is unusual here and is why almost everything is allowed. The Empty state's words are content."
+  },
   "examples": [],
   "coverage": {
     "propsTotal": 13,
     "propsDescribed": 13,
     "describedPct": 100,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

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

@@ -0,0 +1,39 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Skeleton",
+  "purpose": "Placeholders in the shape of the content that is loading, plus an Empty state for when there turns out to be nothing.",
+  "intentDomains": [],
+  "accessibility": {
+    "supplied": [
+      "placeholders are hidden from assistive technology, so a screen reader is not read a wall of meaningless boxes",
+      "the loading condition is announced once by the region that owns it, rather than by every bar",
+      "Empty renders a heading and an action, not just an illustration"
+    ],
+    "required": [
+      "announce loading on the container, since the skeletons themselves are silent by design",
+      "an Empty state that says what to do next, not only that there is nothing"
+    ]
+  },
+  "composition": {
+    "notes": "Skeletons should match the shape of what replaces them. A layout that jumps when the content arrives is worse than a spinner."
+  },
+  "safeMutations": {
+    "allowed": [
+      "variant",
+      "animation",
+      "width",
+      "height",
+      "radius",
+      "lines",
+      "lastLineWidth",
+      "size",
+      "icon"
+    ],
+    "forbidden": [
+      "label",
+      "description",
+      "actions"
+    ],
+    "rationale": "Shape and animation are entirely presentational, which is unusual here and is why almost everything is allowed. The Empty state's words are content."
+  }
+}

package/source/components/spinner/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.2",
+    "libraryVersion": "2.7.0",
     "files": [
       "core/index.ts",
       "core/types.ts",
@@ -21,6 +21,7 @@
     ],
     "sourceHash": "sha256:35c2de8415540772f688151782dff3c84c49b7a3d03fd7e575b3d4d4d4e93d85"
   },
+  "purpose": "A loading indicator on its own, beside a label or covering content, with a delay before it appears and a minimum time on screen.",
   "props": [
     {
       "name": "aria-describedby",
@@ -74,7 +75,8 @@
       "default": 0,
       "origin": "derived",
       "description": "Milliseconds to wait before showing, so fast work doesn't flash. Default 0.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Nothing renders before this elapses, which is what stops a spinner flashing on fast connections."
     },
     {
       "name": "hidden",
@@ -226,20 +228,45 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "the spinner graphic is aria-hidden and the label carries the announcement",
+      "a delay before appearing, so fast work never flashes a spinner",
+      "a minimum duration once shown, so it does not flicker out instantly"
+    ],
+    "required": [
+      "a `label` saying what is loading, or `showLabel` where it should be visible too",
+      "use Progress instead when the length is known"
+    ]
+  },
+  "composition": {
+    "notes": "Covering content is a variant of this component rather than a separate overlay."
   },
-  "composition": {},
   "operations": {},
   "intentDomains": [],
-  "safeMutations": {},
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "variant",
+      "delay",
+      "minDuration",
+      "showLabel",
+      "label"
+    ],
+    "forbidden": [
+      "loading"
+    ],
+    "rationale": "Everything here is presentation except whether the work is happening."
+  },
   "examples": [],
   "coverage": {
     "propsTotal": 8,
     "propsDescribed": 8,
     "describedPct": 100,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

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

@@ -0,0 +1,37 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Spinner",
+  "purpose": "A loading indicator on its own, beside a label or covering content, with a delay before it appears and a minimum time on screen.",
+  "intentDomains": [],
+  "accessibility": {
+    "supplied": [
+      "the spinner graphic is aria-hidden and the label carries the announcement",
+      "a delay before appearing, so fast work never flashes a spinner",
+      "a minimum duration once shown, so it does not flicker out instantly"
+    ],
+    "required": [
+      "a `label` saying what is loading, or `showLabel` where it should be visible too",
+      "use Progress instead when the length is known"
+    ]
+  },
+  "composition": {
+    "notes": "Covering content is a variant of this component rather than a separate overlay."
+  },
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "variant",
+      "delay",
+      "minDuration",
+      "showLabel",
+      "label"
+    ],
+    "forbidden": [
+      "loading"
+    ],
+    "rationale": "Everything here is presentation except whether the work is happening."
+  },
+  "propNotes": {
+    "delay": "Nothing renders before this elapses, which is what stops a spinner flashing on fast connections."
+  }
+}

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

@@ -0,0 +1,31 @@
+/*
+ * Switch's agent contract.
+ *
+ * A Switch applies its change as it is flipped, so a write here is the
+ * setting taking effect — not a draft the user will later submit.
+ *
+ * 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 SwitchAgentProps {
+  label?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+}
+
+export function switchContract(props: SwitchAgentProps = {}): FieldContract {
+  return {
+    component: "Switch",
+    kind: "boolean",
+    // No clear: a switch is on or off, and "neither" is not one of its states.
+    operations: ["setValue", "focus"],
+    label: props.label,
+    disabled: props.disabled,
+    readOnly: props.readOnly,
+  };
+}

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

@@ -1,2 +1,4 @@
 export { adopt, idleToggle, request, settle, type ToggleState } from "./toggle";
 export type * from "./types";
+// The agent contract: what a model may ask this field to do.
+export { switchContract, type SwitchAgentProps } from "./agent";

package/source/components/switch/passport.json

@@ -8,8 +8,9 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.2",
+    "libraryVersion": "2.7.0",
     "files": [
+      "core/agent.ts",
       "core/index.ts",
       "core/toggle.ts",
       "core/types.ts",
@@ -18,8 +19,9 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:b2007da7ec91cbad6bd7697048cc205d22e8b94035482a9f631a75e9dabfd0e4"
+    "sourceHash": "sha256:4e168aeb5ca0aef334176cc4edb1b15c63546bf415df867085dadf871f9e24af"
   },
+  "purpose": "A setting that takes effect as it is flipped, on a native checkbox with role=switch, with an optimistic pending state while the change is saved.",
   "props": [
     {
       "name": "aria-describedby",
@@ -190,7 +192,8 @@
       "default": false,
       "origin": "derived",
       "description": "Show the busy state and block presses from outside, e.g. while a form saves.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Managed when the change handler returns a promise. Setting it by hand opts out of that."
     },
     {
       "name": "localeText",
@@ -414,20 +417,75 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "role=switch on a native checkbox, with aria-checked tracking the state",
+      "Space toggles",
+      "the loading state is announced rather than silently blocking the control"
+    ],
+    "required": [
+      "a `label` saying what the setting is, phrased so that on and off are both obvious",
+      "do not use it where the change needs a Save button — that is a Checkbox"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "label"
+    ],
+    "notes": "Renders 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
+    },
+    "focus": {
+      "summary": "Move keyboard focus to the field.",
+      "effects": [
+        "moves focus"
+      ],
+      "reversible": false
+    }
+  },
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "labelPosition",
+      "description"
+    ],
+    "forbidden": [
+      "checked",
+      "defaultChecked",
+      "value",
+      "name",
+      "required",
+      "disabled",
+      "readOnly",
+      "loading",
+      "onChange",
+      "onCheckedChange",
+      "error"
+    ],
+    "rationale": "A Switch applies its change immediately, so writing `checked` is performing the setting, not describing it. `loading` is owned by the component's own async handling."
   },
-  "composition": {},
-  "operations": {},
-  "intentDomains": [],
-  "safeMutations": {},
   "examples": [],
   "coverage": {
     "propsTotal": 11,
     "propsDescribed": 11,
     "describedPct": 100,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "operations",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

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

@@ -0,0 +1,67 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Switch",
+  "purpose": "A setting that takes effect as it is flipped, on a native checkbox with role=switch, with an optimistic pending state while the change is saved.",
+  "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
+    },
+    "focus": {
+      "summary": "Move keyboard focus to the field.",
+      "effects": [
+        "moves focus"
+      ],
+      "reversible": false
+    }
+  },
+  "accessibility": {
+    "supplied": [
+      "role=switch on a native checkbox, with aria-checked tracking the state",
+      "Space toggles",
+      "the loading state is announced rather than silently blocking the control"
+    ],
+    "required": [
+      "a `label` saying what the setting is, phrased so that on and off are both obvious",
+      "do not use it where the change needs a Save button — that is a Checkbox"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "label"
+    ],
+    "notes": "Renders its own label element."
+  },
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "labelPosition",
+      "description"
+    ],
+    "forbidden": [
+      "checked",
+      "defaultChecked",
+      "value",
+      "name",
+      "required",
+      "disabled",
+      "readOnly",
+      "loading",
+      "onChange",
+      "onCheckedChange",
+      "error"
+    ],
+    "rationale": "A Switch applies its change immediately, so writing `checked` is performing the setting, not describing it. `loading` is owned by the component's own async handling."
+  },
+  "propNotes": {
+    "loading": "Managed when the change handler returns a promise. Setting it by hand opts out of that."
+  }
+}