@updog/data-editor-wc 0.1.4 → 0.1.6

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,29 @@ type Filters = {
     }>;
 };
 
+/**
+ * A single operation the LLM wants to apply to rows in the current filtered view.
+ *
+ * - `edit` — `fn` is `(r, ctx) => void`. Mutates `r` in place. Changed fields
+ *   become column deltas. Rows with no changes are no-ops.
+ * - `delete` — `fn` is `(r, ctx) => boolean`. Truthy means "flag this row for
+ *   deletion". Soft delete via `DeleteRowCommand`.
+ */
+type ChatOp = {
+    action: "edit";
+    fn: string;
+} | {
+    action: "delete";
+    fn: string;
+};
+/**
+ * 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`.
+ * - `ops` — array of per-row operations (edits and/or deletes) to apply in order.
+ */
 type ChatResponseChunk<TRow extends DataEditorRow = DataEditorRow> = {
     type: "status";
     content: string;
@@ -575,40 +631,108 @@ type ChatResponseChunk<TRow extends DataEditorRow = DataEditorRow> = {
     type: "rows";
     content: TRow[];
 } | {
-    type: "transform";
-    content: string;
+    type: "ops";
+    content: ChatOp[];
 };
+/** 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: "ops", content: res.ops };
+ *     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 +751,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 +841,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 +1296,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 +1361,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 +1433,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 +1451,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 +1507,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 +1599,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 +1665,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;
 };
 /**