@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/data-grid/agent/intent.ts

@@ -0,0 +1,324 @@
+/*
+ * The intent schema, generated per instance.
+ *
+ * A hand-written GridIntent schema would say "operator is one of sixteen
+ * strings" and leave `startsWith` on a revenue column perfectly legal. The
+ * generated one carries a branch per filterable column, each with the operator
+ * set that column's type actually supports, so the illegal pair cannot be
+ * expressed — not merely rejected afterwards. Feed it to a constrained decoder
+ * and a model is physically unable to emit it; feed it to the validator and
+ * the same rule is enforced a second time, because a schema that only lives
+ * in the decoder is a schema you are trusting someone else to run.
+ *
+ * What is strict and what is not:
+ *
+ *   strict        action names, column ids, operator sets per column,
+ *                 export formats, densities, placements, page bounds
+ *   permissive    the *values* people write — "1 lakh", "20%", "kerala"
+ *
+ * Values stay loose here on purpose. Narrowing them in the schema would reject
+ * the input before the coercion layer had a chance to read it, and coercion is
+ * where "1 lakh" becomes 100000 deterministically instead of a model guessing.
+ */
+
+import type { Density, ExportScope, FilterOperator, FilterValue, RowId } from "../core/types";
+import type { JsonSchema } from "../../shared/core/agent";
+import type { GridRuntimeContract } from "./contract";
+import type { GridOperationName } from "./operations";
+
+export type GridIntent =
+  | { action: "search"; text: string }
+  | {
+      action: "filter";
+      column: string;
+      operator: FilterOperator;
+      value?: FilterValue;
+      value2?: FilterValue;
+    }
+  | { action: "clearFilters" }
+  | { action: "sort"; column: string; direction: "asc" | "desc"; append?: boolean }
+  | { action: "clearSort" }
+  | { action: "selectRows"; rowIds: RowId[]; value?: boolean }
+  | { action: "selectAll"; value?: boolean }
+  | { action: "clearSelection" }
+  | { action: "setColumnVisibility"; column: string; visible: boolean }
+  | { action: "pinColumn"; column: string; side: "left" | "right" | null }
+  | { action: "moveColumn"; column: string; target: string; placement: "before" | "after" }
+  | { action: "setColumnWidth"; column: string; width: number | null }
+  | { action: "resetColumns" }
+  | { action: "setPage"; index: number }
+  | { action: "setPageSize"; size: number }
+  | { action: "setDensity"; density: Density }
+  | { action: "export"; format: "csv" | "excel" | "pdf"; scope?: ExportScope; fileName?: string }
+  | { action: "print"; scope?: ExportScope; title?: string }
+  | { action: "copy" }
+  | { action: "undo" }
+  | { action: "redo" };
+
+/** Which column flag an action needs, so a refusal can say why. */
+export const COLUMN_REQUIREMENT: Partial<
+  Record<GridOperationName, "filterable" | "sortable" | "hideable" | "pinnable" | "reorderable" | "resizable">
+> = {
+  filter: "filterable",
+  sort: "sortable",
+  setColumnVisibility: "hideable",
+  pinColumn: "pinnable",
+  moveColumn: "reorderable",
+  setColumnWidth: "resizable",
+};
+
+export interface GeneratedIntentSchema {
+  /** The whole union. Hand this to a constrained decoder. */
+  schema: JsonSchema;
+  /** One entry per action, for targeted error messages. */
+  byAction: Map<GridOperationName, JsonSchema>;
+}
+
+const ANY_VALUE: JsonSchema = {
+  anyOf: [
+    { type: "string" },
+    { type: "number" },
+    { type: "boolean" },
+    { type: "null" },
+    { type: "array", items: { type: ["string", "number"] } },
+  ],
+};
+
+const SCOPE = (): JsonSchema => ({ enum: ["filtered", "all", "selected", "page"] });
+
+const branch = (
+  action: GridOperationName,
+  properties: Record<string, JsonSchema> = {},
+  required: string[] = [],
+  description?: string,
+): JsonSchema => ({
+  type: "object",
+  additionalProperties: false,
+  ...(description ? { description } : {}),
+  required: ["action", ...required],
+  properties: { action: { const: action }, ...properties },
+});
+
+/**
+ * Builds the intent schema for one live contract.
+ *
+ * Deterministic: the only inputs are the contract's columns, capabilities and
+ * page count, and they are walked in order. The same contract always produces
+ * byte-identical JSON.
+ */
+export function buildIntentSchema(contract: GridRuntimeContract): GeneratedIntentSchema {
+  const has = new Set(contract.operations);
+  const byAction = new Map<GridOperationName, JsonSchema>();
+  const ids = (predicate: (column: GridRuntimeContract["columns"][number]) => boolean) =>
+    contract.columns.filter(predicate).map((column) => column.id);
+
+  const add = (action: GridOperationName, schema: JsonSchema | JsonSchema[]) => {
+    if (!has.has(action)) return;
+    const list = Array.isArray(schema) ? schema : [schema];
+    if (list.length === 0) return;
+    byAction.set(action, list.length === 1 ? list[0] : { oneOf: list });
+  };
+
+  add("search", branch("search", { text: { type: "string", maxLength: 200 } }, ["text"]));
+
+  // One branch per filterable column: this is what couples operator to type.
+  add(
+    "filter",
+    contract.columns
+      .filter((column) => column.filterable && column.operators.length > 0)
+      .map((column) =>
+        branch(
+          "filter",
+          {
+            column: { const: column.id },
+            operator: { enum: column.operators as FilterOperator[] },
+            value: ANY_VALUE,
+            value2: ANY_VALUE,
+          },
+          ["column", "operator"],
+          column.description ?? `Filter ${column.label}${column.unit ? ` (${column.unit})` : ""}.`,
+        ),
+      ),
+  );
+
+  add("clearFilters", branch("clearFilters"));
+
+  add(
+    "sort",
+    branch(
+      "sort",
+      {
+        column: { enum: ids((column) => column.sortable) },
+        direction: { enum: ["asc", "desc"] },
+        append: { type: "boolean" },
+      },
+      ["column", "direction"],
+    ),
+  );
+  add("clearSort", branch("clearSort"));
+
+  add(
+    "selectRows",
+    branch(
+      "selectRows",
+      {
+        rowIds: { type: "array", items: { type: "string" }, minItems: 1 },
+        value: { type: "boolean" },
+      },
+      ["rowIds"],
+    ),
+  );
+  add("selectAll", branch("selectAll", { value: { type: "boolean" } }));
+  add("clearSelection", branch("clearSelection"));
+
+  add(
+    "setColumnVisibility",
+    branch(
+      "setColumnVisibility",
+      { column: { enum: ids((column) => column.hideable) }, visible: { type: "boolean" } },
+      ["column", "visible"],
+    ),
+  );
+  add(
+    "pinColumn",
+    branch(
+      "pinColumn",
+      { column: { enum: ids((column) => column.pinnable) }, side: { enum: ["left", "right", null] } },
+      ["column", "side"],
+    ),
+  );
+  add(
+    "moveColumn",
+    branch(
+      "moveColumn",
+      {
+        column: { enum: ids((column) => column.reorderable) },
+        target: { enum: ids(() => true) },
+        placement: { enum: ["before", "after"] },
+      },
+      ["column", "target", "placement"],
+    ),
+  );
+  add(
+    "setColumnWidth",
+    branch(
+      "setColumnWidth",
+      {
+        column: { enum: ids((column) => column.resizable) },
+        width: { type: ["integer", "null"], minimum: 1, maximum: 2000 },
+      },
+      ["column", "width"],
+    ),
+  );
+  add("resetColumns", branch("resetColumns"));
+
+  add(
+    "setPage",
+    branch(
+      "setPage",
+      { index: { type: "integer", minimum: 0, maximum: Math.max(0, contract.state.page.count - 1) } },
+      ["index"],
+    ),
+  );
+  add("setPageSize", branch("setPageSize", { size: { type: "integer", minimum: 1, maximum: 1000 } }, ["size"]));
+  add(
+    "setDensity",
+    branch("setDensity", { density: { enum: ["compact", "standard", "comfortable"] } }, ["density"]),
+  );
+
+  add(
+    "export",
+    branch(
+      "export",
+      {
+        format: { enum: [...contract.capabilities.exportFormats] },
+        scope: SCOPE(),
+        fileName: { type: "string", maxLength: 120 },
+      },
+      ["format"],
+    ),
+  );
+  add("print", branch("print", { scope: SCOPE(), title: { type: "string", maxLength: 120 } }));
+  add("copy", branch("copy"));
+  add("undo", branch("undo"));
+  add("redo", branch("redo"));
+
+  return {
+    schema: {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      title: `GridIntent (${contract.instanceId})`,
+      description:
+        "One operation on this DataGrid instance. Column ids, operators and formats are " +
+        "fixed to what this instance supports; values are read by the validator's coercion layer.",
+      oneOf: [...byAction.values()].flatMap((entry) => (entry.oneOf ? [...entry.oneOf] : [entry])),
+    },
+    byAction,
+  };
+}
+
+/* ------------------------------------------------------------- the envelope */
+
+/**
+ * What a producer of intents — a model, a form, a macro recorder — is allowed
+ * to answer with.
+ *
+ * Three outcomes, not one. A producer that can only return a command has no
+ * way to say "that is ambiguous" or "this grid cannot do that", so it will
+ * guess, and a confident wrong filter is the failure mode the whole validator
+ * exists to prevent. Making refusal and clarification *first-class answers*
+ * rather than error paths is what lets them be measured — and rewarded.
+ */
+export type GridResponse =
+  | { result: "command"; intents: GridIntent[] }
+  | { result: "clarify"; question: string; options?: string[] }
+  | { result: "declined"; reason: string };
+
+/**
+ * The schema a producer is held to, including the two non-command answers.
+ *
+ * Clarifying and declining are validated like anything else: a `clarify` with
+ * no question is not a clarification, it is malformed output wearing a label.
+ */
+export function buildResponseSchema(contract: GridRuntimeContract): JsonSchema {
+  const { schema: intent } = buildIntentSchema(contract);
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: `GridResponse (${contract.instanceId})`,
+    description:
+      "Answer with a command when the request maps onto this grid, clarify when more " +
+      "than one reading is defensible, and decline when this grid cannot do it.",
+    oneOf: [
+      {
+        type: "object",
+        additionalProperties: false,
+        required: ["result", "intents"],
+        description: "One or more operations to apply, in order.",
+        properties: {
+          result: { const: "command" },
+          intents: { type: "array", minItems: 1, maxItems: 8, items: intent },
+        },
+      },
+      {
+        type: "object",
+        additionalProperties: false,
+        required: ["result", "question"],
+        description: "The request has more than one defensible reading on this grid.",
+        properties: {
+          result: { const: "clarify" },
+          question: { type: "string", minLength: 8, maxLength: 300 },
+          options: { type: "array", maxItems: 5, items: { type: "string", maxLength: 120 } },
+        },
+      },
+      {
+        type: "object",
+        additionalProperties: false,
+        required: ["result", "reason"],
+        description: "This grid cannot do what was asked.",
+        properties: {
+          result: { const: "declined" },
+          reason: { type: "string", minLength: 4, maxLength: 300 },
+        },
+      },
+    ],
+  };
+}

package/source/components/data-grid/agent/operations.ts

@@ -0,0 +1,335 @@
+/*
+ * What a DataGrid knows how to do.
+ *
+ * This is the static half of the contract — the same set the component's
+ * `passport.json` publishes, kept here in TypeScript so the runtime and the
+ * passport cannot drift apart (a test asserts they match). The input schemas
+ * are the generic ones; `intent.ts` narrows them against a live instance, so
+ * that a filter on a number column cannot even be expressed with `startsWith`.
+ *
+ * Two rules decide what is in this list:
+ *
+ *   1. It is backed by something the grid really implements. Grouping and
+ *      aggregation are absent because the grid has neither.
+ *   2. `apiMethod` is recorded when, and only when, one `GridApi` method
+ *      performs it. `export` spans three methods, and `undo`/`redo` are the
+ *      agent's own history rather than the grid's — those have none, and that
+ *      is normal, not a gap.
+ */
+
+import type { JsonSchema, OperationDefinition } from "../../shared/core/agent";
+
+export type GridOperationName =
+  | "search"
+  | "filter"
+  | "clearFilters"
+  | "sort"
+  | "clearSort"
+  | "selectRows"
+  | "selectAll"
+  | "clearSelection"
+  | "setColumnVisibility"
+  | "pinColumn"
+  | "moveColumn"
+  | "setColumnWidth"
+  | "resetColumns"
+  | "setPage"
+  | "setPageSize"
+  | "setDensity"
+  | "export"
+  | "print"
+  | "copy"
+  | "undo"
+  | "redo";
+
+export interface GridOperationDefinition extends OperationDefinition {
+  readonly name: GridOperationName;
+  /**
+   * Which grid feature flag has to be on for this instance to offer it.
+   * Undefined means always available.
+   */
+  readonly requires?:
+    | "sorting"
+    | "filtering"
+    | "selection"
+    | "pagination"
+    | "columnHiding"
+    | "columnPinning"
+    | "columnReordering"
+    | "columnResizing";
+}
+
+const COLUMN: JsonSchema = { type: "string", description: "Column id from the runtime contract." };
+
+const SCOPE: JsonSchema = {
+  enum: ["filtered", "all", "selected", "page"],
+  default: "filtered",
+  description: "Which rows to take. `filtered` is everything matching the current query.",
+};
+
+export const GRID_OPERATIONS: Readonly<Record<GridOperationName, GridOperationDefinition>> = {
+  search: {
+    name: "search",
+    summary: "Free-text match across every searchable column.",
+    apiMethod: "setGlobalFilter",
+    requires: "filtering",
+    input: {
+      type: "object",
+      required: ["text"],
+      properties: { text: { type: "string", maxLength: 200 } },
+    },
+    effects: ["filters visible rows", "resets to page 0"],
+    reversible: true,
+  },
+
+  filter: {
+    name: "filter",
+    summary: "Apply a typed filter to one column. Operators are constrained by the column's type.",
+    apiMethod: "setFilter",
+    requires: "filtering",
+    input: {
+      type: "object",
+      required: ["column", "operator"],
+      properties: {
+        column: COLUMN,
+        operator: {
+          enum: [
+            "contains", "notContains", "equals", "notEquals", "startsWith", "endsWith",
+            "gt", "gte", "lt", "lte", "between", "before", "after", "in",
+            "isEmpty", "isNotEmpty",
+          ],
+        },
+        value: {},
+        value2: { description: "Upper bound; only for the `between` operator." },
+      },
+    },
+    effects: ["filters visible rows", "resets to page 0"],
+    reversible: true,
+  },
+
+  clearFilters: {
+    name: "clearFilters",
+    summary: "Remove every column filter and the search text.",
+    apiMethod: "clearFilters",
+    requires: "filtering",
+    effects: ["restores every row"],
+    reversible: true,
+  },
+
+  sort: {
+    name: "sort",
+    summary: "Sort by one column, replacing the current sort unless `append` is set.",
+    apiMethod: "setSorting",
+    requires: "sorting",
+    input: {
+      type: "object",
+      required: ["column", "direction"],
+      properties: {
+        column: COLUMN,
+        direction: { enum: ["asc", "desc"] },
+        append: { type: "boolean", default: false, description: "Add to the existing sort instead of replacing it." },
+      },
+    },
+    effects: ["reorders visible rows"],
+    reversible: true,
+  },
+
+  clearSort: {
+    name: "clearSort",
+    summary: "Return to the data's original order.",
+    apiMethod: "setSorting",
+    requires: "sorting",
+    effects: ["reorders visible rows"],
+    reversible: true,
+  },
+
+  selectRows: {
+    name: "selectRows",
+    summary: "Select or deselect rows by id.",
+    apiMethod: "toggleRowSelected",
+    requires: "selection",
+    input: {
+      type: "object",
+      required: ["rowIds"],
+      properties: {
+        rowIds: { type: "array", items: { type: "string" }, minItems: 1 },
+        value: { type: "boolean", default: true },
+      },
+    },
+    effects: ["changes rowSelection"],
+    reversible: true,
+  },
+
+  selectAll: {
+    name: "selectAll",
+    summary: "Select, or clear, every row matching the current filters.",
+    apiMethod: "toggleAllRowsSelected",
+    requires: "selection",
+    input: { type: "object", properties: { value: { type: "boolean", default: true } } },
+    effects: ["changes rowSelection"],
+    reversible: true,
+  },
+
+  clearSelection: {
+    name: "clearSelection",
+    summary: "Deselect every row.",
+    apiMethod: "clearSelection",
+    requires: "selection",
+    effects: ["changes rowSelection"],
+    reversible: true,
+  },
+
+  setColumnVisibility: {
+    name: "setColumnVisibility",
+    summary: "Show or hide one column.",
+    apiMethod: "setColumnVisibility",
+    requires: "columnHiding",
+    input: {
+      type: "object",
+      required: ["column", "visible"],
+      properties: { column: COLUMN, visible: { type: "boolean" } },
+    },
+    effects: ["changes columnVisibility"],
+    reversible: true,
+  },
+
+  pinColumn: {
+    name: "pinColumn",
+    summary: "Pin a column to an edge, or unpin it with a null side.",
+    apiMethod: "pinColumn",
+    requires: "columnPinning",
+    input: {
+      type: "object",
+      required: ["column", "side"],
+      properties: { column: COLUMN, side: { enum: ["left", "right", null] } },
+    },
+    effects: ["changes columnPinning"],
+    reversible: true,
+  },
+
+  moveColumn: {
+    name: "moveColumn",
+    summary: "Move a column before or after another one.",
+    apiMethod: "moveColumn",
+    requires: "columnReordering",
+    input: {
+      type: "object",
+      required: ["column", "target", "placement"],
+      properties: { column: COLUMN, target: COLUMN, placement: { enum: ["before", "after"] } },
+    },
+    effects: ["changes columnOrder"],
+    reversible: true,
+  },
+
+  setColumnWidth: {
+    name: "setColumnWidth",
+    summary: "Set a column's width in pixels, or null to restore its default.",
+    apiMethod: "setColumnWidth",
+    requires: "columnResizing",
+    input: {
+      type: "object",
+      required: ["column", "width"],
+      properties: { column: COLUMN, width: { type: ["integer", "null"], minimum: 1 } },
+    },
+    effects: ["changes columnSizing"],
+    reversible: true,
+  },
+
+  resetColumns: {
+    name: "resetColumns",
+    summary: "Restore column order, width, visibility and pinning to their defaults.",
+    apiMethod: "resetColumns",
+    effects: ["changes columnOrder", "changes columnVisibility", "changes columnSizing", "changes columnPinning"],
+    reversible: true,
+  },
+
+  setPage: {
+    name: "setPage",
+    summary: "Jump to a page, counting from zero.",
+    apiMethod: "setPageIndex",
+    requires: "pagination",
+    input: { type: "object", required: ["index"], properties: { index: { type: "integer", minimum: 0 } } },
+    effects: ["changes the visible page"],
+    reversible: true,
+  },
+
+  setPageSize: {
+    name: "setPageSize",
+    summary: "Change how many rows a page holds.",
+    apiMethod: "setPageSize",
+    requires: "pagination",
+    input: { type: "object", required: ["size"], properties: { size: { type: "integer", minimum: 1 } } },
+    effects: ["changes the visible page"],
+    reversible: true,
+  },
+
+  setDensity: {
+    name: "setDensity",
+    summary: "Change row height.",
+    apiMethod: "setDensity",
+    input: {
+      type: "object",
+      required: ["density"],
+      properties: { density: { enum: ["compact", "standard", "comfortable"] } },
+    },
+    effects: ["changes row height"],
+    reversible: true,
+  },
+
+  export: {
+    name: "export",
+    summary: "Download the chosen rows as a file.",
+    // Three formats, three GridApi methods — so no single apiMethod applies.
+    input: {
+      type: "object",
+      required: ["format"],
+      properties: {
+        format: { enum: ["csv", "excel", "pdf"] },
+        scope: SCOPE,
+        fileName: { type: "string", maxLength: 120 },
+      },
+    },
+    effects: ["downloads a file"],
+    reversible: false,
+    requiresConfirmation: true,
+  },
+
+  print: {
+    name: "print",
+    summary: "Open the browser's print dialog with the table laid out for paper.",
+    apiMethod: "print",
+    input: { type: "object", properties: { scope: SCOPE, title: { type: "string", maxLength: 120 } } },
+    effects: ["opens the print dialog"],
+    reversible: false,
+    requiresConfirmation: true,
+  },
+
+  copy: {
+    name: "copy",
+    summary: "Copy the selected rows to the clipboard as tab-separated text.",
+    apiMethod: "copyToClipboard",
+    effects: ["writes to the clipboard"],
+    reversible: false,
+    requiresConfirmation: true,
+  },
+
+  undo: {
+    name: "undo",
+    // Performed by the agent's snapshot history, not by the grid.
+    summary: "Restore the state from before the last operation.",
+    effects: ["restores a previous state"],
+    reversible: false,
+  },
+
+  redo: {
+    name: "redo",
+    summary: "Re-apply the operation that was last undone.",
+    effects: ["restores a later state"],
+    reversible: false,
+  },
+};
+
+export const GRID_OPERATION_NAMES = Object.keys(GRID_OPERATIONS) as GridOperationName[];
+
+export const isGridOperation = (name: string): name is GridOperationName =>
+  Object.prototype.hasOwnProperty.call(GRID_OPERATIONS, name);