@updog/data-editor-wc 0.1.10 → 0.1.12

package/index.d.ts

@@ -370,37 +370,63 @@ declare var export_default = {
       redo: "Redo",
     },
     validation: {
-      required: "This field is required",
-      invalidNumber: "Invalid number",
-      invalidEmail: "Invalid email address",
-      invalidDate: "Invalid date",
       endDateBeforeStart: "End date must be after start date",
+      invalidDate: "Invalid date",
+      invalidEmail: "Invalid email address",
+      invalidFormat: "Invalid format",
+      invalidNumber: "Invalid number",
+      invalidOption: "Invalid option",
+      outOfRange: "Out of range",
+      required: "This field is required",
       valueMustBeUnique: "Value must be unique",
     },
     license: {
       loading: "Loading data editor",
-      errors: {
-        LICENSE_INVALID: {
+    },
+    connecting: {
+      label: "Connecting to server…",
+    },
+    errors: {
+      RENDER_ERROR: {
+        title: "Something went wrong",
+        text: "Please close this window and try again",
+      },
+      license: {
+        invalid: {
           title: "Invalid license",
           text: "Please contact support for assistance.",
         },
-        MISSING_API_KEY: {
+        missing: {
           title: "Missing API key",
           text: "No API key was provided. Please configure a valid API key.",
         },
-        DOMAIN_NOT_ALLOWED: {
+        domain_not_allowed: {
           title: "Domain not allowed",
           text: "This domain is not authorized for this license. Please check your domain settings.",
         },
-        SUBSCRIPTION_INACTIVE: {
+        subscription_inactive: {
           title: "Subscription inactive",
           text: "Your subscription is no longer active. Please renew to continue.",
         },
       },
-    },
-    errorState: {
-      title: "Something went wrong",
-      text: "Please close this window and try again",
+      scale: {
+        bootstrap_failed: {
+          title: "Couldn't connect to the server",
+          text: "The server returned an error. Please refresh the page or contact support.",
+        },
+        workspace_lost: {
+          title: "Connection lost",
+          text: "The session ended unexpectedly. Refresh the page to reconnect.",
+        },
+        unreachable: {
+          title: "Server unreachable",
+          text: "Check your connection and refresh the page.",
+        },
+        server_error: {
+          title: "Server error",
+          text: "The server returned an error. Please refresh the page or contact support.",
+        },
+      },
     },
     uploader: {
       steps: {
@@ -516,43 +542,6 @@ type ExpandPluralKeys<T> = T extends Record<string, unknown>
  */
 type DataEditorTranslations = DeepPartial<ExpandPluralKeys<typeof export_default>>;
 
-/**
- * Categories of internal errors surfaced through the `onError` callback.
- *
- * - `PARSE_ERROR` — file parsing failed (corrupt CSV, invalid XLSX, etc.).
- * - `RENDER_ERROR` — component render failed (caught by error boundary).
- * - `TRANSFORM_ERROR` — data transformation failed (column transform, value mapping).
- * - `VALIDATION_ERROR` — validation execution failed (validator threw instead of returning).
- * - `WORKER_ERROR` — Web Worker failed (filter worker, chat transform worker).
- * - `COMMAND_ERROR` — undo/redo command failed.
- * - `OPERATION_ERROR` — general operation failed (bulk mutations, imports).
- */
-type UpdogErrorCode = "PARSE_ERROR" | "RENDER_ERROR" | "TRANSFORM_ERROR" | "VALIDATION_ERROR" | "WORKER_ERROR" | "COMMAND_ERROR" | "OPERATION_ERROR";
-/**
- * An internal error caught by the SDK and passed to `onError`. The SDK
- * recovers gracefully where possible — `onError` is for your logging and
- * monitoring (Sentry, Datadog, etc.).
- *
- * @example
- * ```ts
- * onError={(error) => {
- *   Sentry.captureException(error.originalError ?? error, {
- *     tags: { code: error.code, source: error.source },
- *   });
- * }}
- * ```
- */
-type UpdogError = {
-    /** The error category. */
-    code: UpdogErrorCode;
-    /** Human-readable description. */
-    message: string;
-    /** Module or subsystem that raised the error. */
-    source: string;
-    /** The underlying thrown value, when available. */
-    originalError?: unknown;
-};
-
 /**
  * Base row shape. Each key is a column ID, each value is the cell data.
  * Extend this with your own type via the `<DataEditor<TRow>>` generic for
@@ -566,175 +555,66 @@ type UpdogError = {
  * ```
  */
 type DataEditorRow = Record<string, unknown>;
-/** Sort direction. */
-type SortDirection = "asc" | "desc";
-/** Current sort state. `null` means no active sort. */
-type SortState = {
-    columnId: string;
-    direction: SortDirection;
-} | null;
-type Filters = {
-    search: string;
-    matchCase: boolean;
-    matchEntireCell: boolean;
-    errorMessageFilters: string[];
-    showOnlyNewRows: boolean;
-    showOnlyEditedRows: boolean;
-    showOnlyEmptyCells: boolean;
-    /** When true, show only rows flagged for deletion (bin mode). All other filters are bypassed. */
-    showOnlyDeletedRows: boolean;
-    filterColumns: string[] | null;
-    /** Per-column value filters. Key = column ID, value = allowed display-formatted strings. */
-    columnValueFilters: Record<string, string[]>;
-    /** Per-column numeric range filters. Key = column ID. */
-    columnRangeFilters: Record<string, {
-        min?: number;
-        max?: number;
-    }>;
-    /** Per-column date range filters. Key = column ID, values are ISO date strings (YYYY-MM-DD). */
-    columnDateRangeFilters: Record<string, {
-        min?: string;
-        max?: string;
-    }>;
-};
 
 /**
- * A single operation the LLM wants to apply to rows in the current filtered view.
- *
- * - `edit` — `fn` is `(r, ctx) => void`. Mutates `r` in place. Changed fields
- *   become column deltas. Rows with no changes are no-ops.
- * - `delete` — `fn` is `(r, ctx) => boolean`. Truthy means "flag this row for
- *   deletion". Soft delete via `DeleteRowCommand`.
+ * A built-in declarative validator. Mode-symmetric: the SDK ships a TS
+ * interpreter, the Updog Scale Go binary ships a Go interpreter, and both
+ * agree on pass/fail outcomes per `api/validators.json`.
  */
-type ChatOp = {
-    action: "edit";
-    fn: string;
+type BuiltInValidator = {
+    type: "required";
+    message?: string;
 } | {
-    action: "delete";
-    fn: string;
-};
-/**
- * A single chunk in the stream returned from `DataEditorChat.onMessage`.
- *
- * - `status` — progress message shown while processing (e.g. "Analyzing 500 rows...").
- * - `message` — chat reply shown to the user.
- * - `rows` — updated rows to apply to the grid. Matched by `primaryKey`.
- * - `ops` — array of per-row operations (edits and/or deletes) to apply in order.
- */
-type ChatResponseChunk<TRow extends DataEditorRow = DataEditorRow> = {
-    type: "status";
-    content: string;
+    type: "regex";
+    pattern: string;
+    flags?: string;
+    message?: string;
 } | {
-    type: "message";
-    content: string;
+    type: "oneOf";
+    values: string[];
+    message?: string;
 } | {
-    type: "rows";
-    content: TRow[];
+    type: "range";
+    min?: number;
+    max?: number;
+    message?: string;
 } | {
-    type: "ops";
-    content: ChatOp[];
-};
-/** Status of a row in the chat sample, relative to its origin snapshot. */
-type ChatRowStatus = "new" | "edited" | "original";
-/** A sample row handed to the chat callback, with its current status and validation errors. */
-type ChatRow<TRow extends DataEditorRow = DataEditorRow> = {
-    /** Row data keyed by column ID. */
-    data: TRow;
-    /** Whether the row was newly added, edited, or is unchanged. */
-    status: ChatRowStatus;
-    /** Validation errors keyed by column ID. */
-    errors: Record<string, string[]>;
-    /** The source this row belongs to. */
-    source: string;
-};
-/** Aggregated error count across the current view, grouped by field and message. */
-type ChatErrorSummary = {
-    /** Column ID where the error occurred. */
-    field: string;
-    /** The validation message. */
-    message: string;
-    /** How many rows hit this error. */
-    count: number;
-    /** A few example values that triggered the error. */
-    examples: string[];
+    type: "email";
+    message?: string;
+} | {
+    type: "date";
+    format?: "YYYY-MM-DD" | "DD/MM/YYYY";
+    message?: string;
+} | {
+    type: "numeric";
+    message?: string;
 };
 /**
- * Context about the current dataset, passed to `loadSuggestions` and extended
- * into `ChatContext` for `onMessage`.
+ * Server-mode-only escape hatch: an expression evaluated by the Go binary
+ * via expr-lang. Skipped at runtime in client mode (warned at mount).
  */
-type ChatDataContext<TRow extends DataEditorRow = DataEditorRow> = {
-    /** Full column definitions. */
-    columns: DataEditorColumn[];
-    /** Row identifier field. */
-    primaryKey: keyof TRow;
-    /** Total rows in the dataset. */
-    totalRowCount: number;
-    /** Rows in the current filtered view. */
-    filteredRowCount: number;
-    /** Sample rows, with status and errors. Size controlled by `sampleSize`. */
-    sample: ChatRow<TRow>[];
-    /** Aggregated error counts by field and message. */
-    errorSummary: ChatErrorSummary[];
-    /** Access all rows. Use for full-dataset operations. */
-    getRows: () => ChatRow<TRow>[];
+type ExpressionValidator = {
+    type: "expression";
+    expr: string;
+    message?: string;
 };
 /**
- * The full context passed to `DataEditorChat.onMessage` when the user sends
- * a prompt. Includes the prompt itself and all dataset context.
+ * Client-mode-only escape hatch: a JS predicate run inline. Dropped (with
+ * one warn per column) when the SDK serializes the schema for server mode.
  */
-type ChatContext<TRow extends DataEditorRow = DataEditorRow> = ChatDataContext<TRow> & {
-    /** The user's chat prompt. */
-    message: string;
+type FunctionValidator = {
+    type: "function";
+    fn: CellValidator;
 };
 /**
- * Bring-your-own-AI chat configuration. When provided via the `chat` prop,
- * the editor shows a chat panel alongside the grid. You own the AI
- * integration; the SDK hands you dataset context and renders the streamed
- * response.
+ * The validator-rule union accepted by `DataEditorColumn.validators`.
+ * - Built-ins and `expression` are declarative objects (cross the wire).
+ * - `function` wraps a `CellValidator`; client-mode-only, dropped+warned in server mode.
  *
- * @example
- * ```ts
- * chat={{
- *   sampleSize: 50,
- *   onMessage: async function* (context) {
- *     yield { type: "status", content: "Thinking..." };
- *     const res = await fetch("/api/ai", {
- *       method: "POST",
- *       body: JSON.stringify({
- *         prompt: context.message,
- *         columns: context.columns,
- *         sample: context.sample.map(r => r.data),
- *         errors: context.errorSummary,
- *       }),
- *     }).then(r => r.json());
- *     yield { type: "rows", content: res.updatedRows };
- *     yield { type: "ops", content: res.ops };
- *     yield { type: "message", content: res.reply };
- *   },
- * }}
- * ```
+ * Named `ValidatorRule` (not `Validator`) so it doesn't clash with the
+ * runtime `Validator` class in `core/Validator.ts`.
  */
-type DataEditorChat<TRow extends DataEditorRow = DataEditorRow> = {
-    /**
-     * How many rows to include in the context sample. The SDK picks a
-     * representative slice including rows with errors. When omitted, the SDK decides.
-     */
-    sampleSize?: number;
-    /** Title shown above the suggestion list when the chat is empty. */
-    emptyTitle?: string;
-    /** How many suggestions to request from `loadSuggestions`. */
-    suggestionsCount?: number;
-    /** Optional prompt generator for the empty-state suggestion chips. */
-    loadSuggestions?: (context: ChatDataContext<TRow>) => Promise<string[]>;
-    /**
-     * Called when the user sends a message. Receives full dataset context.
-     * Returns an async iterable of response chunks — the SDK streams them
-     * into the UI.
-     */
-    onMessage: (context: ChatContext<TRow>) => AsyncIterable<ChatResponseChunk<TRow>>;
-    /** Called when the user cancels a pending request. Use to abort your API call. */
-    onCancel?: () => void;
-};
+type ValidatorRule = BuiltInValidator | ExpressionValidator | FunctionValidator;
 
 /** Severity level for a validation message. */
 type ValidationLevel = "error";
@@ -755,9 +635,10 @@ type ValidationError = {
  * does not block submission — invalid rows are delivered to `onComplete`
  * alongside valid ones, tagged via the `isValid` flag.
  *
- * Built-in validator factories: `required(msg)`, `numeric(msg)`, `email(msg)`,
- * `date(msg)`, `oneOf(values, msg)`, `endDateAfterStart(startField, msg)`.
- * Import them from the package root.
+ * To use a `CellValidator` in the `validators` array, wrap it as
+ * `{ type: "function", fn: (value, row) => ... }`. For declarative rules,
+ * pass a built-in object literal — e.g. `{ type: "required" }`,
+ * `{ type: "email" }`. See `ValidatorRule` for the full union.
  *
  * @param value - The current cell value.
  * @param row - The full row, useful for cross-field checks.
@@ -841,13 +722,11 @@ type ColumnLockMode = "all" | "default";
  *
  * @example
  * ```ts
- * import { required, email, numeric } from "@updog/data-editor";
- *
  * const columns: DataEditorColumn[] = [
- *   { id: "name", title: "Full Name", size: 200, validate: required("Name is required") },
- *   { id: "email", title: "Email", size: 250, validate: [required("Email is required"), email("Invalid email")], unique: true },
+ *   { id: "name", title: "Full Name", size: 200, validators: [{ type: "required", message: "Name is required" }] },
+ *   { id: "email", title: "Email", size: 250, validators: [{ type: "required", message: "Email is required" }, { type: "email", message: "Invalid email" }], unique: true },
  *   { id: "role", title: "Role", editor: { type: "select", options: ["Admin", "Editor", "Viewer"] } },
- *   { id: "salary", title: "Salary", validate: numeric("Must be a number"), formatter: (v) => v ? `$${v}` : "" },
+ *   { id: "salary", title: "Salary", validators: [{ type: "numeric", message: "Must be a number" }], formatter: (v) => v ? `$${v}` : "" },
  * ];
  * ```
  */
@@ -857,11 +736,14 @@ type DataEditorColumn = {
     /** Column header text shown to the user. */
     title: string;
     /**
-     * One or more validators run on every edit. Each receives the cell value and
-     * the full row, and returns a `ValidationError` to flag a problem or `null`
-     * if valid. Errors do not block submission — see `CellValidator`.
+     * One or more validators run on every edit. Accepts:
+     * - Built-in object literals: `{ type: "required" | "email" | "regex" | "range" | "oneOf" | "date" | "numeric", ... }`.
+     * - `{ type: "expression", expr }` — server-mode only. Warned in client mode.
+     * - `{ type: "function", fn }` — client-mode only. Dropped+warned in server mode.
+     *
+     * See `_specs/VALIDATIONS.md` §4.5 for the per-mode support matrix.
      */
-    validate?: CellValidator | CellValidator[];
+    validators?: ValidatorRule[];
     /**
      * When `true`, the editor flags duplicate values in this column as errors.
      * The error message is localized via the `translations` prop
@@ -902,398 +784,179 @@ type DataEditorColumn = {
     locked?: boolean | ColumnLockMode;
 };
 
-/** Params passed to `findAndReplace.onFind` when the user types a search query. */
-type FindParams = {
-    /** The search string. */
-    search: string;
-    /** When `true`, matching is case-sensitive. */
-    matchCase?: boolean;
-    /** When `true`, the entire cell value must equal the search string. */
-    matchEntireCell?: boolean;
-    /** Restrict search to these columns. `null` or omitted = all columns. */
-    columnIds?: string[] | null;
-    /** Current view filters so the server can scope matches to the active filter set. */
-    filters?: QueryFilters;
-    /** Current sort state so match ordering follows the visual row order. */
-    sort?: SortState;
-};
-/** A single match location returned by the server. */
-type FindMatch = {
-    /** Row position in the current filtered+sorted view (for grid scrolling). */
-    rowIndex: number;
-    /** Column ID where the match occurs. */
-    columnId: string;
-    /** Character offset within the cell value (for inline highlight). */
-    startIndex: number;
-    /** 0-based position in the ordered match list (for counter display). */
-    matchIndex: number;
-};
-/** Response from `findAndReplace.onFind`. */
-type FindResponse = {
-    /** Total number of matches across all rows. */
-    totalCount: number;
-    /** The first match. Omit when `totalCount` is 0. */
-    current?: FindMatch;
-};
-/** Params passed to `findAndReplace.onNavigate` when the user clicks prev/next. */
-type FindNavigateParams = FindParams & {
-    /** Navigation direction. */
-    direction: "next" | "prev";
-    /** Current match position so the server knows where to navigate from. */
-    currentMatchIndex: number;
-};
-/** Params passed to `findAndReplace.onReplace`. */
-type ReplaceParams = FindParams & {
-    /** The replacement text. */
-    replacement: string;
-    /** When `true`, replace all matches. When omitted or `false`, replace only `target`. */
-    all?: boolean;
-    /** The specific match to replace. Required when `all` is not `true`. */
-    target?: FindMatch;
-};
-/** Response from `findAndReplace.onReplace`. */
-type ReplaceResponse = {
-    /** Remaining match count after replacement. */
-    totalCount: number;
-    /** Next match to navigate to after replacement. Omit when none left. */
-    current?: FindMatch;
-};
-/** Server-side find and replace configuration. */
-type FindAndReplaceConfig = {
-    /** Called when the user types a search query. Returns total count and first match. */
-    onFind: (params: FindParams) => Promise<FindResponse>;
-    /** Called when the user clicks prev/next arrows. Returns the target match. */
-    onNavigate: (params: FindNavigateParams) => Promise<FindMatch>;
-    /** Called when the user clicks Replace or Replace All. */
-    onReplace: (params: ReplaceParams) => Promise<ReplaceResponse>;
-};
-type ServerRowId = string | number;
-/** Row-level status flags returned by the server. Drive row filters and sidebar counts. */
-type ServerRowStatus = {
-    edited?: boolean;
-    new?: boolean;
-    deleted?: boolean;
-    hasErrors?: boolean;
-    hasEmptyCells?: boolean;
-};
-/** Server-reported change for a single cell. The current value lives in `fields`. */
-type ServerCellChange = {
-    original: unknown;
-};
-/** Server-reported validation error for a single cell. */
-type ServerCellError = {
-    message: string;
-    code?: number | string;
-};
-/** Per-row metadata returned by the server in server-delegated mode. */
-type ServerRowMeta = {
-    /** Row-level status flags — drive row filters and sidebar counts. */
-    status?: ServerRowStatus;
-    /** Cell-level change tracking. Key = field name. */
-    changes?: Record<string, ServerCellChange>;
-    /** Cell-level validation errors. Key = field name. */
-    errors?: Record<string, ServerCellError[]>;
-};
-/** Per-source row count returned by the server. Drives the Data Sources sidebar. */
-type ServerSourceCount = {
-    id: string;
-    name: string;
-    count: number;
-};
-/** Aggregate row counts returned alongside a query page. Drive sidebar indicators. */
-type ServerQueryCounts = {
-    edited?: number;
-    new?: number;
-    deleted?: number;
-    errors?: number;
-    emptyCells?: number;
-    sources?: ServerSourceCount[];
-};
-type ServerRow<T extends DataEditorRow = DataEditorRow> = {
-    id: ServerRowId;
-    fields: T;
-    meta?: ServerRowMeta;
-};
-type ServerResponse<T> = {
-    data: T;
-    meta?: Record<string, unknown>;
-};
-type QueryFilters<F = Record<string, unknown>> = Partial<Filters> & F;
-type QueryParams<F = Record<string, unknown>> = {
-    filters?: QueryFilters<F>;
-    sort?: SortState;
-    /** When present, only rows belonging to these source IDs are returned. Omit to include all sources. */
-    sources?: string[];
-    offset?: number;
-    limit: number;
-    signal?: AbortSignal;
-};
-type QueryResponse<T extends DataEditorRow = DataEditorRow> = ServerResponse<{
-    rows: ServerRow<T>[];
-    totalCount: number;
-    filteredCount?: number;
-    counts?: ServerQueryCounts;
-}>;
 /**
- * Filter options returned by `onFilterOptions` for populating sidebar filter controls in server mode.
- * Keys are column IDs. Only include columns that have a `filter` configured.
+ * Categories of internal errors surfaced through the `onError` callback.
+ *
+ * Existing categories cover client-side failures. `scale.*` codes cover
+ * server-mode (Updog Scale) failures. `license.*` codes cover license
+ * validation failures (previously a separate `LicenseErrorCode` enum).
  */
-type FilterOptionsResponse = {
-    [columnId: string]: {
-        /** Values for `"select"` filters. Raw display strings — no formatter is applied. */
-        options?: string[];
-        /** Bounds for `"number-range"` filters. */
-        range?: {
-            min: number;
-            max: number;
-        };
-        /** Bounds for `"date-range"` filters. Values are ISO date strings (YYYY-MM-DD). */
-        dateRange?: {
-            min: string;
-            max: string;
-        };
-    };
-};
-type ServerCallOptions = {
-    signal: AbortSignal;
-};
+type UpdogErrorCode = "PARSE_ERROR" | "RENDER_ERROR" | "TRANSFORM_ERROR" | "VALIDATION_ERROR" | "WORKER_ERROR" | "COMMAND_ERROR" | "OPERATION_ERROR" | "license.invalid" | "license.missing" | "license.domain_not_allowed" | "license.subscription_inactive" | "license.trial_expired" | "scale.bootstrap_failed" | "scale.workspace_lost" | "scale.unreachable" | "scale.server_error";
 /**
- * Coordinate rectangle within the server's data view.
- * Uses ServerRowId (primary key) for rows and column ID strings for columns.
- *
- * Convention:
- * - Both row fields omitted → all rows.
- * - Both column fields omitted → all columns.
- * - Single row: `fromRow` AND `toRow` both set, `toRow === fromRow`.
- * - Single column: `fromColumn` AND `toColumn` both set, `toColumn === fromColumn`.
- * - Range: both `from` and `to` set, `to !== from`.
- * - `allSelected: true` → all rows and all columns.
- * - Empty `{}` → used only for insert operations.
+ * An internal error caught by the SDK and passed to `onError`. The SDK
+ * recovers gracefully where possible — `onError` is for your logging and
+ * monitoring (Sentry, Datadog, etc.).
  *
- * INVALID: `from` present without `to`, or vice versa.
+ * @example
+ * ```ts
+ * onError={(error) => {
+ *   Sentry.captureException(error.originalError ?? error, {
+ *     tags: { code: error.code, source: error.source },
+ *   });
+ * }}
+ * ```
  */
-type Region = {
-    fromRow?: ServerRowId;
-    toRow?: ServerRowId;
-    fromColumn?: string;
-    toColumn?: string;
-    allSelected?: boolean;
-};
-/** Describes where and how to insert a new row. */
-type InsertParams = {
-    /** Existing row to anchor the insert relative to. Omitted when appending to the end. */
-    anchorRow?: ServerRowId;
-    /** Insert before or after the anchor row. */
-    position: "above" | "below";
-    /** Column IDs matching the order of `values` entries. */
-    columns: string[];
+type UpdogError = {
+    /** The error category. */
+    code: UpdogErrorCode;
+    /** Human-readable description. */
+    message: string;
+    /** Module or subsystem that raised the error. */
+    source: string;
+    /** The underlying thrown value, when available. */
+    originalError?: unknown;
 };
+
 /**
- * Unified edit params for all data mutations in server-delegated mode.
- *
- * The combination of fields determines the operation:
- * - `target` + `values`             → cell edit, clear, or external paste
- * - `target` + `source`             → internal paste (+ `cut` for cut-paste)
- * - `target` + `source` (fill)      → fill handle
- * - `target` + `transform`          → transform / revert
- * - `target` + `delete: true`       → mark rows for deletion
- * - `target` + `delete: false`      → restore rows (unmark deletion)
- * - `insert` + `values`             → create a new row
- *
- * `values` is always a 2D array. For a single cell edit: `[["newValue"]]`.
- * For clearing: `[[""]]`. The server interprets dimensions relative to `target`:
- * a 1×1 `values` applied to a multi-cell target means "fill all cells with this value".
+ * A single operation the LLM wants to apply to rows in the current filtered view.
  *
- * `filters` and `sort` provide the view context so the server can resolve
- * which rows fall between `fromRow` and `toRow` in the current view.
- * Omitted for single-cell edits where `fromRow` is a direct row ID.
+ * - `edit` — `fn` is `(r, ctx) => void`. Mutates `r` in place. Changed fields
+ *   become column deltas. Rows with no changes are no-ops.
+ * - `delete` — `fn` is `(r, ctx) => boolean`. Truthy means "flag this row for
+ *   deletion". Soft delete via `DeleteRowCommand`.
  */
-type EditParams = {
-    target: Region[];
-    source?: Region[];
-    values?: unknown[][];
-    transform?: TransformParams;
-    cut?: boolean;
-    delete?: boolean;
-    insert?: InsertParams;
-    undo?: boolean;
-    filters?: QueryFilters;
-    sort?: SortState;
-    lockedColumns?: Array<{
-        columnId: string;
-        mode: "all" | "default";
-    }>;
-};
-type ExportParams<F = Record<string, unknown>> = {
-    format: "csv" | "tsv" | "xlsx" | "json" | "xml";
-    allRows: boolean;
-    rtl?: boolean;
-    filters?: QueryFilters<F>;
-    sort?: SortState;
-    signal?: AbortSignal;
-};
-/** Transform operation descriptor. `type` identifies the operation, optional fields carry parameters. */
-type TransformParams = {
-    type: string;
-    separator?: string;
-    /** When `true`, the server should delete the dynamic source columns after applying the transform. */
-    deleteSource?: boolean;
+type ChatOp = {
+    action: "edit";
+    fn: string;
+} | {
+    action: "delete";
+    fn: string;
 };
-/** Params passed to `onColumnDelete` when the user deletes a dynamic column. */
-type ColumnDeleteParams = {
-    /** ID of the dynamic column to delete. */
-    columnId: string;
-    /** `true` when the server should reverse this operation (undo). Omitted on initial call and redo. */
-    undo?: boolean;
+/**
+ * A single chunk in the stream returned from `DataEditorChat.onMessage`.
+ *
+ * - `status` — progress message shown while processing (e.g. "Analyzing 500 rows...").
+ * - `message` — chat reply shown to the user.
+ * - `rows` — updated rows to apply to the grid. Matched by `primaryKey`.
+ * - `ops` — array of per-row operations (edits and/or deletes) to apply in order.
+ */
+type ChatResponseChunk<TRow extends DataEditorRow = DataEditorRow> = {
+    type: "status";
+    content: string;
+} | {
+    type: "message";
+    content: string;
+} | {
+    type: "rows";
+    content: TRow[];
+} | {
+    type: "ops";
+    content: ChatOp[];
 };
-/** Params passed to `onColumnEdit` when the user renames a dynamic column. */
-type ColumnEditParams = {
-    /** ID of the dynamic column being edited. */
-    columnId: string;
-    /** New title for the column. */
-    title: string;
-    /** `true` when the server should reverse this operation (undo). Omitted on initial call and redo. */
-    undo?: boolean;
+/** Status of a row in the chat sample, relative to its origin snapshot. */
+type ChatRowStatus = "new" | "edited" | "original";
+/** A sample row handed to the chat callback, with its current status and validation errors. */
+type ChatRow<TRow extends DataEditorRow = DataEditorRow> = {
+    /** Row data keyed by column ID. */
+    data: TRow;
+    /** Whether the row was newly added, edited, or is unchanged. */
+    status: ChatRowStatus;
+    /** Validation errors keyed by column ID. */
+    errors: Record<string, string[]>;
+    /** The source this row belongs to. */
+    source: string;
 };
-/** Server's response after applying a mutation. */
-type EditResponse = {
-    counts?: ServerQueryCounts;
-    /** Business-logic rejection. SDK reverts the optimistic update and shows `reason` in a toast. */
-    rejected?: boolean;
-    /** Why the server rejected. Shown to the user as-is. */
-    reason?: string;
-    /** The full row created by the server. Returned for insert operations. */
-    row?: ServerRow;
-    /** Updated column list. When present, the SDK replaces its columns with this list. */
-    columns?: Array<{
-        id: string;
-        title: string;
-    }>;
+/** Aggregated error count across the current view, grouped by field and message. */
+type ChatErrorSummary = {
+    /** Column ID where the error occurred. */
+    field: string;
+    /** The validation message. */
+    message: string;
+    /** How many rows hit this error. */
+    count: number;
+    /** A few example values that triggered the error. */
+    examples: string[];
 };
 /**
- * Every decision the user made during the import wizard, packed into one object.
- * You get the raw file and the full mapping config. Parse it however you want —
- * stream it, bulk-load it, hand it to a background job. Your call.
+ * Context about the current dataset, passed to `loadSuggestions` and extended
+ * into `ChatContext` for `onMessage`.
  */
-type ImportMappings = {
-    /** CSV header → column ID. Headers the user left unmatched are `undefined`. */
-    columnMapping: Record<string, string | undefined>;
-    /**
-     * Value substitutions for select columns.
-     * Outer key = column ID, inner key = imported value, inner value = target option.
-     * Only present when at least one select column was matched.
-     */
-    valueMapping: Record<string, Record<string, string | undefined>>;
-    /** Column ID used to match imported rows against existing data. Same value as `DataEditorProps.primaryKey`. */
-    primaryKey: string;
-    /** Sheet name the user selected. Only present for multi-sheet XLSX files. */
-    selectedSheet?: string;
-    /** Zero-based index of the row the SDK detected as the header row. */
-    headerRowIndex: number;
-    /** Number format detected from the file contents. Affects how `"1.234,56"` vs `"1,234.56"` is read. */
-    numberFormat: "EU" | "US";
-    /**
-     * Per-column date disambiguation. Key = CSV header (not column ID).
-     * `"EU"` = day-first, `"US"` = month-first.
-     * Only includes columns where the format was ambiguous and had to be resolved.
-     */
-    dateFormats: Record<string, "EU" | "US">;
-    /**
-     * Columns the user created during import for unmatched headers.
-     * These don't exist in your schema yet — you decide whether to persist them.
-     */
-    newColumns: DataEditorColumn[];
-};
-/** Params passed to `onFileImport`. The original file, unchanged, plus everything the wizard collected. */
-type FileImportParams = {
-    /** The original file. Same bytes the user dropped into the browser. */
-    file: File;
-    /** All mapping decisions from the import wizard. */
-    mappings: ImportMappings;
-    /** Display name for this import source. Typically the file name. */
-    sourceName: string;
-    /** Fires when the user cancels the import. */
-    signal?: AbortSignal;
+type ChatDataContext<TRow extends DataEditorRow = DataEditorRow> = {
+    /** Full column definitions. */
+    columns: DataEditorColumn[];
+    /** Row identifier field. */
+    primaryKey: keyof TRow;
+    /** Total rows in the dataset. */
+    totalRowCount: number;
+    /** Rows in the current filtered view. */
+    filteredRowCount: number;
+    /** Sample rows, with status and errors. Size controlled by `sampleSize`. */
+    sample: ChatRow<TRow>[];
+    /** Aggregated error counts by field and message. */
+    errorSummary: ChatErrorSummary[];
+    /** Access all rows. Use for full-dataset operations. */
+    getRows: () => ChatRow<TRow>[];
 };
 /**
- * Params passed to `onRowsImport` once per chunk.
- * The SDK already parsed the file, applied column mappings, normalized dates
- * and numbers, and resolved value mappings. You get clean, schema-conformant rows.
+ * The full context passed to `DataEditorChat.onMessage` when the user sends
+ * a prompt. Includes the prompt itself and all dataset context.
  */
-type RowsImportParams = {
-    /** Stable ID for this import session. Use it for idempotency or correlation. */
-    importId: string;
-    /** Display name for this import source. Typically the file name. */
-    sourceName: string;
-    /** Zero-based chunk index. Together with `importId`, uniquely identifies each chunk. */
-    chunkIndex: number;
-    /** `true` on the last chunk. Safe to finalize, run post-import hooks, or trigger validation. */
-    isLastChunk: boolean;
-    /** Transformed rows, keyed by column ID. Ready to store. */
-    rows: Record<string, unknown>[];
-    /** Columns the user created during import. Only present on the first chunk (`chunkIndex === 0`). */
-    newColumns?: DataEditorColumn[];
-    /** Column ID used to match imported rows against existing data. */
-    primaryKey: string;
-    /** Fires when the user cancels mid-import. Clean up any partial state. */
-    signal?: AbortSignal;
-};
-/** Your response after processing a chunk. */
-type RowsImportResponse = {
-    /** How many rows you accepted from this chunk. Drives progress reporting. */
-    accepted: number;
-    /** Per-row errors. `rowIndex` is relative to the chunk (0-based). Surfaced in the UI after import. */
-    errors?: Array<{
-        rowIndex: number;
-        message: string;
-    }>;
-};
-/** Params passed to `onSourceRemove` when the user deletes a data source. */
-type SourceRemoveParams = {
-    /** The source ID to remove. Matches the `id` from `ServerQueryCounts.sources`. */
-    sourceId: string;
-    /** Fires when the user cancels. */
-    signal?: AbortSignal;
+type ChatContext<TRow extends DataEditorRow = DataEditorRow> = ChatDataContext<TRow> & {
+    /** The user's chat prompt. */
+    message: string;
 };
-type DataEditorServer<TRow extends DataEditorRow = DataEditorRow, TFilters = Record<string, unknown>> = {
-    onQuery: (params: QueryParams<TFilters>) => Promise<QueryResponse<TRow>>;
-    /** Fetches filter dictionaries for all filterable columns. Called once after license validation. */
-    onFilterOptions?: () => Promise<FilterOptionsResponse>;
-    /** Called when the user triggers an export. The consumer handles file generation and download. */
-    onExport?: (params: ExportParams<TFilters>) => Promise<void>;
-    /** Called after optimistic local apply. Return `{ rejected: true }` for business-logic errors; throw for infra failures. */
-    onEdit: (params: EditParams, options?: ServerCallOptions) => Promise<EditResponse | void>;
-    /**
-     * File import strategy. You get the raw file and the mapping config.
-     * You own parsing, transformation, and storage.
-     * Mutually exclusive with `onRowsImport`.
-     */
-    onFileImport?: (params: FileImportParams) => Promise<void>;
+/**
+ * Bring-your-own-AI chat configuration. When provided via the `chat` prop,
+ * the editor shows a chat panel alongside the grid. You own the AI
+ * integration; the SDK hands you dataset context and renders the streamed
+ * response.
+ *
+ * @example
+ * ```ts
+ * chat={{
+ *   sampleSize: 50,
+ *   onMessage: async function* (context) {
+ *     yield { type: "status", content: "Thinking..." };
+ *     const res = await fetch("/api/ai", {
+ *       method: "POST",
+ *       body: JSON.stringify({
+ *         prompt: context.message,
+ *         columns: context.columns,
+ *         sample: context.sample.map(r => r.data),
+ *         errors: context.errorSummary,
+ *       }),
+ *     }).then(r => r.json());
+ *     yield { type: "rows", content: res.updatedRows };
+ *     yield { type: "ops", content: res.ops };
+ *     yield { type: "message", content: res.reply };
+ *   },
+ * }}
+ * ```
+ */
+type DataEditorChat<TRow extends DataEditorRow = DataEditorRow> = {
     /**
-     * Rows import strategy. The SDK parses the file, applies all mappings,
-     * normalizes dates and numbers, and sends you clean rows in chunks.
-     * Called once per chunk. Awaited before sending the next chunk.
-     * Mutually exclusive with `onFileImport`.
+     * How many rows to include in the context sample. The SDK picks a
+     * representative slice including rows with errors. When omitted, the SDK decides.
      */
-    onRowsImport?: (params: RowsImportParams) => Promise<RowsImportResponse | void>;
-    /** Number of rows per import chunk when using `onRowsImport`. @default 5000 */
-    importChunkSize?: number;
-    /** Called when the user removes a data source. Delete all rows belonging to this source. */
-    onSourceRemove?: (params: SourceRemoveParams) => Promise<void>;
-    /** Called when the user deletes, undoes, or redoes a dynamic column deletion. */
-    onColumnDelete?: (params: ColumnDeleteParams) => Promise<EditResponse | void>;
-    /** Called when the user edits a dynamic column (e.g. renames it). */
-    onColumnEdit?: (params: ColumnEditParams) => Promise<EditResponse | void>;
+    sampleSize?: number;
+    /** Title shown above the suggestion list when the chat is empty. */
+    emptyTitle?: string;
+    /** How many suggestions to request from `loadSuggestions`. */
+    suggestionsCount?: number;
+    /** Optional prompt generator for the empty-state suggestion chips. */
+    loadSuggestions?: (context: ChatDataContext<TRow>) => Promise<string[]>;
     /**
-     * Server-side find and replace. When provided, enables Find & Replace UI
-     * in server mode. The server owns all searching and replacing; the SDK
-     * handles counts, navigation, and highlighting.
+     * Called when the user sends a message. Receives full dataset context.
+     * Returns an async iterable of response chunks — the SDK streams them
+     * into the UI.
      */
-    findAndReplace?: FindAndReplaceConfig;
-    /** Number of rows per page. @default 200 */
-    pageSize?: number;
-    /** Controls how eagerly the SDK fetches data while scrolling. 0 = always debounce, 1 = fetch immediately. @default 0.5 */
-    scrollSensitivity?: number;
+    onMessage: (context: ChatContext<TRow>) => AsyncIterable<ChatResponseChunk<TRow>>;
+    /** Called when the user cancels a pending request. Use to abort your API call. */
+    onCancel?: () => void;
+};
+
+type ScaleServerConfig = {
+    url: string;
 };
 
 /**
@@ -1483,12 +1146,6 @@ type DataEditorBaseProps<TRow extends DataEditorRow = DataEditorRow> = {
      * ```
      */
     loadData?: (onChunk: (rows: TRow[], options?: ChunkSourceOptions) => void) => Promise<void>;
-    /**
-     * Server-delegated mode. When provided, the SDK acts as a rendering head
-     * and delegates data operations (fetching, filtering, sorting, mutations)
-     * to the client's backend via callbacks.
-     */
-    server?: DataEditorServer<TRow>;
     /**
      * Called when the user clicks "Submit". Receives the edited data grouped
      * by source. Use `actions.reset()` to clear changes after a successful save.
@@ -1643,6 +1300,11 @@ type DataEditorLocalStorage = false | {
 type DataEditorCommonProps<TRow extends DataEditorRow = DataEditorRow> = DataEditorBaseProps<TRow> & {
     /** Your Updog license key. Validated on each open. */
     apiKey: string;
+    /**
+     * @internal
+     * Reserved for future server-delegated mode. Not part of the public API.
+     */
+    __server?: ScaleServerConfig;
     /**
      * Controls what the editor stores in `localStorage`. Set to `false` to
      * disable all local storage usage.
@@ -1722,67 +1384,6 @@ type DataEditorInlineProps<TRow extends DataEditorRow = DataEditorRow> = DataEdi
  */
 type DataEditorProps<TRow extends DataEditorRow = DataEditorRow> = DataEditorModalProps<TRow> | DataEditorInlineProps<TRow>;
 
-/**
- * Creates a validator that rejects empty values.
- *
- * @param message - Error message shown when the cell is empty.
- *
- * @example
- * ```ts
- * const columns = [
- *   { id: "name", title: "Name", validate: [required("Name is required")] },
- * ];
- * ```
- */
-declare function required(message: string): CellValidator;
-/**
- * Creates a validator that rejects non-numeric values.
- *
- * @param message - Error message shown when the value is not a valid number.
- */
-declare function numeric(message: string): CellValidator;
-/**
- * Creates a validator that rejects invalid email addresses.
- *
- * @param message - Error message shown when the value is not a valid email.
- */
-declare function email(message: string): CellValidator;
-/**
- * Creates a validator that rejects values not matching `YYYY-MM-DD` or `DD/MM/YYYY`.
- *
- * @param message - Error message shown when the value is not a valid date.
- */
-declare function date(message: string): CellValidator;
-/**
- * Creates a validator that ensures this date is on or after the date in another column.
- *
- * @param startDateField - Column ID of the start-date field to compare against.
- * @param message - Error message shown when the end date is before the start date.
- *
- * @example
- * ```ts
- * const columns = [
- *   { id: "startDate", title: "Start", dependentFields: ["endDate"] },
- *   { id: "endDate", title: "End", validate: [endDateAfterStart("startDate", "End must be after start")] },
- * ];
- * ```
- */
-/**
- * Creates a validator that rejects values not in the allowed set.
- *
- * @param values - Array of allowed values (matched by strict equality).
- * @param message - Error message shown when the value is not in the set.
- *
- * @example
- * ```ts
- * const columns = [
- *   { id: "status", title: "Status", validate: [oneOf(["active", "inactive"], "Invalid status")] },
- * ];
- * ```
- */
-declare function oneOf(values: string[], message: string): CellValidator;
-declare function endDateAfterStart(startDateField: string, message: string): CellValidator;
-
 type Props = DataEditorProps;
 /**
  * All properties available on the `<updog-editor>` element.
@@ -1852,5 +1453,3 @@ declare global {
         "updog-editor": UpdogEditorElement;
     }
 }
-
-export { date, email, endDateAfterStart, numeric, oneOf, required };