wysiwygido 0.3.0 → 1.0.0

package/CHANGELOG.md

@@ -1,6 +1,26 @@
 # Changelog
 
-All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/). Until 1.0, minor versions may contain breaking changes; they are listed under "Changed" or "Removed".
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/). Before 1.0.0 minor versions could contain breaking changes. From 1.0.0 on, only a major version may break the public API (see "Stability and versioning" in the README); changes are listed under "Changed" or "Removed".
+
+## 1.0.0
+
+The first stable release. The public API (the exported names, the plugin contract, the stored document formats and the `--wy-*` colour variables) now follows semantic versioning, and tests guard it. New since 0.4.0: the data table and its stand-alone version.
+
+- Added: **data table** (`DataTable` plugin): a block of records with typed columns (text, number, currency, date, yes/no, choice), search, column filters, multi-column sort, paging, cell editing, tick boxes, footer totals, custom toolbar buttons and row actions, right-click and heading menus, keyboard navigation and undo. Export to CSV, Excel (.xlsx, written without a library) and PDF; import from CSV and Excel; convert to and from a regular table; written to Word and Markdown as a table.
+- Added: the data table on its own, with no editor: `createDataTable` and `<wysiwyg-data-table>` from the new entry point `wysiwygido/data-table` (it imports no package, checked by the build), with its own undo, themes, change events and right-click menu.
+- Added: the data table's stored format is versioned (`v`). A table saved by a newer version is shown but not edited, and is kept exactly as it was.
+- Added: rows of a data table may be objects by column key; `createFetchDataSource` and a `GET /api/orders` route in the example server.
+- Added: tests that guard the public API (`tests/api-surface.json`) and the stored formats (`tests/formats.test.ts`); a "Stability and versioning" section in the README.
+- Changed (data table names, before they were released): types are `DataTable*` (`DataTableOptions` is the plugin's options, `DataTableSettings` the table's own), `formatDataTableCell`, `queryDataTable`; `DataTableContext.editor` is `null` when the table stands alone.
+- Added: data table extras: formula columns (own safe parser), highlight rules and data bars (also written to .xlsx and PDF), saved views, openable row details (`DataTable({ detail })`), column resizing by mouse or keyboard, row reordering by drag or Alt+Up/Down, and charts from the rows on screen.
+- Fixed: a data table's heading did not stay in view while the table scrolled.
+- Added: data table at scale: group by up to three columns with folding and per-group totals, virtual scrolling for long tables without paging, rows loaded page by page from a data source (`DataTable({ sources, onEdit })`, `options.source`), and import of Excel (.xlsx) files read without a library (`dataTableFromFile`).
+- Added: data table (`DataTable` plugin): a block of records with typed columns, search, column filters, multi-column sort, paging, cell editing, selection, footer totals, custom toolbar buttons and row actions, right-click and heading menus, and keyboard navigation. Export to CSV, Excel (.xlsx, written without a library) and PDF; import from CSV; convert to and from a regular table. Written to Word and Markdown as a table.
+
+## 0.4.0
+
+- Added: colour themes (`Themes` plugin): light, dark, sepia, ocean, forest, rose, solarized, midnight, nord and high-contrast, a View → Themes menu, `colorTheme` / `cycleColorTheme` / `clearColorTheme` commands, your own theme from a handful of colours, and `<wysiwyg-editor theme="sepia">`.
+- Added: the editor emits a `theme` event when Dark Mode or Switch Background changes.
 
 ## 0.3.0
 

package/README.md

@@ -11,7 +11,7 @@ Everything is opt-in plugins; the core is small. Install from npm (the first rel
 
 ```sh
 pnpm install
-pnpm dev        # the demo gallery at http://localhost:5173 (39 examples)
+pnpm dev        # the demo gallery at http://localhost:5173 (49 examples)
 pnpm test       # 196 tests (unit, accessibility with axe-core, server integration)
 pnpm build      # library in dist/
 pnpm server     # reference backend on :8787
@@ -332,6 +332,17 @@ A provider is any `(req) => Promise<string> | AsyncIterable<string>`; stream chu
 Model output is parsed as Markdown with raw HTML disabled, so it cannot inject markup. What the endpoint must return is described in
 [Endpoints your app provides](#endpoints-your-app-provides).
 
+## Stability and versioning
+
+The package follows [semantic versioning](https://semver.org/). Since 1.0.0 only a major release may break the public API (before it, minor releases could). What counts as the public API:
+
+- **Everything exported** from `wysiwygido` and its entry points (`/data-table`, `/docx`, `/pdf`, `/epub`, `/collab`, `/react`, `/vue`, `/svelte`, `/adapter`). The list of names is a test (`tests/api-surface.json`): removing or renaming one fails the build.
+- **The plugin contract**: the `EditorPlugin` hooks, `editor.registerCommand` / `execute` / `on`, command names, and the events the editor emits.
+- **What is stored in documents**: the HTML attributes (`data-data-table`, `data-chart`, `data-cover-page`…) and the JSON they hold. Each stored format is read by every later version; the data table's format carries a version number (`v`), and a table saved by a *newer* version than the one reading it is shown, kept untouched and not editable, so an older copy can never lose data. Golden files for these formats are tests (`tests/formats.test.ts`).
+- **The CSS custom properties** (`--wy-*`) used for theming.
+
+Not part of it: the `wy-*` class names and the exact DOM the editor builds, internal modules not exported from an entry point, and the exact wording of interface text and error messages. `defaultPlugins` may gain plugins in a minor release. Anything deprecated keeps working for at least one minor release and is listed in the changelog. Supported browsers are the current versions of Chrome, Edge, Firefox and Safari (all four are tested); the pure functions (`dataTableToCSV`, `dataTableToXlsx`, `queryDataTable`…) also run on Node 18+.
+
 ## Endpoints your app provides
 
 The editor calls your code at a few points. Each contract below is exercised by `server/examples/api.ts` (`pnpm server:examples`, port 8788),
@@ -347,6 +358,7 @@ Try it with the AI demo: `…/demo/ai.html?endpoint=http://127.0.0.1:8788/api/ai
 | `SpellCheck({ provider: createLanguageToolProvider(url) })` | `POST` form `text=…&language=…` | LanguageTool's JSON: `{ matches: [{ offset, length, message, replacements: [{ value }], rule: { id, issueType } }] }` |
 | `SpellCheck({ provider })` (your own) | `{ text, lang, signal }` | `[{ offset, length, message, replacements?: string[], rule?, kind?: 'spelling' \| 'grammar' \| 'style' }]`, offsets in characters of the text sent |
 | `Mentions({ search })` | the typed text | `[{ id, label }]` (may be a Promise) |
+| `DataTable({ sources: { orders: createFetchDataSource(url) } })` | `GET url?page&pageSize&search&sort&filters` (`sort` and `filters` are JSON) | JSON `{ rows, total, totals? }`: one page, the number of matching rows, and footer totals over all of them. Try it with the data table demo: `…/demo/data-table.html?endpoint=http://127.0.0.1:8788/api/orders` |
 | `PdfEpub`, `Embeds`, `Offline` | nothing to your server | they run in the browser |
 
 **What an AI endpoint returns per `action`** (the full instruction is in `instruction`, pass it to the model as the system prompt and `text` as the user message). The reply is the text itself: no "Here is…", no quotes, no JSON wrapper.
@@ -469,6 +481,121 @@ tOGGLE cASE (`Ctrl/⌘+Alt+G`), snake_case (`Ctrl/⌘+Alt+S`), camelCase (`Ctrl/
 in the right-click menu. Upper/lower/toggle/title/sentence keep every bold, link and colour in place; snake/camel/kebab join the words into one
 identifier that takes the formatting of its first letter. From code: `editor.execute('changeCase', 'snake')` or the pure `convertCase(text, 'camel')`.
 
+## Data table
+
+A table of records that people can search, sort, filter, page through, edit and export, in the middle of a document. It is a separate block from the ordinary table: the rows are stored as data, so sorting or filtering changes only what is shown, never the document.
+
+```ts
+import { createEditor, defaultPlugins, DataTable } from 'wysiwygido';
+
+const editor = createEditor({
+  element,
+  plugins: [...defaultPlugins, DataTable({
+    buttons: [{ id: 'ship', label: 'Ship', needsSelection: true, onClick: ({ selected }) => ship(selected) }],
+    rowActions: [{ label: 'View', onClick: (row, index) => open(row.id) }],
+  })],
+});
+
+editor.execute('insertDataTable', {
+  columns: [{ key: 'name', title: 'Product', type: 'text' }, { key: 'price', title: 'Price', type: 'currency', currency: 'USD', total: 'sum' }],
+  rows: [['Tea', 4.5], ['Cake', 6]],
+  options: { title: 'Menu', pageSize: 25, filters: true, selectable: true },
+});
+```
+
+- **Columns** are `text`, `number`, `currency`, `date`, `boolean` or `select`, each with its own editor, format, alignment and an optional footer total (`sum`, `avg`, `count`, `min`, `max`). Add, edit, move, hide and delete them from the heading menu.
+- **Search and filter:** a search box, and an optional filter row. Text filters match "contains"; number and date filters take `>5`, `>=5`, `<5`, `5..10`, `=5`, `!=5`.
+- **Sort** by clicking a heading (Shift+click for a second column). Empty values always come last.
+- **Paging** with 10, 25, 50, 100 or all rows per page. Nothing is drawn beyond the page. With paging off, a table of more than about 200 rows draws only the rows in view and scrolls (20,000 rows stay smooth).
+- **Group by** one to three columns from the heading menu (or `options.groupBy`). Each group has a heading with its row count and the footer totals of its columns, and can be folded. A page that starts inside a group repeats the heading.
+- **Editing:** double-click or press Enter on a cell, Enter or Tab to save and move, Esc to cancel. Arrow keys move between cells. Every edit is one undo step.
+- **Buttons:** your own toolbar buttons (`needsSelection` keeps one disabled until rows are ticked) and a button on every row.
+- **Export:** CSV, Excel (.xlsx) and PDF from the Export menu, using what is shown (filtered, sorted, visible columns), or only the ticked rows. The .xlsx file is written by the editor itself, with no library: a bold frozen header, filter buttons, number, currency and date formats. CSV text that starts with `=`, `+`, `-` or `@` is quoted so a spreadsheet does not run it. PDF uses the print dialog (choose "Save as PDF"), so every script and font works.
+- **Convert both ways:** `tableToDataTable` turns the table at the cursor into a data table (the first row names the columns, types are guessed from the values), and `dataTableToTable` turns the selected data table back into an ordinary table. Also in the right-click menu.
+- **Look:** follows the colour theme. Options: striped rows, cell borders, row height, a fixed height with a sticky heading. The block is exported to Word as a real table, to Markdown as a table, and to HTML with a plain table inside.
+- **Import:** `editor.execute('dataTableFromFile')` opens a file picker for CSV, TSV or Excel (.xlsx); `dataTableFromCSV(text)` and `dataTableFromExcel(file)` take the content directly. The first row names the columns and each column's type is guessed (dates stay dates). The .xlsx reader is also written here, with no library, and reads the first visible sheet.
+- **Formula columns:** give a column a formula over the other columns of the same row: `[Price] * [Qty]`, `IF([Stock] < 5, "Reorder", "OK")`, `ROUND([Total] / [Count], 2)`. The results are calculated, never stored, and can be searched, filtered, sorted, totalled and exported like any column. Operators `+ - * / % ^ &` and comparisons; functions `IF AND OR NOT ROUND FLOOR CEIL ABS SQRT POWER MOD MIN MAX SUM AVERAGE COUNT LEN UPPER LOWER TRIM LEFT RIGHT CONCAT CONTAINS ISEMPTY TODAY YEAR MONTH DAY DAYS`. Errors show as `#DIV/0!`, `#REF!`, `#CYCLE!` and so on. The formula language is its own small parser (no `eval`): it can only calculate from its row.
+- **Highlight rules and bars:** Options → Highlight rules colours cells (or whole rows) that match a condition written like a filter box (`>100`, `5..10`, `Overdue`, `empty`) in red, green, amber, blue, gray or bold, using the theme's colours. The colours also go into .xlsx and PDF files. A column can draw a bar in each cell, in proportion to the largest value.
+- **Saved views:** Views → Save current view keeps the search, filters, sort, grouping, hidden columns and rows per page under a name; readers can apply a view too (they get the search, filters and sort).
+- **Details:** `options.detail` adds an open button to each row. By default it lists every field, including hidden columns; `DataTable({ detail: (row) => element })` shows what you build (it may be async).
+- **Resize and reorder:** drag a heading's right edge (or focus it and use the arrow keys; double-click resets). With `options.reorder`, drag the ⠿ handle or press Alt+Up / Alt+Down to move a row, while no search, sort or filter makes the order on screen different from the stored one.
+- **Charts:** Options → Chart of these rows makes a bar, line or pie chart (the Charts plugin) from the rows on screen, right after the table.
+- **Rows from a server:** set `options.source` to a name and give the plugin a function for it. The table then asks for one page at a time and stores no rows in the document.
+
+```ts
+DataTable({
+  sources: {
+    orders: createFetchDataSource('/api/orders'),      // GET /api/orders?page=0&pageSize=25&search=…&sort=[…]&filters={…} -> { rows, total, totals }
+    // or write your own: async ({ page, pageSize, search, filters, sort }) => ({ rows, total, totals: { amount } })   (rows as arrays or { columnKey: value })
+  },
+  onEdit: async ({ key, value, row }) => api.patch(row.id, { [key]: value }),      // optional: without it the table is read-only
+});
+editor.execute('insertDataTable', { columns: [...], rows: [], options: { source: 'orders', pageSize: 25, filters: true } });
+```
+
+  Search is sent after a short pause, only the newest answer is shown, a failure shows its message with a "Try again" button, and Export asks the source for every matching row. Ticked rows are those on the current page. Groups show the rows of the current page.
+
+The pure parts (`dataTableToCSV`, `dataTableToXlsx`, `dataTableToPrintHTML`, `queryDataTable`, `cleanDataTable`, `dataTableWithFormulas`, `parseXlsx`) are exported too, so a server can build the same files.
+
+### Without the editor
+
+The same table works on its own: no editor, no ProseMirror. Import `wysiwygido/data-table` (a small entry point that pulls in nothing else; the build checks that) and the stylesheet.
+
+```ts
+import { createDataTable } from 'wysiwygido/data-table';
+import 'wysiwygido/style.css';
+
+const app = createDataTable({
+  element: document.querySelector('#grid')!,
+  table: { columns: [{ key: 'name', title: 'Name' }, { key: 'qty', title: 'Qty', type: 'number', total: 'sum' }], rows: [{ name: 'Tea', qty: 3 }], options: { pageSize: 25, filters: true } },
+  theme: 'nord',                       // 'light' | 'dark' | 'auto' | a theme name | a theme object
+  onChange: (table) => save(table),    // after every edit, new row, resized column…
+  buttons: [{ id: 'ship', label: 'Ship', needsSelection: true, onClick: ({ selected }) => ship(selected) }],
+  sources: { orders: createFetchDataSource('/api/orders') },   // for tables with options.source
+});
+
+app.getRows();  app.visibleRows();  app.selectedRows();
+app.undo();  app.redo();             // its own history (Ctrl/⌘+Z and Ctrl+Y work too)
+app.setTheme('dark');  app.setReadOnly(true);  app.setTable(newTable);
+app.export('xlsx');  app.download('csv');
+app.destroy();
+```
+
+Rows can be arrays in column order or objects by column key (objects are easier when some columns are calculated). Everything above (search, filters, sort, paging, groups, formulas, highlight rules, saved views, details, resizing, reordering, export, loading from a server) works the same way, and the table has its own right-click menu. As a custom element:
+
+```html
+<script type="module">import { defineDataTableElement } from 'wysiwygido/data-table'; defineDataTableElement();</script>
+<wysiwyg-data-table theme="nord" readonly>
+  <script type="application/json">{ "columns": [{ "title": "Language" }, { "title": "Year", "type": "number" }], "rows": [["C", 1972], ["TypeScript", 2012]] }</script>
+</wysiwyg-data-table>
+```
+
+Events `table-ready` and `table-change` (`detail.table`); the element's `table` property sets or reads the table.
+
+## Themes
+
+Ten colour themes ship with the editor: `light`, `dark`, `sepia`, `ocean`, `forest`, `rose`, `solarized`, `midnight`, `nord` and `high-contrast`. A theme restyles the toolbar, ribbon, panels and the paper, and only inside the editor.
+
+```ts
+import { createEditor, defaultPlugins, Themes } from 'wysiwygido';
+
+createEditor({ element, plugins: [...defaultPlugins, Themes({ initial: 'sepia' })] });
+editor.execute('colorTheme', 'midnight');
+editor.execute('cycleColorTheme');
+editor.execute('clearColorTheme'); // back to the stock look
+```
+
+Pick one from **View → Themes** in the ribbon, or use `<wysiwyg-editor theme="nord">`. Dark Mode on its own returns to the stock look.
+
+Your own theme is a handful of colours; hover, borders, selection and the rest are derived from them:
+
+```ts
+Themes({ extra: [{ name: 'brand', label: 'Brand', palette: { mode: 'light', bg: '#fff8f0', surface: '#ffeede', fg: '#2a1a10',
+  muted: '#7a5a44', border: '#f0d6bf', accent: '#e8590c', workspace: '#f0d2b8', pageBg: '#fff', pageFg: '#2a1a10' } }] });
+```
+
+`editor.extensions.themes` gives `list()`, `current()`, `register(theme)`, `apply(name)` and `clear()`. A theme can also set any `--wy-*` variable through `vars`.
+
 ## Cover page
 
 `Cover` (in `defaultPlugins`) adds a cover page: one picture that fills the whole first page, edge to edge, with the text starting on page 2. Use

package/dist/adapter.js

@@ -1,4 +1,4 @@
-import { t as createEditor } from "./src-CW6adV6q.js";
+import { t as createEditor } from "./src-ByAIGOkX.js";
 //#region src/adapter.ts
 /**
 * Framework-neutral binding for anything that needs a "value in, value out" control: Angular's `ControlValueAccessor`, Svelte, Solid,

package/dist/collab.js

@@ -1,4 +1,4 @@
-import { n as avatar } from "./dialog-Dl0WPFKl.js";
+import { n as avatar } from "./dialog-DVjlHRqv.js";
 import { keymap } from "prosemirror-keymap";
 import { Plugin } from "prosemirror-state";
 import { redoCommand, relativePositionToAbsolutePosition, undoCommand, yCursorPlugin, ySyncPlugin, ySyncPluginKey, yUndoPlugin, yUndoPluginKey } from "y-prosemirror";