@grampro/kit 0.0.0-stage → 2.4.0

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

@@ -0,0 +1,107 @@
+/*
+ * The DataGrid's WebMCP tool.
+ *
+ * All of the mechanism lives in `shared/core/agent/webmcp`. What belongs here
+ * is only what is true of a grid: the tool's name, how to describe this grid
+ * to an agent in words, and which numbers a successful call should report.
+ *
+ * Framework-free, like the rest of `agent/` — no React import, so a host can
+ * register the tool from an effect, a router, or not at all.
+ */
+
+import {
+  registerAgentTool,
+  type ModelContext,
+  type RegistrationResult,
+  type ToolCallLog,
+} from "../../shared/core/agent/webmcp";
+import type { GridAgent } from "./engine";
+
+/*
+ * Re-exported so a host that only imports from `data-grid` has every type that
+ * appears in this module's options and results.
+ */
+export type {
+  ModelContext,
+  RegistrationResult,
+  ToolCallLog,
+  ToolResultPayload,
+} from "../../shared/core/agent/webmcp";
+
+export const GRID_TOOL_NAME = "operate_grid";
+
+export interface RegisterGridToolOptions {
+  /** Override the tool name when a page carries more than one grid. */
+  name?: string;
+  /** Observe every call, for a UI log or a test. */
+  onCall?: (entry: ToolCallLog) => void;
+  /** Where to register. Defaults to `document.modelContext`. */
+  modelContext?: ModelContext;
+  /** How many operations an agent may send in one call. Default 8. */
+  maxIntents?: number;
+}
+
+/**
+ * How the grid introduces itself to an agent.
+ *
+ * Built from the live contract rather than written once, so a grid with
+ * different columns advertises different columns. Policy-restricted fields are
+ * absent from the generated schema entirely, so they are not listed here
+ * either — an agent should not be told about a column it cannot address.
+ */
+function describeGrid(agent: GridAgent<unknown>): string {
+  const contract = agent.contract();
+  const columns = contract.columns
+    .filter((column) => column.filterable || column.sortable)
+    .map((column) => column.id)
+    .join(", ");
+
+  return [
+    "Filter, sort, search, paginate, select rows in, or export the data grid on this page.",
+    `Columns: ${columns}.`,
+    `Operations: ${contract.operations.join(", ")}.`,
+    'Values may be written as a person would — "1 lakh", "20%", "last month" — and are',
+    "converted exactly. Every call is validated before anything happens; an invalid request",
+    "is refused with a reason rather than approximated.",
+  ].join(" ");
+}
+
+/**
+ * Registers `operate_grid` against the browser's WebMCP surface.
+ *
+ * Returns rather than throws when WebMCP is absent, because that is the normal
+ * case in most browsers today: the caller shows the grid regardless and the
+ * agent affordance is simply not there.
+ *
+ * ```ts
+ * const agent = createGridAgent({ api: apiRef.current, options });
+ * const result = registerGridTool(agent);
+ * if (!result.registered) console.info(result.reason);
+ * ```
+ *
+ * One tool per page: WebMCP throws on a duplicate name, and React's
+ * StrictMode runs effects twice in development, so guard the call with a ref
+ * or register outside the render path.
+ */
+export function registerGridTool(
+  agent: GridAgent<unknown>,
+  options: RegisterGridToolOptions = {},
+): RegistrationResult {
+  return registerAgentTool(agent, {
+    name: options.name ?? GRID_TOOL_NAME,
+    describe: describeGrid,
+    maxIntents: options.maxIntents,
+    intentsDescription:
+      "Operations to apply in order. Several filters on different columns combine with AND.",
+    summarise: (current) => {
+      const contract = current.contract();
+      return {
+        rowsShowing: contract.stats.filteredRows,
+        rowsTotal: contract.stats.totalRows,
+        canUndo: contract.state.canUndo,
+      };
+    },
+    onCall: options.onCall,
+    modelContext: options.modelContext,
+  });
+}

package/source/components/data-grid/core/columnHelper.ts

@@ -0,0 +1,21 @@
+import type { ColumnDef } from "./types";
+
+type Base<T, V> = Omit<ColumnDef<T, V>, "id" | "field" | "accessor">;
+
+/**
+ * Typed column builders: `value` in `cell`, `format`, `validate` and friends is
+ * inferred from the field or accessor.
+ */
+export function createColumnHelper<T>() {
+  return {
+    field<K extends Extract<keyof T, string>>(field: K, def: Base<T, T[K]> & { id?: string } = {}): ColumnDef<T> {
+      return { ...def, field } as unknown as ColumnDef<T>;
+    },
+    accessor<V>(id: string, accessor: (row: T) => V, def: Base<T, V> = {}): ColumnDef<T> {
+      return { ...def, id, accessor } as unknown as ColumnDef<T>;
+    },
+    display(id: string, def: Base<T, undefined>): ColumnDef<T> {
+      return { ...def, id } as unknown as ColumnDef<T>;
+    },
+  };
+}

package/source/components/data-grid/core/columns.ts

@@ -0,0 +1,288 @@
+import type {
+  ColumnDef,
+  ColumnLayout,
+  ColumnLayoutItem,
+  ColumnPinningState,
+  GridState,
+  PinSide,
+  ResolvedColumn,
+} from "./types";
+
+export const SELECTION_COLUMN_ID = "__select__";
+
+const DEFAULT_WIDTH = 160;
+const DEFAULT_MIN_WIDTH = 60;
+const DEFAULT_MAX_WIDTH = 1200;
+
+type LayoutState = Pick<
+  GridState,
+  "columnOrder" | "columnVisibility" | "columnSizing" | "columnPinning"
+>;
+
+export function getColumnId<T>(def: ColumnDef<T>): string {
+  const id = def.id ?? def.field;
+  if (!id) {
+    throw new Error("[DataGrid] Every column needs an `id` or a `field`.");
+  }
+  return id;
+}
+
+function humanize(id: string): string {
+  const spaced = id
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .trim();
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+const clamp = (value: number, min: number, max: number) =>
+  Math.min(max, Math.max(min, value));
+
+export function resolveColumns<T>(
+  defs: readonly ColumnDef<T>[],
+): ResolvedColumn<T>[] {
+  const seen = new Set<string>();
+
+  return defs.map((def) => {
+    const id = getColumnId(def);
+    if (seen.has(id)) {
+      throw new Error(`[DataGrid] Duplicate column id "${id}".`);
+    }
+    seen.add(id);
+
+    const { field, accessor } = def;
+    const hasValue = accessor !== undefined || field !== undefined;
+    const getValue: (row: T) => unknown = accessor
+      ? (row) => accessor(row)
+      : field
+        ? (row) => row[field]
+        : () => undefined;
+    const type = def.type ?? "string";
+    const minWidth = def.minWidth ?? DEFAULT_MIN_WIDTH;
+    const maxWidth = def.maxWidth ?? DEFAULT_MAX_WIDTH;
+
+    return {
+      id,
+      def,
+      header: def.header ?? humanize(id),
+      type,
+      hasValue,
+      getValue,
+      width: clamp(def.width ?? DEFAULT_WIDTH, minWidth, maxWidth),
+      minWidth,
+      maxWidth,
+      align:
+        def.align ??
+        (type === "number" ? "end" : type === "boolean" ? "center" : "start"),
+      sortable: hasValue && def.sortable !== false,
+      filterable: hasValue && def.filterable !== false,
+      resizable: def.resizable !== false,
+      hideable: def.hideable !== false,
+      reorderable: def.reorderable !== false,
+      pinnable: def.pinnable !== false,
+      searchable: hasValue && def.searchable !== false,
+      exportable:
+        (hasValue || def.exportValue !== undefined) && def.exportable !== false,
+      internal: false,
+    };
+  });
+}
+
+export function createSelectionColumn<T>(): ResolvedColumn<T> {
+  return {
+    id: SELECTION_COLUMN_ID,
+    def: { id: SELECTION_COLUMN_ID },
+    header: "",
+    type: "boolean",
+    hasValue: false,
+    getValue: () => undefined,
+    width: 44,
+    minWidth: 44,
+    maxWidth: 44,
+    align: "center",
+    sortable: false,
+    filterable: false,
+    resizable: false,
+    hideable: false,
+    reorderable: false,
+    pinnable: false,
+    searchable: false,
+    exportable: false,
+    internal: true,
+  };
+}
+
+/** Columns in user order: ids from `order` first, the rest in definition order. */
+export function orderColumns<T>(
+  columns: readonly ResolvedColumn<T>[],
+  order: readonly string[],
+): ResolvedColumn<T>[] {
+  if (order.length === 0) return [...columns];
+  const byId = new Map(columns.map((c) => [c.id, c]));
+  const result: ResolvedColumn<T>[] = [];
+  const used = new Set<string>();
+  for (const id of order) {
+    const column = byId.get(id);
+    if (column && !used.has(id)) {
+      result.push(column);
+      used.add(id);
+    }
+  }
+  for (const column of columns) {
+    if (!used.has(column.id)) result.push(column);
+  }
+  return result;
+}
+
+export function getColumnWidth<T>(
+  column: ResolvedColumn<T>,
+  sizing: Record<string, number>,
+): number {
+  const width = sizing[column.id];
+  return width === undefined
+    ? column.width
+    : clamp(width, column.minWidth, column.maxWidth);
+}
+
+export function computeLayout<T>(
+  columns: readonly ResolvedColumn<T>[],
+  state: LayoutState,
+  leading: readonly ResolvedColumn<T>[] = [],
+): ColumnLayout<T> {
+  const byId = new Map(columns.map((c) => [c.id, c]));
+  const isVisible = (c: ResolvedColumn<T> | undefined): c is ResolvedColumn<T> =>
+    c !== undefined && state.columnVisibility[c.id] !== false;
+
+  const pinnedIds = new Set([
+    ...state.columnPinning.left,
+    ...state.columnPinning.right,
+  ]);
+  const leftColumns = [
+    ...leading,
+    ...state.columnPinning.left.map((id) => byId.get(id)).filter(isVisible),
+  ];
+  const rightColumns = state.columnPinning.right
+    .map((id) => byId.get(id))
+    .filter(isVisible);
+  const centerColumns = orderColumns(columns, state.columnOrder).filter(
+    (c) => !pinnedIds.has(c.id) && isVisible(c),
+  );
+
+  let visibleIndex = 0;
+  const build = (
+    section: ResolvedColumn<T>[],
+    pinned: PinSide | false,
+  ): [ColumnLayoutItem<T>[], number] => {
+    let offset = 0;
+    const items = section.map((column) => {
+      const width = getColumnWidth(column, state.columnSizing);
+      const index = visibleIndex++;
+      const style: Record<string, string> = { width: `var(--dg-c${index}-w)` };
+      if (pinned === "left") style.insetInlineStart = `var(--dg-c${index}-o)`;
+      if (pinned === "right") style.insetInlineEnd = `var(--dg-c${index}-o)`;
+      const item = { column, width, pinned, offset, visibleIndex: index, style, pinEdge: false };
+      offset += width;
+      return item;
+    });
+    return [items, offset];
+  };
+
+  const [left, leftWidth] = build(leftColumns, "left");
+  const [center, centerWidth] = build(centerColumns, false);
+  const [right, rightWidth] = build(rightColumns, "right");
+  const lastLeft = left.at(-1);
+  if (lastLeft) lastLeft.pinEdge = true;
+  if (right[0]) right[0].pinEdge = true;
+
+  return {
+    columns: [...left, ...center, ...right],
+    left,
+    center,
+    right,
+    leftWidth,
+    centerWidth,
+    rightWidth,
+    totalWidth: leftWidth + centerWidth + rightWidth,
+  };
+}
+
+/**
+ * CSS custom properties that size and position every column. Resizing only
+ * rewrites these variables, so cells never re-render during a drag.
+ */
+export function getLayoutVars<T>(
+  layout: ColumnLayout<T>,
+  overrides?: Record<string, number>,
+): Record<string, string> {
+  const widthOf = (item: ColumnLayoutItem<T>) =>
+    overrides?.[item.column.id] ?? item.width;
+  const vars: Record<string, string> = {};
+  let total = 0;
+
+  let leftOffset = 0;
+  for (const item of layout.left) {
+    const width = widthOf(item);
+    vars[`--dg-c${item.visibleIndex}-w`] = `${width}px`;
+    vars[`--dg-c${item.visibleIndex}-o`] = `${leftOffset}px`;
+    leftOffset += width;
+  }
+  for (const item of layout.center) {
+    vars[`--dg-c${item.visibleIndex}-w`] = `${widthOf(item)}px`;
+    total += widthOf(item);
+  }
+  let rightOffset = 0;
+  for (let i = layout.right.length - 1; i >= 0; i--) {
+    const item = layout.right[i];
+    const width = widthOf(item);
+    vars[`--dg-c${item.visibleIndex}-w`] = `${width}px`;
+    vars[`--dg-c${item.visibleIndex}-o`] = `${rightOffset}px`;
+    rightOffset += width;
+  }
+
+  total += leftOffset + rightOffset;
+  vars["--dg-total-width"] = `${total}px`;
+  return vars;
+}
+
+export function pinColumn(
+  pinning: ColumnPinningState,
+  columnId: string,
+  side: PinSide | false,
+): ColumnPinningState {
+  const left = pinning.left.filter((id) => id !== columnId);
+  const right = pinning.right.filter((id) => id !== columnId);
+  if (side === "left") left.push(columnId);
+  if (side === "right") right.unshift(columnId);
+  return { left, right };
+}
+
+/** Moves a column next to another one, adopting the target's pin section. */
+export function moveColumn<T>(
+  columns: readonly ResolvedColumn<T>[],
+  state: Pick<GridState, "columnOrder" | "columnPinning">,
+  columnId: string,
+  targetId: string,
+  placement: "before" | "after",
+): Pick<GridState, "columnOrder" | "columnPinning"> {
+  if (columnId === targetId) return state;
+
+  const insert = (ids: string[]) => {
+    const next = ids.filter((id) => id !== columnId);
+    const targetIndex = next.indexOf(targetId);
+    if (targetIndex === -1) return next;
+    next.splice(placement === "before" ? targetIndex : targetIndex + 1, 0, columnId);
+    return next;
+  };
+
+  const { left, right } = state.columnPinning;
+  const stripped = pinColumn(state.columnPinning, columnId, false);
+
+  if (left.includes(targetId)) {
+    return { ...state, columnPinning: { ...stripped, left: insert(stripped.left) } };
+  }
+  if (right.includes(targetId)) {
+    return { ...state, columnPinning: { ...stripped, right: insert(stripped.right) } };
+  }
+  const order = orderColumns(columns, state.columnOrder).map((c) => c.id);
+  return { columnOrder: insert(order), columnPinning: stripped };
+}

package/source/components/data-grid/core/filtering.ts

@@ -0,0 +1,237 @@
+import type {
+  ColumnFilter,
+  FilterOperator,
+  FilterValue,
+  GridRow,
+  ResolvedColumn,
+} from "./types";
+import {
+  formatCellValue,
+  isEmptyValue,
+  startOfDay,
+  startOfNextDay,
+  toTime,
+  type Formatters,
+} from "./values";
+
+const STRING_OPERATORS: FilterOperator[] = [
+  "contains",
+  "notContains",
+  "equals",
+  "notEquals",
+  "startsWith",
+  "endsWith",
+  "isEmpty",
+  "isNotEmpty",
+];
+const NUMBER_OPERATORS: FilterOperator[] = [
+  "equals",
+  "notEquals",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "between",
+  "isEmpty",
+  "isNotEmpty",
+];
+const DATE_OPERATORS: FilterOperator[] = [
+  "equals",
+  "before",
+  "after",
+  "between",
+  "isEmpty",
+  "isNotEmpty",
+];
+
+export function getFilterOperators<T>(column: ResolvedColumn<T>): FilterOperator[] {
+  if (column.def.options) return ["in", "isEmpty", "isNotEmpty"];
+  switch (column.type) {
+    case "number":
+      return NUMBER_OPERATORS;
+    case "date":
+      return DATE_OPERATORS;
+    case "boolean":
+      return ["equals"];
+    default:
+      return STRING_OPERATORS;
+  }
+}
+
+const hasValue = (value: FilterValue | undefined) =>
+  value !== undefined &&
+  value !== null &&
+  value !== "" &&
+  !(Array.isArray(value) && value.length === 0);
+
+/** A filter with no usable value (e.g. an empty text box) matches everything. */
+export function isFilterActive(filter: ColumnFilter): boolean {
+  switch (filter.operator) {
+    case "isEmpty":
+    case "isNotEmpty":
+      return true;
+    case "between":
+      return hasValue(filter.value) || hasValue(filter.value2);
+    default:
+      return hasValue(filter.value);
+  }
+}
+
+const toNumber = (value: unknown): number | null => {
+  if (value === null || value === undefined || value === "") return null;
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isNaN(n) ? null : n;
+};
+
+type Predicate<T> = (row: T) => boolean;
+
+export function compileFilter<T>(
+  column: ResolvedColumn<T>,
+  filter: ColumnFilter,
+  formatters: Formatters,
+): Predicate<T> | null {
+  if (!isFilterActive(filter)) return null;
+
+  const { getValue } = column;
+  const { filterFn } = column.def;
+  if (filterFn) return (row) => filterFn(getValue(row), filter, row);
+
+  const { operator } = filter;
+  if (operator === "isEmpty") return (row) => isEmptyValue(getValue(row));
+  if (operator === "isNotEmpty") return (row) => !isEmptyValue(getValue(row));
+
+  if (operator === "in") {
+    const values = Array.isArray(filter.value) ? filter.value : [filter.value];
+    const allowed = new Set(values.map(String));
+    return (row) => allowed.has(String(getValue(row)));
+  }
+
+  switch (column.type) {
+    case "number": {
+      const a = toNumber(filter.value);
+      const b = toNumber(filter.value2);
+      return (row) => {
+        const v = toNumber(getValue(row));
+        if (v === null) return operator === "notEquals";
+        switch (operator) {
+          case "equals": return a === null || v === a;
+          case "notEquals": return a === null || v !== a;
+          case "gt": return a === null || v > a;
+          case "gte": return a === null || v >= a;
+          case "lt": return a === null || v < a;
+          case "lte": return a === null || v <= a;
+          case "between": return (a === null || v >= a) && (b === null || v <= b);
+          default: return true;
+        }
+      };
+    }
+
+    case "date": {
+      const a = toTime(filter.value);
+      const b = toTime(filter.value2);
+      const aStart = a === null ? null : startOfDay(a);
+      const aEnd = a === null ? null : startOfNextDay(a);
+      const bEnd = b === null ? null : startOfNextDay(b);
+      return (row) => {
+        const t = toTime(getValue(row));
+        if (t === null) return false;
+        switch (operator) {
+          case "equals": return aStart === null || (t >= aStart && t < aEnd!);
+          case "before": return aStart === null || t < aStart;
+          case "after": return aEnd === null || t >= aEnd;
+          case "between":
+            return (aStart === null || t >= aStart) && (bEnd === null || t < bEnd);
+          default: return true;
+        }
+      };
+    }
+
+    case "boolean": {
+      const wanted = filter.value === true || filter.value === "true";
+      return (row) => Boolean(getValue(row)) === wanted;
+    }
+
+    default: {
+      const needle = String(filter.value).toLocaleLowerCase();
+      const text = (row: T) =>
+        formatCellValue(column, getValue(row), row, formatters).toLocaleLowerCase();
+      switch (operator) {
+        case "contains": return (row) => text(row).includes(needle);
+        case "notContains": return (row) => !text(row).includes(needle);
+        case "equals": return (row) => text(row) === needle;
+        case "notEquals": return (row) => text(row) !== needle;
+        case "startsWith": return (row) => text(row).startsWith(needle);
+        case "endsWith": return (row) => text(row).endsWith(needle);
+        default: return null;
+      }
+    }
+  }
+}
+
+/**
+ * Search text per row, built once per (columns, formatters) and reused across
+ * keystrokes. Rows are rebuilt when `data` changes, which invalidates the cache.
+ */
+const searchCache = new WeakMap<
+  readonly ResolvedColumn<unknown>[],
+  { formatters: Formatters; text: WeakMap<object, string> }
+>();
+
+function getSearchText<T>(
+  row: GridRow<T>,
+  columns: readonly ResolvedColumn<T>[],
+  formatters: Formatters,
+): string {
+  const key = columns as readonly ResolvedColumn<unknown>[];
+  let entry = searchCache.get(key);
+  if (!entry || entry.formatters !== formatters) {
+    entry = { formatters, text: new WeakMap() };
+    searchCache.set(key, entry);
+  }
+  let text = entry.text.get(row);
+  if (text === undefined) {
+    const parts: string[] = [];
+    for (const column of columns) {
+      if (!column.searchable) continue;
+      const value = column.getValue(row.original);
+      parts.push(formatCellValue(column, value, row.original, formatters));
+    }
+    text = parts.join("
").toLocaleLowerCase();
+    entry.text.set(row, text);
+  }
+  return text;
+}
+
+/** Applies column filters (AND) and the global search (every term must match). */
+export function filterRows<T>(
+  rows: GridRow<T>[],
+  columns: readonly ResolvedColumn<T>[],
+  filters: readonly ColumnFilter[],
+  globalFilter: string,
+  formatters: Formatters,
+): GridRow<T>[] {
+  const byId = new Map(columns.map((c) => [c.id, c]));
+  const predicates: Predicate<T>[] = [];
+  for (const filter of filters) {
+    const column = byId.get(filter.columnId);
+    const predicate = column && compileFilter(column, filter, formatters);
+    if (predicate) predicates.push(predicate);
+  }
+  const terms = globalFilter.trim().toLocaleLowerCase().split(/\s+/).filter(Boolean);
+
+  // Returning the same array keeps downstream memoization intact.
+  if (predicates.length === 0 && terms.length === 0) return rows;
+
+  return rows.filter((row) => {
+    for (const predicate of predicates) {
+      if (!predicate(row.original)) return false;
+    }
+    if (terms.length > 0) {
+      const text = getSearchText(row, columns, formatters);
+      for (const term of terms) {
+        if (!text.includes(term)) return false;
+      }
+    }
+    return true;
+  });
+}