apexgrid-skill 1.0.0 → 2.1.0

package/references/state-and-features.md

@@ -0,0 +1,204 @@
+# State, Localization & Interaction Features (3.1+)
+
+> Everything here landed in **apex-grid 3.1 – 3.3** on top of the 3.0 API. The setup rules from `SKILL.md` (register + bounded host height, no theme import) still apply. Row pinning / reordering, undo-redo, and validators are all **opt-in** via a config object — off by default.
+
+## Row pinning — sticky top / bottom bands
+
+Lift rows out of the scrolling body into sticky top / bottom bands. Identity is **by reference**, so pass the same object held in `grid.data`.
+
+```ts
+grid.rowPinning = { enabled: true };            // GridRowPinningConfiguration
+grid.pinRow(grid.data[0], 'top');               // 'top' | 'bottom' (default 'top')
+grid.pinRow(grid.data[1], 'bottom');
+grid.unpinRow(grid.data[0]);
+grid.pinnedRows;                                // getter → { top: T[]; bottom: T[] }
+```
+
+| Member | Signature | Notes |
+|---|---|---|
+| `rowPinning` | `{ enabled: boolean }` | Disabled when omitted. |
+| `pinRow(row, position?)` | `(T, 'top' \| 'bottom') => boolean` | Moves between bands if already pinned. `false` when disabled / cancelled. |
+| `unpinRow(row)` | `(T) => boolean` | No-op (returns `true`) when not pinned. |
+| `pinnedRows` *(getter)* | `{ top: T[]; bottom: T[] }` | In pin order. |
+
+Events: `rowPinning` (cancellable) → `rowPinned`, both `CustomEvent<{ row: T; position: 'top' | 'bottom' | null }>` (`null` when unpinning). Pins survive sort / filter / pagination as long as row identity is preserved; re-pin after a wholesale `data` swap.
+
+## Row reordering — drag / keyboard / API
+
+```ts
+grid.rowReordering = { enabled: true, applyToData: false, handle: true };
+grid.moveRow(2, 0, 'before');                   // (from, to, position?: 'before' | 'after')
+```
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `enabled` | `boolean` | — | Disabled when omitted. |
+| `applyToData` | `boolean` | `false` | `true` also splices `grid.data` in place; otherwise the order lives in the grid and you persist via `rowMoved`. |
+| `handle` | `boolean` | `true` | `true` renders a leading grip cell (drag only from it); `false` drags from anywhere on the row. |
+
+`moveRow(from, to, position?)` indices are into `grid.pageItems`; returns `boolean`. A manual order is **mutually exclusive with column sorting** — applying a sort clears it. Events: `rowMoving` (cancellable) → `rowMoved`, both `CustomEvent<{ from: number; to: number; data: T }>`.
+
+## Inline-edit undo / redo
+
+Opt in via `editing.history` (requires `editing.enabled`). Tracks every committed cell edit — single, row-mode, and bulk paste / fill.
+
+```ts
+grid.editing = { enabled: true, history: { enabled: true, stackSize: 100 } };
+grid.undo();                                    // Ctrl/Cmd+Z
+grid.redo();                                    // Ctrl/Cmd+Shift+Z or Ctrl+Y
+grid.clearHistory();
+grid.canUndo;  grid.canRedo;                    // getters (false unless history.enabled)
+```
+
+`stackSize` defaults to `100` (older commands evicted past the cap). Event: `historyChanged` — `CustomEvent<{ canUndo: boolean; canRedo: boolean }>`, fires after any record / undo / redo / clear (drive toolbar button enablement from it).
+
+## Declarative column validators
+
+`column.validators: Validator[]` run **before** a candidate value is written. Each returns an error `string` (reject) or `null` (pass). All run and every message is collected, so one commit can surface multiple errors. A failing commit keeps the editor open, marks the cell `aria-invalid`, and emits `cellValidationFailed`. Covers bulk edits (paste / fill) too.
+
+```ts
+import { required, min, max, pattern, custom } from 'apex-grid';
+
+const columns: ColumnConfiguration<User>[] = [
+  { key: 'name', editable: true, validators: [required('Name is required')] },
+  { key: 'age',  type: 'number', editable: true,
+    validators: [required(), min(0), max(120)] },
+  { key: 'email', editable: true,
+    validators: [pattern(/^\S+@\S+$/, 'Invalid email')] },
+  { key: 'code', editable: true,
+    validators: [custom((value, ctx) => value === ctx.data.id ? 'Cannot equal id' : null)] },
+];
+```
+
+| Factory | Signature | Fails when |
+|---|---|---|
+| `required(message?)` | `(msg?) => Validator` | value is `null` / `undefined` / empty-or-whitespace string |
+| `min(limit, message?)` | `(number, msg?) => Validator` | numeric value `< limit` (non-numeric / empty pass — compose with `required`) |
+| `max(limit, message?)` | `(number, msg?) => Validator` | numeric value `> limit` (non-numeric / empty pass) |
+| `pattern(regex, message?)` | `(RegExp, msg?) => Validator` | `String(value)` doesn't match `regex` (empty passes) |
+| `custom(fn)` | `(Validator) => Validator` | wraps a predicate; an inline arrow works identically |
+
+```ts
+// Validator signature
+type Validator<T, K> = (value: unknown, context: ValidatorContext<T, K>) => string | null;
+interface ValidatorContext<T, K> { column: ColumnConfiguration<T, K>; data: T; rowIndex: number; }
+```
+
+Event: `cellValidationFailed` — `CustomEvent<{ key; rowIndex; data: T; value: unknown; errors: readonly string[] }>`.
+
+## Column groups — spanning headers
+
+A presentational header layer above the column header row. `columns` stays flat; a column joins a group via its `group` id. Members must be **contiguous within one pin region** (the grid warns and skips the spanning cell otherwise). v1 ships static spanning headers only (`collapsible` is reserved / inert).
+
+```ts
+grid.columnGroups = [
+  { id: 'name', headerText: 'Name' },
+  { id: 'contact', headerText: 'Contact',
+    headerTemplate: ({ group, span }) => html`<em>${group.headerText} (${span})</em>` },
+];
+grid.columns = [
+  { key: 'first', group: 'name' },
+  { key: 'last',  group: 'name' },
+  { key: 'email', group: 'contact' },
+  { key: 'phone', group: 'contact' },
+];
+```
+
+| `ColumnGroupConfiguration` | Type | Notes |
+|---|---|---|
+| `id` | `string` | Referenced by a column's `group`. |
+| `headerText` | `string` | Text in the spanning cell. |
+| `headerTemplate?` | `(ctx: { group; span }) => TemplateResult` | Overrides `headerText`. |
+| `collapsible?` | `boolean` | Reserved for a future collapse affordance; inert in v1. |
+
+Getters: `hasColumnGroups` (a group has ≥1 visible member), `columnGroupDepth` (0 or 1 in v1), `displayColumns` (`readonly ColumnConfiguration<T>[]` in visual render order: start-pinned, unpinned, end-pinned).
+
+## State & schema — persist / restore / drive AI
+
+`getState()` returns a serializable, JSON-safe snapshot (functions / templates omitted); `setState()` applies a partial one. `getSchema()` returns a machine-readable descriptor of the grid (columns, per-column operations, capabilities, current state) — the contract an AI layer hands an LLM and validates a returned patch against.
+
+```ts
+const snapshot = grid.getState();               // GridState
+localStorage.setItem('grid', JSON.stringify(snapshot));
+// later …
+grid.setState(JSON.parse(localStorage.getItem('grid')!));   // → SetStateResult
+
+// Selection / expansion survive a wholesale data reload only with a stable id:
+grid.rowId = (row) => row.id;
+```
+
+`GridState` (`version: 1`) captures: `columns` (order/width/pinning/visibility), `sort`, `filter` (condition by operand name), `quickFilter`, `pagination` (`{ page, pageSize }`), `selection`, `expansion`, `treeExpanded` / `treeExpandedKeys`, `rowPinning`, `rowOrder`, and per-`modules` state. Rows are captured as `RowRef` — a stable `id` when `rowId` is set, else a positional `index` into `data` (round-trips within a session, not across a data swap).
+
+`setState(state, options?)` is **partial and defensive** — only present slices apply (omit a slice to leave it untouched; a present-but-empty `sort`/`filter` clears it). It never throws on malformed / stale / LLM input unless `options.strict` is set; unknown columns/operands, out-of-range pages, and unresolvable rows are dropped / clamped and reported. `rowOrder` is mutually exclusive with `sort` (a snapshot with both drops `rowOrder`).
+
+```ts
+interface SetStateResult { applied: string[]; skipped: string[]; warnings: string[]; }
+interface GetStateOptions<T> { rowId?: (row: T) => string | number; }
+interface SetStateOptions<T> { rowId?: (row: T) => string | number; strict?: boolean; }
+```
+
+Event: `stateChanged` — `CustomEvent<{ state: GridState }>`, debounced after the render pipeline settles. Fires for programmatic (including `setState`) and UI changes. The payload is only computed while a listener is attached (zero-cost otherwise); identical snapshots don't re-fire, so compare before persisting to avoid a save loop.
+
+## Programmatic pagination, quick-filter, and column pinning
+
+All emit the same cancellable-then-notify event pairs as their UI equivalents and return `Promise<boolean>`.
+
+```ts
+await grid.gotoPage(2);          // clamped into [0, pageCount - 1]
+await grid.nextPage();
+await grid.previousPage();
+await grid.firstPage();
+await grid.lastPage();
+await grid.setPageSize(50);      // returns to the first page
+await grid.setQuickFilter('john');   // '' to clear
+await grid.pinColumn('name', 'start');   // 'start' | 'end' | null
+await grid.unpinColumn('actions');       // = pinColumn(key, null)
+```
+
+`gotoPage` / `setPageSize` / `nextPage` / `previousPage` / `firstPage` / `lastPage` emit `pageChanging` → `pageChanged`. `setQuickFilter` emits `quickFilterChanging` → `quickFilterChanged`. `pinColumn` / `unpinColumn` emit `columnPinning` → `columnPinned` and only change the visual render order (the `columns` array isn't reordered).
+
+## Localization — `localeText`
+
+Every built-in UI string (pagination, filter operators, toolbar, row/selection labels) is localizable through a `GridLocaleText` map keyed by dot-namespaced `GridLocaleKey`s. Partial maps are valid — any omitted key falls back to the English default.
+
+```ts
+import { esLocale } from 'apex-grid';
+
+grid.localeText = esLocale;                                   // whole-UI Spanish
+grid.localeText = { 'toolbar.searchPlaceholder': 'Buscar…' };  // or override a few keys
+
+grid.localize('pagination.summary', { start: 1, end: 25, total: 100 });   // resolve a key
+```
+
+Exports: `EN_LOCALE` (the default dictionary / source of truth for keys), `esLocale` (ready-made Spanish), `interpolate` (`{token}` substitution), `localize`, and the types `GridLocaleKey` / `GridLocaleText` / `LocaleParams`. `grid.localize(key, params?, fallback?)` applies any `localeText` override over the English default and interpolates `{placeholder}` tokens; `fallback` covers keys outside the built-in set (e.g. a custom operand label).
+
+## Column menu & column separator
+
+| Property | Type | Default | Notes |
+|---|---|---|---|
+| `columnMenu` | `boolean` (JS property, no attr) | `true` | Kebab-menu button in each header, always visible. Set `false` to hide it. |
+| `columnSeparator` (attr `column-separator`) | `boolean` | `true` | Persistent trailing divider on every header. On resizable columns it doubles as the resize handle. Theme via `--ag-header-separator` / `--header-separator-color` and inset via `--apex-header-separator-inset`. |
+
+```ts
+grid.columnMenu = false;
+grid.columnSeparator = false;
+```
+
+## Export source & formats
+
+`exportToCSV` / `exportAs` accept a `source` selecting which rows to export:
+
+| `source` | Rows exported |
+|---|---|
+| `'view'` *(default)* | post-filter, post-sort rows across all pages |
+| `'page'` | current page slice only |
+| `'selected'` | current row selection (insertion order) |
+| `'all'` | the raw `data` array |
+
+```ts
+grid.exportToCSV();                                       // download data.csv (view)
+grid.exportToCSV({ filename: 'users', source: 'selected' });
+const text = grid.exportToCSV({ filename: '' });          // string only, no download
+```
+
+`exportFormats` *(getter)* → `readonly ExportFormat[]` (`{ id, label }`) — the community grid offers CSV only; it drives the toolbar export menu, one item per entry, dispatching to `exportAs(formatId, options?)`. Other `ExportOptions` fields: `columns?` (keys to include), `includeHeader?` (default `true`), `formatter?`; CSV adds `delimiter?` (`','`), `bom?` (`true`), `newline?` (`'\r\n'`).

package/references/vanilla-js.md

@@ -0,0 +1,154 @@
+# Vanilla JavaScript — Without Lit's `render` in Your App Code
+
+`apex-grid` is built with Lit internally, but you don't have to use Lit's `render` / `html` in your application code. You can write a pure-DOM page that imports the custom element, sets properties directly, and listens for events with `addEventListener`.
+
+**One honest caveat:** `cellTemplate` and `headerTemplate` are the **only** places that still require Lit's `html` tag — they must return a `TemplateResult` and there is no string-template escape hatch. Returning a plain string renders as escaped text. If you only need the default rendering (no custom cells), you can avoid Lit entirely.
+
+---
+
+## 1. Pure-DOM, default rendering (no Lit at all)
+
+Open this in a Vite dev server (`npm create vite@latest`, then `npm run dev`):
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Apex Grid — vanilla JS</title>
+    <style>
+      body { margin: 0; padding: 20px; font-family: system-ui; }
+      apex-grid { height: 480px; }                    /* REQUIRED — bounded host. NEVER set `display` here — it overrides the component's `:host { display: grid }` and collapses the virtualizer. */
+    </style>
+  </head>
+  <body>
+    <h1>Users</h1>
+    <apex-grid id="grid"></apex-grid>
+
+    <script type="module">
+      // 1. Register the element + adopt host sizing (no theme import needed)
+      import { setup } from 'apex-grid';
+      setup();
+
+      // 2. Set properties on the element
+      const grid = document.getElementById('grid');
+
+      grid.columns = [
+        { key: 'id',         type: 'number',  headerText: 'ID',         width: '80px',  sort: true, filter: true },
+        { key: 'name',       type: 'string',  headerText: 'Name',       width: '240px', sort: true, filter: true },
+        { key: 'age',        type: 'number',  headerText: 'Age',        width: '100px', sort: true, filter: true },
+        { key: 'subscribed', type: 'boolean', headerText: 'Subscribed', width: '140px', sort: true, filter: true },
+      ];
+
+      grid.data = [
+        { id: 1, name: 'Ada Lovelace',  age: 36, subscribed: true  },
+        { id: 2, name: 'Carl Sagan',    age: 62, subscribed: false },
+        { id: 3, name: 'Grace Hopper',  age: 85, subscribed: true  },
+      ];
+
+      // 3. Listen for events
+      grid.addEventListener('sorted',   (e) => console.log('sorted',   e.detail));
+      grid.addEventListener('filtered', (e) => console.log('filtered', e.detail));
+    </script>
+  </body>
+</html>
+```
+
+This works without any `import { html, render } from 'lit'` in your code. The grid renders, sorts, and filters with the default cell display.
+
+---
+
+## 2. When you need a custom cell — minimal Lit usage
+
+The moment you want to style a cell (e.g. render the `subscribed` column as a checkbox), you must import `html` from Lit. There's no way around it.
+
+```js
+// Add this to the imports above:
+import { html } from 'lit';
+
+grid.columns = [
+  { key: 'id',   type: 'number',  width: '80px',  sort: true, filter: true },
+  { key: 'name', type: 'string',  width: '240px', sort: true, filter: true,
+    cellTemplate: ({ value }) => html`<strong>${value}</strong>`,
+  },
+  { key: 'age',  type: 'number',  width: '100px', sort: true, filter: true },
+  { key: 'subscribed', type: 'boolean', width: '140px', sort: true, filter: true,
+    cellTemplate: ({ value }) => html`<input type="checkbox" .checked=${value} disabled />`,
+  },
+];
+```
+
+You're still not calling Lit's `render(...)` anywhere — you only import `html` to author template values that the custom element internally renders for each cell.
+
+### Why not a string template?
+
+```js
+// ❌ This renders as literal text: <strong>Ada Lovelace</strong>
+cellTemplate: ({ value }) => `<strong>${value}</strong>`,
+```
+
+The cell renderer treats the return value as a Lit template, not as HTML markup. Strings are coerced to text nodes, so any `<tag>` characters are escaped. There is no `dangerouslySetInnerHTML` equivalent.
+
+---
+
+## 3. Auto-generation — the genuinely 3-line demo
+
+If you don't care about specific columns and just want to see your data in a grid:
+
+```html
+<apex-grid auto-generate id="grid"></apex-grid>
+
+<script type="module">
+  import { setup } from 'apex-grid';
+  setup();
+
+  document.getElementById('grid').data = [
+    { id: 1, name: 'Ada',  age: 36 },
+    { id: 2, name: 'Carl', age: 62 },
+  ];
+</script>
+```
+
+Auto-generation infers columns from `Object.keys(data[0])` and runtime types. `sort` and `filter` default to `false`, so the auto path is read-only out of the box. To enable them with auto-generated columns, run `updateColumns` after the auto-pass:
+
+```js
+grid.updateColumns([
+  { key: 'id',   sort: true, filter: true },
+  { key: 'name', sort: true, filter: true },
+  { key: 'age',  sort: true, filter: true },
+]);
+```
+
+---
+
+## 4. Programmatic sort & filter without templates
+
+```js
+grid.sort({ key: 'age', direction: 'descending' });
+
+grid.filter({ key: 'age', condition: 'greaterThan', searchTerm: 30 });
+
+grid.filter({ key: 'subscribed', condition: 'true' });    // boolean operands are unary
+
+grid.clearSort();
+grid.clearFilter();
+```
+
+Programmatic calls don't fire `sorting` / `sorted` / `filtering` / `filtered` events. If you need a hook for every state change regardless of source, watch `grid.dataView` after each programmatic call:
+
+```js
+grid.sort({ key: 'age', direction: 'descending' });
+queueMicrotask(() => console.log('post-sort:', grid.dataView));
+```
+
+---
+
+## 5. Common vanilla-JS gotchas
+
+| ❌ | ✅ |
+|---|---|
+| Setting `grid.setAttribute('columns', JSON.stringify(cols))` | `grid.columns = cols` — must be a property, not an attribute |
+| Forgetting `<script type="module">` | All `apex-grid` imports are ESM; you need `type="module"` |
+| Opening the HTML with `file://` | Use a dev server — ESM imports fail CORS over `file://` |
+| `cellTemplate: ({ value }) => '<b>' + value + '</b>'` | `cellTemplate: ({ value }) => html\`<b>${value}</b>\`` — Lit `html` is required |
+| Setting `grid.columns` *before* the script tag's module imports resolve | Set them inside the same `<script type="module">` as the imports |