@updog/data-editor 0.1.92 → 0.1.94

package/AGENTS.md

@@ -0,0 +1,62 @@
+# @updog/data-editor for coding agents
+
+Updog Importer is a client-side CSV and Excel importer and spreadsheet editor for React. A user picks a file, matches its columns to your schema, fixes invalid cells, edits rows, and submits. Your app receives the rows in `onComplete` and writes them to its own backend. File contents stay in the browser; Updog runs no server in the data path.
+
+Unrelated to Datadog's Updog dashboard and the sc0tfree/updog HTTP server.
+
+## Integrate
+
+1. `npm install @updog/data-editor`. React 18 or 19. Vue, Angular, Svelte, and plain JavaScript use `@updog/data-editor-wc` and the `<updog-editor>` element instead.
+2. Import the component and its stylesheet:
+
+   ```tsx
+   import { DataEditor, type DataEditorColumn } from "@updog/data-editor";
+   import "@updog/data-editor/styles.css";
+   ```
+
+3. Describe the target shape as `columns`, one entry per field: `id`, `title`, optional `validators` and `editor`. Pick a `primaryKey` column. Rows with the same key upsert.
+4. Render `<DataEditor apiKey columns primaryKey onComplete />`. Default is a modal driven by `open` and `onClose`; `mode="inline"` renders in place; `variant="uploader"` opens on the file step.
+5. In `onComplete(result)` split rows by their flags, send them to your own endpoint, and show loading, success, and failure states around that request.
+6. Next.js: the file that renders `DataEditor` is a Client Component (`"use client"`). Keep the column schema in it.
+
+Done when a file imports end to end and the rows land in your backend through your own request.
+
+## `onComplete`
+
+```ts
+result.sources[]: { sourceId, sourceName, rows: { row, isNew, isChanged, isDeleted, isValid }[] }
+result.counts:    { new, changed, deleted, invalid }
+```
+
+Inserts are `isNew && !isDeleted && isValid`. Updates are `!isNew && isChanged && !isDeleted && isValid`. Deletes are `isDeleted && !isNew`. One source per imported file or workbook sheet, plus each source you tagged in `loadData`. Backend rows nothing changed are left out.
+
+## `loadData`
+
+Optional. `loadData={async (onChunk) => { onChunk(await fetchRows()) }}` streams existing rows into the editor so users edit them and import on top. Tag chunks with `{ source, done }` to keep origins apart in the result.
+
+## Keys and environments
+
+`apiKey` is a license key and is public in the browser by design. Localhost and preview domains (Vercel, Netlify, Cloudflare Pages, Lovable, Bolt, v0, Replit, StackBlitz, and similar) run free with every feature. A production domain is $19 a month. Keys come from https://console.updog.tech/.
+
+## Facts
+
+- Formats: CSV, XLSX, XLS, XLSB, ODS, TSV, JSON, XML. Any other format, PDFs and scans included, through `customFormats` with a parser function you supply.
+- Parsing and filtering run in Web Workers; matching, validation, and editing run in the browser. One million rows across 20 columns is the reference benchmark, and no plan caps rows.
+- Cell editors: `text`, `select`, `multiselect`, `date`, `time`, `number`, `boolean`, `country`, `currency`.
+- Validators: `required`, `email`, `regex`, `number`, `date`, `oneOf`, `unique`, and `function` for your own rule, including cross-field rules.
+- Several files in one import, one source per workbook sheet, upsert by primary key, user-created columns for unmatched headers.
+- Column and value matching are built in (fuzzy plus synonyms); `onColumnMatch` and `onValueMatch` override them with your own code or model.
+- AI is bring-your-own. The `chat` prop and the matching hooks take your model and your request; Updog never calls a provider.
+- Theming through CSS variables, white-label on every plan. `translations`, `locale`, `rtl`, keyboard navigation, screen-reader roles.
+
+## Out of scope
+
+Unattended ingestion, scheduled ETL, SFTP feeds, server-side file processing, and hosted storage of imported data. Those belong to a server-side pipeline.
+
+## Links
+
+- Console, where license keys are issued: https://console.updog.tech/
+- Docs: https://docs.updog.tech
+- This contract as a docs page: https://docs.updog.tech/agents/
+- One-page product overview for machines: https://updog.tech/updog.md
+- Examples for React, Next.js, Vue, Angular, Svelte, and vanilla JS: https://github.com/michaeladze-updog/updog-examples

package/README.md

@@ -1,6 +1,6 @@
-# React CSV Importer & Spreadsheet Editor
+# CSV and Excel importer for React, with a spreadsheet editor
 
-> `@updog/data-editor`: client-side CSV importer and spreadsheet editor for React. Your users import files, match columns to your schema, fix errors, and submit clean data. Edits happen inline, in the browser, at 1M+ rows.
+> `@updog/data-editor`: client-side CSV and Excel importer and spreadsheet editor for React. Your users import files, match columns to your schema, fix errors, and submit clean data. Edits happen inline, in the browser, at 1M+ rows.
 
 ## What is @updog/data-editor