@updog/data-editor-wc 0.1.0

package/index.d.ts

@@ -0,0 +1,1593 @@
+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>>;
+
+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;
+};
+
+/**
+ * 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;
+};
+/**
+ * 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 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<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;
+};
+/** 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<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;
+};
+
+/** 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;
+/** 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;
+};
+/** 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 Props = DataEditorProps;
+/**
+ * All properties available on the `<updog-editor>` element.
+ *
+ * Set simple values as HTML attributes (`api-key`, `open`, `readonly`, `rtl`, `locale`, `variant`, `primary-key`).
+ * Set complex values (objects, functions, arrays) as JS properties or via `configure()`.
+ *
+ * Closing is handled via the `"close"` event — listen for it and call `editor.hide()`.
+ *
+ * @example
+ * ```ts
+ * const editor = document.querySelector("updog-editor")!;
+ *
+ * editor.apiKey = "your-license-key";
+ * editor.primaryKey = "id";
+ * editor.columns = [
+ *   { id: "name", title: "Name", width: 200 },
+ *   { id: "email", title: "Email", width: 250 },
+ * ];
+ *
+ * editor.loadData = async (onChunk) => {
+ *   const rows = await fetch("/api/employees").then(r => r.json());
+ *   onChunk(rows);
+ * };
+ *
+ * editor.onComplete = (result, actions) => {
+ *   console.log("Valid rows:", result.valid);
+ *   actions.reset();
+ * };
+ *
+ * editor.addEventListener("close", () => editor.hide());
+ * editor.show();
+ * ```
+ */
+type UpdogEditorProps = Omit<Props, "onClose" | "className"> & {
+    /**
+     * Set multiple properties at once. Useful for initial setup.
+     *
+     * @example
+     * ```ts
+     * editor.configure({
+     *   apiKey: "your-key",
+     *   columns: [...],
+     *   primaryKey: "id",
+     *   loadData: async (onChunk) => onChunk(await fetchRows()),
+     * });
+     * ```
+     */
+    configure(props: Partial<Props>): void;
+    /** Open the editor modal. Same as setting `editor.open = true`. */
+    show(): void;
+    /** Close the editor modal. Same as setting `editor.open = false`. */
+    hide(): void;
+};
+declare global {
+    /**
+     * The `<updog-editor>` custom element. A full-screen modal spreadsheet editor.
+     *
+     * Supports CSV/XLSX import, cell validation, undo/redo, find & replace, and exporting.
+     * Works in any framework (Angular, Vue, vanilla JS) — no React needed.
+     *
+     * @see {@link UpdogEditorProps} for all available properties.
+     */
+    interface UpdogEditorElement extends HTMLElement, UpdogEditorProps {
+    }
+    interface HTMLElementTagNameMap {
+        "updog-editor": UpdogEditorElement;
+    }
+}
+
+export { date, email, endDateAfterStart, numeric, oneOf, required };