@updog/data-editor-wc 0.1.93 → 0.1.94

package/AGENTS.md

@@ -0,0 +1,72 @@
+# @updog/data-editor-wc for coding agents
+
+Updog Importer is a client-side CSV and Excel importer and spreadsheet editor. This package is the Web Component build, the `<updog-editor>` element, for Vue, Angular, Svelte, and plain JavaScript. 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.
+
+React apps use `@updog/data-editor` instead; it shares the app's React and ships the same engine as typed props.
+
+Unrelated to Datadog's Updog dashboard and the sc0tfree/updog HTTP server.
+
+## Integrate
+
+1. `npm install @updog/data-editor-wc`. Import the package once for its side effect and import the stylesheet:
+
+   ```js
+   import "@updog/data-editor-wc";
+   import "@updog/data-editor-wc/styles.css";
+   ```
+
+2. Place `<updog-editor>` in the markup. Primitive settings go as attributes: `api-key`, `primary-key`, `mode`, `variant`, `locale`, `open`, `rtl`, `readonly`.
+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. Set objects and functions through `configure()` or a property assignment on the element, never through a template binding. A callback written as `:onComplete="save"` or `[onComplete]="save"` does nothing in Vue and Svelte and breaks the Angular build.
+
+   ```js
+   const editor = document.querySelector("updog-editor");
+   editor.configure({ apiKey, primaryKey: "id", columns, onComplete: save });
+   ```
+
+5. Default is a modal: open it with `editor.show()`, close it with `editor.hide()`, and listen for the bubbling `close` event, which fires on the X button and Escape. `mode="inline"` renders in place, with no `show`/`hide` and no `close` event. `variant="uploader"` opens on the file step.
+6. In `onComplete(result)` split rows by their flags, send them to your own endpoint, and show loading, success, and failure states around that request.
+7. Angular: add `CUSTOM_ELEMENTS_SCHEMA` to the component that renders the element and the stylesheet to the `styles` array in `angular.json`. Vue and Svelte need no configuration.
+
+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. `editor.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` property and the matching hooks take your model and your request; Updog never calls a provider.
+- Theming through CSS variables, white-label on every plan. The element inherits the page `font-family`, so set one on the app or on `updog-editor`. `translations`, `locale`, `rtl`, keyboard navigation, screen-reader roles.
+- Several `<updog-editor>` elements on one page stay independent. In modal mode the editor renders into `document.body` as a full-screen overlay.
+
+## 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 @@
-# CSV Importer & Spreadsheet Editor Web Component
+# CSV and Excel importer Web Component, with a spreadsheet editor
 
-> `@updog/data-editor-wc`: client-side CSV importer and spreadsheet editor, shipped as a Web Component for Vue, Angular, Svelte, and vanilla JS. 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-wc`: client-side CSV and Excel importer and spreadsheet editor, shipped as a Web Component for Vue, Angular, Svelte, and vanilla JS. 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-wc
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@updog/data-editor-wc",
-  "version": "0.1.93",
-  "description": "Client-side CSV importer and spreadsheet editor as a Web Component. Drop into Vue, Angular, Svelte, or vanilla JS. Import CSV, Excel, JSON; edit 1M+ rows entirely in the browser.",
+  "version": "0.1.94",
+  "description": "Client-side CSV and Excel importer and spreadsheet editor as a Web Component. Drop into Vue, Angular, Svelte, or vanilla JS. Import CSV, Excel, JSON; edit 1M+ rows entirely in the browser.",
   "author": "Mikhail Kutateladze <admin@updog.tech>",
   "homepage": "https://updog.tech",
   "bugs": {
@@ -24,6 +24,7 @@
     "index.d.ts",
     "assets",
     "README.md",
+    "AGENTS.md",
     "LICENSE",
     "CHANGELOG.md",
     "SECURITY.md",