@opencorestack/opengridx 3.3.0 → 3.4.0

package/lib/ai/coerce.ts

@@ -0,0 +1,90 @@
+// Value coercion for the AI validator. Text goes through the same parsers as clipboard paste
+// (`lib/utils/parsing.ts`), so a value the grid accepts from Excel is accepted from a model and the
+// other way round. Model output is JSON, so typed values (a number, a boolean, a Date) are taken as
+// they are. Empty input is valid: null, or '' for text columns.
+import {
+  parseBooleanText,
+  parseDateText,
+  parseNumberText,
+  parseSingleSelectText,
+  type GridParsedValue,
+} from '../utils/parsing';
+
+export type CoerceResult<T = unknown> = { ok: true; value: T } | { ok: false; reason: 'invalidValue' };
+
+/** The column properties coercion reads. */
+export interface CoerceColumn {
+  type?: string;
+  valueOptions?: readonly (string | number | { value: unknown; label: string })[];
+}
+
+const ok = <T>(value: T): CoerceResult<T> => ({ ok: true, value });
+const INVALID: CoerceResult<never> = { ok: false, reason: 'invalidValue' };
+
+const fromParsed = <T>(parsed: GridParsedValue): CoerceResult<T> =>
+  parsed.ok ? ok(parsed.value as T) : INVALID;
+
+function isBlank(text: unknown): boolean {
+  return text == null || (typeof text === 'string' && text.trim() === '');
+}
+
+/** `string` and `image` columns: text as is. Numbers and booleans become their text. */
+export function coerceString(text: unknown): CoerceResult<string> {
+  if (text == null) return ok('');
+  if (typeof text === 'string') return ok(text);
+  if (typeof text === 'number' || typeof text === 'boolean') return ok(String(text));
+  return INVALID;
+}
+
+/** `number` columns: a finite number, or text in the paste format (`1,234.5`, `12%`, `$40`). */
+export function coerceNumber(text: unknown): CoerceResult<number | null> {
+  if (isBlank(text)) return ok(null);
+  if (typeof text === 'number') return Number.isFinite(text) ? ok(text) : INVALID;
+  if (typeof text !== 'string') return INVALID;
+  return fromParsed(parseNumberText(text));
+}
+
+/** `date` columns: a Date, epoch milliseconds, or text in the paste format (ISO `2026-10-07` …). */
+export function coerceDate(text: unknown): CoerceResult<Date | null> {
+  if (isBlank(text)) return ok(null);
+  if (text instanceof Date) return Number.isNaN(text.getTime()) ? INVALID : ok(text);
+  if (typeof text === 'number') return Number.isFinite(text) ? ok(new Date(text)) : INVALID;
+  if (typeof text !== 'string') return INVALID;
+  return fromParsed(parseDateText(text));
+}
+
+/** `boolean` columns: a boolean, or `true`/`false`, `yes`/`no`, `1`/`0` (case-insensitive). */
+export function coerceBoolean(text: unknown): CoerceResult<boolean | null> {
+  if (isBlank(text)) return ok(null);
+  if (typeof text === 'boolean') return ok(text);
+  if (typeof text !== 'string' && typeof text !== 'number') return INVALID;
+  return fromParsed(parseBooleanText(String(text)));
+}
+
+/**
+ * `singleSelect` columns: an option value or label, case-insensitive; returns the option's value.
+ * Without `valueOptions` the model has nothing to choose from, so any scalar is kept as it is.
+ */
+export function coerceSingleSelect(text: unknown, colDef: CoerceColumn): CoerceResult<unknown> {
+  if (isBlank(text)) return ok(null);
+  if (typeof text !== 'string' && typeof text !== 'number' && typeof text !== 'boolean') return INVALID;
+  const options = colDef.valueOptions;
+  if (!options || options.length === 0) return ok(text);
+  return fromParsed(parseSingleSelectText(String(text), options));
+}
+
+/** Coerces `text` for the column's `type`. */
+export function coerceValue(text: unknown, colDef: CoerceColumn): CoerceResult<unknown> {
+  switch (colDef.type) {
+    case 'number':
+      return coerceNumber(text);
+    case 'date':
+      return coerceDate(text);
+    case 'boolean':
+      return coerceBoolean(text);
+    case 'singleSelect':
+      return coerceSingleSelect(text, colDef);
+    default:
+      return coerceString(text);
+  }
+}

package/lib/ai/columns.ts

@@ -0,0 +1,90 @@
+// Which columns may take part in each part of the state. The schema and the validator both read
+// these, so the model is never offered a field the validator would drop.
+import { getOperatorsForType } from '../utils/filtering';
+import type { GridFilterOperator, GridPivotAggFn } from '../types';
+import type { GridAiColumn, GridAiPart, GridAiPartOptions } from './types';
+
+/** The built-in aggregation functions (`AGGREGATION_FUNCTIONS` in lib/utils/aggregation). */
+export const AGGREGATION_FNS: readonly string[] = ['sum', 'avg', 'count', 'min', 'max', 'unique'];
+/** The functions a pivot value field takes (`GridPivotAggFn`). */
+export const PIVOT_FNS: readonly GridPivotAggFn[] = ['sum', 'avg', 'count', 'min', 'max'];
+/** Operators without a value. */
+export const NO_VALUE_OPS: readonly string[] = ['isEmpty', 'isNotEmpty'];
+/** Deepest nesting of filter groups. */
+export const MAX_FILTER_DEPTH = 3;
+
+export const ALL_PARTS: readonly GridAiPart[] = ['filter', 'sort', 'grouping', 'aggregation', 'pivot', 'columnVisibility'];
+
+/** State key of each part, in output order. */
+export const PART_KEYS: Record<GridAiPart, string> = {
+  filter: 'filterModel',
+  sort: 'sortModel',
+  grouping: 'rowGroupingModel',
+  aggregation: 'aggregationModel',
+  pivot: 'pivotModel',
+  columnVisibility: 'columnVisibilityModel',
+};
+
+export function hasOwn(obj: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function selectedParts(options: GridAiPartOptions | undefined): GridAiPart[] {
+  const include = Array.isArray(options?.include) ? options.include : ALL_PARTS;
+  const exclude = Array.isArray(options?.exclude) ? options.exclude : [];
+  return ALL_PARTS.filter((part) => include.includes(part) && !exclude.includes(part));
+}
+
+/**
+ * The usable columns, first one per field. System columns (`__check__`, `__group__`, …), spacers
+ * and fields that are not plain strings are skipped.
+ */
+export function usableColumns(columns: readonly GridAiColumn[] | unknown): GridAiColumn[] {
+  if (!Array.isArray(columns)) return [];
+  const seen = new Set<string>();
+  const out: GridAiColumn[] = [];
+  for (const col of columns as unknown[]) {
+    if (!isPlainObject(col)) continue;
+    const field = col.field;
+    if (typeof field !== 'string' || field === '' || field.startsWith('__') || col.isSpacer === true || seen.has(field)) continue;
+    seen.add(field);
+    out.push(col as unknown as GridAiColumn);
+  }
+  return out;
+}
+
+export function operatorsOf(col: GridAiColumn): GridFilterOperator[] {
+  return getOperatorsForType(col.type);
+}
+
+export const isFilterable = (col: GridAiColumn): boolean => col.filterable !== false;
+export const isSortable = (col: GridAiColumn): boolean => col.sortable !== false;
+export const isGroupable = (col: GridAiColumn): boolean => col.groupable !== false;
+export const isHideable = (col: GridAiColumn): boolean => col.hideable !== false;
+
+/**
+ * Aggregation functions for a column, as the Summaries panel offers them: every built-in function
+ * for number columns (or `aggregable: true`), `count` for the others, never with `aggregable: false`,
+ * and limited by `availableAggregationFunctions`.
+ */
+export function aggregationFnsOf(col: GridAiColumn, fns: readonly string[] = AGGREGATION_FNS): string[] {
+  if (col.aggregable === false) return [];
+  const base = col.type === 'number' || col.aggregable === true ? fns : fns.filter((fn) => fn === 'count');
+  const allowed = col.availableAggregationFunctions;
+  return Array.isArray(allowed) ? base.filter((fn) => allowed.includes(fn)) : [...base];
+}
+
+/** JSON-safe option values of a singleSelect column, in order, without duplicates. */
+export function optionValues(col: GridAiColumn): (string | number)[] {
+  const out: (string | number)[] = [];
+  if (!Array.isArray(col.valueOptions)) return out;
+  for (const option of col.valueOptions) {
+    const value: unknown = option !== null && typeof option === 'object' ? option.value : option;
+    if ((typeof value === 'string' || (typeof value === 'number' && Number.isFinite(value))) && !out.includes(value)) out.push(value);
+  }
+  return out;
+}

package/lib/ai/index.ts

@@ -0,0 +1,16 @@
+// @opencorestack/opengridx/ai: schema and validator for driving the grid from a language model.
+// No React, no dependencies and no AI SDK; the app sends the schema to its own model.
+export { getGridAiSchema } from './schema';
+export { validateGridAiState } from './validate';
+export type {
+  GridAiColumn,
+  GridAiJsonSchema,
+  GridAiPart,
+  GridAiPartOptions,
+  GridAiSchema,
+  GridAiSchemaOptions,
+  GridAiState,
+  GridAiValidateOptions,
+  GridAiValidationError,
+  GridAiValidationResult,
+} from './types';

package/lib/ai/schema.ts

@@ -0,0 +1,214 @@
+// getGridAiSchema: a JSON Schema (draft 2020-12) of the grid state a model may produce. Built from
+// the column definitions only; no row data is read. Same columns and options, same schema.
+import {
+  MAX_FILTER_DEPTH,
+  NO_VALUE_OPS,
+  PART_KEYS,
+  PIVOT_FNS,
+  aggregationFnsOf,
+  isFilterable,
+  isGroupable,
+  isHideable,
+  isSortable,
+  operatorsOf,
+  optionValues,
+  selectedParts,
+  usableColumns,
+} from './columns';
+import type { GridAiColumn, GridAiJsonSchema, GridAiPart, GridAiSchema, GridAiSchemaOptions } from './types';
+
+/** Title of every schema. Also the marker `check-bundle` uses to keep this code out of the core bundle. */
+export const GRID_AI_SCHEMA_TITLE = 'OpenGridX grid state';
+
+const MAX_EXAMPLES = 10;
+
+interface Ctx {
+  descriptions: boolean;
+  examples: boolean;
+}
+
+function label(col: GridAiColumn): string {
+  const header = typeof col.headerName === 'string' && col.headerName !== '' ? col.headerName : col.field;
+  const desc = typeof col.description === 'string' && col.description !== '' ? ` (${col.description})` : '';
+  return `${header}${desc}`;
+}
+
+function describe(node: GridAiJsonSchema, text: string, ctx: Ctx): GridAiJsonSchema {
+  return ctx.descriptions ? { ...node, description: text } : node;
+}
+
+function examplesOf(col: GridAiColumn, ctx: Ctx): unknown[] {
+  if (!ctx.examples || !Array.isArray(col.aiExamples)) return [];
+  return col.aiExamples
+    .filter((v) => typeof v === 'string' || typeof v === 'boolean' || (typeof v === 'number' && Number.isFinite(v)))
+    .slice(0, MAX_EXAMPLES);
+}
+
+/** Schema of one filter value for the column's type. */
+function valueSchema(col: GridAiColumn, ctx: Ctx): GridAiJsonSchema {
+  let node: GridAiJsonSchema;
+  switch (col.type) {
+    case 'number':
+      node = { type: 'number' };
+      break;
+    case 'date':
+      node = { type: 'string', format: 'date' };
+      break;
+    case 'boolean':
+      node = { type: 'boolean' };
+      break;
+    case 'singleSelect': {
+      const values = optionValues(col);
+      const one: GridAiJsonSchema = values.length > 0 ? { enum: values } : { type: 'string' };
+      node = { anyOf: [one, { type: 'array', items: one }] };
+      break;
+    }
+    default:
+      node = { type: 'string' };
+  }
+  const examples = examplesOf(col, ctx);
+  return examples.length > 0 ? { ...node, examples } : node;
+}
+
+function filterItemSchema(col: GridAiColumn, ctx: Ctx): GridAiJsonSchema {
+  const operators = operatorsOf(col);
+  const noValue = operators.filter((op) => NO_VALUE_OPS.includes(op));
+  const hint = col.type === 'singleSelect' ? '; isAnyOf takes an array' : '';
+  const ops = noValue.length > 0 ? `${noValue.join(' and ')} take no value${hint}` : hint.slice(2);
+  return describe(
+    {
+      type: 'object',
+      properties: {
+        field: { const: col.field },
+        operator: { enum: operators },
+        value: valueSchema(col, ctx),
+      },
+      required: ['field', 'operator'],
+      additionalProperties: false,
+    },
+    ops ? `${label(col)}: ${ops}` : label(col),
+    ctx,
+  );
+}
+
+function filterSchema(cols: GridAiColumn[], ctx: Ctx, defs: Record<string, GridAiJsonSchema>): GridAiJsonSchema | null {
+  const filterable = cols.filter(isFilterable);
+  const properties: Record<string, GridAiJsonSchema> = {};
+  const logic = { enum: ['and', 'or'] };
+  if (filterable.length > 0) {
+    defs.filterItem = { oneOf: filterable.map((col) => filterItemSchema(col, ctx)) };
+    // Groups are unrolled to MAX_FILTER_DEPTH levels: the deepest one holds items only.
+    for (let depth = MAX_FILTER_DEPTH; depth >= 1; depth--) {
+      const child = depth === MAX_FILTER_DEPTH ? { $ref: '#/$defs/filterItem' } : { anyOf: [{ $ref: '#/$defs/filterItem' }, { $ref: `#/$defs/filterGroup${depth + 1}` }] };
+      defs[`filterGroup${depth}`] = {
+        type: 'object',
+        properties: { logicOperator: logic, items: { type: 'array', items: child } },
+        required: ['logicOperator', 'items'],
+        additionalProperties: false,
+      };
+    }
+    properties.items = { type: 'array', items: { anyOf: [{ $ref: '#/$defs/filterItem' }, { $ref: '#/$defs/filterGroup1' }] } };
+    properties.logicOperator = logic;
+  }
+  properties.quickFilterValues = describe({ type: 'array', items: { type: 'string' } }, 'Words a row must contain, in any column', ctx);
+  return { type: 'object', properties, additionalProperties: false };
+}
+
+function fieldEnum(cols: GridAiColumn[]): GridAiJsonSchema {
+  return { enum: cols.map((c) => c.field) };
+}
+
+function partSchema(part: GridAiPart, cols: GridAiColumn[], ctx: Ctx, defs: Record<string, GridAiJsonSchema>): GridAiJsonSchema | null {
+  switch (part) {
+    case 'filter':
+      return filterSchema(cols, ctx, defs);
+    case 'sort': {
+      const sortable = cols.filter(isSortable);
+      if (sortable.length === 0) return null;
+      return describe(
+        {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: { field: fieldEnum(sortable), sort: { enum: ['asc', 'desc'] } },
+            required: ['field', 'sort'],
+            additionalProperties: false,
+          },
+        },
+        'Most significant first',
+        ctx,
+      );
+    }
+    case 'grouping': {
+      const groupable = cols.filter(isGroupable);
+      if (groupable.length === 0) return null;
+      return describe({ type: 'array', items: fieldEnum(groupable), uniqueItems: true }, 'Outermost first', ctx);
+    }
+    case 'aggregation': {
+      const properties: Record<string, GridAiJsonSchema> = {};
+      for (const col of cols) {
+        const fns = aggregationFnsOf(col);
+        if (fns.length > 0) properties[col.field] = describe({ enum: fns }, label(col), ctx);
+      }
+      if (Object.keys(properties).length === 0) return null;
+      return { type: 'object', properties, additionalProperties: false };
+    }
+    case 'pivot': {
+      const dims = cols.filter(isGroupable);
+      const values = cols
+        .map((col) => ({ col, fns: aggregationFnsOf(col, PIVOT_FNS) }))
+        .filter((v) => v.fns.length > 0)
+        .map(({ col, fns }) => describe({
+          type: 'object',
+          properties: { field: { const: col.field }, aggFn: { enum: fns } },
+          required: ['field', 'aggFn'],
+          additionalProperties: false,
+        }, label(col), ctx));
+      if (dims.length === 0 || values.length === 0) return null;
+      const dimArray = { type: 'array', items: fieldEnum(dims), uniqueItems: true };
+      return {
+        type: 'object',
+        properties: { rowFields: dimArray, columnFields: dimArray, valueFields: { type: 'array', items: { oneOf: values } } },
+        required: ['rowFields', 'columnFields', 'valueFields'],
+        additionalProperties: false,
+      };
+    }
+    case 'columnVisibility': {
+      const properties: Record<string, GridAiJsonSchema> = {};
+      for (const col of cols.filter(isHideable)) properties[col.field] = describe({ type: 'boolean' }, label(col), ctx);
+      if (Object.keys(properties).length === 0) return null;
+      return describe({ type: 'object', properties, additionalProperties: false }, 'false hides a column', ctx);
+    }
+  }
+}
+
+/**
+ * A JSON Schema (draft 2020-12) of the grid state a model may return for these columns: filter,
+ * sort, grouping, aggregation, pivot and column visibility, each limited to the fields, operators
+ * and functions the columns allow. Send it with the user's prompt to a model with structured
+ * output, then pass the reply to `validateGridAiState`. Reads column definitions only, never rows.
+ * @since v3.4
+ */
+export function getGridAiSchema<C extends GridAiColumn>(columns: readonly C[], options: GridAiSchemaOptions = {}): GridAiSchema {
+  const ctx: Ctx = { descriptions: options.descriptions !== false, examples: options.examples !== false };
+  const cols = usableColumns(columns);
+  const defs: Record<string, GridAiJsonSchema> = {};
+  const properties: Record<string, GridAiJsonSchema> = {};
+  for (const part of selectedParts(options)) {
+    const node = partSchema(part, cols, ctx, defs);
+    if (node) properties[PART_KEYS[part]] = node;
+  }
+  const schema: GridAiSchema = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    schemaVersion: 1,
+    title: GRID_AI_SCHEMA_TITLE,
+    type: 'object',
+    properties,
+    additionalProperties: false,
+  };
+  if (ctx.descriptions) {
+    schema.description = 'Grid state to apply. Include only the parts the user asked to change.';
+  }
+  if (Object.keys(defs).length > 0) schema.$defs = defs;
+  return schema;
+}

package/lib/ai/types.ts

@@ -0,0 +1,88 @@
+import type {
+  GridAggregationModel,
+  GridColumnVisibilityModel,
+  GridFilterModel,
+  GridPivotModel,
+  GridRowGroupingModel,
+  GridSortItem,
+} from '../types';
+
+/**
+ * The column properties the AI toolkit reads. A `GridColDef` (typed or untyped) is accepted as is;
+ * renderers, getters and formatters are never called, and no row data is read.
+ * @since v3.4
+ */
+export interface GridAiColumn {
+  field: string;
+  headerName?: string;
+  description?: string;
+  type?: string;
+  filterable?: boolean;
+  sortable?: boolean;
+  groupable?: boolean;
+  hideable?: boolean;
+  aggregable?: boolean;
+  availableAggregationFunctions?: readonly string[];
+  valueOptions?: readonly (string | number | { value: unknown; label: string })[];
+  /** Example values sent to the model. Real data: see `GridColDef.aiExamples`. */
+  aiExamples?: readonly unknown[];
+  /** Internal spacer columns are skipped. */
+  isSpacer?: boolean;
+}
+
+/** A part of the grid state the model may change. */
+export type GridAiPart = 'filter' | 'sort' | 'grouping' | 'aggregation' | 'pivot' | 'columnVisibility';
+
+/** Chooses the parts of the state; `exclude` wins over `include`. Default: every part. */
+export interface GridAiPartOptions {
+  include?: readonly GridAiPart[];
+  exclude?: readonly GridAiPart[];
+}
+
+export interface GridAiSchemaOptions extends GridAiPartOptions {
+  /**
+   * Put each column's `headerName` and `description` into the schema, so the model can map the
+   * user's words ("revenue") to a field (`amt_usd`).
+   * @default true
+   */
+  descriptions?: boolean;
+  /**
+   * Include the columns' `aiExamples`. Columns without `aiExamples` never send example values.
+   * @default true
+   */
+  examples?: boolean;
+}
+
+export type GridAiValidateOptions = GridAiPartOptions;
+
+/** A JSON Schema (draft 2020-12) node. */
+export type GridAiJsonSchema = { [keyword: string]: unknown };
+
+/** The schema returned by `getGridAiSchema`. `schemaVersion` changes when its shape changes. */
+export interface GridAiSchema extends GridAiJsonSchema {
+  $schema: 'https://json-schema.org/draft/2020-12/schema';
+  schemaVersion: 1;
+  type: 'object';
+  properties: Record<string, GridAiJsonSchema>;
+}
+
+/** The validated state: only parts, fields, operators and values the columns allow. */
+export interface GridAiState {
+  filterModel?: GridFilterModel;
+  sortModel?: GridSortItem[];
+  rowGroupingModel?: GridRowGroupingModel;
+  aggregationModel?: GridAggregationModel;
+  pivotModel?: GridPivotModel;
+  columnVisibilityModel?: GridColumnVisibilityModel;
+}
+
+/** One thing the validator dropped or could not use. `path` points into the model output. */
+export interface GridAiValidationError {
+  path: string;
+  message: string;
+}
+
+export interface GridAiValidationResult {
+  state: GridAiState;
+  errors: GridAiValidationError[];
+}