@grampro/kit 2.6.3 → 2.7.1

package/source/components/radio-group/passport.manual.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "RadioGroup",
+  "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.",
+  "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 radio semantics: one tab stop for the group, arrow keys to move and select",
+      "a fieldset with the group label as its legend",
+      "description and error linked by aria-describedby"
+    ],
+    "required": [
+      "a `label` for the group — a set of radios with no question is meaningless",
+      "`name`, so the browser treats them as one group"
+    ]
+  },
+  "composition": {
+    "allowedChildren": [
+      "Radio",
+      "RadioCard"
+    ],
+    "notes": "Children or `options`, not both. A radio outside a RadioGroup loses the arrow-key behaviour."
+  },
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "orientation",
+      "variant",
+      "description"
+    ],
+    "forbidden": [
+      "value",
+      "defaultValue",
+      "name",
+      "options",
+      "required",
+      "disabled",
+      "readOnly",
+      "onChange",
+      "onValueChange",
+      "error"
+    ],
+    "rationale": "The selected value is the user's answer and `options` is the question."
+  },
+  "propNotes": {
+    "variant": "`card` renders each option as a selectable surface; the semantics are identical."
+  }
+}

package/source/components/shared/core/agent/field-agent.ts

@@ -0,0 +1,101 @@
+/*
+ * The loop: an intent arrives, the validator rules on it, and only then does
+ * an executor run.
+ *
+ * There is nothing here but that order, which is the whole point. Every route
+ * into a field — a model's proposal, a WebMCP tool call, a test — goes through
+ * this function, so there is one place where "is this allowed" is decided and
+ * no second path that skips it.
+ */
+
+import { fieldOperations, validateFieldIntent } from "./field";
+import type { FieldCommand, FieldContract, FieldIntent } from "./field";
+import type { ExecutorRegistry, ValidationIssue } from "./types";
+
+export interface FieldExecution {
+  readonly ok: boolean;
+  /** What was applied, once the validator agreed to it. */
+  readonly command?: FieldCommand;
+  /** Coercions applied and plausibility notes. Never a reason for refusal. */
+  readonly warnings: readonly ValidationIssue[];
+  /** Present when refused: the reason, in the words the person should see. */
+  readonly reason?: string;
+  readonly code?: string;
+  readonly layer?: ValidationIssue["layer"];
+  readonly suggestion?: string;
+  /** Whatever the executor returned, for a caller that wants it. */
+  readonly result?: unknown;
+}
+
+export interface FieldAgentOptions {
+  readonly contract: FieldContract;
+  readonly executors: ExecutorRegistry<FieldContract>;
+}
+
+export interface FieldAgent {
+  /** What this instance can do, with `setValue` narrowed to its type. */
+  readonly operations: ReturnType<typeof fieldOperations>;
+  readonly contract: FieldContract;
+  /** Validate and, if it passes, perform. */
+  run(intent: FieldIntent, options?: { dryRun?: boolean; signal?: AbortSignal }): Promise<FieldExecution>;
+  /** Validate only. Useful for a confirmation prompt before anything happens. */
+  check(intent: FieldIntent): FieldExecution;
+}
+
+export function createFieldAgent({ contract, executors }: FieldAgentOptions): FieldAgent {
+  const check = (intent: FieldIntent): FieldExecution => {
+    const verdict = validateFieldIntent(intent, contract);
+    if (!verdict.ok) {
+      return {
+        ok: false,
+        warnings: [],
+        reason: verdict.reason,
+        code: verdict.code,
+        layer: verdict.layer,
+        ...(verdict.suggestion ? { suggestion: verdict.suggestion } : {}),
+      };
+    }
+    return { ok: true, command: verdict.command, warnings: verdict.warnings };
+  };
+
+  return {
+    contract,
+    operations: fieldOperations(contract),
+    check,
+    async run(intent, options = {}) {
+      const verdict = check(intent);
+      if (!verdict.ok) return verdict;
+
+      const executor = executors.get(verdict.command!.action);
+      if (!executor) {
+        return {
+          ok: false,
+          warnings: verdict.warnings,
+          reason: `${contract.component} declares "${verdict.command!.action}" but nothing performs it.`,
+          code: "no-executor",
+          layer: "reference",
+        };
+      }
+
+      try {
+        const result = await executor.execute(verdict.command as never, {
+          contract,
+          dryRun: options.dryRun ?? false,
+          ...(options.signal ? { signal: options.signal } : {}),
+        });
+        return { ...verdict, result };
+      } catch (error) {
+        // An executor throwing is a failure to *reach* the field, which is a
+        // different thing from the field refusing — and is reported as such,
+        // so "it is disabled" never reads as "your wording was wrong".
+        return {
+          ok: false,
+          warnings: verdict.warnings,
+          reason: error instanceof Error ? error.message : String(error),
+          code: "execution-failed",
+          layer: "policy",
+        };
+      }
+    },
+  };
+}

package/source/components/shared/core/agent/field-executors.ts

@@ -0,0 +1,137 @@
+/*
+ * How a field actually performs what the validator allowed.
+ *
+ * Two kinds of field exist in this library and the difference is not cosmetic:
+ *
+ *   - Input, Textarea, NumberInput, Checkbox, Switch and Radio hand you the
+ *     DOM element as their ref. They are written through the element.
+ *   - Combobox and DatePicker hand you a handle object, because their value is
+ *     not a string in an input — it is a selection, or a date. They are
+ *     written through that handle.
+ *
+ * Both end up satisfying the same `OperationExecutor`, which is the point of
+ * the executor being a separate thing from the operation. Everything above
+ * this file — the contract, the schemas, the validator, the refusals — is
+ * identical for both, and neither knows which it is driving.
+ */
+
+import { writeChecked, writeValue, writable } from "./write";
+import type { FieldCommand, FieldContract, FieldOperationName } from "./field";
+import type { ExecutionContext, RegisteredExecutor } from "./types";
+
+export type FieldExecutionContext = ExecutionContext<FieldContract>;
+
+/** What a component with a real handle must provide to be driven. */
+export interface FieldHandleTarget {
+  setValue(value: unknown): void;
+  clear?(): void;
+  focus?(): void;
+  open?(): void;
+  close?(): void;
+}
+
+type Registry = Map<string, RegisteredExecutor<FieldContract>>;
+
+const define = (
+  registry: Registry,
+  operation: FieldOperationName,
+  execute: (input: FieldCommand, context: FieldExecutionContext) => unknown,
+) => {
+  registry.set(operation, { operation, execute } as RegisteredExecutor<FieldContract>);
+};
+
+/**
+ * Executors for a field whose ref is the DOM element.
+ *
+ * `getElement` is a function rather than the element itself because the ref is
+ * not populated on the first render, and an executor registry built once must
+ * still work on the tenth.
+ */
+export function domFieldExecutors(
+  getElement: () => HTMLInputElement | HTMLTextAreaElement | null,
+  options: { readonly checkable?: boolean } = {},
+): Registry {
+  const registry: Registry = new Map();
+
+  const element = () => {
+    const found = getElement();
+    if (!found) throw new Error("The field is not mounted.");
+    return found;
+  };
+
+  define(registry, "setValue", (command, context) => {
+    const target = element();
+    if (context.dryRun) return { wouldWrite: command.value };
+    if (!writable(target)) throw new Error("The field is disabled or read-only.");
+    if (options.checkable) writeChecked(target as HTMLInputElement, Boolean(command.value));
+    else writeValue(target, String(command.value ?? ""));
+    return { wrote: command.value };
+  });
+
+  define(registry, "clear", (_command, context) => {
+    const target = element();
+    if (context.dryRun) return { wouldClear: true };
+    if (!writable(target)) throw new Error("The field is disabled or read-only.");
+    if (options.checkable) writeChecked(target as HTMLInputElement, false);
+    else writeValue(target, "");
+    return { cleared: true };
+  });
+
+  define(registry, "focus", (_command, context) => {
+    if (context.dryRun) return { wouldFocus: true };
+    element().focus();
+    return { focused: true };
+  });
+
+  return registry;
+}
+
+/** Executors for a field that exposes a handle object rather than an element. */
+export function handleFieldExecutors(getHandle: () => FieldHandleTarget | null): Registry {
+  const registry: Registry = new Map();
+
+  const handle = () => {
+    const found = getHandle();
+    if (!found) throw new Error("The field is not mounted.");
+    return found;
+  };
+
+  define(registry, "setValue", (command, context) => {
+    const target = handle();
+    if (context.dryRun) return { wouldWrite: command.value };
+    target.setValue(command.value);
+    return { wrote: command.value };
+  });
+
+  define(registry, "clear", (_command, context) => {
+    const target = handle();
+    if (context.dryRun) return { wouldClear: true };
+    // A handle without `clear` still clears: writing null is the same thing.
+    if (target.clear) target.clear();
+    else target.setValue(null);
+    return { cleared: true };
+  });
+
+  define(registry, "focus", (_command, context) => {
+    const target = handle();
+    if (context.dryRun) return { wouldFocus: true };
+    target.focus?.();
+    return { focused: true };
+  });
+
+  define(registry, "open", (_command, context) => {
+    const target = handle();
+    if (context.dryRun) return { wouldOpen: true };
+    target.open?.();
+    return { opened: true };
+  });
+
+  define(registry, "close", (_command, context) => {
+    const target = handle();
+    if (context.dryRun) return { wouldClose: true };
+    target.close?.();
+    return { closed: true };
+  });
+
+  return registry;
+}