@updog/data-editor 0.1.0

package/index.d.ts

@@ -0,0 +1,2866 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+declare var export_default = {
+  ui: {
+    button: {
+      defaultAriaLabel: "Button",
+    },
+    calendar: {
+      previousMonth: "Previous month",
+      nextMonth: "Next month",
+      months: {
+        january: "January",
+        february: "February",
+        march: "March",
+        april: "April",
+        may: "May",
+        june: "June",
+        july: "July",
+        august: "August",
+        september: "September",
+        october: "October",
+        november: "November",
+        december: "December",
+      },
+      monthsShort: {
+        january: "Jan",
+        february: "Feb",
+        march: "Mar",
+        april: "Apr",
+        may: "May",
+        june: "Jun",
+        july: "Jul",
+        august: "Aug",
+        september: "Sep",
+        october: "Oct",
+        november: "Nov",
+        december: "Dec",
+      },
+      weekDays: {
+        mo: "Mo",
+        tu: "Tu",
+        we: "We",
+        th: "Th",
+        fr: "Fr",
+        sa: "Sa",
+        su: "Su",
+      },
+      weekDaysFull: {
+        mo: "Monday",
+        tu: "Tuesday",
+        we: "Wednesday",
+        th: "Thursday",
+        fr: "Friday",
+        sa: "Saturday",
+        su: "Sunday",
+      },
+      label: "Calendar",
+      selectMonth: "{{month}}, select month",
+      selectYear: "{{year}}, select year",
+    },
+    datePicker: {
+      placeholder: "DD/MM/YYYY",
+      openCalendar: "Open calendar",
+      clearSelection: "Clear selection",
+    },
+    input: {
+      clearField: "Clear field",
+      showPassword: "Show password",
+      hidePassword: "Hide password",
+    },
+    select: {
+      noResults: "No results",
+      clearSelection: "Clear selection",
+    },
+    comboBox: {
+      noResults: "No results",
+      clearSelection: "Clear selection",
+    },
+    emptyState: {
+      illustrationAlt: "No data illustration",
+    },
+    tag: {
+      remove: "Remove",
+    },
+    modal: {
+      closeLabel: "Close",
+    },
+    drawer: {
+      closeLabel: "Close",
+    },
+    toast: {
+      closeNotification: "Close notification",
+    },
+    confirmDialog: {
+      cancel: "Cancel",
+    },
+    menu: {
+      submenuAriaLabel: "{{text}} submenu",
+    },
+    formField: {
+      optional: "Optional",
+    },
+    segment: {
+      segmentControl: "Segment control",
+    },
+    stepper: {
+      progress: "Progress",
+    },
+  },
+  dataEditor: {
+    modal: {
+      importTitle: "Import Data",
+      editTitle: "Edit Data",
+    },
+    confirmClose: {
+      title: "Discard changes?",
+      text: "You have unsaved changes. Are you sure you want to close?",
+      action: "Discard",
+    },
+    confirmSubmit: {
+      title: "Confirm submission",
+      text: "You are about to submit the following changes:",
+      createRows_one: "{{count}} new row will be created",
+      createRows_other: "{{count}} new rows will be created",
+      updateRows_one: "{{count}} row will be updated",
+      updateRows_other: "{{count}} rows will be updated",
+      deleteRows_one: "{{count}} row will be deleted",
+      deleteRows_other: "{{count}} rows will be deleted",
+      bannerTitle_one: "{{count}} row has errors",
+      bannerTitle_other: "{{count}} rows have errors",
+      action: "Submit",
+    },
+    footer: {
+      submit: "Submit",
+      import: "Import",
+      next: "Next",
+      cancel: "Cancel",
+      back: "Back",
+      export: "Export",
+      exportAll: "Export all",
+      exportFiltered: "Export filtered",
+      csvFormat: "Comma-separated values (.csv)",
+      tsvFormat: "Tab-separated values (.tsv)",
+      excelFormat: "Microsoft Excel (.xlsx)",
+      jsonFormat: "JSON (.json)",
+      xmlFormat: "XML (.xml)",
+    },
+    statusBar: {
+      totalRows: "{{total}} rows",
+      filteredRows: "{{filtered}} of {{total}} rows",
+    },
+    toast: {
+      dismiss: "Dismiss",
+      rowMayNotBeVisible:
+        "Row has been added but may not be visible due to active filters or sorting",
+    },
+    grid: {
+      emptyTitle: "No data",
+      emptyText: "Import data or add rows manually",
+      loading: "Loading data...",
+      emptyCell: "Empty",
+      a11y: {
+        gridLabel: "Data editor",
+        cellFocus: "Row {{row}}, {{column}}: {{value}}",
+        cellFocusEmpty: "Row {{row}}, {{column}}: empty",
+        selectAll: "All cells selected",
+        rowsSelected: "{{count}} rows selected",
+        columnsSelected: "{{count}} columns selected",
+      },
+      contextMenu: {
+        cut: "Cut",
+        cutCells: "Cut ({{count}})",
+        copy: "Copy",
+        copyCells: "Copy ({{count}})",
+        paste: "Paste",
+        deleteRow: "Delete row",
+        deleteRows: "Delete rows ({{count}})",
+        restoreRow: "Restore row",
+        restoreRows: "Restore rows ({{count}})",
+        sortAsc: "Sort A to Z",
+        sortDesc: "Sort Z to A",
+        sortRemove: "Remove sorting",
+        insertAbove: "Insert row above",
+        insertBelow: "Insert row below",
+        duplicateRow: "Duplicate row",
+        cutRow: "Cut row",
+        cutRows: "Cut rows ({{count}})",
+        copyRow: "Copy row",
+        copyRows: "Copy rows ({{count}})",
+        clearRow: "Clear row",
+        clearRows: "Clear rows ({{count}})",
+        clearAll: "Clear all",
+        pin: "Pin column",
+        pinColumns: "Pin columns",
+        unpin: "Unpin column",
+        unpinColumns: "Unpin columns",
+        cutColumn: "Cut column",
+        copyColumn: "Copy column",
+        pasteColumn: "Paste column",
+        lockColumn: "Lock column",
+        lockColumns: "Lock columns",
+        lockedCannotClear: "Can't clear a locked column",
+        lockedCannotDelete: "Can't delete a locked column",
+        lockedCannotRevert: "Can't revert a locked column",
+        lockedCannotUnlock: "This column was locked by configuration",
+        unlockColumn: "Unlock column",
+        unlockColumns: "Unlock columns",
+        clearColumn: "Clear column",
+        clearColumns: "Clear columns",
+        deleteColumn: "Delete column",
+        deleteColumns: "Delete columns",
+        editColumn: "Edit column",
+        transform: "Transform",
+        transformMerge: "Merge",
+        transformSplit: "Split",
+        formula: "Formula",
+        lockedCannotFormula: "Can't apply a formula to a locked column",
+        revertChanges: "Revert changes",
+      },
+      formulaModal: {
+        title: "Apply formula",
+        apply: "Apply",
+        applyToRows_one: "Apply to {{count}} row",
+        applyToRows_other: "Apply to {{count}} rows",
+        inputLabel: "Formula",
+        placeholder: "=UPPER(value) · Type @ to browse",
+        groupFunctions: "Functions",
+        groupColumns: "Columns",
+        groupKeywords: "Keywords",
+        keywordValue: "Current cell value",
+        preview: "Preview",
+        errors: {
+          "unexpected-character": "'{{char}}' isn't valid here",
+          "unexpected-escape":
+            "Invalid escape '\\{{char}}' — only \\} and \\\\ are allowed inside @{}",
+          "unterminated-column-ref": "@{...} isn't closed — add a closing }",
+          "expected-equals": "Formulas must start with =",
+          "expected-expression": "Add a function, value, or @column after =",
+          "expected-open-paren": "Missing '(' after {{name}}",
+          "expected-close-paren": "Missing closing ')'",
+          "expected-column-name":
+            "Add a column name after @ — e.g. @Name or @{First Name}",
+          "unexpected-token": "'{{token}}' isn't expected here",
+          "unknown-function": "No function named '{{name}}'",
+          "unknown-column": "No column named '{{name}}'",
+          "arity-mismatch-too-few":
+            "{{name}} expects at least {{min}} arguments — got {{actual}}",
+          "arity-mismatch-too-many":
+            "{{name}} takes at most {{max}} arguments — got {{actual}}",
+          "function-not-in-expression-mode":
+            "'{{name}}' can't be used here — use Merge or Split from the Transform menu",
+          "column-not-numeric":
+            "'{{name}}' is not a number column — arithmetic requires number columns",
+        },
+      },
+      formulas: {
+        UPPER: { label: "Uppercase" },
+        LOWER: { label: "Lowercase" },
+        TRIM: { label: "Trim whitespace" },
+        CAPITALIZE: { label: "Capitalize" },
+        ROUND: { label: "Round" },
+        ROUND_UP: { label: "Round up" },
+        ROUND_DOWN: { label: "Round down" },
+        ABS: { label: "Absolute value" },
+        CLEAR: { label: "Clear" },
+        CONCAT: { label: "Concatenate" },
+        LEFT: { label: "Left" },
+        RIGHT: { label: "Right" },
+        MID: { label: "Mid" },
+        SUBSTITUTE: { label: "Substitute" },
+        MERGE: { label: "Merge columns" },
+        SPLIT: { label: "Split column" },
+      },
+      transformMerge: {
+        addColumn: "Add column",
+        apply: "Apply",
+        deleteSource: "Delete source columns",
+        deleteSourceDescription:
+          "Columns added during import can be deleted. Schema columns will remain.",
+        from: "From",
+        into: "Into",
+        joinWith: "Join with",
+        joinWithPlaceholder: "e.g. space, comma",
+        preview: "Preview",
+        removeColumn: "Remove column",
+        applyToRows_one: "Apply to {{count}} row",
+        applyToRows_other: "Apply to {{count}} rows",
+        selectColumn: "Select column",
+        title: "Merge",
+      },
+      transformSplit: {
+        addColumn: "Add column",
+        apply: "Apply",
+        applyToRows_one: "Apply to {{count}} row",
+        applyToRows_other: "Apply to {{count}} rows",
+        deleteSource: "Delete source column",
+        deleteSourceDescription:
+          "Columns added during import can be deleted. Schema columns will remain.",
+        from: "From",
+        into: "Into",
+        preview: "Preview",
+        removeColumn: "Remove column",
+        selectColumn: "Select column",
+        splitBy: "Split by",
+        splitByPlaceholder: "e.g. space, comma",
+        title: "Split",
+      },
+      phase: {
+        splitting: "Splitting columns...",
+        merging: "Merging columns...",
+        pasting: "Pasting data...",
+        clearing: "Clearing cells...",
+        filling: "Filling cells...",
+        sorting: "Sorting rows...",
+        undoing: "Reverting changes...",
+        redoing: "Reapplying changes...",
+        deleting: "Deleting rows...",
+        deletingSource: "Removing data source...",
+        importing: "Importing data...",
+        transforming: "Transforming...",
+        default: "Processing...",
+      },
+    },
+    dataSources: {
+      title: "Data Sources",
+      importData: "Import data",
+      addRow: "Add row",
+      manuallyAdded: "Manually added",
+      existingData: "Existing data",
+      addDataSource: "Add data source",
+      show: "Show",
+      hide: "Hide",
+      remove: "Remove",
+      confirmRemove: {
+        title: "Remove data source?",
+        text: "All data imported from this source will be removed.",
+        action: "Remove",
+      },
+    },
+    filters: {
+      title: "Filters",
+      search: "Search",
+      replace: "Replace",
+      findAndReplace: "Find & Replace",
+      searchMode: "Search mode",
+      matchCase: "Match case",
+      matchEntireCell: "Match entire cell",
+      rows: "Rows",
+      columns: "Columns",
+      searchInColumns: "Search in columns",
+      allColumns: "All columns",
+      rowsWithErrors: "Rows with errors",
+      editedRows: "Changed rows",
+      newRows: "New rows",
+      rowsWithEmptyCells: "Rows with empty cells",
+      deletedRows: "Deleted rows",
+      previousOccurrence: "Previous occurrence",
+      nextOccurrence: "Next occurrence",
+      zeroResults: "No results found",
+      allValues: "All values",
+      min: "Min",
+      max: "Max",
+      from: "From",
+      to: "To",
+      replaceAll: "Replace all",
+      resetFilters: "Reset filters",
+      showMore: "View error details",
+      showLess: "Hide error details",
+    },
+    undoRedo: {
+      undo: "Undo",
+      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",
+    },
+    license: {
+      loading: "Loading data editor",
+      errors: {
+        LICENSE_INVALID: {
+          title: "Invalid license",
+          text: "Please contact support for assistance.",
+        },
+        MISSING_API_KEY: {
+          title: "Missing API key",
+          text: "No API key was provided. Please configure a valid API key.",
+        },
+        DOMAIN_NOT_ALLOWED: {
+          title: "Domain not allowed",
+          text: "This domain is not authorized for this license. Please check your domain settings.",
+        },
+        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",
+    },
+    uploader: {
+      steps: {
+        selectFiles: "Select files",
+        sheetSelection: "Select sheet",
+        matchColumns: "Match columns",
+        matchValues: "Match values",
+        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",
+        formats: "CSV, TSV, XLSX, JSON, XML",
+        downloadExample: "Download sample file",
+      },
+      remoteSources: {
+        browseFile: "Browse file",
+        emptyData: "The source returned no data",
+        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",
+        targetColumns: "Target columns",
+        unmatchedCount: "{{count}} unmatched",
+        selectColumnPlaceholder: "Select column",
+        bestMatch: "Best match",
+        createColumn: "Create column",
+        createColumnNameLabel: "Column name",
+        createColumnNamePlaceholder: "Enter column name",
+        createColumnNameTaken: "A column with this name already exists",
+        createColumnSubmit: "Create",
+        createColumnTitle: "Create column",
+        editColumnSubmit: "Save",
+        editColumnTitle: "Edit column",
+        createColumnWarning: "A matching column already exists",
+        newColumnTag: "New",
+        unmatchedWarning:
+          "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",
+        targetValue: "Target value",
+        fullyMatched: "All matched",
+        unmatchedCount: "{{matched}}/{{total}} matched",
+        selectValuePlaceholder: "Select value",
+        showMatched: "Show matched",
+        allMatched: "All values are matched",
+        unmatchedWarning: "Unmatched values won't be imported",
+      },
+      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.",
+      },
+    },
+    chat: {
+      emptyTitle: "What would you like to fix?",
+      header: "Chat with AI",
+      placeholder: "Ask AI...",
+      send: "Send",
+    },
+    common: {
+      cancel: "Cancel",
+      collapse: "Collapse",
+      expand: "Expand",
+      remove: "Remove",
+      search: "Search",
+    },
+  },
+};
+
+type PluralSuffixes = "_zero" | "_one" | "_two" | "_few" | "_many" | "_other";
+
+/** Makes all properties optional recursively. */
+type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends Record<string, unknown>
+    ? DeepPartial<T[P]>
+    : T[P];
+};
+
+/**
+ * Expands any key ending in a plural suffix to include all 6 CLDR plural suffixes.
+ * e.g. `{ createRows_one: string; createRows_other: string }` becomes
+ *      `{ createRows_zero?: string; createRows_one?: string; createRows_two?: string; ... }`
+ */
+type ExpandPluralKeys<T> = T extends Record<string, unknown>
+  ? {
+      [K in keyof T as K extends `${infer Base}${PluralSuffixes}`
+        ? `${Base}_zero` | `${Base}_one` | `${Base}_two` | `${Base}_few` | `${Base}_many` | `${Base}_other`
+        : K]: T[K] extends Record<string, unknown> ? ExpandPluralKeys<T[K]> : T[K];
+    }
+  : T;
+
+/**
+ * Consumer-facing translations type. All keys optional — consumers override only what they need.
+ * Plural keys are expanded to all 6 CLDR forms.
+ */
+type DataEditorTranslations = DeepPartial<ExpandPluralKeys<typeof export_default>>;
+
+/**
+ * ChunkedProcessor — Generic utility for processing items in prioritized chunks
+ * with cancellation support via generation counter.
+ *
+ * Used to break O(N) synchronous operations into non-blocking background work:
+ *   1. Priority items are processed synchronously first (e.g. viewport rows)
+ *   2. Remaining items are processed in chunks via MessageChannel
+ *   3. Between chunks the browser can paint frames and handle events
+ *
+ * Uses MessageChannel instead of setTimeout(0) to avoid the browser's ~4ms
+ * minimum delay imposed on nested setTimeouts, reducing scheduling overhead
+ * from ~6ms/chunk to ~1ms/chunk.
+ *
+ * Cancellation uses the same generation counter pattern as FilterEngine:
+ * calling cancel() or run() again increments the generation, and any
+ * in-flight MessageChannel callbacks silently exit when they detect
+ * their generation is stale.
+ *
+ * This class has zero domain knowledge — it works with any item type.
+ */
+type ChunkedProcessorCallbacks<T> = {
+    /** All items to process (excluding priority items). */
+    all: T[];
+    /** Items processed synchronously before any chunking begins. */
+    priority: T[];
+    /** Called for each batch of items (priority batch first, then chunks). */
+    onChunk: (items: T[]) => void;
+    /** Called after each chunk with (processed so far, total). */
+    onProgress: (processed: number, total: number) => void;
+    /** Called once when all items have been processed. */
+    onComplete: () => void;
+    /** Called when processing is cancelled via cancel(). */
+    onCancel: () => void;
+};
+declare class ChunkedProcessor<T> {
+    private _generation;
+    private _isRunning;
+    private _chunkSize;
+    private _activeOnCancel;
+    private _channel;
+    private _pendingChunkFn;
+    constructor(chunkSize?: number);
+    get isRunning(): boolean;
+    get chunkSize(): number;
+    run(params: ChunkedProcessorCallbacks<T>): void;
+    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;
+}
+
+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: DataEditorServer<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;
+}
+
+type UpdogErrorCode = "PARSE_ERROR" | "RENDER_ERROR" | "TRANSFORM_ERROR" | "VALIDATION_ERROR" | "WORKER_ERROR" | "COMMAND_ERROR" | "OPERATION_ERROR";
+type UpdogError = {
+    code: UpdogErrorCode;
+    message: string;
+    source: string;
+    originalError?: unknown;
+};
+
+declare class ErrorHandler {
+    private onError?;
+    constructor(onError?: (error: UpdogError) => void);
+    handleError(error: UpdogError): void;
+}
+
+/**
+ * DirtyTracker — Change classification and revert detection for rows.
+ *
+ * Every row falls into one of three categories:
+ *   - Clean    — matches the backend; not tracked here at all
+ *   - New      — created locally (CSV import or manual add), never existed on the backend
+ *   - Edited   — exists on the backend but has been modified locally
+ *
+ * Classification uses inverted tracking via `nonBackendRowIds`: only non-backend
+ * rows (CSV imports, manual adds) are stored in the set. Since backend rows are
+ * the vast majority (~1M), this inverted approach saves ~50MB by assuming any
+ * row NOT in the set is a backend row.
+ *   - First edit of a backend row → "edited", original row is snapshotted
+ *   - First edit of a non-backend row → "new"
+ *
+ * Smart revert: after every edit, the current row is compared field-by-field
+ * against the snapshot. If all fields match the original, the row silently
+ * reverts to "clean" — no dirty flag, no undo entry needed. This lets users
+ * fix typos by simply typing the original value back.
+ *
+ * Merge snapshots: when a CSV import overwrites an existing row, the original
+ * data + classification is saved so it can be restored if the source is removed.
+ */
+
+type IDirtyTracker<TRow extends DataEditorRow = DataEditorRow> = {
+    markDeleted(id: TRowId): void;
+    unmarkDeleted(id: TRowId): void;
+    isDeleted(id: TRowId): boolean;
+    getDeletedRowIds(): ReadonlySet<TRowId>;
+    deletedCount(): number;
+    isDefaultSourceRow(id: TRowId): boolean;
+    isNew(id: TRowId): boolean;
+    isEdited(id: TRowId): boolean;
+    isCellDirty(id: TRowId, field: string, currentRow: TRow | undefined): boolean;
+    getOriginalCellValue(id: TRowId, field: string): unknown | undefined;
+    getOriginalRow(id: TRowId): TRow | undefined;
+    hasOriginalRow(id: TRowId): boolean;
+    trackNonBackendRow(id: TRowId): void;
+    markNew(id: TRowId): void;
+    markEdited(id: TRowId): void;
+    snapshotOriginal(id: TRowId, row: TRow): void;
+    classifyOnFirstEdit(id: TRowId, row: TRow): void;
+    checkRevert(id: TRowId, currentRow: TRow): {
+        wasNew: boolean;
+        wasEdited: boolean;
+    };
+    removeTracking(id: TRowId): void;
+    getNewRowIds(): ReadonlySet<TRowId>;
+    getEditedRowIds(): ReadonlySet<TRowId>;
+    getMergeSnapshot(id: TRowId): {
+        isNew: boolean;
+        isEdited: boolean;
+    };
+    restoreMergeClassification(id: TRowId, isNew: boolean, isEdited: boolean): void;
+    clear(): void;
+};
+
+interface FlagReader {
+    hasError(id: TRowId): boolean;
+    isNew(id: TRowId): boolean;
+    isEdited(id: TRowId): boolean;
+    hasEmptyCells(id: TRowId): boolean;
+    isDeleted(id: TRowId): boolean;
+    hasDeletedRows(): boolean;
+    getSourceId(id: TRowId): string;
+    getErrorBitmask(id: TRowId, fieldOrder: string[], wordIdx: number): number;
+    getEditedBitmask(id: TRowId, fieldOrder: string[], wordIdx: number): number;
+    getErrorMessageToRows(): ReadonlyMap<string, ReadonlySet<TRowId>>;
+    getRowValidations(id: TRowId): Map<string, NonNullable<ValidationResult>> | undefined;
+}
+interface FilterRowReader<TRow extends DataEditorRow = DataEditorRow> {
+    getRowIds(): TRowId[];
+    getRowById(id: TRowId): TRow | undefined;
+    getHiddenSourceIds(): Set<DataSourceId>;
+}
+type IFilterEngine<TRow extends DataEditorRow = DataEditorRow> = {
+    getFilteredRowIds(): TRowId[] | null;
+    getBaseFilteredRowIds(): TRowId[] | null;
+    getFilterVersion(): number;
+    isFiltering(): boolean;
+    getFilters(): Filters;
+    getFieldOrder(): string[];
+    getWordsPerRow(): number;
+    getShowOnlyDeletedRows(): boolean;
+    getSortState(): SortState;
+    setReaders(rowReader: FilterRowReader<TRow>, flagReader: FlagReader): void;
+    setColumns(columns: DataEditorColumn[]): void;
+    setFilters(filters: Partial<Filters>): void;
+    setSortState(state: SortState, sortType?: SortType, locales?: string[]): Promise<void>;
+    updateRowText(rowId: TRowId, row: TRow): void;
+    updateRowsText(rows: {
+        id: TRowId;
+        row: TRow;
+    }[]): void;
+    deleteRowTextCache(rowId: TRowId): void;
+    clearRowTextCacheAll(): void;
+    setRowTextCache(rowId: TRowId, row: TRow): void;
+    rebuild(): void;
+    refilterAfterColumnsChange(): void;
+    notifyRowsAdded(ids: TRowId[]): void;
+    notifyRowsDeleted(deletedIds: TRowId[]): void;
+    notifyRowsInserted(restoredIds: TRowId[], positions: number[]): void;
+    refilterAfterSourceToggle(sourceId: DataSourceId, isVisible: boolean): void;
+    refilterAfterFlagChange(): void;
+    flushPendingFlags(): void;
+    markFlagsDirty(): void;
+    testRowAgainstFilters(rowId: TRowId, row: TRow, flagReader: FlagReader, hiddenSourceIds: Set<DataSourceId>): boolean;
+    getAllRowIdsSorted(rowReader: FilterRowReader<TRow>): Promise<TRowId[]>;
+    clear(): void;
+    destroy(): void;
+};
+
+/**
+ * RowStore — Row storage with dual-access pattern for the grid engine.
+ *
+ * Maintains two parallel structures:
+ *   - (TRow | undefined)[]  → O(1) lookup by stable internal ID (rows[id])
+ *   - TRowId[]              → O(1) lookup by visual index (required by the grid)
+ *
+ * The grid calls getRow(index) on every frame, so index-based access must be
+ * instant. Filtered views are supported by passing an alternate ID array
+ * (filteredIds) to the access methods — the store itself is unaware of filters.
+ *
+ * An inverted index (rowId → visual index) is lazily rebuilt on demand for
+ * O(1) reverse lookups (e.g., scrolling to a specific row after undo).
+ *
+ * Internal row IDs are auto-generated as sequential numbers (1, 2, 3, …).
+ * Using a plain array indexed by ID eliminates Map hash table overhead
+ * (~10MB saved at 1M rows). Deleted slots are set to undefined (not delete)
+ * to keep V8 in HOLEY_ELEMENTS mode.
+ */
+
+declare class RowStore<TRow extends DataEditorRow = DataEditorRow> {
+    private rows;
+    private rowIds;
+    private rowIdCounter;
+    private rowIdToIndex;
+    private _rowIndexDirty;
+    nextRowId(): TRowId;
+    getRow(index: number, filteredIds: TRowId[] | null): TRow | undefined;
+    getRowById(id: TRowId): TRow | undefined;
+    getRowId(index: number, filteredIds: TRowId[] | null): TRowId | undefined;
+    getRowIndex(rowId: TRowId, filteredIds: TRowId[] | null): number;
+    getRowIds(): TRowId[];
+    getRowCount(): number;
+    allRows(): IterableIterator<TRow>;
+    hasRow(id: TRowId): boolean;
+    setRow(id: TRowId, row: TRow): void;
+    deleteRow(id: TRowId): void;
+    pushRowId(id: TRowId): void;
+    spliceRowId(pos: number, id: TRowId): void;
+    removeRowId(id: TRowId): void;
+    filterRowIds(predicate: (id: TRowId) => boolean): void;
+    trimFromStart(count: number): TRowId[];
+    trimFromEnd(count: number): TRowId[];
+    unshiftRowIds(ids: TRowId[]): void;
+    invalidateIndex(): void;
+    clear(): void;
+    private rebuildRowIdToIndex;
+}
+
+/**
+ * SnapshotManager — Immutable snapshot construction and listener notification
+ * for React's useSyncExternalStore integration.
+ *
+ * Builds a DataStoreSnapshot object that React components subscribe to via
+ * useSyncExternalStore(subscribe, getSnapshot). A new snapshot object is
+ * created on every notify() call, which triggers React's shallow comparison
+ * and re-renders only when values actually change.
+ *
+ * Count tracking has two tiers:
+ *   - Visible counts: new/edited/error/empty rows from visible sources only.
+ *     Updated incrementally via adjust*() methods on single-row edits, or
+ *     recomputed in bulk when _countsDirty is set (after deletes, source changes, etc.).
+ *   - Filtered counts: subset of visible counts restricted to filteredRowIds.
+ *     Recomputed when _filteredCountsDirty is set (after filter changes).
+ *
+ * Batching: multiple operations can be grouped via beginBatch()/endBatch().
+ * While batching, notify() calls are deferred — only the outermost endBatch()
+ * triggers a single notification, preventing intermediate snapshots from
+ * reaching React during multi-step operations (fill handle, batch delete, etc.).
+ *
+ * The SnapshotStateReader interface decouples this module from all other modules.
+ * DataStore implements the interface by delegating to RowStore, DirtyTracker,
+ * FilterEngine, and ValidationStore, so SnapshotManager never imports them directly.
+ */
+
+type Listener = () => void;
+interface SnapshotStateReader {
+    getRowCount(): number;
+    getFilteredRowIds(): TRowId[] | null;
+    getBaseFilteredRowIds(): TRowId[] | null;
+    getNewRowIds(): ReadonlySet<TRowId>;
+    getEditedRowIds(): ReadonlySet<TRowId>;
+    getRowsWithErrors(): ReadonlySet<TRowId>;
+    getRowsWithEmptyCells(): ReadonlySet<TRowId>;
+    getDeletedCount(): number;
+    isDeleted(id: TRowId): boolean;
+    getSources(): DataSourceState[];
+    isRowVisible(id: TRowId): boolean;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    isLoading(): boolean;
+    isFiltering(): boolean;
+    getVersion(): number;
+    getFilteredNewCount(ids: TRowId[] | null): number;
+    getFilteredEditedCount(ids: TRowId[] | null): number;
+    getFilteredDirtyCount(ids: TRowId[] | null): number;
+    getFilteredErrorCount(ids: TRowId[] | null): number;
+    getFilteredEmptyCount(ids: TRowId[] | null): number;
+    getErrorMessageCounts(filteredRowIds: TRowId[] | null): Record<string, number>;
+    hasColumnScoping(): boolean;
+    getSortState(): SortState;
+    getShowOnlyDeletedRows(): boolean;
+    /** Server-provided aggregate counts. Present only in server mode. */
+    getServerEditedCount?(): number;
+    getServerNewCount?(): number;
+    getServerErrorCount?(): number;
+    getServerEmptyCount?(): number;
+    getServerDeletedCount?(): number;
+}
+declare class SnapshotManager {
+    private _visibleNewCount;
+    private _visibleEditedCount;
+    private _visibleDirtyCount;
+    private _visibleErrorCount;
+    private _visibleEmptyCount;
+    private _countsDirty;
+    private _filteredDirtyCount;
+    private _filteredNewCount;
+    private _filteredEditedCount;
+    private _filteredErrorCount;
+    private _filteredEmptyCount;
+    private _errorMessageCounts;
+    private _filteredCountsDirty;
+    private _phase;
+    private _processingInfo;
+    private snapshot;
+    private listeners;
+    private batchDepth;
+    private pendingNotify;
+    get countsDirty(): boolean;
+    markCountsDirty(): void;
+    markFilteredCountsDirty(): void;
+    adjustVisibleErrorCount(delta: number): void;
+    adjustVisibleNewCount(delta: number): void;
+    adjustVisibleEditedCount(delta: number): void;
+    adjustVisibleDirtyCount(delta: number): void;
+    subscribe: (listener: Listener) => (() => void);
+    getSnapshot: () => DataStoreSnapshot;
+    isBatching(): boolean;
+    beginBatch(): boolean;
+    endBatch(): boolean;
+    setPhase(phase: ProcessingPhase, info?: ProcessingInfo): void;
+    getPhase(): ProcessingPhase;
+    notify(reader: SnapshotStateReader): void;
+    clear(): void;
+    clearListeners(): void;
+    private recomputeVisibleCounts;
+    private recomputeFilteredCounts;
+}
+
+/**
+ * ValidationStore — Cell-level validation state with incremental count tracking.
+ *
+ * Stores validation results in a two-level map: rowId → fieldId → ValidationResult[].
+ * Maintains a running error count and a pre-computed row-level set
+ * (_rowsWithErrors) for O(1) "does this row have errors?" checks.
+ *
+ * The key design decision is the ValidationDelta return type from setCellValidation().
+ * Instead of directly triggering notifications, it returns a delta object describing
+ * what changed (error count +/- 1, row-level error membership flipped).
+ * The caller (DataStore) uses this delta for incremental snapshot count updates,
+ * avoiding a full recount on every validation change.
+ *
+ * Empty cell tracking (_rowsWithEmptyCells) is separate from validation — it
+ * tracks rows where any visible column has a null/empty value, used by the
+ * "show only rows with empty cells" filter.
+ */
+
+type ValidationDelta = {
+    errorDelta: number;
+    rowErrorChanged: boolean;
+};
+type IValidationStore = {
+    setCellValidation(rowId: TRowId, field: string, result: ValidationResult): ValidationDelta;
+    getCellValidation(rowId: TRowId, field: string): ValidationResult;
+    clearRowValidations(rowId: TRowId): void;
+    hasRowErrors(rowId: TRowId): boolean;
+    getRowsWithErrors(): ReadonlySet<TRowId>;
+    getRowsWithEmptyCells(): ReadonlySet<TRowId>;
+    hasEmptyCells(rowId: TRowId): boolean;
+    checkRowEmptyCells(rowId: TRowId, row: Record<string, unknown> | undefined, fieldOrder: string[]): boolean;
+    deleteRowTracking(rowId: TRowId): void;
+    getErrorCount(): number;
+    getRowValidations(rowId: TRowId): Map<string, NonNullable<ValidationResult>> | undefined;
+    getErrorMessageToRows(): ReadonlyMap<string, ReadonlySet<TRowId>>;
+    clear(): void;
+};
+
+type IValidator<TRow extends DataEditorRow = DataEditorRow> = {
+    validateRow(rowId: TRowId): void;
+    validateRows(rows: TRow[], rowIds: TRowId[]): void;
+    validateUniqueness(): Promise<void>;
+    validateCell(rowId: TRowId, field: string, oldValue?: unknown, _visited?: Set<string>): void;
+    revalidateColumn(field: string): void;
+    validateColumn(field: string, oldValues: ReadonlyMap<TRowId, unknown>): void;
+    revalidateColumnChunked(field: string, oldValues: ReadonlyMap<TRowId, unknown>, newValues: ReadonlyMap<TRowId, unknown>, processor: ChunkedProcessor<TRowId>, onComplete: () => void): void;
+    removeRow(rowId: TRowId): void;
+    destroy(): void;
+};
+
+type IValueIndex<TRow extends DataEditorRow = DataEditorRow> = {
+    setTrackedFields(fields: Set<string>): void;
+    addRow(row: TRow): void;
+    removeRow(row: TRow): void;
+    updateField(field: string, oldValue: unknown, newValue: unknown): void;
+    rebuild(rows: Iterable<TRow>): void;
+    getValues(field: string): ReadonlyMap<string, number>;
+    getVersion(): number;
+    isTracked(field: string): boolean;
+    getMinMax(field: string): {
+        min: number;
+        max: number;
+    } | null;
+    getDateMinMax(field: string): {
+        min: string;
+        max: string;
+    } | null;
+    bumpVersion(): void;
+};
+
+type RowEntry<TRow extends DataEditorRow> = {
+    rowId: TRowId;
+    row: TRow;
+    sourceId: DataSourceId;
+    isNew: boolean;
+    isEdited: boolean;
+    isDeleted: boolean;
+    originalRow?: TRow;
+};
+type OverlayEntry<TRow extends DataEditorRow> = {
+    rowId: TRowId;
+    displayValue: TRow;
+};
+type SourceSnapshot<TRow extends DataEditorRow> = {
+    state: DataSourceState;
+    ownedRows: RowEntry<TRow>[];
+    overlayRows: OverlayEntry<TRow>[];
+    rowIds: TRowId[];
+    plan: ExtendedRemovalPlan<TRow>;
+};
+type SourceLifecycleHost<TRow extends DataEditorRow> = {
+    getValidator: () => IValidator<TRow> | null;
+    pushCommand: (cmd: Command<TRow>, cost?: number) => number;
+    notify: () => void;
+    isServerStrategy: () => boolean;
+    checkRowEmptyCells: (rowId: TRowId) => void;
+    clearRowValidations: (rowId: TRowId) => void;
+};
+declare class SourceLifecycle<TRow extends DataEditorRow = DataEditorRow> {
+    private readonly sourceManager;
+    private readonly rowStore;
+    private readonly dirtyTracker;
+    private readonly filterEngine;
+    private readonly valueIndex;
+    private readonly validationStore;
+    private readonly snapshotManager;
+    private readonly host;
+    private readonly importTrackers;
+    constructor(sourceManager: SourceManager<TRow>, rowStore: RowStore<TRow>, dirtyTracker: IDirtyTracker<TRow>, filterEngine: IFilterEngine<TRow>, valueIndex: IValueIndex<TRow>, validationStore: IValidationStore, snapshotManager: SnapshotManager, host: SourceLifecycleHost<TRow>);
+    plan(sourceId: DataSourceId): ExtendedRemovalPlan<TRow> | null;
+    capture(sourceId: DataSourceId): SourceSnapshot<TRow> | null;
+    apply(plan: ExtendedRemovalPlan<TRow>): void;
+    private applyToStores;
+    restore(snapshot: SourceSnapshot<TRow>): void;
+    register(options: RegisterSourceOptions): DataSourceId;
+    trackAppend(sourceId: DataSourceId, rowIds: TRowId[], rows: TRow[], usedIdMap: boolean): void;
+    trackPrimaryKey(sourceId: DataSourceId, primaryKey: keyof TRow): void;
+    finalize(sourceId: DataSourceId): Promise<void>;
+    private pushImportCommandIfTracked;
+    private removeInternal;
+    remove(sourceId: DataSourceId): Promise<SourceSnapshot<TRow> | null>;
+    finalizeAllSources(): void;
+}
+
+/**
+ * Fill-level delta computations.
+ *
+ * Pure functions that compute ColumnDelta[] for fill handle operations.
+ * Zero side effects — take a spec + row reader, return deltas.
+ *
+ * buildFillSpec()       — reads source values once, builds tiling index
+ * computeFillDeltas()   — processes a chunk of target rows against the spec
+ *
+ * Fill uses a tiling pattern: source values repeat cyclically.
+ * For row r in fill range: srcRow = r % sourceHeight.
+ * For col c in fill range: srcCol = c % sourceWidth.
+ */
+
+type FillSpec = {
+    /** 2D source grid: sourceValues[row][col]. Read once — source region is always small. */
+    sourceValues: unknown[][];
+    sourceHeight: number;
+    sourceWidth: number;
+    /** Column IDs for the fill target columns. */
+    fields: string[];
+    /** Target rowId → position within the fill range, for tiling modulo. */
+    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.
+ *
+ * Pure functions that compute ColumnDelta[] for paste operations.
+ * Zero side effects — take a spec + row reader, return deltas.
+ *
+ * buildPasteSpec()       — pre-resolves the source→target row mapping and column metadata
+ * computePasteDeltas()   — processes a chunk of target rows against the spec
+ *
+ * Designed for the same chunked execution pattern as columnTransforms:
+ *   - DataStore builds the spec once
+ *   - Small datasets: call computePasteDeltas() once with all target rows
+ *   - Large datasets: orchestrator calls computePasteDeltas() per chunk
+ */
+
+type PasteSpec = {
+    sourceColumnIds: string[];
+    targetColumnIds: string[];
+    targetToSource: ReadonlyMap<TRowId, TRowId>;
+    selectOptionsMap: ReadonlyMap<string, ReadonlySet<string>>;
+    skipColumnIndices: ReadonlySet<number>;
+    isCut: boolean;
+};
+
+type ApplyFormulaOptions = {
+    /**
+     * Column IDs to delete AFTER the formula has been applied.
+     * Only dynamic (user-added) columns are actually deleted; schema columns
+     * in this list are silently ignored. All operations (formula + deletes)
+     * are wrapped in a single CompoundCommand so that one Undo call restores
+     * every change, regardless of how many columns were listed.
+     */
+    readonly deleteColumnsAfter?: readonly string[];
+};
+declare class DataStore<TRow extends DataEditorRow = DataEditorRow> {
+    private readonly _mode;
+    isServer(): boolean;
+    isClient(): boolean;
+    private rowStore;
+    readonly formulaRegistry: FormulaRegistry;
+    private _isLoading;
+    private sourceManager;
+    readonly sourceLifecycle: SourceLifecycle<TRow>;
+    private dirtyTracker;
+    private filterEngine;
+    private validationStore;
+    private snapshotManager;
+    private history;
+    private validator;
+    private valueIndex;
+    private serverCounts;
+    private editBuilder;
+    private isUndoRedoing;
+    private pendingBatchCommands;
+    private _version;
+    private _skipNotify;
+    private _bulkMode;
+    private _editedCells;
+    private _primaryKey;
+    /** Columns that are currently locked (pre-locked from schema + user-locked at runtime). */
+    private _lockedColumns;
+    /** Columns locked via schema definition — user cannot unlock these. */
+    private _preLockedColumns;
+    /** Last-known visible row range reported by the canvas scroll handler. */
+    private _viewportStart;
+    private _viewportEnd;
+    private pendingMutations;
+    private editParamsHistory;
+    readonly errorHandler: ErrorHandler;
+    readonly server: ServerDataManager<TRow> | null;
+    private readonly strategy;
+    private readonly serverStrategy;
+    private snapshotReader;
+    private flagReader;
+    private buildErrorBitmask;
+    private buildEditedBitmask;
+    private buildColumnMasks;
+    private countFilteredNew;
+    private countFilteredEdited;
+    private countFilteredDirty;
+    private countFilteredErrors;
+    private countErrorMessageRows;
+    private countFilteredEmpty;
+    private filterRowReader;
+    private bulkMutationHost;
+    private orchestrator;
+    constructor(mode?: StoreMode, serverInit?: {
+        config: DataEditorServer<TRow>;
+        sourceLabel: string;
+    }, errorHandler?: ErrorHandler);
+    get mode(): StoreMode;
+    getEditBuilder(): ServerEditBuilder<TRow> | null;
+    getRowId(index: number): TRowId | undefined;
+    getLocalRowCount(): number;
+    setValidator(validator: IValidator<TRow>): void;
+    setPrimaryKey(key: string): void;
+    isColumnLocked(field: string): boolean;
+    isColumnPreLocked(field: string): boolean;
+    lockColumn(field: string, mode?: ColumnLockMode): void;
+    unlockColumn(field: string): void;
+    getLockedColumns(): ReadonlySet<string>;
+    getColumnLockMode(field: string): ColumnLockMode | undefined;
+    /** Sync pre-locked columns from schema definitions. */
+    private syncPreLockedColumns;
+    /** Returns true if the cell is locked for this specific row. */
+    isCellLocked(field: string, rowId: TRowId): boolean;
+    /** Filter out locked fields from an array. */
+    private filterLockedFields;
+    /** Build a new PasteSpec with locked target columns removed. */
+    private filterLockedFieldsFromPasteSpec;
+    private _schemaColumns;
+    private _dynamicColumns;
+    private _effectiveColumns;
+    private _lastColumnsInput;
+    setSchemaColumns(columns: DataEditorColumn[]): void;
+    getDynamicColumns(): DataEditorColumn[];
+    getEffectiveColumns: () => DataEditorColumn[];
+    setDynamicColumns(fn: (prev: DataEditorColumn[]) => DataEditorColumn[]): void;
+    addDynamicColumns(columns: DataEditorColumn[]): void;
+    setColumns(columns: DataEditorColumn[]): void;
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => DataStoreSnapshot;
+    willRowBeVisible(rowId: TRowId): boolean;
+    getColumnValues(field: string): ReadonlyMap<string, number>;
+    getColumnMinMax(field: string): {
+        min: number;
+        max: number;
+    } | null;
+    getColumnDateMinMax(field: string): {
+        min: string;
+        max: string;
+    } | null;
+    getValueIndexVersion: () => number;
+    getRow(index: number): TRow | undefined;
+    getRowIds(): TRowId[];
+    getFilterVersion(): number;
+    consumeEditedCells(): Set<string>;
+    getFilteredRowIds(): TRowId[] | null;
+    getAllRowIdsSorted(): Promise<TRowId[]>;
+    getRowById(id: TRowId): TRow | undefined;
+    getRowIndex(rowId: TRowId): number;
+    registerSource(options: RegisterSourceOptions): DataSourceId;
+    setSourceLoading(sourceId: DataSourceId, isLoading: boolean): void;
+    /**
+     * Mark a source's load as complete. If no rows landed in it (e.g., every row
+     * from the import matched an existing anchor and stayed in its original
+     * source), the source is removed so users don't see an empty entry.
+     */
+    finalizeSource(sourceId: DataSourceId): Promise<void>;
+    hasSource(sourceId: DataSourceId): boolean;
+    finalizeAllSources(): void;
+    planSourceRemoval(sourceId: DataSourceId): ExtendedRemovalPlan<TRow> | null;
+    applySourceRemovalPlan(plan: ExtendedRemovalPlan<TRow>): void;
+    captureSourceSnapshot(sourceId: DataSourceId): SourceSnapshot<TRow> | null;
+    restoreSourceFromSnapshot(snapshot: SourceSnapshot<TRow>): void;
+    removeSource(sourceId: DataSourceId): Promise<void>;
+    toggleSourceVisibility(sourceId: DataSourceId): void;
+    /**
+     * Physically removes a row from all stores.
+     * Used only by InsertRowCommand.undo() to reverse a row creation.
+     * NOT for user-initiated deletion — that will use flag-based soft delete.
+     */
+    removeRowPhysically(rowId: TRowId): void;
+    isDefaultSourceRow(rowId: TRowId): boolean;
+    isNew(rowId: TRowId): boolean;
+    isEdited(rowId: TRowId): boolean;
+    isDeleted(rowId: TRowId): boolean;
+    getSourceId(rowId: TRowId): DataSourceId;
+    getRowsWithErrors(): ReadonlySet<TRowId>;
+    /**
+     * Flag rows as deleted. Pushes a command for undo/redo.
+     * Rows stay in all stores — they are just excluded from alive-mode filters.
+     */
+    deleteRows(rowIds: TRowId[], rowRanges?: [TRowId, TRowId][]): Promise<void>;
+    /**
+     * Delete all visible rows at once. In server mode sends { allSelected: true }
+     * instead of enumerating every row. Locally marks all loaded rows as deleted
+     * and clears the RowStore display list.
+     */
+    deleteAllRows(): Promise<void>;
+    /**
+     * Optimistic bulk delete for server mode. Marks all locally loaded rows
+     * as deleted, clears the RowStore, and adjusts counts.
+     */
+    private deleteAllServer;
+    /**
+     * Unflag rows (restore from deletion). Pushes a command for undo/redo.
+     */
+    restoreRows(rowIds: TRowId[], rowRanges?: [TRowId, TRowId][]): Promise<void>;
+    /**
+     * Restore all deleted rows at once. In server mode sends { allSelected: true }
+     * instead of enumerating every row. Locally clears all deleted flags and
+     * empties the RowStore display list (bin view becomes empty).
+     */
+    restoreAllRows(): Promise<void>;
+    /**
+     * Optimistic bulk restore for server mode. Clears all locally known deleted
+     * flags and empties the RowStore display list (we are in deleted-only view,
+     * so every visible row is being restored out). Server-provided counts will
+     * be authoritative after the sync response arrives.
+     */
+    private restoreAllDeletedServer;
+    /**
+     * Apply delete flags directly without cost-gating. Called by commands
+     * (DeleteRowCommand.redo/undo, restore inline commands) where runHeavy
+     * already gated the operation at the public method level.
+     */
+    applyDeleteFlagsDirect(rowIds: TRowId[], deleted: boolean): void;
+    private applyDeleteFlags;
+    /**
+     * Returns rows flagged for deletion. Used by onComplete.
+     */
+    getDeletedRows(): TRow[];
+    getRealRowPosition(rowId: TRowId): number;
+    insertRow(sourceId: DataSourceId, row: TRow, position: number): Promise<TRowId>;
+    insertRowDirect(rowId: TRowId, row: TRow, sourceId: DataSourceId, position: number): void;
+    /**
+     * Ingest a single ServerRow at a specific local position.
+     * Used after the server confirms an insert and returns the full row.
+     * Source counts come from the server via counts.sources — no local source tracking.
+     */
+    insertServerRow(serverRow: ServerRow<TRow>, position: number): TRowId;
+    /**
+     * Server-mode insert: send insert request to server, wait for response,
+     * then ingest the returned row locally. Non-optimistic.
+     */
+    insertRowServer(row: TRow, localPosition: number, anchorRowId: TRowId | undefined, insertPosition: 'above' | 'below', columnIds: string[]): Promise<TRowId>;
+    appendRows(sourceId: DataSourceId, newRows: TRow[], rowIdMap?: Map<number, TRowId>): TRowId[];
+    upsertRows(sourceId: DataSourceId, newRows: TRow[], options?: {
+        anchorKey?: keyof TRow;
+        newRowIds?: TRowId[];
+    }): UpsertResult<TRow>;
+    setLoading(isLoading: boolean): void;
+    setPhase(phase: ProcessingPhase, info?: ProcessingInfo): void;
+    getPhase(): ProcessingPhase;
+    cancelProcessing(): void;
+    setBulkMode(enabled: boolean): void;
+    /**
+     * Called by the orchestrator after all chunks complete, before validation.
+     * Deferred per-row work from updateColumnDirect is flushed here in bulk:
+     * - rowTextCache cleared once instead of per-row
+     * - checkRevert run for each affected row
+     * - _editedCells populated for FindReplace incremental matching
+     */
+    flushBulkMode(deltas: ColumnDelta[]): void;
+    setViewportRange(start: number, end: number): void;
+    clearViewportRange(): void;
+    /**
+     * Returns row IDs for the current viewport range +1 row above and below
+     * to cover semi-scrolled rows at the edges. Returns empty array if the
+     * viewport range has not been set.
+     */
+    getViewportRowIds(): TRowId[];
+    getAllFilteredRowIds(): TRowId[];
+    replaceServerRows(sourceId: DataSourceId, serverRows: ServerRow<TRow>[], offset: number, counts?: ServerQueryCounts): void;
+    appendServerRows(serverRows: ServerRow<TRow>[], counts?: ServerQueryCounts): void;
+    prependServerRows(serverRows: ServerRow<TRow>[], newOffset: number, counts?: ServerQueryCounts): void;
+    /**
+     * Seeds DirtyTracker from server-provided row metadata.
+     * For rows with `meta.status.edited`, builds a synthetic original row
+     * from `meta.changes` so that `isCellDirty()` and `getOriginalCellValue()`
+     * work through the existing DirtyTracker comparison logic.
+     */
+    private hydrateServerMeta;
+    private hydrateRowMeta;
+    applyServerRowMeta(serverRows: ServerRow<TRow>[], counts?: ServerQueryCounts): void;
+    clear(): void;
+    destroy(): void;
+    setFilters(filters: Partial<Filters>): void;
+    getFilters(): Filters;
+    setSort(sortState: SortState, sortType?: SortType, locales?: string[]): Promise<void>;
+    handleServerScroll(visibleStart: number, visibleEnd: number): void;
+    reloadServerData(): void;
+    resetFilters(): void;
+    fetchFilterOptions(): void;
+    getFilterOptions(): FilterOptionsResponse | null;
+    get hasServerExport(): boolean;
+    serverExport(format: DataEditorFormat, allRows: boolean, rtl: boolean): Promise<void>;
+    syncWorkerFlags(): void;
+    setCellValidation(rowId: TRowId, field: string, result: ValidationResult): void;
+    getCellValidation(rowId: TRowId, field: string): ValidationResult;
+    private clearRowValidations;
+    updateRow(rowId: TRowId, field: string, value: unknown): void;
+    updateRowDirect(rowId: TRowId, field: string, value: unknown): void;
+    /**
+     * Bulk-write a single column for many rows in one pass.
+     * Skips per-row validation, notification, and snapshot adjustments.
+     * Caller must handle validation (via Validator.revalidateColumn) and notification.
+     */
+    updateColumnDirect(field: string, values: ReadonlyMap<TRowId, unknown>): void;
+    batch(fn: () => void): number | undefined;
+    canUndo(): boolean;
+    getAllRowIds(): readonly TRowId[];
+    undo(): Promise<UndoRedoResult>;
+    private _undoSync;
+    pushCommand(cmd: Command<TRow>, cost?: number): number;
+    removeCommandById(id: number): void;
+    /**
+     * Delegate to ServerStrategy. Called by ActionsDispatcher and ClipboardManager
+     * for non-cell edits (clear, paste, fill, transform).
+     */
+    syncServerEdit(params: EditParams, cmdId: number, revertFn: () => void): void;
+    fireServerEditParams(params: EditParams): void;
+    syncColumnEdit(params: ColumnEditParams, cmdId: number, revertFn: () => void): void;
+    redo(): Promise<UndoRedoResult>;
+    private _redoSync;
+    getOriginalCellValue(rowId: TRowId, field: string): unknown | undefined;
+    isCellDirty(rowId: TRowId, field: string): boolean;
+    hasRowErrors(rowId: TRowId): boolean;
+    hasEmptyCells(rowId: TRowId): boolean;
+    private checkRowEmptyCells;
+    getValidAndInvalidRows(): {
+        valid: TRow[];
+        invalid: TRow[];
+    };
+    getValidRows(): TRow[];
+    getInvalidRows(): TRow[];
+    getResultBySource(): DataEditorResult<TRow>;
+    private isRowVisible;
+    applyFormula(formulaOrName: string | CellFormula, params: Record<string, unknown>, rects: SelectionRect[], options?: ApplyFormulaOptions): Promise<void>;
+    private applyFormulaCompound;
+    private runFormulaWithReturnCommand;
+    private _runFormulaOperation;
+    private captureDeleteColumnSnapshots;
+    private applyDeleteColumnSnapshots;
+    private syncFormulaToServer;
+    private transformWorker;
+    private initTransformWorker;
+    private buildChatTransformCommand;
+    applyChatTransform(fnString: string, ctx: {
+        opts: Record<string, Set<string>>;
+    }): Promise<void>;
+    private _applyChatTransformViaWorker;
+    private _applyChatTransformSync;
+    applyChatRows(incomingRows: Record<string, unknown>[], primaryKey: string): Promise<void>;
+    private syncChatTransformToServer;
+    private get revertRowReader();
+    revertColumns(fields: string[]): Promise<void>;
+    revertRange(rects: SelectionRect[]): Promise<void>;
+    private _revertInternal;
+    private _buildRevertCommand;
+    private syncRevertToServer;
+    clearColumn(field: string): Promise<void>;
+    clearColumns(fields: string[]): Promise<void>;
+    private syncClearToServer;
+    deleteColumn(columnId: string): Promise<void>;
+    deleteColumns(columnIds: readonly string[]): Promise<void>;
+    clearRange(rects: SelectionRect[]): Promise<void>;
+    private syncRangeClearToServer;
+    pasteChunked(spec: PasteSpec, targetRowIds: TRowId[], targetCell: {
+        rowId: TRowId;
+        field: string;
+    }, onComplete?: (cmdId: number) => void): void;
+    /**
+     * Store-owned paste: cost-gated sync path or chunked orchestrator.
+     * Replaces executePasteWithOverlay + pasteChunked for internal-clipboard paste.
+     */
+    pasteInternal(spec: PasteSpec, targetRowIds: TRowId[], targetCell: {
+        rowId: TRowId;
+        field: string;
+    }, validator?: IValidator<TRow>): Promise<{
+        cmdId: number;
+    } | null>;
+    /**
+     * Store-owned external paste from TSV text (OS clipboard).
+     * Replaces the pasteFromText helper in pasteUtils.
+     */
+    pasteFromText(text: string, pasteRow: number, pasteCol: number, validator?: IValidator<TRow>): Promise<{
+        cmdId: number;
+    } | null>;
+    /**
+     * Store-owned fill: cost-gated sync path or chunked orchestrator.
+     * Replaces fillChunked + the per-caller isHeavy heuristic in ActionsDispatcher.
+     */
+    fillInternal(spec: FillSpec, targetRowIds: TRowId[], targetCell: {
+        rowId: TRowId;
+        field: string;
+    }, onComplete?: (cmdId: number) => void): Promise<{
+        cmdId: number;
+    } | null>;
+    notify(): void;
+}
+
+/**
+ * Command interface for undo/redo operations.
+ * Each command knows how to apply and revert its changes.
+ */
+interface Command<TRow extends DataEditorRow = DataEditorRow> {
+    /** Assigned by CommandHistory.push(). Used by removeById() to target specific commands. */
+    id?: number;
+    redo(store: DataStore<TRow>, validator: IValidator<TRow>): void;
+    undo(store: DataStore<TRow>, validator: IValidator<TRow>): void;
+    readonly description: string;
+    /** Target cell for selection restoration on undo/redo */
+    readonly targetCell: CellLocation;
+}
+
+/**
+ * BulkMutationOrchestrator — Viewport-first chunked execution for heavy
+ * column operations (split, merge, clear, paste, fill, backspace).
+ *
+ * When operation cost >= LARGE_OP_CELLS:
+ *   1. Viewport rows are applied synchronously (instant visual result)
+ *   2. Remaining rows are processed in chunks via requestIdleCallback
+ *   3. Validation runs chunked after all mutations complete
+ *   4. Command is pushed to history only after everything finishes
+ *
+ * Communicates with DataStore via BulkMutationHost interface to avoid
+ * circular imports. DataStore constructs the host from its own methods.
+ */
+
+type ColumnDelta = {
+    field: string;
+    oldValues: Map<TRowId, unknown>;
+    newValues: Map<TRowId, unknown>;
+};
+
+/**
+ * Base row shape. Each key is a column ID, each value is the cell data.
+ * Extend this with your own type for type-safe column access.
+ *
+ * @example
+ * ```ts
+ * type Employee = { id: string; name: string; email: string };
+ * <DataEditor<Employee> columns={...} primaryKey="id" />
+ * ```
+ */
+type DataEditorRow = Record<string, unknown>;
+type SortDirection = "asc" | "desc";
+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;
+    }>;
+};
+
+type ChatResponseChunk<TRow extends DataEditorRow = DataEditorRow> = {
+    type: "status";
+    content: string;
+} | {
+    type: "message";
+    content: string;
+} | {
+    type: "rows";
+    content: TRow[];
+} | {
+    type: "transform";
+    content: string;
+};
+type ChatRowStatus = "new" | "edited" | "original";
+type ChatRow<TRow extends DataEditorRow = DataEditorRow> = {
+    data: TRow;
+    status: ChatRowStatus;
+    errors: Record<string, string[]>;
+    source: string;
+};
+type ChatErrorSummary = {
+    field: string;
+    message: string;
+    count: number;
+    examples: string[];
+};
+type ChatDataContext<TRow extends DataEditorRow = DataEditorRow> = {
+    columns: DataEditorColumn[];
+    primaryKey: keyof TRow;
+    totalRowCount: number;
+    filteredRowCount: number;
+    sample: ChatRow<TRow>[];
+    errorSummary: ChatErrorSummary[];
+    getRows: () => ChatRow<TRow>[];
+};
+type ChatContext<TRow extends DataEditorRow = DataEditorRow> = ChatDataContext<TRow> & {
+    message: string;
+};
+type DataEditorChat<TRow extends DataEditorRow = DataEditorRow> = {
+    sampleSize?: number;
+    emptyTitle?: string;
+    suggestionsCount?: number;
+    loadSuggestions?: (context: ChatDataContext<TRow>) => Promise<string[]>;
+    onMessage: (context: ChatContext<TRow>) => AsyncIterable<ChatResponseChunk<TRow>>;
+    onCancel?: () => void;
+};
+
+/** Severity level for a validation message. */
+type ValidationLevel = "error";
+/**
+ * A single validation message attached to a cell.
+ * Return this from a `CellValidator` to flag a problem.
+ */
+type ValidationError = {
+    level: ValidationLevel;
+    /** Human-readable message shown in the cell tooltip. */
+    message: string;
+};
+type ValidationResult = ValidationError[] | null;
+/**
+ * A function that validates a single cell value.
+ * Return a `ValidationError` to flag a problem, or `null` if the value is valid.
+ *
+ * Built-in validator factories: `required(msg)`, `numeric(msg)`, `email(msg)`,
+ * `date(msg)`, `endDateAfterStart(startField, msg)`. Import them from the package root.
+ *
+ * @param value - The current cell value.
+ * @param row - The full row, useful for cross-field checks.
+ */
+type CellValidator = (value: unknown, row: DataEditorRow) => ValidationError | null;
+/** Text input cell. This is the default editor when no `editor` is specified. */
+type TextEditorCell = {
+    type: "text";
+};
+/** Date picker cell. Optionally restrict the selectable date range. */
+type DateEditorCell = {
+    type: "date";
+    /** Earliest selectable date. */
+    minDate?: Date;
+    /** Latest selectable date. */
+    maxDate?: Date;
+};
+/** Dropdown select cell. The user picks from a fixed list of options. */
+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[];
+};
+/** Number input cell with locale-aware formatting. */
+type NumberEditorCell = {
+    type: "number";
+    /** Maximum number of decimal digits allowed. When omitted, decimals are unrestricted. */
+    decimalPlaces?: number;
+    /** Character used as the decimal point (e.g. `"."` or `","`). Defaults to the browser locale. */
+    decimalSeparator?: string;
+    /** Character inserted between groups of three digits (e.g. `","` or `"."`). Defaults to the browser locale. */
+    thousandsSeparator?: string;
+    /** Extra characters to allow beyond digits, decimal separator, and minus sign (e.g. `"%-"`). When defined, minus is only kept if explicitly included. */
+    allowChars?: string;
+};
+/**
+ * Controls how a cell is edited.
+ *
+ * - `"text"` — plain text input (default).
+ * - `"date"` — date picker with optional min/max bounds.
+ * - `"select"` — dropdown with a fixed list of options.
+ * - `"number"` — number input with locale-aware formatting.
+ */
+type CellEditor = TextEditorCell | DateEditorCell | SelectEditorCell | NumberEditorCell;
+/** Dropdown filter shown in the sidebar Filters panel. */
+type SelectColumnFilter = {
+    type: "select";
+    /** Label displayed above the filter. */
+    label?: string;
+    /** Placeholder text when nothing is selected. */
+    placeholder?: string;
+    /** Fixed list of filter options. When omitted, options are derived from column values. */
+    options?: string[];
+    /** Allow selecting multiple values at once. */
+    multiple?: boolean;
+};
+/** Numeric min/max range filter shown in the sidebar Filters panel. */
+type NumberRangeColumnFilter = {
+    type: "number-range";
+    /** Label displayed above the filter. */
+    label?: string;
+};
+/** Date min/max range filter shown in the sidebar Filters panel. */
+type DateRangeColumnFilter = {
+    type: "date-range";
+    /** Label displayed above the filter. */
+    label?: string;
+};
+/**
+ * Filter control shown in the sidebar Filters panel for a column.
+ *
+ * - `"select"` — dropdown to pick one or more values.
+ * - `"number-range"` — two inputs for min and max number.
+ * - `"date-range"` — two date pickers for start and end date.
+ */
+type ColumnFilter = SelectColumnFilter | NumberRangeColumnFilter | DateRangeColumnFilter;
+/** Lock mode for a column. `"all"` locks for every row; `"default"` locks only default-source rows. */
+type ColumnLockMode = "all" | "default";
+/**
+ * Defines a column in the editor grid.
+ *
+ * @example
+ * ```ts
+ * const columns: DataEditorColumn[] = [
+ *   { id: "name", title: "Full Name", width: 200, validate: required },
+ *   { id: "email", title: "Email", width: 250, validate: [required, email], unique: true },
+ *   { id: "role", title: "Role", editor: { type: "select", options: roleOptions } },
+ *   { id: "salary", title: "Salary", validate: numeric, formatter: (v) => `$${v}` },
+ * ];
+ * ```
+ */
+type DataEditorColumn = {
+    /** Unique column identifier. Must match the keys in your row data. */
+    id: string;
+    /** Column header text. */
+    title: string;
+    /** One or more validators to run on every edit. */
+    validate?: CellValidator | CellValidator[];
+    /** When `true`, the editor flags duplicate values in this column as errors. */
+    unique?: boolean;
+    /** Column IDs to revalidate when this column changes. Use for cross-field rules like "end date must be after start date". */
+    dependentFields?: string[];
+    /** Format the display value without changing stored data. E.g. add `$` prefix. */
+    formatter?: (value: string) => string;
+    /** Transform the value before it enters the store. Runs on every edit and import. */
+    transformer?: (value: unknown) => unknown;
+    /** How the cell is edited. Defaults to text input. */
+    editor?: CellEditor;
+    /** Adds a filter control for this column in the sidebar Filters panel. */
+    filter?: ColumnFilter;
+    /** Whether this column can be pinned to the left via the header context menu. @default true */
+    pinnable?: boolean;
+    /** Column width in pixels. @default 150 */
+    size?: number;
+    /**
+     * Controls whether cells in this column are locked.
+     * - `true` | `"all"` — locked for all rows.
+     * - `"default"` — locked only for default-source rows; non-default-source rows remain editable.
+     * - `false` | `undefined` — not locked.
+     */
+    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 StoreMode = "client" | "server";
+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.
+ */
+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;
+};
+/**
+ * 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.
+ *
+ * INVALID: `from` present without `to`, or vice versa.
+ */
+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[];
+};
+/**
+ * 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".
+ *
+ * `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.
+ */
+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$1<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 FormulaParams = {
+    formula: string;
+    params: Record<string, unknown>;
+};
+/** 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;
+};
+/** 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;
+};
+/** 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;
+    }>;
+};
+/**
+ * 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.
+ */
+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;
+};
+/**
+ * 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.
+ */
+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 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$1<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>;
+    /**
+     * 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`.
+     */
+    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>;
+    /**
+     * 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.
+     */
+    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;
+};
+
+/** Numeric row identifier. V8 stores small integers (Smi) inline — no heap allocation. */
+type TRowId = number;
+type SortType = "text" | "number" | "date";
+
+/** A pointer to a specific cell in the grid. */
+type CellLocation = {
+    /** Row identifier. */
+    rowId: TRowId;
+    /** Column ID (matches `DataEditorColumn.id`). */
+    field: string;
+};
+type UndoRedoResult = {
+    success: boolean;
+    targetCell?: CellLocation;
+};
+/** Actions available inside the `onComplete` callback. */
+type DataEditorActions = {
+    /** Discard all changes and reload the original data. */
+    reset: () => void;
+};
+/**
+ * A single row in the submit result, with orthogonal flags describing its state.
+ *
+ * - `isNew` — provenance: the row was imported or manually added this session.
+ *   Permanent from creation; does not flip on cell edits or reverts.
+ * - `isChanged` — mutation: cell values differ from the row's origin snapshot.
+ *   Can flip back to false if the user types the original value back.
+ * - `isDeleted` — the user marked the row for deletion via the UI.
+ * - `isValid` — the row passes all validation rules.
+ *
+ * Clients route rows to INSERT/UPDATE/DELETE by filtering on these flags; the
+ * SDK does not pre-group them because the routing rules are client-specific.
+ */
+type ResultRow<TRow extends DataEditorRow = DataEditorRow> = {
+    row: TRow;
+    isNew: boolean;
+    isChanged: boolean;
+    isDeleted: boolean;
+    isValid: boolean;
+};
+/**
+ * Per-source bucket of result rows. Pristine backend rows (isNew=false,
+ * isChanged=false, isDeleted=false) are omitted — they are no-ops for the
+ * client. Every other row state is emitted, including pristine imports
+ * (isNew=true, isChanged=false) which the client will INSERT.
+ */
+type DataEditorSourceResult<TRow extends DataEditorRow = DataEditorRow> = {
+    sourceId: DataSourceId;
+    sourceName: string;
+    rows: ResultRow<TRow>[];
+};
+/**
+ * The result object passed to `onComplete` when the user submits changes.
+ * Grouped by source; each row carries flags for client-side routing.
+ *
+ * @example
+ * ```ts
+ * onComplete={async (result, actions) => {
+ *   for (const source of result.sources) {
+ *     const inserts = source.rows.filter(r => r.isNew && !r.isDeleted && r.isValid);
+ *     const updates = source.rows.filter(r => !r.isNew && r.isChanged && !r.isDeleted && r.isValid);
+ *     const deletes = source.rows.filter(r => r.isDeleted && !r.isNew);
+ *     await persist(source.sourceId, { inserts, updates, deletes });
+ *   }
+ *   actions.reset();
+ * }}
+ * ```
+ */
+type DataEditorResult<TRow extends DataEditorRow = DataEditorRow> = {
+    sources: DataEditorSourceResult<TRow>[];
+    counts: {
+        new: number;
+        changed: number;
+        deleted: number;
+        invalid: number;
+    };
+};
+type ChunkSourceOptions = {
+    /** Display name for this data source. */
+    source: string;
+    /** Stable identifier. Defaults to `source` value when omitted. */
+    id?: string;
+    /** Can the user delete this source? @default false */
+    deletable?: boolean;
+    /** Marks this source as finished loading. */
+    done?: boolean;
+};
+type DataSourceId = string;
+type DataSourceState = {
+    id: DataSourceId;
+    name: string;
+    rowCount: number;
+    isLoading: boolean;
+    isVisible: boolean;
+    isDeletable: boolean;
+    isInitialData: boolean;
+};
+
+type UpsertResult<TRow extends DataEditorRow = DataEditorRow> = {
+    rows: TRow[];
+    rowIds: TRowId[];
+};
+type ProcessingPhase = "idle" | "loading" | "processing";
+type ProcessingCode = "pasting" | "clearing" | "filling" | "sorting" | "undoing" | "redoing" | "deleting" | "deletingSource" | "importing" | "transforming" | "reverting";
+type ProcessingInfo = {
+    code: ProcessingCode;
+};
+type DataStoreSnapshot = {
+    rowCount: number;
+    filteredCount: number;
+    newRowCount: number;
+    editedRowCount: number;
+    dirtyRowCount: number;
+    deletedRowCount: number;
+    filteredDirtyRowCount: number;
+    filteredNewRowCount: number;
+    filteredEditedRowCount: number;
+    filteredErrorCount: number;
+    errorCount: number;
+    /** Per-error-message row counts. Key = distinct error message, value = visible non-deleted row count. */
+    errorMessageCounts: Record<string, number>;
+    emptyRowCount: number;
+    filteredEmptyRowCount: number;
+    isLoading: boolean;
+    isFiltering: boolean;
+    /** Unified phase state machine. Controls what actions are allowed. */
+    phase: ProcessingPhase;
+    /** Details about the in-progress operation. Null when phase is "idle". */
+    processing: ProcessingInfo | null;
+    sources: DataSourceState[];
+    canUndo: boolean;
+    canRedo: boolean;
+    /** Increments on undo/redo to force canvas grid re-render */
+    version: number;
+    sortState: SortState;
+    /** True when the "show deleted rows" filter is active (bin mode). */
+    showOnlyDeletedRows: boolean;
+};
+/** Per-column data passed to `onValueMatch`: the unique imported values and the allowed select options. */
+type ValueMatchInput = {
+    importedValues: string[];
+    options: string[];
+};
+/** Per-column result from `onValueMatch`: maps each imported value to an option value, or `null` to skip auto-matching. */
+type ValueMatchOutput = Record<string, Record<string, string | null>>;
+/** File formats supported for import and export. */
+type DataEditorFormat = "csv" | "tsv" | "xlsx" | "json" | "xml";
+/**
+ * A client-defined remote data source (e.g. Google Sheets, S3, Dropbox).
+ *
+ * The SDK renders a button per source and calls `fetch()` when clicked.
+ * The client owns all integration complexity — auth, pickers, downloads.
+ *
+ * @example
+ * ```ts
+ * const googleSheets: RemoteSource = {
+ *   id: "google-sheets",
+ *   label: "Google Sheets",
+ *   icon: "<svg>...</svg>",
+ *   fetch: async () => {
+ *     const data = await myGoogleSheetsLib.pick();
+ *     return data.rows; // Record<string, unknown>[]
+ *   },
+ * };
+ * ```
+ */
+type RemoteSource = {
+    /** Unique identifier for this source. */
+    id: string;
+    /** Button label shown to the user. */
+    label: string;
+    /** SVG markup or image URL for the button icon. */
+    icon: string;
+    /** Optional tooltip text. */
+    description?: string;
+    /** Returns a File (parsed via CSV/XLSX/JSON/XML pipeline) or structured records (used directly). */
+    fetch: () => Promise<File | Record<string, unknown>[]>;
+};
+/**
+ * Controls the initial view when the editor opens.
+ *
+ * - `"editor"` — opens directly into the spreadsheet grid.
+ * - `"uploader"` — opens the file import wizard first, then transitions to the grid.
+ */
+type DataEditorVariant = "editor" | "uploader";
+/** Base configuration shared by the public `DataEditorProps` and the internal provider. */
+type DataEditorBaseProps<TRow extends DataEditorRow = DataEditorRow> = {
+    /** Column definitions. Each entry describes one column in the grid. */
+    columns: DataEditorColumn[];
+    /**
+     * The column ID used to uniquely identify each row (e.g. `"id"` or `"employeeId"`).
+     * Used to match imported rows to existing data and to track edits.
+     */
+    primaryKey: keyof TRow;
+    /**
+     * Async function that feeds data into the editor. Called once when the editor opens.
+     * Call `onChunk` one or more times to stream rows in batches.
+     * The editor processes each chunk without blocking the UI.
+     *
+     * Pass `options` to tag chunks with a data source. Sources are auto-registered
+     * on first encounter. Omit `options` to send rows to "Existing Data".
+     *
+     * @example
+     * ```ts
+     * // Single source
+     * loadData={async (onChunk) => {
+     *   const rows = await fetch("/api/employees").then(r => r.json());
+     *   onChunk(rows);
+     * }}
+     *
+     * // Multi-source
+     * loadData={async (onChunk) => {
+     *   const sf = await fetchSalesforce();
+     *   onChunk(sf, { source: "Salesforce", done: true });
+     *
+     *   const hs = await fetchHubSpot();
+     *   onChunk(hs, { source: "HubSpot", deletable: true, done: true });
+     * }}
+     * ```
+     */
+    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.
+     *
+     * @example
+     * ```ts
+     * onComplete={async (result, actions) => {
+     *   for (const source of result.sources) {
+     *     const inserts = source.rows.filter(r => r.isNew && !r.isDeleted && r.isValid);
+     *     const updates = source.rows.filter(r => !r.isNew && r.isChanged && !r.isDeleted && r.isValid);
+     *     const deletes = source.rows.filter(r => r.isDeleted && !r.isNew);
+     *     await persist(source.sourceId, { inserts, updates, deletes });
+     *   }
+     *   actions.reset();
+     * }}
+     * ```
+     */
+    onComplete?: (result: DataEditorResult<TRow>, actions: DataEditorActions) => void;
+    /** Controls the initial view. `"editor"` opens the grid, `"uploader"` opens the import wizard first. @default "editor" */
+    variant?: DataEditorVariant;
+    /** Override any UI string. Pass a partial object — only the keys you provide are replaced. */
+    translations?: DataEditorTranslations;
+    /** BCP 47 locale tag (e.g. `"en"`, `"fr"`, `"ar"`). Used for plural rules and locale-aware features. @default "en" */
+    locale?: string;
+    /**
+     * Controls row deletion via the right-click context menu.
+     * - `false` — deletion disabled (default).
+     * - `"new"` — only manually added or imported rows can be deleted.
+     * - `"all"` — any row can be deleted.
+     * @default false
+     */
+    enableDeleteRow?: "all" | "new" | false;
+    /** Show the "Add row" button in the data sources panel. @default true */
+    enableAddRow?: boolean;
+    /** Which file formats the user can import. `undefined` allows all, `[]` disables import entirely. */
+    importFormats?: DataEditorFormat[];
+    /** Client-defined remote data sources rendered as buttons on the upload step. */
+    remoteSources?: RemoteSource[];
+    /** Which file formats the user can export. `undefined` allows all, `[]` disables export entirely. */
+    exportFormats?: DataEditorFormat[];
+    /** Row height in pixels. @default 34 */
+    rowHeight?: number;
+    /** Header row height in pixels. @default 36 */
+    headerHeight?: number;
+    /** When `true`, hides all editing UI (submit, add row, delete, import). The grid becomes view-only. */
+    readonly?: boolean;
+    /** Enable right-to-left layout for RTL languages. @default false */
+    rtl?: boolean;
+    /** Allow creating new columns for unmatched CSV headers during import. @default true */
+    enableCreateColumn?: boolean;
+    /** Override column matching during import. Return a map of `{ csvHeader: columnId | null }`. Unmapped or `null` entries fall back to built-in matching. */
+    onColumnMatch?: (headers: string[], columns: DataEditorColumn[]) => Record<string, string | null> | Promise<Record<string, string | null>>;
+    /**
+     * Override value matching during import for select columns. Called once after column mapping
+     * is established with all select columns' imported values and allowed options. Return a map
+     * of `{ columnId: { importedValue: optionValue | null } }`. `null` entries skip auto-matching
+     * for that value. Unmapped values fall back to built-in fuzzy matching.
+     *
+     * @example
+     * ```ts
+     * onValueMatch={async (valuesToMatch) => {
+     *   // valuesToMatch = { country: { importedValues: ["espana", "fr"], options: ["Spain", "France", ...] } }
+     *   return {
+     *     country: { espana: "Spain", fr: "France" },
+     *   };
+     * }}
+     * ```
+     */
+    onValueMatch?: (valuesToMatch: Record<string, ValueMatchInput>) => ValueMatchOutput | Promise<ValueMatchOutput>;
+    /** Extra synonyms for column auto-matching, e.g. `{ productsku: ["sku", "articleno"] }`. */
+    synonyms?: Record<string, string[]>;
+    /** Sample rows included in the "Download Example" file. When omitted, a generic row is auto-generated from column config. */
+    sampleData?: Record<string, unknown>[];
+    /** Bring Your Own AI chat. When provided, a chat panel is shown alongside the grid. */
+    chat?: DataEditorChat<TRow>;
+};
+/**
+ * Controls what the editor stores in `localStorage`.
+ * Set to `false` to disable all local storage usage.
+ */
+type DataEditorLocalStorage = false | {
+    /** Cache the license validation result to skip re-validation on reload. @default true */
+    licenseGrant?: boolean;
+};
+/** Rendering mode: `"modal"` wraps in a dialog overlay, `"inline"` renders directly in the DOM. */
+type DataEditorMode = "modal" | "inline";
+/** Shared props present in both modal and inline modes. */
+type DataEditorCommonProps<TRow extends DataEditorRow = DataEditorRow> = DataEditorBaseProps<TRow> & {
+    /** Your Updog license key. Validates on each open. */
+    apiKey: string;
+    /** Controls what the editor stores in `localStorage`. Set to `false` to disable. */
+    localStorage?: DataEditorLocalStorage;
+    /** CSS class added to the wrapper element. */
+    className?: string;
+    /** Called when the SDK catches an internal error. Use for logging, Sentry, etc. Client mode only. */
+    onError?: (error: UpdogError) => void;
+};
+/**
+ * Props for modal mode (default). The editor renders as a full-screen dialog
+ * controlled by `open` / `onClose`.
+ */
+type DataEditorModalProps<TRow extends DataEditorRow = DataEditorRow> = DataEditorCommonProps<TRow> & {
+    /** Rendering mode. @default "modal" */
+    mode?: "modal";
+    /** When `true`, the editor modal is visible. This is a controlled prop. Required in modal mode. */
+    open: boolean;
+    /** Called when the user closes the modal (clicks X or presses Escape). Required in modal mode. */
+    onClose: () => void;
+};
+/**
+ * Props for inline mode. The editor renders directly in the DOM with no
+ * modal overlay or close button.
+ */
+type DataEditorInlineProps<TRow extends DataEditorRow = DataEditorRow> = DataEditorCommonProps<TRow> & {
+    /** Rendering mode. Must be `"inline"` to render without a modal. */
+    mode: "inline";
+    /** Not applicable in inline mode. */
+    open?: never;
+    /** Not applicable in inline mode. */
+    onClose?: never;
+};
+/**
+ * Props for the `<DataEditor />` component.
+ *
+ * Supports two rendering modes:
+ * - **Modal** (default): full-screen dialog controlled by `open` / `onClose`.
+ * - **Inline**: renders directly in the DOM, no overlay.
+ *
+ * @example
+ * ```tsx
+ * // Modal mode (default)
+ * <DataEditor
+ *   apiKey="your-license-key"
+ *   open={isOpen}
+ *   onClose={() => setIsOpen(false)}
+ *   columns={columns}
+ *   primaryKey="id"
+ *   loadData={async (onChunk) => onChunk(await fetchRows())}
+ *   onComplete={(result, actions) => { saveChanges(result); actions.reset(); }}
+ * />
+ *
+ * // Inline mode
+ * <DataEditor
+ *   mode="inline"
+ *   apiKey="your-license-key"
+ *   columns={columns}
+ *   primaryKey="id"
+ *   loadData={async (onChunk) => onChunk(await fetchRows())}
+ *   onComplete={(result, actions) => { saveChanges(result); actions.reset(); }}
+ * />
+ * ```
+ */
+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 ExportParams<TRow extends DataEditorRow> = {
+    store: DataStore<TRow>;
+    columns: DataEditorColumn[];
+    format: DataEditorFormat;
+    scope: "all" | "filtered";
+    fileName?: string;
+    rtl?: boolean;
+};
+/**
+ * Download a template file with column headers and a sample row matching your editor config.
+ * Useful for giving users a file to fill in and import back.
+ *
+ * @param columns - Your column definitions (headers are taken from `column.title`).
+ * @param format - File format to generate (`"csv"`, `"xlsx"`, etc.).
+ */
+declare function downloadExampleFile(columns: DataEditorColumn[], format: DataEditorFormat, sampleData?: Record<string, unknown>[]): Promise<void>;
+/**
+ * Export the editor's data as a downloadable file.
+ *
+ * @param params.store - The DataStore instance (available from the editor context).
+ * @param params.columns - Column definitions (for headers and formatting).
+ * @param params.format - File format (`"csv"`, `"xlsx"`, `"tsv"`, `"json"`, `"xml"`).
+ * @param params.scope - `"all"` exports every row, `"filtered"` exports only currently visible rows.
+ * @param params.fileName - Base filename without extension. Defaults to `"data-export-YYYY-MM-DD"`.
+ */
+declare function exportDataEditor<TRow extends DataEditorRow>(params: ExportParams<TRow>): Promise<void>;
+
+/**
+ * Full-screen modal spreadsheet editor for large datasets.
+ *
+ * Opens as a controlled modal (`open` / `onClose`). Supports CSV/XLSX import,
+ * cell validation, undo/redo, find & replace, and exporting.
+ *
+ * @see {@link DataEditorProps} for all available props.
+ *
+ * @example
+ * ```tsx
+ * <DataEditor
+ *   apiKey="your-license-key"
+ *   open={isOpen}
+ *   onClose={() => setIsOpen(false)}
+ *   columns={columns}
+ *   primaryKey="id"
+ *   loadData={async (onChunk) => onChunk(await fetchRows())}
+ *   onComplete={(result, actions) => { saveChanges(result); actions.reset(); }}
+ * />
+ * ```
+ */
+declare function DataEditor<TRow extends DataEditorRow = DataEditorRow>(allProps: DataEditorProps<TRow>): react_jsx_runtime.JSX.Element;
+
+export { DataEditor, date, downloadExampleFile, email, endDateAfterStart, exportDataEditor, numeric, oneOf, required };
+export type { CellValidator, ChatContext, ChatErrorSummary, ChatResponseChunk, ChatRow, ChatRowStatus, ChunkSourceOptions, ColumnDeleteParams, ColumnEditParams, DataEditorChat, DataEditorColumn, DataEditorFormat, DataEditorInlineProps, DataEditorLocalStorage, DataEditorModalProps, DataEditorMode, DataEditorProps, DataEditorResult, DataEditorRow, DataEditorServer, DataEditorSourceResult, DataEditorTranslations, DataEditorVariant, EditParams, EditResponse, ExportParams$1 as ExportParams, FileImportParams, FilterOptionsResponse, FindNavigateParams, FindParams, FormulaParams, ImportMappings, QueryFilters, QueryParams, QueryResponse, Region, RemoteSource, ReplaceParams, ResultRow, RowsImportParams, RowsImportResponse, ServerCallOptions, ServerCellChange, ServerCellError, ServerQueryCounts, ServerRow, ServerRowMeta, ServerRowStatus, SourceRemoveParams, TransformParams, UpdogError, UpdogErrorCode, ValidationError, ValueMatchInput, ValueMatchOutput };