@updog/data-editor-wc 0.1.4 → 0.1.5

package/README.md

@@ -1,11 +1,15 @@
 # @updog/data-editor-wc
 
-Web Component wrapper for the Updog Data Editor. Framework-agnostic — works with vanilla JS, Angular, Vue, or any framework.
+Client-side data importer and spreadsheet editor SDK, shipped as a Web Component. Your users import files, match columns to your schema, fix errors, and submit clean data. Edits happen inline, in the browser, at 1M+ rows.
+
+Framework-agnostic — works with vanilla JS, Angular, Vue, Svelte, or any framework that renders HTML.
+
+> **Using React?** Use the first-class React SDK instead — [`@updog/data-editor`](https://www.npmjs.com/package/@updog/data-editor) — for typed props, hooks-friendly integration, and a smaller bundle (shares your app's React).
 
 ## Requirements
 
-- An API key — this is a **commercial SDK**. Sign up at [updog.tech](https://updog.tech) to get one. The editor will not render without it.
 - Any modern evergreen browser (Chrome, Firefox, Safari, Edge).
+- An API key — this is a **commercial SDK**. Sign up at [updog.tech](https://updog.tech) to get one.
 
 ## Installation
 
@@ -13,205 +17,427 @@ Web Component wrapper for the Updog Data Editor. Framework-agnostic — works wi
 npm install @updog/data-editor-wc
 ```
 
-## Usage
+## Register
+
+```js
+import "@updog/data-editor-wc";
+import "@updog/data-editor-wc/styles.css";
+```
+
+Defines `<updog-editor>` globally. Import once, typically at your app entry.
+
+How you wire the element into a framework (Angular's `CUSTOM_ELEMENTS_SCHEMA`, Vue's `compilerOptions.isCustomElement`, Svelte's `svelte:element`, etc.) depends on your stack. Once registered, the rest of this guide is the same.
+
+## Quick Start
 
 ```html
+<button id="open-btn">Open Editor</button>
+<updog-editor id="editor"></updog-editor>
+
 <script type="module">
   import "@updog/data-editor-wc";
   import "@updog/data-editor-wc/styles.css";
+  import { required, email } from "@updog/data-editor-wc";
+
+  const editor = document.getElementById("editor");
+
+  editor.configure({
+    apiKey: "your-license-key",
+    primaryKey: "id",
+    columns: [
+      { 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"] } },
+    ],
+    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();
+      editor.hide();
+    },
+  });
 
-  const editor = document.querySelector("updog-editor");
+  document.getElementById("open-btn").addEventListener("click", () => editor.show());
+  editor.addEventListener("close", () => editor.hide());
+</script>
+```
 
-  editor.columns = [
-    { id: "name", title: "Name", width: 150 },
-    { id: "email", title: "Email", width: 260 },
-  ];
-  editor.primaryKey = "id";
-  editor.apiKey = "your-api-key";
+## Setting Props
 
-  editor.loadData = async (onChunk) => {
-    const res = await fetch("/api/data");
-    onChunk(await res.json());
-  };
+Two ways to configure the element: HTML attributes for primitives, JS properties for everything else.
 
-  editor.onComplete = (result) => {
-    console.log("Submitted:", result);
-    editor.hide();
-  };
+### HTML attributes
 
-  editor.addEventListener("close", () => editor.hide());
-  document.getElementById("open-btn").addEventListener("click", () => editor.show());
-</script>
+Use for primitive values. The element observes these and re-renders on change.
 
-<button id="open-btn">Open Editor</button>
-<updog-editor></updog-editor>
-```
+| Attribute | Maps to | Type |
+|---|---|---|
+| `api-key` | `apiKey` | string |
+| `primary-key` | `primaryKey` | string |
+| `locale` | `locale` | string |
+| `variant` | `variant` | `"editor"` \| `"uploader"` |
+| `mode` | `mode` | `"modal"` \| `"inline"` |
+| `open` | `open` | boolean (presence = true) |
+| `rtl` | `rtl` | boolean (presence = true) |
+| `readonly` | `readonly` | boolean (presence = true) |
 
-## HTML Attributes
+```html
+<updog-editor api-key="your-key" primary-key="id" variant="uploader" readonly></updog-editor>
+```
 
-Simple values settable directly in HTML:
+### JS properties
 
-| Attribute | Type | Description |
-|---|---|---|
-| `api-key` | string | License key |
-| `primary-key` | string | Row identifier column |
-| `locale` | string | BCP 47 locale tag (default: `"en"`) |
-| `variant` | `"editor"` \| `"uploader"` | UI mode |
-| `mode` | `"modal"` \| `"inline"` | Rendering mode (default: `"modal"`) |
-| `open` | boolean (presence) | Whether the editor modal is open (modal mode only) |
-| `rtl` | boolean (presence) | Right-to-left layout |
-| `readonly` | boolean (presence) | Hide write-oriented UI |
+Everything else — objects, functions, arrays — must be set as a JS property or via `configure()`.
 
-## JS Properties
+```js
+const editor = document.querySelector("updog-editor");
+editor.columns = [...];
+editor.loadData = async (onChunk) => { ... };
+editor.onComplete = (result, actions) => { ... };
+```
 
-Complex values set via JavaScript:
+### `configure(props)`
 
-| Property | Type |
-|---|---|
-| `columns` | `DataEditorColumn[]` |
-| `loadData` | `(onChunk: (rows) => void) => Promise<void>` |
-| `onComplete` | `(result, actions) => void` |
-| `translations` | `DataEditorTranslations` |
-| `importFormats` | `("csv" \| "tsv" \| "xlsx" \| "json" \| "xml")[]` |
-| `exportFormats` | `("csv" \| "tsv" \| "xlsx" \| "json" \| "xml")[]` |
-| `enableDeleteRow` | `"all"` \| `"new"` \| `false` |
-| `enableAddRow` | `boolean` |
-| `localStorage` | `false \| { licenseGrant?: boolean }` |
-| `rowHeight` | `number` (default: 34) |
-| `headerHeight` | `number` (default: 36) |
-
-All properties can also be set in bulk via `configure()`:
+Set multiple properties at once. Useful during setup. Accepts every prop except `onClose`. Property updates are batched — the editor re-renders once per microtask regardless of how many properties you set.
 
 ```js
 editor.configure({
-  columns: [...],
+  apiKey: "your-key",
   primaryKey: "id",
-  loadData: myLoadFn,
+  columns: [...],
+  loadData: async (onChunk) => onChunk(await fetchRows()),
+  onComplete: (result, actions) => { save(result); actions.reset(); },
 });
 ```
 
+## Inline Mode
+
+Render the editor directly in the DOM without a modal overlay:
+
+```html
+<updog-editor mode="inline" api-key="your-key"></updog-editor>
+```
+
+In inline mode, `show()` / `hide()` and the `open` attribute don't apply. The `close` event is not fired.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `apiKey` | `string` | Yes | — | Your Updog license key. Validated on each open. |
+| `columns` | `DataEditorColumn[]` | Yes | — | Column definitions. |
+| `primaryKey` | `string` | Yes | — | Column ID that uniquely identifies each row. |
+| `mode` | `"modal"` \| `"inline"` | No | `"modal"` | Rendering mode. |
+| `open` | `boolean` | Modal only | — | Controlled modal visibility. Equivalent to `show()` / `hide()`. |
+| `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` | No | — | Server-delegated mode: SDK renders, your backend handles queries and mutations. |
+| `chat` | `DataEditorChat` | 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. |
+
 ## Methods
 
 | Method | Description |
 |---|---|
-| `show()` | Opens the editor modal |
-| `hide()` | Closes the editor modal |
-| `configure(props)` | Bulk-set any props |
+| `show()` | Opens the editor modal. Equivalent to setting `open` to `true`. No-op in `mode="inline"`. |
+| `hide()` | Closes the editor modal. Equivalent to setting `open` to `false`. No-op in `mode="inline"`. |
+| `configure(props)` | Bulk-set any props. See [`configure(props)`](#configureprops). |
 
 ## Events
 
-| Event | Description |
-|---|---|
-| `close` | Fired when the user closes the editor from inside (X button, discard). Call `editor.hide()` in response. |
+### `close`
 
-## Angular
+Fires when the user closes the modal (X button or Escape key). Replaces the React `onClose` prop — the WC dispatches a bubbling `CustomEvent` instead. Not fired in `mode="inline"`.
 
-```ts
-// app.module.ts
-@NgModule({ schemas: [CUSTOM_ELEMENTS_SCHEMA] })
+```js
+editor.addEventListener("close", () => editor.hide());
+```
 
-// main.ts
-import "@updog/data-editor-wc";
-import "@updog/data-editor-wc/styles.css";
+## Column Configuration
+
+```js
+import { required, email } from "@updog/data-editor-wc";
+
+editor.columns = [
+  {
+    id: "email",
+    title: "Email",
+    size: 260,
+
+    // One validator, or an array. Each returns `{ level: "error", message }` or null.
+    validate: [required("Email is required"), email("Enter a valid email")],
+
+    // Flag duplicates in this column as errors.
+    unique: true,
+
+    // Revalidate these columns when this one changes.
+    dependentFields: ["confirmEmail"],
+
+    // Cell editor. Default is "text".
+    editor: { type: "select", options: ["US", "UK", "DE"] },
+
+    // Display-only formatting. Does not mutate stored data.
+    formatter: (value) => value.toLowerCase(),
+
+    // Runs when rows are uploaded to the editor. Mutates the stored value.
+    transformer: (value) => String(value).trim(),
+
+    // Sidebar filter control.
+    filter: { type: "select" },
+
+    // Lock cells in this column. `"default"` locks only default-source rows.
+    locked: "default",
+  },
+];
 ```
 
-```html
-<updog-editor api-key="xxx" #editor (close)="onClose()"></updog-editor>
+**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.
+
+```js
+import {
+  required,
+  numeric,
+  email,
+  date,
+  oneOf,
+  endDateAfterStart,
+} from "@updog/data-editor-wc";
+
+editor.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" },
+  },
+];
 ```
 
-```ts
-@ViewChild("editor") editorRef: ElementRef;
-
-ngOnInit() {
-  const el = this.editorRef.nativeElement;
-  el.columns = this.columns;
-  el.primaryKey = "id";
-  el.loadData = this.loadData;
-  el.onComplete = this.handleComplete;
-}
+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"`.
+
+```js
+const mustContainAt = (value) => {
+  if (!value) return null;
+  if (!String(value).includes("@")) return { level: "error", message: "Must contain @" };
+  return null;
+};
+```
+
+## Data Loading
+
+`loadData` is called once when the editor opens. Call `onChunk` one or more times to stream rows. The grid renders each chunk without blocking.
+
+```js
+// Single source
+editor.loadData = async (onChunk) => {
+  for (let page = 0; page < totalPages; page++) {
+    const rows = await fetch(`/api/employees?page=${page}`).then((r) => r.json());
+    onChunk(rows);
+  }
+};
+
+// Multiple sources — each chunk tagged with a source
+editor.loadData = async (onChunk) => {
+  onChunk(await fetchSalesforce(), { source: "Salesforce", done: true });
+  onChunk(await fetchHubSpot(), { source: "HubSpot", deletable: true, done: true });
+};
 ```
 
-## Vue
+`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
+
+`onComplete(result, actions)` fires when the user submits.
 
 ```ts
-import "@updog/data-editor-wc";
-import "@updog/data-editor-wc/styles.css";
+type DataEditorResult = {
+  sources: {
+    sourceId: string;
+    sourceName: string;
+    rows: {
+      row: Record<string, unknown>;
+      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 };
+};
+
+type DataEditorActions = {
+  reset: () => void; // discard changes and reload via loadData
+};
+```
+
+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:
+
+```js
+editor.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();
+};
 ```
 
-```vue
-<template>
-  <updog-editor ref="editor" api-key="xxx" @close="editor.hide()" />
-</template>
+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.
 
-<script setup>
-import { ref, onMounted } from "vue";
+## Import Configuration
 
-const editor = ref();
+The import wizard guides users through uploading a file, mapping columns to your schema, and resolving value mismatches.
 
-onMounted(() => {
-  editor.value.columns = columns;
-  editor.value.primaryKey = "id";
-  editor.value.loadData = loadData;
-  editor.value.onComplete = handleComplete;
-});
-</script>
+### Formats
+
+Supported: `"csv"`, `"tsv"`, `"xlsx"`, `"json"`, `"xml"`.
+
+```js
+editor.importFormats = ["csv", "xlsx"]; // only CSV and XLSX
+editor.exportFormats = [];              // disable export entirely
 ```
 
-## Column Configuration
+### Override column matching
 
 ```js
-editor.columns = [
+editor.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:
+
+```js
+editor.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:
+
+```js
+editor.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.
+
+```js
+editor.remoteSources = [
   {
-    id: "email",
-    title: "Email",
-    width: 260,
-    // Validation
-    validate: (value) => {
-      if (!value) return { level: "error", message: "Required" };
-      return null;
+    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
     },
-    unique: true,
-    // Cell editor type: "text" (default), "date", or "select"
-    editor: { type: "text" },
-    // Visual formatting (display only)
-    formatter: (value) => value.toLowerCase(),
-    // Data transformation on input
-    transformer: (value) => String(value).trim(),
-    // Filter panel configuration
-    filter: { type: "select" },
   },
 ];
 ```
 
-## Inline Mode
+Return a `File` to parse via the standard CSV/XLSX/JSON/XML pipeline, or return structured records to skip parsing.
 
-Render the editor directly in the DOM without a modal overlay:
+## Error Handling
 
-```html
-<updog-editor mode="inline" api-key="xxx"></updog-editor>
+Log SDK-internal errors through `onError`. The SDK recovers gracefully — use this for monitoring, not recovery.
+
+```js
+editor.onError = (error) => {
+  Sentry.captureException(error.originalError ?? error, {
+    tags: { code: error.code, source: error.source },
+  });
+};
 ```
 
-In inline mode, `show()`/`hide()` and the `open` attribute are no-ops. The editor renders in-place immediately.
+Error codes: `PARSE_ERROR`, `RENDER_ERROR`, `TRANSFORM_ERROR`, `VALIDATION_ERROR`, `WORKER_ERROR`, `COMMAND_ERROR`, `OPERATION_ERROR`.
 
 ## Styling
 
-`<updog-editor>` renders in **light DOM by design** — no Shadow DOM isolation. This is intentional: you can override any editor style with your own CSS targeting descendants of `updog-editor`.
+`<updog-editor>` renders in **light DOM by design** — no Shadow DOM isolation. This is intentional: you can override any editor style with CSS targeting descendants of `updog-editor`.
 
 ### CSS variables
 
-The editor reads colors, spacing, and typography from CSS custom properties. Override them in your page's CSS:
+The editor reads colors from CSS custom properties. Override them on `:root` or on the element itself:
 
 ```css
 updog-editor {
-  --updog-color-primary: #0070f3;
-  --updog-font-family: "Inter", system-ui, sans-serif;
-  --updog-radius-md: 8px;
+  --updog-grid-cell-bg-idle: #ffffff;
+  --updog-grid-header-bg-idle: #f8f9fa;
 }
 ```
 
+See the [Styling reference](https://docs.updog.tech/styling/) for the full variable list.
+
 ### Class names
 
-Internal elements use BEM-style class names prefixed with `updog__`. Target them directly for deep customization:
+Internal elements use BEM-style class names prefixed with `updog__`. Target them for deep customization:
 
 ```css
 updog-editor .updog__button--primary { background: purple; }
@@ -228,9 +454,19 @@ body *:not(updog-editor *) { /* your global rules */ }
 ## Notes
 
 - Fonts are inherited from your page. The editor uses `var(--updog-font-family)` which defaults to system fonts.
-- In modal mode, the editor portals to `document.body` as a full-screen overlay. In inline mode, it renders in-place with no overlay.
+- In modal mode, the editor portals to `document.body` as a full-screen overlay. In inline mode, it renders in place with no overlay.
 - Multiple `<updog-editor>` instances on the same page are fully independent.
 
+## Using React?
+
+Use the first-class React SDK instead:
+
+```bash
+npm install @updog/data-editor
+```
+
+See [@updog/data-editor](https://www.npmjs.com/package/@updog/data-editor).
+
 ## 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 bundled with this package are listed in `THIRD_PARTY_NOTICES.txt`.

package/index.d.ts

@@ -516,17 +516,48 @@ type ExpandPluralKeys<T> = T extends Record<string, unknown>
  */
 type DataEditorTranslations = DeepPartial<ExpandPluralKeys<typeof export_default>>;
 
+/**
+ * Categories of internal errors surfaced through the `onError` callback.
+ *
+ * - `PARSE_ERROR` — file parsing failed (corrupt CSV, invalid XLSX, etc.).
+ * - `RENDER_ERROR` — component render failed (caught by error boundary).
+ * - `TRANSFORM_ERROR` — data transformation failed (column transform, value mapping).
+ * - `VALIDATION_ERROR` — validation execution failed (validator threw instead of returning).
+ * - `WORKER_ERROR` — Web Worker failed (filter worker, chat transform worker).
+ * - `COMMAND_ERROR` — undo/redo command failed.
+ * - `OPERATION_ERROR` — general operation failed (bulk mutations, imports).
+ */
 type UpdogErrorCode = "PARSE_ERROR" | "RENDER_ERROR" | "TRANSFORM_ERROR" | "VALIDATION_ERROR" | "WORKER_ERROR" | "COMMAND_ERROR" | "OPERATION_ERROR";
+/**
+ * An internal error caught by the SDK and passed to `onError`. The SDK
+ * recovers gracefully where possible — `onError` is for your logging and
+ * monitoring (Sentry, Datadog, etc.).
+ *
+ * @example
+ * ```ts
+ * onError={(error) => {
+ *   Sentry.captureException(error.originalError ?? error, {
+ *     tags: { code: error.code, source: error.source },
+ *   });
+ * }}
+ * ```
+ */
 type UpdogError = {
+    /** The error category. */
     code: UpdogErrorCode;
+    /** Human-readable description. */
     message: string;
+    /** Module or subsystem that raised the error. */
     source: string;
+    /** The underlying thrown value, when available. */
     originalError?: unknown;
 };
 
 /**
  * Base row shape. Each key is a column ID, each value is the cell data.
- * Extend this with your own type 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
@@ -535,7 +566,9 @@ type UpdogError = {
  * ```
  */
 type DataEditorRow = Record<string, unknown>;
+/** Sort direction. */
 type SortDirection = "asc" | "desc";
+/** Current sort state. `null` means no active sort. */
 type SortState = {
     columnId: string;
     direction: SortDirection;
@@ -565,6 +598,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;
@@ -578,37 +619,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;
 };
 
@@ -627,8 +736,13 @@ type ValidationError = {
  * 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.
@@ -712,41 +826,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;
@@ -1146,9 +1281,12 @@ type DataEditorServer<TRow extends DataEditorRow = DataEditorRow, TFilters = Rec
     scrollSensitivity?: number;
 };
 
-/** 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;
 };
 /**
@@ -1208,31 +1346,55 @@ 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;
-/** 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
@@ -1256,7 +1418,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>[]>;
 };
 /**
@@ -1271,8 +1436,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;
     /**
@@ -1326,37 +1492,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>>;
@@ -1377,30 +1584,63 @@ 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;
 };
 /** 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;
 };
 /**
@@ -1410,9 +1650,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-wc",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Web Component wrapper for @updog/data-editor. Framework-agnostic, zero dependencies.",
   "author": "Mikhail Kutateladze <admin@updog.tech>",
   "homepage": "https://updog.tech",