@updog/data-editor-wc 0.1.3 → 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`.