@grampro/kit 0.0.0-stage → 2.4.0

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

@@ -0,0 +1,169 @@
+/*
+ * The vocabulary an agent-operable component shares with its callers.
+ *
+ * Four things are kept apart on purpose, because they change for different
+ * reasons and at different times:
+ *
+ *   OperationDefinition  what a component knows how to do        (static, from the passport)
+ *   RuntimeContract      what this instance can do, right now    (per instance, per render)
+ *   Intent               what the caller is asking for           (untrusted input)
+ *   OperationExecutor    how this instance actually performs it  (per application)
+ *
+ * The last one is the reason this file exists. An operation must not be
+ * welded to an imperative handle: a grid performs `filter` by calling
+ * `GridApi.setFilter`, while a controlled component would perform its
+ * equivalent by calling the host's `onChange`. Same operation, same schema,
+ * different executor. Nothing here mentions either.
+ */
+
+// ---------------------------------------------------------------- JSON Schema
+
+/**
+ * The slice of JSON Schema this library emits and checks. Deliberately small:
+ * it is what a constrained decoder and a validator both need, and no more.
+ */
+export interface JsonSchema {
+  $schema?: string;
+  title?: string;
+  description?: string;
+  type?: JsonSchemaType | readonly JsonSchemaType[];
+  const?: unknown;
+  enum?: readonly unknown[];
+  properties?: Readonly<Record<string, JsonSchema>>;
+  required?: readonly string[];
+  additionalProperties?: boolean | JsonSchema;
+  items?: JsonSchema;
+  minItems?: number;
+  maxItems?: number;
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+  pattern?: string;
+  oneOf?: readonly JsonSchema[];
+  anyOf?: readonly JsonSchema[];
+  default?: unknown;
+  examples?: readonly unknown[];
+}
+
+export type JsonSchemaType =
+  | "object"
+  | "array"
+  | "string"
+  | "number"
+  | "integer"
+  | "boolean"
+  | "null";
+
+// ----------------------------------------------------------------- operations
+
+/**
+ * One thing a component can be asked to do. This is the static half of the
+ * contract and mirrors the component's `passport.json` `operations` block.
+ */
+export interface OperationDefinition {
+  readonly name: string;
+  readonly summary: string;
+  /** JSON Schema for the operation's input, minus the `action` discriminator. */
+  readonly input?: JsonSchema;
+  /** Plain-language consequences, for a confirmation prompt. */
+  readonly effects?: readonly string[];
+  /** Whether undoing it is a matter of restoring the previous state. */
+  readonly reversible: boolean;
+  /** Leaves the page: downloads, prints, writes to the clipboard. */
+  readonly requiresConfirmation?: boolean;
+  /**
+   * The imperative method that happens to back this operation, when one does.
+   * Metadata only — never required. An operation performed through host state
+   * has no API method, and that is a normal case, not a gap.
+   */
+  readonly apiMethod?: string;
+}
+
+export interface ExecutionContext<TContract = unknown> {
+  readonly contract: TContract;
+  /** Report what would happen and change nothing. */
+  readonly dryRun: boolean;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * How one instance performs one operation.
+ *
+ * Implementations close over whatever they need — an imperative handle, a
+ * state setter, a transport — and the rest of the pipeline never learns which.
+ */
+export interface OperationExecutor<TInput, TContract = unknown, TResult = void> {
+  readonly operation: string;
+  /** Set only when `execute` really does call that method. */
+  readonly apiMethod?: string;
+  execute(input: TInput, context: ExecutionContext<TContract>): TResult | Promise<TResult>;
+}
+
+/**
+ * An executor in a heterogeneous registry. `never` as the input type is sound
+ * here: a function taking a specific input is assignable to one taking
+ * `never`, so concrete executors slot in without a cast. Callers cast at the
+ * point of dispatch, where the validator has already proved the shape.
+ */
+export type RegisteredExecutor<TContract = unknown> = OperationExecutor<never, TContract, unknown>;
+
+export type ExecutorRegistry<TContract = unknown> = ReadonlyMap<string, RegisteredExecutor<TContract>>;
+
+// ----------------------------------------------------------------- validation
+
+export type ValidationLayer =
+  | "schema"
+  | "reference"
+  | "coercion"
+  | "policy"
+  | "plausibility";
+
+export interface ValidationIssue {
+  layer: ValidationLayer;
+  /** Stable, machine-readable. Messages may be reworded; codes may not. */
+  code: string;
+  message: string;
+  /** JSON pointer-ish path into the intent, when the issue has a location. */
+  path?: string;
+  suggestion?: string;
+}
+
+/** Something the caller should see and agree to before the command runs. */
+export interface ConfirmRequest {
+  code: string;
+  message: string;
+}
+
+export type ValidationResult<TCommand> =
+  | {
+      ok: true;
+      command: TCommand;
+      /** Non-blocking: coercions applied, plausibility notes. */
+      warnings: ValidationIssue[];
+      confirm: ConfirmRequest | null;
+    }
+  | {
+      ok: false;
+      /** The issue that stopped it, flattened for display. */
+      reason: string;
+      code: string;
+      layer: ValidationLayer;
+      suggestion?: string;
+      issues: ValidationIssue[];
+    };
+
+export const ok = <T>(
+  command: T,
+  warnings: ValidationIssue[] = [],
+  confirm: ConfirmRequest | null = null,
+): ValidationResult<T> => ({ ok: true, command, warnings, confirm });
+
+export const fail = <T>(issue: ValidationIssue, issues: ValidationIssue[] = []): ValidationResult<T> => ({
+  ok: false,
+  reason: issue.message,
+  code: issue.code,
+  layer: issue.layer,
+  ...(issue.suggestion ? { suggestion: issue.suggestion } : {}),
+  issues: issues.length > 0 ? issues : [issue],
+});

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

@@ -0,0 +1,328 @@
+/*
+ * WebMCP projection: exposing an already-validated command boundary to
+ * whatever agent is driving the browser.
+ *
+ * This is an adapter and nothing else. It owns no schema, no semantics and no
+ * execution path. The chain stays:
+ *
+ *   component source → passport → runtime contract → intent schema
+ *     → [this file] → the component's validator → its executors → the component
+ *
+ * Nothing here knows about a grid. A component's agent satisfies
+ * `ProjectableAgent` structurally, and everything component-specific arrives
+ * through `describe` and `summarise`.
+ *
+ * Why one tool and not one per operation: the operation list is not the
+ * agent's interface — the generated intent schema is, because that is where
+ * the contract and the validation layers already meet. Twenty-one operations
+ * exposed separately would be twenty-one schemas to keep in step with a
+ * contract that already describes itself.
+ *
+ * Surface notes, each of which cost a wrong run to learn:
+ *
+ *   - It is `document.modelContext`. `navigator.modelContext` was the early
+ *     spelling and is deprecated since Chromium 150.
+ *   - Chrome hands `inputSchema` to the agent as a JSON *string*, and returns
+ *     a tool result as a JSON string. That is the browser's wire format, not
+ *     something to pre-serialise here.
+ *   - It needs `--enable-features=WebMCPTesting`, the
+ *     `chrome://flags/#enable-webmcp-testing` flag, or an origin-trial token.
+ *
+ * The specification is a Draft Community Group Report and is not on the W3C
+ * standards track, so this module is deliberately small and replaceable.
+ */
+
+import type { ConfirmRequest, JsonSchema, ValidationIssue, ValidationLayer } from "./types";
+
+// ----------------------------------------------------------- browser surface
+
+/** One command the validator accepted, in the form this projection reports. */
+export interface ProjectedCommand {
+  readonly intent: unknown;
+  readonly explain: { readonly summary: string };
+}
+
+/**
+ * What the validator answers. Mirrors the component-level execution result;
+ * a component may carry extra fields, which are ignored here.
+ */
+export type ProjectedOutcome =
+  | { status: "done"; commands: readonly ProjectedCommand[]; warnings: readonly ValidationIssue[] }
+  | {
+      status: "needs-confirmation";
+      commands: readonly ProjectedCommand[];
+      warnings: readonly ValidationIssue[];
+      confirm: ConfirmRequest;
+    }
+  | {
+      status: "rejected";
+      reason: string;
+      code: string;
+      layer: ValidationLayer;
+      suggestion?: string;
+    }
+  | { status: "clarify"; question: string; options?: readonly string[] }
+  | { status: "declined"; reason: string };
+
+/**
+ * The part of a component's agent this projection uses.
+ *
+ * Structural on purpose: a DataGrid agent, a DatePicker agent or a test double
+ * satisfies it without importing anything from here.
+ */
+export interface ProjectableAgent {
+  /** The generated per-instance schema for one intent. */
+  schema(): JsonSchema;
+  /** Validate without changing anything. */
+  validate(intent: unknown): ProjectedOutcome;
+  execute(intent: unknown, options?: { confirm?: boolean }): Promise<ProjectedOutcome>;
+}
+
+/** The slice of the WebMCP surface this projection touches. */
+export interface ModelContext {
+  registerTool(descriptor: {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    execute(input: unknown): Promise<unknown>;
+  }): void | Promise<void>;
+  getTools?(): unknown;
+  executeTool?(tool: unknown, input: unknown): Promise<unknown>;
+}
+
+declare global {
+  interface Document {
+    modelContext?: ModelContext;
+  }
+}
+
+// -------------------------------------------------------------------- result
+
+/** What the agent gets back, before the MCP content envelope is put round it. */
+export interface ToolResultPayload extends Record<string, unknown> {
+  ok: boolean;
+  status: string;
+  message: string;
+}
+
+export interface ToolCallLog {
+  readonly input: unknown;
+  readonly result: ToolResultPayload;
+}
+
+export interface RegistrationResult {
+  registered: boolean;
+  toolName: string;
+  /** Why not, when `registered` is false. Safe to show a developer. */
+  reason?: string;
+  /** The schema handed to the agent, for inspection in a test or a UI. */
+  inputSchema?: JsonSchema;
+}
+
+export interface RegisterAgentToolOptions<TAgent extends ProjectableAgent> {
+  /** The tool name the agent sees. One per page. */
+  name: string;
+  /** Natural-language description, built from the live contract. */
+  describe: (agent: TAgent) => string;
+  /** Extra fields merged into a successful result — row counts, undo state. */
+  summarise?: (agent: TAgent) => Record<string, unknown>;
+  /** How many operations may be sent in one call. Default 8. */
+  maxIntents?: number;
+  /** Description for the `intents` array itself. */
+  intentsDescription?: string;
+  /** Observe every call, for a UI log or a test. Must not throw. */
+  onCall?: (entry: ToolCallLog) => void;
+  /**
+   * Where to register. Defaults to `document.modelContext`. Supplying one is
+   * for tests and for hosts that polyfill the surface elsewhere.
+   */
+  modelContext?: ModelContext;
+}
+
+const UNAVAILABLE =
+  "document.modelContext is unavailable. Chrome needs --enable-features=WebMCPTesting, " +
+  "the chrome://flags/#enable-webmcp-testing flag, or an origin-trial token.";
+
+/**
+ * Whether this page can register WebMCP tools at all.
+ *
+ * Guards `document` rather than assuming it: this module is imported by code
+ * that also runs during server rendering, where touching `document` throws.
+ */
+export function webmcpAvailable(modelContext?: ModelContext): boolean {
+  const target = modelContext ?? (typeof document === "undefined" ? undefined : document.modelContext);
+  return typeof target?.registerTool === "function";
+}
+
+/**
+ * The tool's input schema, derived from the live contract.
+ *
+ * Not hand-written. `agent.schema()` is the generated per-instance schema, so
+ * a tool registered against a component with different columns, operators or
+ * policy advertises different arguments automatically.
+ */
+export function buildToolInputSchema(
+  agent: ProjectableAgent,
+  options: { maxIntents?: number; intentsDescription?: string } = {},
+): JsonSchema {
+  return {
+    type: "object",
+    additionalProperties: false,
+    required: ["intents"],
+    properties: {
+      intents: {
+        type: "array",
+        minItems: 1,
+        maxItems: options.maxIntents ?? 8,
+        description:
+          options.intentsDescription ??
+          "Operations to apply in order. Several filters on different fields combine with AND.",
+        items: agent.schema(),
+      },
+    },
+  };
+}
+
+/**
+ * Registers one tool, if the browser has WebMCP.
+ *
+ * `execute` runs the production pipeline and nothing else:
+ *
+ *   validate  → a refusal is returned as the validator wrote it
+ *   confirm   → anything irreversible stops here and asks, rather than running
+ *   execute   → only after validation passed
+ *
+ * There is no repair, no retry, and no path that exists only for WebMCP. An
+ * agent sending something the component cannot do gets the same refusal, with
+ * the same code and layer, that a form would have got.
+ */
+export function registerAgentTool<TAgent extends ProjectableAgent>(
+  agent: TAgent,
+  options: RegisterAgentToolOptions<TAgent>,
+): RegistrationResult {
+  const modelContext =
+    options.modelContext ?? (typeof document === "undefined" ? undefined : document.modelContext);
+
+  if (typeof modelContext?.registerTool !== "function") {
+    return { registered: false, toolName: options.name, reason: UNAVAILABLE };
+  }
+
+  const inputSchema = buildToolInputSchema(agent, options);
+
+  modelContext.registerTool({
+    name: options.name,
+    description: options.describe(agent),
+    inputSchema,
+
+    async execute(rawInput: unknown) {
+      const intents = (rawInput as { intents?: unknown } | null | undefined)?.intents;
+
+      const reply = (payload: ToolResultPayload) => {
+        try {
+          options.onCall?.({ input: rawInput, result: payload });
+        } catch {
+          /* A broken observer must not turn a good command into an error. */
+        }
+        return {
+          // MCP's content shape, so an agent reading text gets something useful…
+          content: [{ type: "text", text: payload.message }],
+          // …and the structured result for anything that wants to inspect it.
+          structuredContent: payload,
+          isError: payload.ok === false,
+        };
+      };
+
+      if (!Array.isArray(intents) || intents.length === 0) {
+        return reply({
+          ok: false,
+          status: "rejected",
+          code: "missing-intents",
+          message: '"intents" must be a non-empty array of operations.',
+        });
+      }
+
+      /* Layer one of the real pipeline. Nothing has touched the component yet. */
+      let checked: ProjectedOutcome;
+      try {
+        checked = agent.validate(intents);
+      } catch (error) {
+        return reply({
+          ok: false,
+          status: "rejected",
+          code: "validator-threw",
+          message: error instanceof Error ? error.message : String(error),
+        });
+      }
+
+      if (checked.status === "rejected") {
+        return reply({
+          ok: false,
+          status: "rejected",
+          code: checked.code,
+          layer: checked.layer,
+          suggestion: checked.suggestion,
+          message: checked.reason,
+        });
+      }
+
+      if (checked.status === "clarify") {
+        return reply({
+          ok: false,
+          status: "clarify",
+          message: checked.question,
+          options: checked.options,
+        });
+      }
+
+      if (checked.status === "declined") {
+        return reply({ ok: false, status: "declined", message: checked.reason });
+      }
+
+      if (checked.status === "needs-confirmation") {
+        /*
+         * An agent does not get to skip a confirmation a person would see. The
+         * component is left untouched and the request is handed back.
+         */
+        return reply({
+          ok: false,
+          status: "needs-confirmation",
+          code: checked.confirm.code,
+          message: checked.confirm.message,
+          explain: checked.commands.map((command) => command.explain.summary),
+        });
+      }
+
+      let run: ProjectedOutcome;
+      try {
+        run = await agent.execute(intents);
+      } catch (error) {
+        return reply({
+          ok: false,
+          status: "failed",
+          code: "executor-threw",
+          message: error instanceof Error ? error.message : String(error),
+        });
+      }
+
+      if (run.status !== "done") {
+        return reply({
+          ok: false,
+          status: run.status,
+          message:
+            "reason" in run ? run.reason : "question" in run ? run.question : run.status,
+        });
+      }
+
+      return reply({
+        ok: true,
+        status: "done",
+        message: run.commands.map((command) => command.explain.summary).join("; "),
+        applied: run.commands.map((command) => command.intent),
+        warnings: run.warnings.map((warning) => `${warning.code}: ${warning.message}`),
+        ...(options.summarise?.(agent) ?? {}),
+      });
+    },
+  });
+
+  return { registered: true, toolName: options.name, inputSchema };
+}

package/source/components/shared/core/cx.ts

@@ -0,0 +1,9 @@
+/**
+ * Joins class names, dropping anything falsy.
+ *
+ * Every component builds its class strings with this, so a `className` or
+ * `classNames` prop that is `undefined` contributes nothing rather than the
+ * string "undefined".
+ */
+export const cx = (...names: (string | false | null | undefined)[]) =>
+  names.filter(Boolean).join(" ");

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

@@ -0,0 +1,35 @@
+import { cx } from "./cx";
+
+export interface DescribedByParts {
+  /** An `aria-describedby` the caller passed in; kept first so it reads first. */
+  extra?: string;
+  /** Renders `#{id}-hint`. */
+  hint?: unknown;
+  /** Renders `#{id}-description`. */
+  description?: unknown;
+  /** Renders `#{id}-error`. */
+  error?: unknown;
+}
+
+/**
+ * The `aria-describedby` for a form control, built from whichever of its hint,
+ * description and error are actually rendered.
+ *
+ * Every control derives the ids the same way (`{id}-description`, `{id}-error`),
+ * so the helper owns both the ids and their order: a screen reader reads the
+ * caller's own description first, then the hint, then ours, and the error last,
+ * which is the part that changes and that the listener is waiting for.
+ *
+ * Returns `undefined` rather than `""` when nothing is described, because an
+ * empty `aria-describedby` still points at nothing and confuses some readers.
+ */
+export function describeField(id: string, parts: DescribedByParts): string | undefined {
+  return (
+    cx(
+      typeof parts.extra === "string" ? parts.extra : "",
+      parts.hint ? `${id}-hint` : "",
+      parts.description ? `${id}-description` : "",
+      parts.error ? `${id}-error` : "",
+    ) || undefined
+  );
+}

package/source/components/shared/core/position.ts

@@ -0,0 +1,124 @@
+/** The side of the anchor a popover is placed on. */
+export type Side = "top" | "bottom" | "left" | "right";
+
+/**
+ * Which edge of the anchor the popover lines up with, in reading order, or
+ * `center` to share its midpoint.
+ */
+export type Align = "start" | "center" | "end";
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+export interface AnchorRect extends Size {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export interface PlacementOptions {
+  /** The side to try first. */
+  side: Side;
+  align: Align;
+  /** Distance between the anchor and the popover. */
+  gap: number;
+  /** Space kept between the popover and the edge of the viewport. */
+  edge: number;
+  /** Mirrors `left`/`right` and swaps which edge `align` means. */
+  rtl: boolean;
+  /**
+   * The content scrolls, so the popover may be capped to the space available
+   * and should prefer whichever side has more of it. Fixed-size panels leave
+   * this off and only move when they fully fit on the other side.
+   */
+  fitHeight: boolean;
+  /** Floor for the cap, so a cramped viewport still shows something. */
+  minHeight: number;
+}
+
+export interface Placement {
+  left: number;
+  top: number;
+  /** Where it actually ended up, which is not the requested side after a flip. */
+  side: Side;
+  /** Only when `fitHeight` asked for one. */
+  maxHeight?: number;
+}
+
+const clamp = (value: number, min: number, max: number) =>
+  Math.min(Math.max(value, min), Math.max(min, max));
+
+/**
+ * Where to put a popover: on the requested side of its anchor, moved to the
+ * opposite side when there is no room, and kept inside the viewport.
+ *
+ * Pure arithmetic, so the rules can be tested without a browser. The caller
+ * measures, this decides, the caller writes the styles.
+ */
+export function placePopover(
+  anchor: AnchorRect,
+  size: Size,
+  viewport: Size,
+  options: PlacementOptions,
+): Placement {
+  const { side, align, gap, edge, rtl, fitHeight, minHeight } = options;
+  const alignEnd = (align === "end") !== rtl;
+
+  /** The cross-axis offset: centred, or against one edge of the anchor. */
+  const across = (start: number, length: number, extent: number) =>
+    align === "center"
+      ? start + (length - extent) / 2
+      : alignEnd
+        ? start + length - extent
+        : start;
+
+  if (side === "top" || side === "bottom") {
+    const roomBelow = viewport.height - anchor.bottom - gap - edge;
+    const roomAbove = anchor.top - gap - edge;
+    const prefersBelow = side === "bottom";
+    const roomPreferred = prefersBelow ? roomBelow : roomAbove;
+    const roomOther = prefersBelow ? roomAbove : roomBelow;
+
+    const flip =
+      size.height > roomPreferred &&
+      (fitHeight ? roomOther > roomPreferred : size.height <= roomOther);
+    const below = prefersBelow !== flip;
+
+    return {
+      side: below ? "bottom" : "top",
+      left: clamp(
+        across(anchor.left, anchor.width, size.width),
+        edge,
+        viewport.width - size.width - edge,
+      ),
+      top: Math.max(edge, below ? anchor.bottom + gap : anchor.top - gap - size.height),
+      maxHeight: fitHeight
+        ? Math.max(minHeight, below ? roomBelow : roomAbove)
+        : undefined,
+    };
+  }
+
+  const roomRight = viewport.width - anchor.right - gap - edge;
+  const roomLeft = anchor.left - gap - edge;
+  const prefersRight = (side === "right") !== rtl;
+  const roomPreferred = prefersRight ? roomRight : roomLeft;
+  const roomOther = prefersRight ? roomLeft : roomRight;
+
+  // Sideways there is nothing to scroll, so it only moves when it fully fits.
+  const flip = size.width > roomPreferred && size.width <= roomOther;
+  const right = prefersRight !== flip;
+
+  return {
+    side: right ? "right" : "left",
+    left: Math.max(edge, right ? anchor.right + gap : anchor.left - gap - size.width),
+    top: clamp(
+      across(anchor.top, anchor.height, size.height),
+      edge,
+      viewport.height - size.height - edge,
+    ),
+    maxHeight: fitHeight ? Math.max(minHeight, viewport.height - 2 * edge) : undefined,
+  };
+}

package/source/components/shared/core/text.ts

@@ -0,0 +1,14 @@
+let segmenter: Intl.Segmenter | null | undefined;
+
+/**
+ * Characters as a person counts them. `"👍🏽".length` is 4 and `"é"` can be 2,
+ * but each is one character here. Falls back to code points where
+ * `Intl.Segmenter` is missing.
+ */
+export function countCharacters(value: string): number {
+  if (!value) return 0;
+  if (segmenter === undefined) {
+    segmenter = typeof Intl !== "undefined" && "Segmenter" in Intl ? new Intl.Segmenter() : null;
+  }
+  return segmenter ? Array.from(segmenter.segment(value)).length : Array.from(value).length;
+}

package/source/components/shared/index.ts

@@ -0,0 +1,17 @@
+export { cx } from "./core/cx";
+export { countCharacters } from "./core/text";
+export { describeField, type DescribedByParts } from "./core/field";
+export { useControllableState } from "./react/useControllableState";
+export { AnchoredPopover, type AnchoredPopoverProps } from "./react/Popover";
+export { placePopover, type Align, type Placement, type Side } from "./core/position";
+export * as icons from "./react/icons";
+export { version as sharedVersion } from "./version";
+
+// Agent runtime: the component-agnostic operation/validation/history layer.
+export * from "./core/agent";
+export {
+  GramproAIProvider,
+  useAgentAdapter,
+  type GramproAIProviderProps,
+} from "./react/GramproAIProvider";
+export { useAskAgent, type AskableAgent, type AskExecution, type UseAskAgent } from "./react/useAskAgent";