@updog/data-editor 0.1.4 → 0.1.5

package/README.md

@@ -1,11 +1,13 @@
 # @updog/data-editor
 
-Enterprise-grade spreadsheet editor SDK for React. Designed for editing large datasets (100k+ rows) with multi-source data merging, file imports, validation, and undo/redo.
+Client-side data importer and spreadsheet editor SDK for React. Your users import files, match columns to your schema, fix errors, and submit clean data. Edits happen inline, in the browser, at 1M+ rows.
+
+> **Not using React?** Use the framework-agnostic Web Component build — [`@updog/data-editor-wc`](https://www.npmjs.com/package/@updog/data-editor-wc) — for Angular, Vue, Svelte, or vanilla JS.
 
 ## Requirements
 
 - React 18.x or 19.x
-- An API key — this is a **commercial SDK**. Sign up at [updog.tech](https://updog.tech) to create an account and get a key. The editor will not render without one.
+- An API key — this is a **commercial SDK**. Sign up at [updog.tech](https://updog.tech) to get one.
 
 ## Installation
 
@@ -16,44 +18,71 @@ npm install @updog/data-editor
 ## Quick Start
 
 ```tsx
-import { DataEditor } from "@updog/data-editor";
+import { useState } from "react";
+import { DataEditor, required, email } from "@updog/data-editor";
 import "@updog/data-editor/styles.css";
+import type { DataEditorColumn } from "@updog/data-editor";
 
-function App() {
-  const [open, setOpen] = useState(false);
-
-  const columns = [
-    { id: "name", title: "Name", width: 150 },
-    { id: "email", title: "Email", width: 260 },
-  ];
+type Employee = {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+};
 
-  const loadData = async (onChunk) => {
-    const res = await fetch("/api/employees");
-    onChunk(await res.json());
-  };
+const columns: DataEditorColumn[] = [
+  { id: "name", title: "Full Name", size: 200, validate: required("Name is required") },
+  { id: "email", title: "Email", size: 250, validate: [required("Email is required"), email("Invalid email")] },
+  { id: "role", title: "Role", editor: { type: "select", options: ["Admin", "Editor", "Viewer"] } },
+];
 
-  const onComplete = (result) => {
-    console.log(result.valid, result.invalid, result.deleted);
-    setOpen(false);
-  };
+export function App() {
+  const [open, setOpen] = useState(false);
 
   return (
     <>
       <button onClick={() => setOpen(true)}>Open Editor</button>
-      <DataEditor
-        apiKey="your-api-key"
+      <DataEditor<Employee>
+        apiKey="your-license-key"
         open={open}
         onClose={() => setOpen(false)}
         columns={columns}
         primaryKey="id"
-        loadData={loadData}
-        onComplete={onComplete}
+        loadData={async (onChunk) => {
+          const res = await fetch("/api/employees");
+          onChunk(await res.json());
+        }}
+        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();
+          setOpen(false);
+        }}
       />
     </>
   );
 }
 ```
 
+## TypeScript
+
+`DataEditor` accepts a generic type parameter for row data. This gives you type-safe access to `primaryKey` and the result rows in `onComplete`.
+
+```tsx
+type Employee = { id: string; name: string; email: string };
+
+<DataEditor<Employee>
+  primaryKey="id"  // autocomplete shows "id" | "name" | "email"
+  // ...
+/>
+```
+
+When you omit the generic, rows are typed as `Record<string, unknown>`.
+
 ## Inline Mode
 
 Render the editor directly in the DOM without a modal overlay:
@@ -61,7 +90,7 @@ Render the editor directly in the DOM without a modal overlay:
 ```tsx
 <DataEditor
   mode="inline"
-  apiKey="your-api-key"
+  apiKey="your-license-key"
   columns={columns}
   primaryKey="id"
   loadData={loadData}
@@ -69,151 +98,296 @@ Render the editor directly in the DOM without a modal overlay:
 />
 ```
 
+In inline mode, `open` and `onClose` don't apply.
+
 ## Props
 
 | Prop | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `mode` | `"modal"` \| `"inline"` | No | `"modal"` | Rendering mode |
-| `apiKey` | `string` | Yes | — | License key |
-| `open` | `boolean` | Modal only | — | Controls modal visibility. Required in modal mode only |
-| `onClose` | `() => void` | Modal only | — | Called when user initiates close. Required in modal mode only |
-| `columns` | `DataEditorColumn[]` | Yes | — | Column definitions |
-| `primaryKey` | `keyof TRow` | Yes | — | Unique row identifier column |
-| `loadData` | `(onChunk) => Promise<void>` | No | — | Async data loader with chunked delivery |
-| `onComplete` | `(result, actions) => void` | No | — | Called on submit with valid/invalid/deleted rows |
-| `variant` | `"editor"` \| `"uploader"` | No | `"editor"` | UI mode |
-| `translations` | `DataEditorTranslations` | No | — | i18n overrides |
-| `locale` | `string` | No | `"en"` | BCP 47 locale tag |
-| `enableDeleteRow` | `"all"` \| `"new"` \| `false` | No | `false` | Row deletion policy |
-| `enableAddRow` | `boolean` | No | `true` | Show "Add row" option |
-| `importFormats` | `DataEditorFormat[]` | No | all | Allowed import formats |
-| `exportFormats` | `DataEditorFormat[]` | No | all | Allowed export formats |
-| `rowHeight` | `number` | No | `34` | Row height in pixels |
-| `headerHeight` | `number` | No | `36` | Header height in pixels |
-| `readonly` | `boolean` | No | `false` | Hide write-oriented UI |
-| `rtl` | `boolean` | No | `false` | Right-to-left layout |
-| `className` | `string` | No | — | CSS class for the modal |
+| `apiKey` | `string` | Yes | — | Your Updog license key. Validated on each open. |
+| `columns` | `DataEditorColumn[]` | Yes | — | Column definitions. |
+| `primaryKey` | `keyof TRow` | Yes | — | Column ID that uniquely identifies each row. |
+| `mode` | `"modal"` \| `"inline"` | No | `"modal"` | Rendering mode. |
+| `open` | `boolean` | Modal only | — | Controlled modal visibility. |
+| `onClose` | `() => void` | Modal only | — | Called when the user closes the modal (X button or Escape). |
+| `loadData` | `(onChunk) => Promise<void>` | No | — | Async data loader. Stream rows in chunks, optionally tagged by source. |
+| `onComplete` | `(result, actions) => void` | No | — | Called on submit. See [Submission Result](#submission-result). |
+| `variant` | `"editor"` \| `"uploader"` | No | `"editor"` | Initial view. `"uploader"` opens the import wizard first. |
+| `translations` | `DataEditorTranslations` | No | — | Partial i18n overrides. |
+| `locale` | `string` | No | `"en"` | BCP 47 locale tag. |
+| `rtl` | `boolean` | No | `false` | Right-to-left layout. |
+| `readonly` | `boolean` | No | `false` | Hide all editing UI. |
+| `enableDeleteRow` | `"all"` \| `"new"` \| `false` | No | `false` | Row deletion policy. |
+| `enableAddRow` | `boolean` | No | `true` | Show the "Add row" button. |
+| `enableCreateColumn` | `boolean` | No | `true` | Allow creating columns for unmatched CSV headers during import. |
+| `importFormats` | `DataEditorFormat[]` | No | all | Allowed import formats. `[]` disables import. |
+| `exportFormats` | `DataEditorFormat[]` | No | all | Allowed export formats. `[]` disables export. |
+| `remoteSources` | `RemoteSource[]` | No | — | Custom import buttons (Google Sheets, S3, etc.) rendered on the upload step. |
+| `rowHeight` | `number` | No | `34` | Row height in pixels. |
+| `headerHeight` | `number` | No | `36` | Header height in pixels. |
+| `server` | `DataEditorServer<TRow>` | No | — | Server-delegated mode: SDK renders, your backend handles queries and mutations. |
+| `chat` | `DataEditorChat<TRow>` | No | — | Bring-your-own AI chat panel. |
+| `onColumnMatch` | `(headers, columns) => ...` | No | — | Override import column matching. |
+| `onValueMatch` | `(valuesToMatch) => ...` | No | — | Override import value matching for `select` columns. |
+| `synonyms` | `Record<string, string[]>` | No | — | Extra synonyms for column auto-matching. |
+| `sampleData` | `Record<string, unknown>[]` | No | — | Rows used in the "Download Example" file. |
+| `localStorage` | `false` \| `{ licenseGrant?: boolean }` | No | `{ licenseGrant: true }` | What the SDK caches in `localStorage`. |
+| `onError` | `(error: UpdogError) => void` | No | — | Called on internal errors. Use for logging or Sentry. |
+| `className` | `string` | No | — | CSS class on the wrapper element. |
 
 ## Column Configuration
 
 ```tsx
+import { required, email } from "@updog/data-editor";
+import type { DataEditorColumn } from "@updog/data-editor";
+
 const columns: DataEditorColumn[] = [
   {
     id: "email",
     title: "Email",
-    width: 260,
+    size: 260,
 
-    // Validation — single or array of validators
-    validate: (value, row) => {
-      if (!value) return { level: "error", message: "Required" };
-      if (!String(value).includes("@")) return { level: "warning", message: "Invalid email" };
-      return null;
-    },
+    // One validator, or an array. Each returns `{ level: "error", message }` or null.
+    validate: [required("Email is required"), email("Enter a valid email")],
 
-    // Uniqueness constraint
+    // Flag duplicates in this column as errors.
     unique: true,
 
-    // Cross-field validation — revalidate these columns when this one changes
+    // Revalidate these columns when this one changes.
     dependentFields: ["confirmEmail"],
 
-    // Cell editor: "text" (default), "date", or "select"
-    editor: { type: "select", options: [{ id: "us", text: "United States" }] },
+    // Cell editor. Default is "text".
+    editor: { type: "select", options: ["US", "UK", "DE"] },
 
-    // Visual formatting (display only, does not change data)
+    // Display-only formatting. Does not mutate stored data.
     formatter: (value) => value.toLowerCase(),
 
-    // Data transformation on input
+    // Runs when rows are uploaded to the editor. Mutates the stored value.
     transformer: (value) => String(value).trim(),
 
-    // Filter panel configuration
+    // Sidebar filter control.
     filter: { type: "select" },
+
+    // Lock cells in this column. `"default"` locks only default-source rows.
+    locked: "default",
   },
 ];
 ```
 
+**Cell editors**: `{ type: "text" }` (default), `{ type: "date", minDate?, maxDate? }`, `{ type: "select", options: string[] }`, `{ type: "number", decimalPlaces?, decimalSeparator?, thousandsSeparator?, allowChars? }`.
+
+**Column filters**: `{ type: "select", label?, placeholder?, options?, multiple? }`, `{ type: "number-range", label? }`, `{ type: "date-range", label? }`.
+
 ## Built-in Validators
 
+Validators are factory functions — call each one with the error message you want displayed.
+
 ```tsx
-import { useDataEditorValidators } from "@updog/data-editor";
-
-function App() {
-  const { required, numeric, email, date, endDateAfterStart } = useDataEditorValidators();
-
-  const columns = [
-    { id: "email", title: "Email", validate: [required, email] },
-    { id: "salary", title: "Salary", validate: numeric },
-    { id: "startDate", title: "Start", validate: date, editor: { type: "date" } },
-    {
-      id: "endDate",
-      title: "End",
-      validate: [date, endDateAfterStart("startDate")],
-      dependentFields: ["startDate"],
-      editor: { type: "date" },
-    },
-  ];
-}
+import {
+  required,
+  numeric,
+  email,
+  date,
+  oneOf,
+  endDateAfterStart,
+} from "@updog/data-editor";
+
+const columns = [
+  { id: "name", title: "Name", validate: required("Required") },
+  { id: "email", title: "Email", validate: [required("Required"), email("Invalid email")] },
+  { id: "salary", title: "Salary", validate: numeric("Must be a number") },
+  { id: "status", title: "Status", validate: oneOf(["active", "inactive"], "Invalid status") },
+  {
+    id: "startDate",
+    title: "Start",
+    validate: date("Use YYYY-MM-DD or DD/MM/YYYY"),
+    editor: { type: "date" },
+    dependentFields: ["endDate"],
+  },
+  {
+    id: "endDate",
+    title: "End",
+    validate: [date("Invalid date"), endDateAfterStart("startDate", "End must be on or after start")],
+    editor: { type: "date" },
+  },
+];
+```
+
+A `ValidationError` with `level: "error"` flags the cell in the grid but does **not** block submission — invalid rows are delivered to `onComplete` tagged via `isValid: false`.
+
+### Custom validators
+
+A validator is `(value, row) => ValidationError | null`. The only `level` is `"error"`.
+
+```tsx
+import type { CellValidator } from "@updog/data-editor";
+
+const mustContainAt: CellValidator = (value) => {
+  if (!value) return null;
+  if (!String(value).includes("@")) return { level: "error", message: "Must contain @" };
+  return null;
+};
 ```
 
 ## Data Loading
 
-Data is loaded in chunks to avoid blocking the UI:
+`loadData` is called once when the editor opens. Call `onChunk` one or more times to stream rows. The grid renders each chunk without blocking.
 
 ```tsx
-const loadData = async (onChunk) => {
-  // Load from API in pages
+// Single source
+loadData={async (onChunk) => {
   for (let page = 0; page < totalPages; page++) {
-    const res = await fetch(`/api/employees?page=${page}`);
-    const rows = await res.json();
-    onChunk(rows); // Each chunk is immediately rendered
+    const rows = await fetch(`/api/employees?page=${page}`).then((r) => r.json());
+    onChunk(rows);
   }
-};
+}}
+
+// Multiple sources — each chunk tagged with a source
+loadData={async (onChunk) => {
+  onChunk(await fetchSalesforce(), { source: "Salesforce", done: true });
+  onChunk(await fetchHubSpot(), { source: "HubSpot", deletable: true, done: true });
+}}
 ```
 
+`ChunkSourceOptions`: `{ source: string; id?: string; deletable?: boolean; done?: boolean }`. Sources are auto-registered on first encounter. Chunks without options go to "Existing Data". When `loadData` resolves, any source still loading is finalized automatically.
+
 ## Submission Result
 
-```tsx
-const onComplete = (result, actions) => {
-  // result.valid    — rows that pass all validation
-  // result.invalid  — rows with validation errors
-  // result.deleted  — rows marked for deletion
-  // result.newCount, result.editedCount, result.deletedCount
+`onComplete(result, actions)` fires when the user submits.
+
+```ts
+type DataEditorResult<TRow> = {
+  sources: {
+    sourceId: string;
+    sourceName: string;
+    rows: {
+      row: TRow;
+      isNew: boolean;      // imported or manually added this session
+      isChanged: boolean;  // cell values differ from origin
+      isDeleted: boolean;  // marked for deletion
+      isValid: boolean;    // passes all validators
+    }[];
+  }[];
+  counts: { new: number; changed: number; deleted: number; invalid: number };
+};
 
-  // actions.reset() — clear all changes and reload
+type DataEditorActions = {
+  reset: () => void; // discard changes and reload via loadData
 };
 ```
 
-## Import/Export Formats
+Pristine backend rows (unchanged, not deleted, not new) are omitted from `sources[].rows` — they're no-ops. The flags are orthogonal: a row can be new, changed, and deleted at once. You own the routing rules:
 
-Supported formats: `"csv"`, `"tsv"`, `"xlsx"`, `"json"`, `"xml"`.
+```tsx
+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();
+}}
+```
+
+If you never tagged sources via `loadData`, you'll get one entry with `sourceId: "backend"`. `result.counts` is an aggregate for summary UI — route with the per-row flags, not counts.
+
+## Import Configuration
+
+The import wizard guides users through uploading a file, mapping columns to your schema, and resolving value mismatches.
+
+### Formats
+
+Supported: `"csv"`, `"tsv"`, `"xlsx"`, `"json"`, `"xml"`.
 
 ```tsx
-// Only allow CSV and XLSX import, disable export
 <DataEditor
-  importFormats={["csv", "xlsx"]}
-  exportFormats={[]}
+  importFormats={["csv", "xlsx"]} // only CSV and XLSX
+  exportFormats={[]}              // disable export entirely
 />
 ```
 
+### Override column matching
+
+```tsx
+onColumnMatch={async (headers, columns) => {
+  const mappings = await myMatchingService.match(headers, columns);
+  return mappings; // { csvHeader: columnId | null }
+}}
+```
+
+Return a map of `{ csvHeader: columnId | null }`. Entries set to `null` or omitted fall back to built-in matching.
+
+### Override value matching
+
+For select columns, override imported-value → option mapping:
+
+```tsx
+onValueMatch={async (valuesToMatch) => {
+  // valuesToMatch = { country: { importedValues: ["espana", "fr"], options: ["Spain", "France"] } }
+  return {
+    country: { espana: "Spain", fr: "France" },
+  };
+}}
+```
+
+Values set to `null` skip auto-matching. Unmapped values fall back to built-in fuzzy matching.
+
+### Synonyms
+
+Extra aliases for the built-in column matcher:
+
+```tsx
+synonyms={{
+  productSku: ["sku", "article_no", "item_code"],
+  firstName: ["first", "given_name", "fname"],
+}}
+```
+
+### Remote sources
+
+Render custom import buttons for third-party sources. You own auth and picker logic; the SDK renders the button and processes the result.
+
+```tsx
+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>[] — or return a File
+  },
+};
+
+<DataEditor remoteSources={[googleSheets]} {...rest} />
+```
+
+Return a `File` to parse via the standard CSV/XLSX/JSON/XML pipeline, or return structured records to skip parsing.
+
+## Error Handling
+
+Log SDK-internal errors through `onError`. The SDK recovers gracefully — use this for monitoring, not recovery.
+
+```tsx
+onError={(error) => {
+  Sentry.captureException(error.originalError ?? error, {
+    tags: { code: error.code, source: error.source },
+  });
+}}
+```
+
+Error codes: `PARSE_ERROR`, `RENDER_ERROR`, `TRANSFORM_ERROR`, `VALIDATION_ERROR`, `WORKER_ERROR`, `COMMAND_ERROR`, `OPERATION_ERROR`.
+
 ## Non-React Usage
 
-For Angular, Vue, or vanilla JS, use the Web Component package:
+For Angular, Vue, Svelte, or vanilla JS use the Web Component build:
 
 ```bash
 npm install @updog/data-editor-wc
 ```
 
-See [@updog/data-editor-wc](https://www.npmjs.com/package/@updog/data-editor-wc) for details.
-
-## Key Features
-
-- Virtualized grid — smooth scrolling with 100k+ rows
-- Multi-source data — backend data + multiple CSV/XLSX imports merged into one view
-- Smart CSV column matching — auto-maps imported columns with 90%+ accuracy
-- Undo/redo — Cmd+Z / Cmd+Shift+Z with batch support
-- Find & replace — search across all columns with match highlighting
-- Cell validation — custom validators, uniqueness constraints, cross-field dependencies
-- Dirty tracking — distinguishes new vs edited rows, detects value reverts
+See [@updog/data-editor-wc](https://www.npmjs.com/package/@updog/data-editor-wc).
 
 ## License
 
-Commercial — see [LICENSE](./LICENSE) for the full terms of the Updog SDK Commercial License v1.0. Contact `admin@updog.tech` for enterprise licensing questions. Third-party dependencies bundled with this package are listed in `THIRD_PARTY_NOTICES.txt`.
+Commercial — see [LICENSE](./LICENSE) for the full terms of the Updog SDK Commercial License v1.0. Contact `admin@updog.tech` for enterprise licensing. Third-party dependencies are listed in `THIRD_PARTY_NOTICES.txt`.

package/index.d.ts

@@ -818,11 +818,40 @@ declare class ServerEditBuilder<TRow extends DataEditorRow = DataEditorRow> {
     private viewContext;
 }
 
+/**
+ * Categories of internal errors surfaced through the `onError` callback.
+ *
+ * - `PARSE_ERROR` — file parsing failed (corrupt CSV, invalid XLSX, etc.).
+ * - `RENDER_ERROR` — component render failed (caught by error boundary).
+ * - `TRANSFORM_ERROR` — data transformation failed (column transform, value mapping).
+ * - `VALIDATION_ERROR` — validation execution failed (validator threw instead of returning).
+ * - `WORKER_ERROR` — Web Worker failed (filter worker, chat transform worker).
+ * - `COMMAND_ERROR` — undo/redo command failed.
+ * - `OPERATION_ERROR` — general operation failed (bulk mutations, imports).
+ */
 type UpdogErrorCode = "PARSE_ERROR" | "RENDER_ERROR" | "TRANSFORM_ERROR" | "VALIDATION_ERROR" | "WORKER_ERROR" | "COMMAND_ERROR" | "OPERATION_ERROR";
+/**
+ * An internal error caught by the SDK and passed to `onError`. The SDK
+ * recovers gracefully where possible — `onError` is for your logging and
+ * monitoring (Sentry, Datadog, etc.).
+ *
+ * @example
+ * ```ts
+ * onError={(error) => {
+ *   Sentry.captureException(error.originalError ?? error, {
+ *     tags: { code: error.code, source: error.source },
+ *   });
+ * }}
+ * ```
+ */
 type UpdogError = {
+    /** The error category. */
     code: UpdogErrorCode;
+    /** Human-readable description. */
     message: string;
+    /** Module or subsystem that raised the error. */
     source: string;
+    /** The underlying thrown value, when available. */
     originalError?: unknown;
 };
 
@@ -1745,7 +1774,9 @@ type ColumnDelta = {
 
 /**
  * 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.
+ * Extend this with your own type via the `<DataEditor<TRow>>` generic for
+ * type-safe column access. When the generic is omitted, rows are typed as
+ * `Record<string, unknown>`.
  *
  * @example
  * ```ts
@@ -1754,7 +1785,9 @@ type ColumnDelta = {
  * ```
  */
 type DataEditorRow = Record<string, unknown>;
+/** Sort direction. */
 type SortDirection = "asc" | "desc";
+/** Current sort state. `null` means no active sort. */
 type SortState = {
     columnId: string;
     direction: SortDirection;
@@ -1784,6 +1817,14 @@ type Filters = {
     }>;
 };
 
+/**
+ * A single chunk in the stream returned from `DataEditorChat.onMessage`.
+ *
+ * - `status` — progress message shown while processing (e.g. "Analyzing 500 rows...").
+ * - `message` — chat reply shown to the user.
+ * - `rows` — updated rows to apply to the grid. Matched by `primaryKey`.
+ * - `transform` — description of the transform applied.
+ */
 type ChatResponseChunk<TRow extends DataEditorRow = DataEditorRow> = {
     type: "status";
     content: string;
@@ -1797,37 +1838,105 @@ type ChatResponseChunk<TRow extends DataEditorRow = DataEditorRow> = {
     type: "transform";
     content: string;
 };
+/** Status of a row in the chat sample, relative to its origin snapshot. */
 type ChatRowStatus = "new" | "edited" | "original";
+/** A sample row handed to the chat callback, with its current status and validation errors. */
 type ChatRow<TRow extends DataEditorRow = DataEditorRow> = {
+    /** Row data keyed by column ID. */
     data: TRow;
+    /** Whether the row was newly added, edited, or is unchanged. */
     status: ChatRowStatus;
+    /** Validation errors keyed by column ID. */
     errors: Record<string, string[]>;
+    /** The source this row belongs to. */
     source: string;
 };
+/** Aggregated error count across the current view, grouped by field and message. */
 type ChatErrorSummary = {
+    /** Column ID where the error occurred. */
     field: string;
+    /** The validation message. */
     message: string;
+    /** How many rows hit this error. */
     count: number;
+    /** A few example values that triggered the error. */
     examples: string[];
 };
+/**
+ * Context about the current dataset, passed to `loadSuggestions` and extended
+ * into `ChatContext` for `onMessage`.
+ */
 type ChatDataContext<TRow extends DataEditorRow = DataEditorRow> = {
+    /** Full column definitions. */
     columns: DataEditorColumn[];
+    /** Row identifier field. */
     primaryKey: keyof TRow;
+    /** Total rows in the dataset. */
     totalRowCount: number;
+    /** Rows in the current filtered view. */
     filteredRowCount: number;
+    /** Sample rows, with status and errors. Size controlled by `sampleSize`. */
     sample: ChatRow<TRow>[];
+    /** Aggregated error counts by field and message. */
     errorSummary: ChatErrorSummary[];
+    /** Access all rows. Use for full-dataset operations. */
     getRows: () => ChatRow<TRow>[];
 };
+/**
+ * The full context passed to `DataEditorChat.onMessage` when the user sends
+ * a prompt. Includes the prompt itself and all dataset context.
+ */
 type ChatContext<TRow extends DataEditorRow = DataEditorRow> = ChatDataContext<TRow> & {
+    /** The user's chat prompt. */
     message: string;
 };
+/**
+ * Bring-your-own-AI chat configuration. When provided via the `chat` prop,
+ * the editor shows a chat panel alongside the grid. You own the AI
+ * integration; the SDK hands you dataset context and renders the streamed
+ * response.
+ *
+ * @example
+ * ```ts
+ * chat={{
+ *   sampleSize: 50,
+ *   onMessage: async function* (context) {
+ *     yield { type: "status", content: "Thinking..." };
+ *     const res = await fetch("/api/ai", {
+ *       method: "POST",
+ *       body: JSON.stringify({
+ *         prompt: context.message,
+ *         columns: context.columns,
+ *         sample: context.sample.map(r => r.data),
+ *         errors: context.errorSummary,
+ *       }),
+ *     }).then(r => r.json());
+ *     yield { type: "rows", content: res.updatedRows };
+ *     yield { type: "transform", content: res.description };
+ *     yield { type: "message", content: res.reply };
+ *   },
+ * }}
+ * ```
+ */
 type DataEditorChat<TRow extends DataEditorRow = DataEditorRow> = {
+    /**
+     * How many rows to include in the context sample. The SDK picks a
+     * representative slice including rows with errors. When omitted, the SDK decides.
+     */
     sampleSize?: number;
+    /** Title shown above the suggestion list when the chat is empty. */
     emptyTitle?: string;
+    /** How many suggestions to request from `loadSuggestions`. */
     suggestionsCount?: number;
+    /** Optional prompt generator for the empty-state suggestion chips. */
     loadSuggestions?: (context: ChatDataContext<TRow>) => Promise<string[]>;
+    /**
+     * Called when the user sends a message. Receives full dataset context.
+     * Returns an async iterable of response chunks — the SDK streams them
+     * into the UI.
+     */
     onMessage: (context: ChatContext<TRow>) => AsyncIterable<ChatResponseChunk<TRow>>;
+    /** Called when the user cancels a pending request. Use to abort your API call. */
     onCancel?: () => void;
 };
 
@@ -1847,8 +1956,13 @@ 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.
  *
+ * A `ValidationError` with `level: "error"` flags the cell in the grid but
+ * does not block submission — invalid rows are delivered to `onComplete`
+ * alongside valid ones, tagged via the `isValid` flag.
+ *
  * Built-in validator factories: `required(msg)`, `numeric(msg)`, `email(msg)`,
- * `date(msg)`, `endDateAfterStart(startField, msg)`. Import them from the package root.
+ * `date(msg)`, `oneOf(values, 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.
@@ -1932,41 +2046,62 @@ type ColumnLockMode = "all" | "default";
  *
  * @example
  * ```ts
+ * import { required, email, numeric } from "@updog/data-editor";
+ *
  * 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}` },
+ *   { id: "name", title: "Full Name", size: 200, validate: required("Name is required") },
+ *   { id: "email", title: "Email", size: 250, validate: [required("Email is required"), email("Invalid email")], unique: true },
+ *   { id: "role", title: "Role", editor: { type: "select", options: ["Admin", "Editor", "Viewer"] } },
+ *   { id: "salary", title: "Salary", validate: numeric("Must be a number"), formatter: (v) => v ? `$${v}` : "" },
  * ];
  * ```
  */
 type DataEditorColumn = {
     /** Unique column identifier. Must match the keys in your row data. */
     id: string;
-    /** Column header text. */
+    /** Column header text shown to the user. */
     title: string;
-    /** One or more validators to run on every edit. */
+    /**
+     * One or more validators run on every edit. Each receives the cell value and
+     * the full row, and returns a `ValidationError` to flag a problem or `null`
+     * if valid. Errors do not block submission — see `CellValidator`.
+     */
     validate?: CellValidator | CellValidator[];
-    /** When `true`, the editor flags duplicate values in this column as errors. */
+    /**
+     * When `true`, the editor flags duplicate values in this column as errors.
+     * The error message is localized via the `translations` prop
+     * (`dataEditor.validation.valueMustBeUnique`).
+     */
     unique?: boolean;
-    /** Column IDs to revalidate when this column changes. Use for cross-field rules like "end date must be after start date". */
+    /**
+     * 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. */
+    /**
+     * Transform a value before it enters the store. Runs when rows are uploaded
+     * to the data editor.
+     */
     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 */
+    /**
+     * Whether this column can be pinned to the left (right in RTL) 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.
+     * Controls whether cells in this column are locked. A column locked via
+     * configuration cannot be unlocked from the UI.
+     * - `true` | `"all"` — locked for every row.
+     * - `"default"` — locked only for default-source rows; rows added manually,
+     *   duplicated, or imported remain editable.
      * - `false` | `undefined` — not locked.
      */
     locked?: boolean | ColumnLockMode;
@@ -2386,9 +2521,12 @@ type UndoRedoResult = {
     success: boolean;
     targetCell?: CellLocation;
 };
-/** Actions available inside the `onComplete` callback. */
+/**
+ * Actions available inside the `onComplete` callback. Call `reset()` after a
+ * successful save to clear the editor and re-fetch via `loadData`.
+ */
 type DataEditorActions = {
-    /** Discard all changes and reload the original data. */
+    /** Discard all changes and reload the original data via `loadData`. */
     reset: () => void;
 };
 /**
@@ -2448,14 +2586,24 @@ type DataEditorResult<TRow extends DataEditorRow = DataEditorRow> = {
         invalid: number;
     };
 };
+/**
+ * Options used to tag a chunk passed to `loadData`'s `onChunk` callback.
+ * Sources are auto-registered on first encounter. Chunks without options go
+ * to "Existing Data".
+ */
 type ChunkSourceOptions = {
-    /** Display name for this data source. */
+    /** Display name for this data source. Required when tagging a source. */
     source: string;
-    /** Stable identifier. Defaults to `source` value when omitted. */
+    /** Stable identifier. Defaults to the `source` value when omitted. */
     id?: string;
-    /** Can the user delete this source? @default false */
+    /** Whether the user can delete this source from the editor. @default false */
     deletable?: boolean;
-    /** Marks this source as finished loading. */
+    /**
+     * Marks this source as finished loading. Shows a completion state in the
+     * UI. When the `loadData` promise resolves, any source still loading is
+     * automatically finalized.
+     * @default false
+     */
     done?: boolean;
 };
 type DataSourceId = string;
@@ -2509,20 +2657,34 @@ type DataStoreSnapshot = {
     /** 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. */
+/**
+ * Per-column input to `onValueMatch`: the unique imported values from the
+ * file and the allowed select options defined on the column.
+ */
 type ValueMatchInput = {
+    /** Distinct values seen in the imported file for this column. */
     importedValues: string[];
+    /** Allowed options from the column's `select` editor. */
     options: string[];
 };
-/** Per-column result from `onValueMatch`: maps each imported value to an option value, or `null` to skip auto-matching. */
+/**
+ * Per-column result from `onValueMatch`. Outer key = column ID, inner key =
+ * imported value, inner value = chosen option, or `null` to skip
+ * auto-matching for that value. Unmapped values fall back to built-in fuzzy
+ * matching.
+ */
 type ValueMatchOutput = Record<string, Record<string, string | null>>;
-/** File formats supported for import and export. */
+/** File formats supported for import and export. Shared by `importFormats` and `exportFormats`. */
 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.
+ * The SDK renders a button per source on the upload step and calls `fetch()`
+ * when clicked. You own all integration complexity — auth, pickers,
+ * downloads. The SDK just processes the result.
+ *
+ * Return a `File` to go through the standard parse pipeline
+ * (CSV/XLSX/JSON/XML), or return structured records to skip parsing entirely.
  *
  * @example
  * ```ts
@@ -2546,7 +2708,10 @@ type RemoteSource = {
     icon: string;
     /** Optional tooltip text. */
     description?: string;
-    /** Returns a File (parsed via CSV/XLSX/JSON/XML pipeline) or structured records (used directly). */
+    /**
+     * Returns a `File` (parsed via the CSV/XLSX/JSON/XML pipeline) or structured
+     * records (used directly, skipping parse).
+     */
     fetch: () => Promise<File | Record<string, unknown>[]>;
 };
 /**
@@ -2561,8 +2726,9 @@ 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.
+     * The column ID used to uniquely identify each row (e.g. `"id"` or
+     * `"employeeId"`). Used to match imported rows against existing data and to
+     * track edits.
      */
     primaryKey: keyof TRow;
     /**
@@ -2616,37 +2782,78 @@ type DataEditorBaseProps<TRow extends DataEditorRow = DataEditorRow> = {
      * ```
      */
     onComplete?: (result: DataEditorResult<TRow>, actions: DataEditorActions) => void;
-    /** Controls the initial view. `"editor"` opens the grid, `"uploader"` opens the import wizard first. @default "editor" */
+    /**
+     * Controls the initial view. `"editor"` opens directly to the spreadsheet
+     * grid. `"uploader"` opens the file import wizard first — the user uploads
+     * a file, maps columns, fixes errors, then continues to the grid.
+     * @default "editor"
+     */
     variant?: DataEditorVariant;
-    /** Override any UI string. Pass a partial object — only the keys you provide are replaced. */
+    /**
+     * Override any UI string. Pass a partial object — only the keys you provide
+     * are replaced. Every key lives under `dataEditor`.
+     */
     translations?: DataEditorTranslations;
-    /** BCP 47 locale tag (e.g. `"en"`, `"fr"`, `"ar"`). Used for plural rules and locale-aware features. @default "en" */
+    /**
+     * 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).
+     * - `false` — deletion disabled.
      * - `"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 */
+    /**
+     * Show the "Add row" button in the data sources panel. When `false`, users
+     * can only edit existing rows or import data — they can't manually add
+     * blank rows.
+     * @default true
+     */
     enableAddRow?: boolean;
-    /** Which file formats the user can import. `undefined` allows all, `[]` disables import entirely. */
+    /**
+     * Which file formats the user can import. `undefined` allows all formats,
+     * `[]` disables import entirely.
+     */
     importFormats?: DataEditorFormat[];
-    /** Client-defined remote data sources rendered as buttons on the upload step. */
+    /**
+     * Client-defined remote data sources rendered as buttons on the upload
+     * step. You own the integration; the SDK renders the button and processes
+     * the result of `fetch()`.
+     */
     remoteSources?: RemoteSource[];
-    /** Which file formats the user can export. `undefined` allows all, `[]` disables export entirely. */
+    /**
+     * Which file formats the user can export to. `undefined` allows all
+     * formats, `[]` 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. */
+    /**
+     * When `true`, hides all editing UI (submit, add row, delete, import). The
+     * grid becomes view-only.
+     * @default false
+     */
     readonly?: boolean;
-    /** Enable right-to-left layout for RTL languages. @default false */
+    /**
+     * Enable right-to-left layout. Set to `true` for Arabic, Hebrew, and other
+     * RTL languages. Affects grid direction, text alignment, and scrollbar
+     * position.
+     * @default false
+     */
     rtl?: boolean;
-    /** Allow creating new columns for unmatched CSV headers during import. @default true */
+    /**
+     * Allow creating new columns for unmatched CSV headers during import. When
+     * enabled, users can keep data from columns that don't match your schema by
+     * creating dynamic columns on the fly.
+     * @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>>;
@@ -2667,32 +2874,68 @@ type DataEditorBaseProps<TRow extends DataEditorRow = DataEditorRow> = {
      * ```
      */
     onValueMatch?: (valuesToMatch: Record<string, ValueMatchInput>) => ValueMatchOutput | Promise<ValueMatchOutput>;
-    /** Extra synonyms for column auto-matching, e.g. `{ productsku: ["sku", "articleno"] }`. */
+    /**
+     * Extra synonyms for column auto-matching. Keys are column IDs, values are
+     * alternative names the matching engine should recognize.
+     *
+     * @example
+     * ```ts
+     * synonyms={{
+     *   productSku: ["sku", "article_no", "item_code"],
+     *   firstName: ["first", "given_name", "fname"],
+     * }}
+     * ```
+     */
     synonyms?: Record<string, string[]>;
-    /** Sample rows included in the "Download Example" file. When omitted, a generic row is auto-generated from column config. */
+    /**
+     * Sample rows included in the "Download Example" file. When the user clicks
+     * "Download Example" in the import wizard, the SDK generates a template
+     * file with column headers and these rows. When omitted, a generic example
+     * row is auto-generated from column definitions.
+     */
     sampleData?: Record<string, unknown>[];
-    /** Bring Your Own AI chat. When provided, a chat panel is shown alongside the grid. */
+    /**
+     * Bring-your-own-AI chat. When provided, a chat panel is shown alongside
+     * the grid. You own the AI integration; the SDK hands you dataset context
+     * and renders the streamed response.
+     */
     chat?: DataEditorChat<TRow>;
 };
 /**
- * Controls what the editor stores in `localStorage`.
- * Set to `false` to disable all local storage usage.
+ * Controls what the editor stores in `localStorage`. Set to `false` to
+ * disable all local storage usage.
+ *
+ * @default { licenseGrant: true }
  */
 type DataEditorLocalStorage = false | {
-    /** Cache the license validation result to skip re-validation on reload. @default true */
+    /**
+     * 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. */
+/**
+ * Rendering mode. `"modal"` wraps the editor in a full-screen dialog
+ * overlay. `"inline"` renders it 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. */
+    /** Your Updog license key. Validated on each open. */
     apiKey: string;
-    /** Controls what the editor stores in `localStorage`. Set to `false` to disable. */
+    /**
+     * Controls what the editor stores in `localStorage`. Set to `false` to
+     * disable all local storage usage.
+     * @default { licenseGrant: true }
+     */
     localStorage?: DataEditorLocalStorage;
-    /** CSS class added to the wrapper element. */
+    /** CSS class added to the wrapper element. Use for scoped styling overrides. */
     className?: string;
-    /** Called when the SDK catches an internal error. Use for logging, Sentry, etc. Client mode only. */
+    /**
+     * Called when the SDK catches an internal error. The SDK recovers
+     * gracefully where possible — use this for your logging and monitoring
+     * (Sentry, Datadog, etc.). Client mode only.
+     */
     onError?: (error: UpdogError) => void;
 };
 /**
@@ -2702,9 +2945,16 @@ type DataEditorCommonProps<TRow extends DataEditorRow = DataEditorRow> = DataEdi
 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. */
+    /**
+     * Controls modal visibility. This is a controlled prop — you manage the
+     * state. Required in modal mode.
+     */
     open: boolean;
-    /** Called when the user closes the modal (clicks X or presses Escape). Required in modal mode. */
+    /**
+     * Called when the user closes the modal (X button or Escape key). If the
+     * user has unsaved changes, the SDK shows a confirmation dialog before
+     * calling `onClose`. Required in modal mode.
+     */
     onClose: () => void;
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@updog/data-editor",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Enterprise-grade spreadsheet editor SDK for React. Edit large datasets with validation, undo/redo, CSV/XLSX import, and multi-source merging.",
   "author": "Mikhail Kutateladze <admin@updog.tech>",
   "homepage": "https://updog.tech",