@updog/data-editor-wc 0.1.93 → 0.1.95

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/index.d.ts

@@ -418,6 +418,7 @@ declare var export_default = {
       invalidNumber: "Invalid number",
       invalidOption: "Invalid option",
       invalidTime: "Invalid time",
+      invalidUrl: "Invalid URL",
       outOfRange: "Out of range",
       required: "This field is required",
       structuralMismatch: "This might be in the wrong column.",
@@ -670,6 +671,23 @@ type CellValidator = (value: unknown, row: DataEditorRow) => ValidationError | n
 type TextEditorCell = {
     type: "text";
 };
+/**
+ * Email cell. A plain text input; the column is checked against
+ * `{ type: "email" }` even when it declares no validator. On the way in,
+ * surrounding spaces are cut and the domain is lower-cased.
+ */
+type EmailEditorCell = {
+    type: "email";
+};
+/**
+ * Web address cell. A plain text input; the column is checked against
+ * `{ type: "url" }` even when it declares no validator. On the way in,
+ * surrounding spaces are cut and a bare host such as `acme.com` becomes
+ * `https://acme.com`.
+ */
+type UrlEditorCell = {
+    type: "url";
+};
 /** Date picker cell. Bounds come from the column's `{ type: "date" }` validator. */
 type DateEditorCell = {
     type: "date";
@@ -768,6 +786,8 @@ type NumberEditorCell = {
  * Controls how a cell is edited.
  *
  * - `"text"` — plain text input (default).
+ * - `"email"` — plain text input; the column is checked against `{ type: "email" }`, spaces cut and the domain lower-cased on the way in.
+ * - `"url"` — plain text input; the column is checked against `{ type: "url" }`, a bare host such as `acme.com` becomes `https://acme.com` on the way in.
  * - `"date"` — date picker; the calendar honours the column's date validator bounds.
  * - `"time"` — plain text input for a time of day; the column is checked against `{ type: "time" }`.
  * - `"select"` — dropdown with a fixed list of options.
@@ -777,7 +797,7 @@ type NumberEditorCell = {
  * - `"number"` — number input with locale-aware formatting.
  * - `"boolean"` — stores a real `true`/`false`; reads yes/no, 1/0, on/off and Excel's localized TRUE/FALSE.
  */
-type CellEditor = TextEditorCell | DateEditorCell | TimeEditorCell | SelectEditorCell | MultiSelectEditorCell | CountryEditorCell | CurrencyEditorCell | NumberEditorCell | BooleanEditorCell;
+type CellEditor = TextEditorCell | EmailEditorCell | UrlEditorCell | DateEditorCell | TimeEditorCell | SelectEditorCell | MultiSelectEditorCell | CountryEditorCell | CurrencyEditorCell | NumberEditorCell | BooleanEditorCell;
 /** Dropdown filter shown in the sidebar Filters panel. */
 type SelectColumnFilter = {
     type: "select";
@@ -940,6 +960,11 @@ type BuiltInValidator = {
 } | {
     type: "email";
     message?: string;
+}
+/** The cell holds an `http` or `https` address with a dotted host. Implicit on every url column. */
+ | {
+    type: "url";
+    message?: string;
 } | {
     type: "date";
     min?: string;