@updog/data-editor 0.1.41 → 0.1.43

package/index.d.ts

@@ -443,9 +443,6 @@ declare var export_default = {
         primaryKey: "Primary key",
       },
       uploadFile: {
-        title: "Upload file",
-        text: "Upload a CSV, TSV, Excel, JSON or XML file to import data",
-        textDynamic: "Upload a {{formats}} file to import data",
         parseError: "Failed to parse file",
         clickToUpload: "Click to upload",
         orDragAndDrop: "or drag and drop",
@@ -462,8 +459,6 @@ declare var export_default = {
         fetchError: "Failed to load data",
       },
       matchColumns: {
-        title: "Match columns",
-        text: "Map imported columns to existing columns",
         banner: "Some columns could not be automatically matched",
         importedColumns: "Imported columns",
         matchedCount: "{{matched}}/{{total}} matched",
@@ -484,25 +479,26 @@ declare var export_default = {
           "Unmatched columns won't be imported. Match this column to keep the data. You can transform columns after importing.",
       },
       sheetSelection: {
-        title: "Select sheet",
-        text: "This file contains multiple sheets. Choose which sheet to import.",
         rowCount: "{{count}} rows",
         emptySheet: "Empty sheet",
       },
       matchValues: {
-        title: "Match values",
-        text: "Review how imported values map to your column options. Adjust any mappings that need a different match.",
         importedValues: "Imported values",
         matchedCount: "{{matched}}/{{total}} matched",
         targetValue: "Target value",
         selectValuePlaceholder: "Select value",
         showMatched: "Show matched",
         allMatched: "All values are matched",
-        unmatchedWarning: "Unmatched values won't be imported",
+        unmatchedWarning:
+          "Unmatched values won't be imported. Match this value to keep the data. You can edit values after importing.",
+        createOption: "Create option",
+        createOptionTitle: "Create option",
+        createOptionNameLabel: "Option name",
+        createOptionNamePlaceholder: "Enter option name",
+        createOptionNameTaken: "This option already exists",
+        createOptionSubmit: "Create",
       },
       primaryKey: {
-        title: "Select primary key",
-        text: "Choose the column that uniquely identifies each row",
         none: "No primary key",
         noneHint:
           "All rows will be appended as new entries without deduplication.",
@@ -720,6 +716,11 @@ type SelectEditorCell = {
     type: "select";
     /** The list of options shown in the dropdown. Each string is both the stored value and the display label. */
     options: string[];
+    /**
+     * Let users add options via "Create option" (matching step + grid); never
+     * created implicitly. Defaults to true; false for a strict closed enum.
+     */
+    enableCustomValue?: boolean;
 };
 /** Number input cell with locale-aware formatting. */
 type NumberEditorCell = {
@@ -1246,78 +1247,6 @@ declare class ChunkedProcessor<T> {
     cancel(): void;
 }
 
-type RegisterSourceOptions = {
-    name: string;
-    id?: DataSourceId;
-    isDeletable?: boolean;
-    isInitialData?: boolean;
-};
-type MergeEntry<TRow> = {
-    row: TRow;
-    sourceId: DataSourceId;
-    isNew: boolean;
-    isEdited: boolean;
-};
-type RemovalPlan<TRow> = {
-    rowsToDelete: Set<TRowId>;
-    rowsToRestore: Array<{
-        rowId: TRowId;
-        row: TRow;
-        originalSourceId: DataSourceId;
-        isNew: boolean;
-        isEdited: boolean;
-    }>;
-};
-type ExtendedRemovalPlan<TRow> = RemovalPlan<TRow> & {
-    sourceId: DataSourceId;
-    repairedEntries: Array<{
-        sourceId: DataSourceId;
-        rowId: TRowId;
-        before: MergeEntry<TRow>;
-        after: MergeEntry<TRow> | null;
-    }>;
-};
-declare class SourceManager<TRow extends DataEditorRow = DataEditorRow> {
-    private readonly _defaultSourceId;
-    private readonly overrides;
-    private readonly sources;
-    private readonly mergedRows;
-    getSourceId(rowId: TRowId): DataSourceId;
-    setSourceId(rowId: TRowId, sourceId: DataSourceId): void;
-    deleteSourceId(rowId: TRowId): void;
-    getOverrides(): ReadonlyMap<TRowId, DataSourceId>;
-    register(options: RegisterSourceOptions): DataSourceId;
-    /**
-     * Re-insert a source using a full captured state, preserving
-     * isVisible, isLoading, rowCount, etc. Used by SourceLifecycle.restore.
-     * If the source already exists, overwrites its state.
-     */
-    restoreState(state: DataSourceState): void;
-    has(sourceId: DataSourceId): boolean;
-    get(sourceId: DataSourceId): DataSourceState | undefined;
-    delete(sourceId: DataSourceId): void;
-    setLoading(sourceId: DataSourceId, isLoading: boolean): void;
-    finalizeAllSources(): void;
-    values(): IterableIterator<DataSourceState>;
-    getHiddenSourceIds(): Set<DataSourceId>;
-    saveMergeSnapshot(sourceId: DataSourceId, rowId: TRowId, existingRow: TRow, previousSourceId: DataSourceId, isNew: boolean, isEdited: boolean): void;
-    /**
-     * Public so commands can re-install merge entries during undo of a remove.
-     */
-    restoreMergeEntry(sourceId: DataSourceId, rowId: TRowId, entry: MergeEntry<TRow>): void;
-    /**
-     * Pure — computes the full removal plan without mutating any state.
-     * Callers run applyRemovalPlan(plan) to commit.
-     */
-    planRemoval(sourceId: DataSourceId): ExtendedRemovalPlan<TRow> | null;
-    /**
-     * Mutates internal state per plan produced by planRemoval.
-     */
-    applyRemovalPlan(plan: ExtendedRemovalPlan<TRow>): void;
-    clear(): void;
-    private getUniqueName;
-}
-
 /**
  * Internal contract: the surface a Scale client exposes to the SDK's data
  * layer. Implemented by `ScaleClient`. Not part of the public SDK API —
@@ -1340,185 +1269,143 @@ type ScaleClientApi<TRow extends DataEditorRow = DataEditorRow, TFilters = Recor
     scrollSensitivity?: number;
 };
 
-type ServerDataManagerDeps<TRow extends DataEditorRow = DataEditorRow> = {
-    clear(): void;
-    setLoading(isLoading: boolean): void;
-    registerSource(options: RegisterSourceOptions): DataSourceId;
-    setSourceLoading(sourceId: DataSourceId, isLoading: boolean): void;
-    getLocalRowCount(): number;
-    replaceServerRows(sourceId: DataSourceId, rows: ServerRow<TRow>[], offset: number, counts?: ServerQueryCounts): void;
-    appendServerRows(rows: ServerRow<TRow>[], counts?: ServerQueryCounts): void;
-    prependServerRows(rows: ServerRow<TRow>[], offset: number, counts?: ServerQueryCounts): void;
-    applyServerRowMeta(rows: ServerRow<TRow>[], counts?: ServerQueryCounts): void;
-};
-type FetchDirection = "forward" | "backward" | "jump";
-declare class ServerDataManager<TRow extends DataEditorRow = DataEditorRow> {
-    private _offset;
-    private _totalCount;
-    private _isFetching;
-    private readonly _pageSize;
-    private readonly _maxBufferRows;
-    private _filters;
-    private _sources;
-    private _sort;
-    private _filterOptions;
-    private _filterOptionsFetched;
-    private _abortController;
-    private _syncAbort;
-    private _lastVisibleStart;
-    private _debouncedFetch;
-    private readonly _config;
-    private readonly _dataStoreRef;
-    private readonly _sourceLabel;
-    private _onChanged;
-    constructor(config: ScaleClientApi<TRow>, dataStoreRef: ServerDataManagerDeps<TRow>, sourceLabel: string);
-    get offset(): number;
-    get totalCount(): number | null;
-    get isFetching(): boolean;
-    get pageSize(): number;
-    get maxBufferRows(): number;
-    setOnChanged(callback: () => void): void;
-    setOffset(offset: number): void;
-    setTotalCount(count: number): void;
-    private setFetching;
-    getExcess(currentCount: number, newCount: number): number;
-    shouldFetch(visibleStart: number, visibleEnd: number, loadedCount: number): FetchDirection | null;
-    /**
-     * Full reload — abort in-flight, clear store, fetch first page.
-     * Called on initial load, search/filter/sort changes, and resetFilters.
-     */
-    reload(): void;
-    /**
-     * Scroll-driven pagination with velocity-based debouncing.
-     * Called from CanvasGrid on every scroll event.
-     */
-    handleScroll(visibleStart: number, visibleEnd: number): void;
-    /**
-     * Fetch a single page based on scroll position and current window state.
-     */
-    private fetchPage;
-    /**
-     * Re-query the current viewport and replace row data, metadata, and counts.
-     * Called after successful edits and find-and-replace mutations.
-     * Each call aborts the previous in-flight sync.
-     */
-    syncCurrentView(): void;
-    /**
-     * Merge filter keys into server filter state and reload.
-     * Called by DataStore.setFilters() in server mode and by filter components.
-     */
-    setFilters(filters: Partial<Filters>): void;
-    /**
-     * Set sort state and reload.
-     */
-    setSort(sort: SortState): void;
-    /**
-     * Restrict query to visible sources and reload.
-     * Pass `undefined` to include all sources.
-     */
-    setSources(sources: string[] | undefined): void;
-    /**
-     * Clear all filters and sort, then reload.
-     */
-    resetFilters(): void;
-    /**
-     * One-time fetch of filter option dictionaries for sidebar filter controls.
-     */
-    fetchFilterOptions(): void;
-    getFilterOptions(): FilterOptionsResponse | null;
-    get onEdit(): (params: EditParams, options?: ServerCallOptions) => Promise<EditResponse | void>;
-    get filters(): Record<string, unknown>;
-    get sort(): SortState;
-    get sources(): string[] | undefined;
-    get onSourceRemove(): ((params: SourceRemoveParams) => Promise<void>) | undefined;
-    get onColumnDelete(): ((params: ColumnDeleteParams) => Promise<EditResponse | void>) | undefined;
-    get onColumnEdit(): ((params: ColumnEditParams) => Promise<EditResponse | void>) | undefined;
-    get hasExport(): boolean;
-    private _exportAbortController;
-    export(format: DataEditorFormat, allRows: boolean, rtl: boolean): Promise<void>;
-    clear(): void;
-    destroy(): void;
-}
-
 /**
- * A post-resolution selection rectangle in stable coordinate space.
- * Produced by grid-layer resolvers from CellRange[] in grid-index space.
- * Consumed by DataStore operations and server sync.
+ * 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`.
  */
-type SelectionRect = {
-    readonly fields: readonly string[];
-    readonly rowIds: readonly TRowId[];
+type ChatOp = {
+    action: "edit";
+    fn: string;
+} | {
+    action: "delete";
+    fn: string;
 };
-
 /**
- * ServerEditBuilder — Stateless coordinate translator for server-delegated edits.
- *
- * Converts frontend coordinates (TRowId, column index, grid ranges) into
- * `EditParams` with `Region[]` that the server can interpret.
- *
- * Does NOT call `onEdit`. Only builds params.
- * DataStore calls the builder, then sends the result to the server.
+ * A single chunk in the stream returned from `DataEditorChat.onMessage`.
  *
- * Responsibilities:
- *   - TRowId → ServerRowId translation via primaryKey
- *   - Grid index → column ID translation via columns array
- *   - Filter/sort context attachment from ServerDataManager
+ * - `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 ServerEditDeps<TRow extends DataEditorRow = DataEditorRow> = {
-    getPrimaryKey: () => string;
-    getRowById: (id: TRowId) => TRow | undefined;
-    getColumnIds: () => string[];
-    getFilters: () => Record<string, unknown>;
-    getSort: () => SortState;
-    getLockedColumns: () => ReadonlyMap<string, ColumnLockMode>;
+type ChatResponseChunk<TRow extends DataEditorRow = DataEditorRow> = {
+    type: "status";
+    content: string;
+} | {
+    type: "message";
+    content: string;
+} | {
+    type: "rows";
+    content: TRow[];
+} | {
+    type: "ops";
+    content: ChatOp[];
 };
-declare class ServerEditBuilder<TRow extends DataEditorRow = DataEditorRow> {
-    private readonly _deps;
-    constructor(deps: ServerEditDeps<TRow>);
-    resolveServerRowId(rowId: TRowId): ServerRowId | undefined;
-    buildRegion(rowIds: TRowId[], columnIds: string[]): Region;
-    /**
-     * Collapse rowIds × columnIds into minimal Region[].
-     * - All columns → omit column fields (row-only regions).
-     * - Contiguous columns in schema order → single fromColumn/toColumn span.
-     * - Non-contiguous → one region per contiguous column group.
-     * Rows are expressed as fromRow/toRow using first/last of the provided array.
-     */
-    buildRegions(rowIds: TRowId[], columnIds: string[]): Region[];
-    /**
-     * Collapse columnIds into minimal column-only Region[] (all rows implied).
-     * - All columns → `{ allSelected: true }`.
-     * - Contiguous in schema order → single `{ fromColumn, toColumn }`.
-     * - Non-contiguous → one region per contiguous group.
-     */
-    buildColumnRegions(columnIds: string[]): Region[];
-    /**
-     * Build minimal Region[] from multiple selection rectangles.
-     * Each rect is collapsed independently, preserving disjoint selections.
-     */
-    buildRegionsFromRects(rects: SelectionRect[]): Region[];
-    buildAllSelectedRegion(): Region;
-    buildColumnRegion(columnId: string): Region;
-    buildRowRegion(fromRowId: TRowId, toRowId: TRowId): Region;
-    cellEdit(rowId: TRowId, field: string, value: unknown): EditParams;
-    clear(target: Region[]): EditParams;
-    paste(source: Region[], target: Region[], cut?: boolean): EditParams;
-    pasteExternal(target: Region[], values: unknown[][]): EditParams;
-    fill(source: Region[], target: Region[]): EditParams;
-    transform(target: Region[], transform: TransformParams): EditParams;
-    deleteRows(rowRanges: [TRowId, TRowId][]): EditParams;
-    restoreRows(rowRanges: [TRowId, TRowId][]): EditParams;
-    deleteAllRows(): EditParams;
-    restoreAllRows(): EditParams;
-    insertRow(anchorRowId: TRowId | undefined, position: InsertParams["position"], values: unknown[][], columnIds: string[]): EditParams;
+/** 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[];
+};
+/**
+ * Context about the current dataset, passed to `loadSuggestions` and extended
+ * into `ChatContext` for `onMessage`.
+ */
+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>[];
+};
+/**
+ * The full context passed to `DataEditorChat.onMessage` when the user sends
+ * a prompt. Includes the prompt itself and all dataset context.
+ */
+type ChatContext<TRow extends DataEditorRow = DataEditorRow> = ChatDataContext<TRow> & {
+    /** The user's chat prompt. */
+    message: string;
+};
+/**
+ * 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> = {
     /**
-     * Returns null when all columns are selected (caller decides representation).
-     * Otherwise returns contiguous column spans as `{ fromColumn, toColumn }` regions.
+     * How many rows to include in the context sample. The SDK picks a
+     * representative slice including rows with errors. When omitted, the SDK decides.
      */
-    private collapseColumns;
-    private viewContext;
-}
+    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;
+};
 
 /**
  * Categories of internal errors surfaced through the `onError` callback.
@@ -1559,6 +1446,341 @@ declare class ErrorHandler {
     handleError(error: UpdogError): void;
 }
 
+type FormulaCellContext = {
+    value: unknown;
+    field: string;
+    rowId: TRowId;
+    getField: (field: string) => unknown;
+    /**
+     * Positional arguments for expression-compiled formulas.
+     * Populated by the expression evaluator when invoking multi-arg function
+     * calls. Single-arg formulas (UPPER, TRIM, etc.) still read from `value`.
+     * Undefined for all non-expression call sites — existing code is unaffected.
+     */
+    args?: readonly unknown[];
+};
+type FormulaParamType = "string" | "number" | "boolean" | "select";
+type FormulaParam = {
+    name: string;
+    label: string;
+    type: FormulaParamType;
+    required?: boolean;
+    defaultValue?: unknown;
+    options?: Array<{
+        id: string;
+        text: string;
+    }>;
+};
+type ColumnInputKind = "single" | "multiple";
+type ColumnInput = {
+    name: string;
+    label: string;
+    kind: ColumnInputKind;
+    required?: boolean;
+};
+type FormulaCategory = "text" | "number" | "logic" | "custom";
+type FormulaArity = {
+    /** Minimum number of positional arguments. 0 means "callable with no args". */
+    min: number;
+    /** Maximum number of positional arguments. Use Number.POSITIVE_INFINITY for variadic. */
+    max: number;
+};
+type FormulaBase = {
+    name: string;
+    label: string;
+    category: FormulaCategory;
+    description?: string;
+    columns?: ColumnInput[];
+    params: FormulaParam[];
+    /**
+     * The call signature of this formula when invoked from the expression
+     * language. Required. For shortcut formulas (UPPER, TRIM, ...) use
+     * { min: 1, max: 1 }. For CLEAR use { min: 0, max: 0 }. For MERGE use
+     * { min: 2, max: Number.POSITIVE_INFINITY }.
+     */
+    arity: FormulaArity;
+    /** Parameter signature shown in autocomplete, without the function name. e.g. "(text, count)" */
+    syntax?: string;
+    /**
+     * Whether this formula may be invoked from the expression parser.
+     * Defaults to true when omitted. MERGE and SPLIT set this to false
+     * because they have dedicated modals that supply their non-expression
+     * params (column lists, separator, ...).
+     */
+    expressionCallable?: boolean;
+};
+type CellFormula = FormulaBase & {
+    kind: "cell";
+    compute: (ctx: FormulaCellContext, params: Record<string, unknown>) => unknown;
+};
+type RowFormula = FormulaBase & {
+    kind: "row";
+    targetFields: (params: Record<string, unknown>) => string[];
+    compute: (ctx: FormulaCellContext, params: Record<string, unknown>) => Record<string, unknown>;
+};
+type FormulaDefinition = CellFormula | RowFormula;
+
+declare class FormulaRegistry {
+    private readonly formulas;
+    register(formula: FormulaDefinition): void;
+    get(name: string): FormulaDefinition | undefined;
+    getAll(): FormulaDefinition[];
+    getByCategory(category: string): FormulaDefinition[];
+    getExpressionCallable(): FormulaDefinition[];
+}
+
+type RegisterSourceOptions = {
+    name: string;
+    id?: DataSourceId;
+    isDeletable?: boolean;
+    isInitialData?: boolean;
+};
+type MergeEntry<TRow> = {
+    row: TRow;
+    sourceId: DataSourceId;
+    isNew: boolean;
+    isEdited: boolean;
+};
+type RemovalPlan<TRow> = {
+    rowsToDelete: Set<TRowId>;
+    rowsToRestore: Array<{
+        rowId: TRowId;
+        row: TRow;
+        originalSourceId: DataSourceId;
+        isNew: boolean;
+        isEdited: boolean;
+    }>;
+};
+type ExtendedRemovalPlan<TRow> = RemovalPlan<TRow> & {
+    sourceId: DataSourceId;
+    repairedEntries: Array<{
+        sourceId: DataSourceId;
+        rowId: TRowId;
+        before: MergeEntry<TRow>;
+        after: MergeEntry<TRow> | null;
+    }>;
+};
+declare class SourceManager<TRow extends DataEditorRow = DataEditorRow> {
+    private readonly _defaultSourceId;
+    private readonly overrides;
+    private readonly sources;
+    private readonly mergedRows;
+    getSourceId(rowId: TRowId): DataSourceId;
+    setSourceId(rowId: TRowId, sourceId: DataSourceId): void;
+    deleteSourceId(rowId: TRowId): void;
+    getOverrides(): ReadonlyMap<TRowId, DataSourceId>;
+    register(options: RegisterSourceOptions): DataSourceId;
+    /**
+     * Re-insert a source using a full captured state, preserving
+     * isVisible, isLoading, rowCount, etc. Used by SourceLifecycle.restore.
+     * If the source already exists, overwrites its state.
+     */
+    restoreState(state: DataSourceState): void;
+    has(sourceId: DataSourceId): boolean;
+    get(sourceId: DataSourceId): DataSourceState | undefined;
+    delete(sourceId: DataSourceId): void;
+    setLoading(sourceId: DataSourceId, isLoading: boolean): void;
+    finalizeAllSources(): void;
+    values(): IterableIterator<DataSourceState>;
+    getHiddenSourceIds(): Set<DataSourceId>;
+    saveMergeSnapshot(sourceId: DataSourceId, rowId: TRowId, existingRow: TRow, previousSourceId: DataSourceId, isNew: boolean, isEdited: boolean): void;
+    /**
+     * Public so commands can re-install merge entries during undo of a remove.
+     */
+    restoreMergeEntry(sourceId: DataSourceId, rowId: TRowId, entry: MergeEntry<TRow>): void;
+    /**
+     * Pure — computes the full removal plan without mutating any state.
+     * Callers run applyRemovalPlan(plan) to commit.
+     */
+    planRemoval(sourceId: DataSourceId): ExtendedRemovalPlan<TRow> | null;
+    /**
+     * Mutates internal state per plan produced by planRemoval.
+     */
+    applyRemovalPlan(plan: ExtendedRemovalPlan<TRow>): void;
+    clear(): void;
+    private getUniqueName;
+}
+
+type ServerDataManagerDeps<TRow extends DataEditorRow = DataEditorRow> = {
+    clear(): void;
+    setLoading(isLoading: boolean): void;
+    registerSource(options: RegisterSourceOptions): DataSourceId;
+    setSourceLoading(sourceId: DataSourceId, isLoading: boolean): void;
+    getLocalRowCount(): number;
+    replaceServerRows(sourceId: DataSourceId, rows: ServerRow<TRow>[], offset: number, counts?: ServerQueryCounts): void;
+    appendServerRows(rows: ServerRow<TRow>[], counts?: ServerQueryCounts): void;
+    prependServerRows(rows: ServerRow<TRow>[], offset: number, counts?: ServerQueryCounts): void;
+    applyServerRowMeta(rows: ServerRow<TRow>[], counts?: ServerQueryCounts): void;
+};
+type FetchDirection = "forward" | "backward" | "jump";
+declare class ServerDataManager<TRow extends DataEditorRow = DataEditorRow> {
+    private _offset;
+    private _totalCount;
+    private _isFetching;
+    private readonly _pageSize;
+    private readonly _maxBufferRows;
+    private _filters;
+    private _sources;
+    private _sort;
+    private _filterOptions;
+    private _filterOptionsFetched;
+    private _abortController;
+    private _syncAbort;
+    private _lastVisibleStart;
+    private _debouncedFetch;
+    private readonly _config;
+    private readonly _dataStoreRef;
+    private readonly _sourceLabel;
+    private _onChanged;
+    constructor(config: ScaleClientApi<TRow>, dataStoreRef: ServerDataManagerDeps<TRow>, sourceLabel: string);
+    get offset(): number;
+    get totalCount(): number | null;
+    get isFetching(): boolean;
+    get pageSize(): number;
+    get maxBufferRows(): number;
+    setOnChanged(callback: () => void): void;
+    setOffset(offset: number): void;
+    setTotalCount(count: number): void;
+    private setFetching;
+    getExcess(currentCount: number, newCount: number): number;
+    shouldFetch(visibleStart: number, visibleEnd: number, loadedCount: number): FetchDirection | null;
+    /**
+     * Full reload — abort in-flight, clear store, fetch first page.
+     * Called on initial load, search/filter/sort changes, and resetFilters.
+     */
+    reload(): void;
+    /**
+     * Scroll-driven pagination with velocity-based debouncing.
+     * Called from CanvasGrid on every scroll event.
+     */
+    handleScroll(visibleStart: number, visibleEnd: number): void;
+    /**
+     * Fetch a single page based on scroll position and current window state.
+     */
+    private fetchPage;
+    /**
+     * Re-query the current viewport and replace row data, metadata, and counts.
+     * Called after successful edits and find-and-replace mutations.
+     * Each call aborts the previous in-flight sync.
+     */
+    syncCurrentView(): void;
+    /**
+     * Merge filter keys into server filter state and reload.
+     * Called by DataStore.setFilters() in server mode and by filter components.
+     */
+    setFilters(filters: Partial<Filters>): void;
+    /**
+     * Set sort state and reload.
+     */
+    setSort(sort: SortState): void;
+    /**
+     * Restrict query to visible sources and reload.
+     * Pass `undefined` to include all sources.
+     */
+    setSources(sources: string[] | undefined): void;
+    /**
+     * Clear all filters and sort, then reload.
+     */
+    resetFilters(): void;
+    /**
+     * One-time fetch of filter option dictionaries for sidebar filter controls.
+     */
+    fetchFilterOptions(): void;
+    getFilterOptions(): FilterOptionsResponse | null;
+    get onEdit(): (params: EditParams, options?: ServerCallOptions) => Promise<EditResponse | void>;
+    get filters(): Record<string, unknown>;
+    get sort(): SortState;
+    get sources(): string[] | undefined;
+    get onSourceRemove(): ((params: SourceRemoveParams) => Promise<void>) | undefined;
+    get onColumnDelete(): ((params: ColumnDeleteParams) => Promise<EditResponse | void>) | undefined;
+    get onColumnEdit(): ((params: ColumnEditParams) => Promise<EditResponse | void>) | undefined;
+    get hasExport(): boolean;
+    private _exportAbortController;
+    export(format: DataEditorFormat, allRows: boolean, rtl: boolean): Promise<void>;
+    clear(): void;
+    destroy(): void;
+}
+
+/**
+ * A post-resolution selection rectangle in stable coordinate space.
+ * Produced by grid-layer resolvers from CellRange[] in grid-index space.
+ * Consumed by DataStore operations and server sync.
+ */
+type SelectionRect = {
+    readonly fields: readonly string[];
+    readonly rowIds: readonly TRowId[];
+};
+
+/**
+ * ServerEditBuilder — Stateless coordinate translator for server-delegated edits.
+ *
+ * Converts frontend coordinates (TRowId, column index, grid ranges) into
+ * `EditParams` with `Region[]` that the server can interpret.
+ *
+ * Does NOT call `onEdit`. Only builds params.
+ * DataStore calls the builder, then sends the result to the server.
+ *
+ * Responsibilities:
+ *   - TRowId → ServerRowId translation via primaryKey
+ *   - Grid index → column ID translation via columns array
+ *   - Filter/sort context attachment from ServerDataManager
+ */
+
+type ServerEditDeps<TRow extends DataEditorRow = DataEditorRow> = {
+    getPrimaryKey: () => string;
+    getRowById: (id: TRowId) => TRow | undefined;
+    getColumnIds: () => string[];
+    getFilters: () => Record<string, unknown>;
+    getSort: () => SortState;
+    getLockedColumns: () => ReadonlyMap<string, ColumnLockMode>;
+};
+declare class ServerEditBuilder<TRow extends DataEditorRow = DataEditorRow> {
+    private readonly _deps;
+    constructor(deps: ServerEditDeps<TRow>);
+    resolveServerRowId(rowId: TRowId): ServerRowId | undefined;
+    buildRegion(rowIds: TRowId[], columnIds: string[]): Region;
+    /**
+     * Collapse rowIds × columnIds into minimal Region[].
+     * - All columns → omit column fields (row-only regions).
+     * - Contiguous columns in schema order → single fromColumn/toColumn span.
+     * - Non-contiguous → one region per contiguous column group.
+     * Rows are expressed as fromRow/toRow using first/last of the provided array.
+     */
+    buildRegions(rowIds: TRowId[], columnIds: string[]): Region[];
+    /**
+     * Collapse columnIds into minimal column-only Region[] (all rows implied).
+     * - All columns → `{ allSelected: true }`.
+     * - Contiguous in schema order → single `{ fromColumn, toColumn }`.
+     * - Non-contiguous → one region per contiguous group.
+     */
+    buildColumnRegions(columnIds: string[]): Region[];
+    /**
+     * Build minimal Region[] from multiple selection rectangles.
+     * Each rect is collapsed independently, preserving disjoint selections.
+     */
+    buildRegionsFromRects(rects: SelectionRect[]): Region[];
+    buildAllSelectedRegion(): Region;
+    buildColumnRegion(columnId: string): Region;
+    buildRowRegion(fromRowId: TRowId, toRowId: TRowId): Region;
+    cellEdit(rowId: TRowId, field: string, value: unknown): EditParams;
+    clear(target: Region[]): EditParams;
+    paste(source: Region[], target: Region[], cut?: boolean): EditParams;
+    pasteExternal(target: Region[], values: unknown[][]): EditParams;
+    fill(source: Region[], target: Region[]): EditParams;
+    transform(target: Region[], transform: TransformParams): EditParams;
+    deleteRows(rowRanges: [TRowId, TRowId][]): EditParams;
+    restoreRows(rowRanges: [TRowId, TRowId][]): EditParams;
+    deleteAllRows(): EditParams;
+    restoreAllRows(): EditParams;
+    insertRow(anchorRowId: TRowId | undefined, position: InsertParams["position"], values: unknown[][], columnIds: string[]): EditParams;
+    /**
+     * Returns null when all columns are selected (caller decides representation).
+     * Otherwise returns contiguous column spans as `{ fromColumn, toColumn }` regions.
+     */
+    private collapseColumns;
+    private viewContext;
+}
+
 /**
  * DirtyTracker — Change classification and revert detection for rows.
  *
@@ -1979,89 +2201,6 @@ type FillSpec = {
     rowIdToFillIndex: ReadonlyMap<TRowId, number>;
 };
 
-type FormulaCellContext = {
-    value: unknown;
-    field: string;
-    rowId: TRowId;
-    getField: (field: string) => unknown;
-    /**
-     * Positional arguments for expression-compiled formulas.
-     * Populated by the expression evaluator when invoking multi-arg function
-     * calls. Single-arg formulas (UPPER, TRIM, etc.) still read from `value`.
-     * Undefined for all non-expression call sites — existing code is unaffected.
-     */
-    args?: readonly unknown[];
-};
-type FormulaParamType = "string" | "number" | "boolean" | "select";
-type FormulaParam = {
-    name: string;
-    label: string;
-    type: FormulaParamType;
-    required?: boolean;
-    defaultValue?: unknown;
-    options?: Array<{
-        id: string;
-        text: string;
-    }>;
-};
-type ColumnInputKind = "single" | "multiple";
-type ColumnInput = {
-    name: string;
-    label: string;
-    kind: ColumnInputKind;
-    required?: boolean;
-};
-type FormulaCategory = "text" | "number" | "logic" | "custom";
-type FormulaArity = {
-    /** Minimum number of positional arguments. 0 means "callable with no args". */
-    min: number;
-    /** Maximum number of positional arguments. Use Number.POSITIVE_INFINITY for variadic. */
-    max: number;
-};
-type FormulaBase = {
-    name: string;
-    label: string;
-    category: FormulaCategory;
-    description?: string;
-    columns?: ColumnInput[];
-    params: FormulaParam[];
-    /**
-     * The call signature of this formula when invoked from the expression
-     * language. Required. For shortcut formulas (UPPER, TRIM, ...) use
-     * { min: 1, max: 1 }. For CLEAR use { min: 0, max: 0 }. For MERGE use
-     * { min: 2, max: Number.POSITIVE_INFINITY }.
-     */
-    arity: FormulaArity;
-    /** Parameter signature shown in autocomplete, without the function name. e.g. "(text, count)" */
-    syntax?: string;
-    /**
-     * Whether this formula may be invoked from the expression parser.
-     * Defaults to true when omitted. MERGE and SPLIT set this to false
-     * because they have dedicated modals that supply their non-expression
-     * params (column lists, separator, ...).
-     */
-    expressionCallable?: boolean;
-};
-type CellFormula = FormulaBase & {
-    kind: "cell";
-    compute: (ctx: FormulaCellContext, params: Record<string, unknown>) => unknown;
-};
-type RowFormula = FormulaBase & {
-    kind: "row";
-    targetFields: (params: Record<string, unknown>) => string[];
-    compute: (ctx: FormulaCellContext, params: Record<string, unknown>) => Record<string, unknown>;
-};
-type FormulaDefinition = CellFormula | RowFormula;
-
-declare class FormulaRegistry {
-    private readonly formulas;
-    register(formula: FormulaDefinition): void;
-    get(name: string): FormulaDefinition | undefined;
-    getAll(): FormulaDefinition[];
-    getByCategory(category: string): FormulaDefinition[];
-    getExpressionCallable(): FormulaDefinition[];
-}
-
 /**
  * Paste-level delta computations.
  *
@@ -2086,144 +2225,6 @@ type PasteSpec = {
     isCut: boolean;
 };
 
-/**
- * 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`.
- */
-type ChatOp = {
-    action: "edit";
-    fn: 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: "message";
-    content: string;
-} | {
-    type: "rows";
-    content: TRow[];
-} | {
-    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[];
-};
-/**
- * Context about the current dataset, passed to `loadSuggestions` and extended
- * into `ChatContext` for `onMessage`.
- */
-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>[];
-};
-/**
- * The full context passed to `DataEditorChat.onMessage` when the user sends
- * a prompt. Includes the prompt itself and all dataset context.
- */
-type ChatContext<TRow extends DataEditorRow = DataEditorRow> = ChatDataContext<TRow> & {
-    /** The user's chat prompt. */
-    message: string;
-};
-/**
- * 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> = {
-    /**
-     * 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 ApplyFormulaOptions = {
     /**
      * Column IDs to delete AFTER the formula has been applied.
@@ -2314,11 +2315,15 @@ declare class DataStore<TRow extends DataEditorRow = DataEditorRow> {
     private _dynamicColumns;
     private _effectiveColumns;
     private _lastColumnsInput;
+    private _addedOptions;
+    private withAddedOptions;
+    private rebuildEffectiveColumns;
     setSchemaColumns(columns: DataEditorColumn[]): void;
     getDynamicColumns(): DataEditorColumn[];
     getEffectiveColumns: () => DataEditorColumn[];
     setDynamicColumns(fn: (prev: DataEditorColumn[]) => DataEditorColumn[]): void;
     addDynamicColumns(columns: DataEditorColumn[]): void;
+    addColumnOptions(columnId: string, values: string[]): void;
     setColumns(columns: DataEditorColumn[]): void;
     subscribe: (listener: () => void) => (() => void);
     getSnapshot: () => DataStoreSnapshot;