apexgrid-skill 2.0.0 → 2.1.1

package/.cursorrules

@@ -0,0 +1,283 @@
+# Apex Grid — AI Coding Rules
+
+You are working with `apex-grid`, a Lit-based web-component data grid by ApexCharts.
+Documentation: https://github.com/apexcharts/apexgrid
+NPM: apex-grid (with a hyphen — no `apexgrid` package exists)
+GitHub: https://github.com/apexcharts/apexgrid
+Confirmed versions: apex-grid@3.0.1, lit@^3.0.0
+
+## Quickstart — register + size the host
+
+The grid styles itself out of the box — there is **no theme CSS to import**.
+The one real gotcha is host sizing: it virtualizes rows and needs a bounded
+height or it collapses and renders nothing. `setup()` handles both.
+
+### 1. Install
+```bash
+npm install apex-grid lit
+```
+`igniteui-webcomponents` installs transitively — you do NOT import theme CSS from it.
+
+### 2. Register + size — `setup()` does both
+```ts
+import { setup } from 'apex-grid';
+setup();                       // registers <apex-grid> + adopts host sizing. Idempotent.
+```
+Manual alternative: `import 'apex-grid/define'` (or `ApexGrid.register()`) plus your own
+`apex-grid { height: 480px; }`. `setup({ hostStyles: false })` skips the injected sizing.
+
+### 3. Style via `--ag-*` CSS variables (no theme import)
+The grid is styled out of the box; retheme by overriding `--ag-*` custom properties on
+`apex-grid`. The deprecated `theme` option / `configureTheme()` does NOT affect appearance.
+```css
+apex-grid { height: 480px; /* + any --ag-* overrides */ }
+```
+
+### Minimal example
+
+```ts
+import { html, render } from 'lit';
+import { setup } from 'apex-grid';
+import type { ColumnConfiguration } from 'apex-grid';
+
+setup();   // register + host sizing; no theme import needed
+
+type User = { id: number; name: string; age: number; subscribed: boolean };
+
+const data: User[] = [
+  { id: 1, name: 'Ada Lovelace',  age: 36, subscribed: true  },
+  { id: 2, name: 'Carl Sagan',    age: 62, subscribed: false },
+];
+
+// Explicit widths prevent the last-column-stretches trap.
+const columns: ColumnConfiguration<User>[] = [
+  { key: 'id',         type: 'number',  width: '80px',  sort: true, filter: true },
+  { key: 'name',       type: 'string',  width: '240px', sort: true, filter: true },
+  { key: 'age',        type: 'number',  width: '100px', sort: true, filter: true },
+  { key: 'subscribed', type: 'boolean', width: '140px', sort: true, filter: true },
+];
+
+render(
+  html`<apex-grid .data=${data} .columns=${columns}></apex-grid>`,
+  document.getElementById('app')!,
+);
+```
+
+### What success looks like
+
+- Visible borders between rows and columns
+- Sort arrows (↕) next to each column header
+- A filter row below the headers with a "Filter" chip per column
+- Hover state on rows
+- Smooth scrolling; only ~20 `<apex-grid-row>` in the DOM at any time
+
+---
+
+## Naming
+
+| Form | What it is |
+|---|---|
+| `apex-grid` | npm package name (with hyphen) |
+| `<apex-grid>` | the custom-element tag rendered in the DOM |
+| `ApexGrid<T>` | the exported class — used for types and `ApexGrid.register()` |
+
+---
+
+## Critical Rules
+
+1. **Apex Grid is a Lit web component, not a JS class.** Don't `new ApexGrid(...)`. Render `<apex-grid>` and set `.data` / `.columns` as properties.
+2. **Two setup steps:** register the element and give the host a bounded height — `setup()` does both. **No theme CSS import is needed** (the grid self-styles via `--ag-*`).
+3. **`columns` and `data` are properties, not attributes.** Use property binding.
+4. **`column.key` must be a real `keyof T`.** No aliases. Compute derived values in `cellTemplate`.
+5. **Set `type` per column.** Primitive `'string'`/`'number'`/`'boolean'` drive sort/filter/editing (default `'string'`). Presentation types also exist: `'select'`, `'rating'`, `'date'`, `'image'`, `'currency'`, `'avatar'`, `'badge'`, `'progress'`, `'sparkline'`, `'status'`.
+6. **`cellTemplate` and `headerTemplate` must return Lit `TemplateResult`s** (`html\`...\``). Strings render as escaped text.
+7. **Sort/filter events fire only for UI-initiated operations.** Programmatic `grid.sort(...)` / `grid.filter(...)` are silent.
+
+---
+
+## Column Configuration
+
+```ts
+interface ColumnConfiguration<T, K extends keyof T> {
+  key: K;                                        // REQUIRED
+  type?: DataType;                               // default 'string' (13 types — see rule 5)
+  headerText?: string;                           // default: String(key)
+  width?: string;                                // CSS — recommended
+  hidden?: boolean;
+  resizable?: boolean;
+  pinned?: 'start' | 'end' | null;               // freeze during horizontal scroll
+  reorderable?: boolean;                         // per-column opt-out of drag reorder
+  exportable?: boolean;                          // default true
+  editable?: boolean;                            // requires grid editing.enabled
+  group?: string;                                // id of a columnGroups spanning header
+  validators?: Validator<T, K>[];                // edit-time validation (3.2+)
+  sort?:   boolean | { caseSensitive?, comparer? };
+  filter?: boolean | { caseSensitive? };
+  headerTemplate?: (ctx) => TemplateResult;
+  cellTemplate?:   (ctx) => TemplateResult;
+  editorTemplate?: (ctx) => TemplateResult;
+  // type-specific: options ('select'), max ('rating'/'progress'), format ('date'),
+  // shape/alt ('image'), currency/locale ('currency'), badgeVariant, statusVariant, showDelta
+}
+```
+
+Applied defaults: `{ type: 'string', resizable: false, hidden: false, sort: false, filter: false, exportable: true }`.
+
+### Templates
+
+```ts
+import { html } from 'lit';
+
+cellTemplate: ({ value, row, parent, column }) =>
+  html`<strong>${value}</strong>`,
+```
+
+### Auto-generation — 3-line demo
+
+```ts
+render(html`<apex-grid auto-generate .data=${data}></apex-grid>`, root);
+// Ignored if `columns` is non-empty. Reset grid.columns = [] before swapping data.
+```
+
+---
+
+## Filter Operands
+
+| Type | Operands |
+|---|---|
+| `'string'` | `contains`, `doesNotContain`, `startsWith`, `endsWith`, `equals`, `doesNotEqual`, `empty`, `notEmpty` |
+| `'number'` | `equals`, `doesNotEqual`, `greaterThan`, `lessThan`, `greaterThanOrEqual`, `lessThanOrEqual`, `empty`, `notEmpty` |
+| `'boolean'` | `all`, `true`, `false`, `empty`, `notEmpty` (all unary — no `searchTerm`) |
+
+```ts
+import { StringOperands, NumberOperands, BooleanOperands } from 'apex-grid';
+grid.filter({ key: 'name', condition: 'contains', searchTerm: 'ad' });
+grid.filter({ key: 'subscribed', condition: 'true' });        // unary
+grid.filter([
+  { key: 'age', condition: 'greaterThan', searchTerm: 30 },
+  { key: 'age', condition: 'lessThan',    searchTerm: 50, criteria: 'and' },
+]);
+```
+
+---
+
+## API
+
+| Property | Type | Notes |
+|---|---|---|
+| `data` | `T[]` | |
+| `columns` | `ColumnConfiguration<T>[]` | |
+| `autoGenerate` | `boolean` | Ignored if `columns` non-empty |
+| `sortConfiguration` | `{ multiple, triState }` | Multi-column + tri-state toggles |
+| `dataPipelineConfiguration` | `{ sort?, filter?, pagination?, quickFilter? }` | Server-side hooks |
+| `selection` / `editing` / `pagination` / `tree` / `expansion` | config objects | Opt-in: `{ enabled, ... }` (see SKILL.md §5) |
+| `quickFilter` / `columnReordering` | `string` / `boolean` | Global search / drag-reorder headers |
+| `sortExpressions` / `filterExpressions` | array (get/set) | To clear, use `clearSort()` / `clearFilter()` |
+| `selectedRows` / `expandedRows` | `T[]` (get/set) | Snapshots; set to replace |
+| `rows` (getter) | `ApexGridRow<T>[]` | Currently rendered only (virtualized) |
+| `dataView` / `pageItems` (getters) | `readonly T[]` | Full post-filter/sort / current page |
+| `totalItems` / `pageCount` (getters) | `number` | |
+
+| Method | Description |
+|---|---|
+| `sort(expr \| expr[])` | Programmatic. **No events.** |
+| `filter(expr \| expr[])` | Programmatic. **No events.** |
+| `clearSort(key?)` / `clearFilter(key?)` | Reset state. |
+| `getColumn(keyOrIndex)` / `updateColumns(col \| col[])` | Find / merge columns by `key`. |
+| `moveColumn(from, to, position?)` | Reorder within pinning group. |
+| `exportToCSV(opts?)` / `exportAs(formatId, opts?)` | Export data (CSV built in). |
+| `selectRow`/`deselectRow`/`selectAllRows`/`clearSelection`/`isRowSelected` | Selection. |
+| `expandRow`/`collapseRow`/`isRowExpanded` (+ `…TreeRow` variants) | Expansion / tree. |
+| `commitEdit()` / `cancelEdit()` | Row-edit batch (`editing.mode: 'row'`). |
+| `ApexGrid.register()` | Static; idempotent. |
+
+Events are **UI-initiated only** (programmatic calls are silent). `*-ing` events are
+cancellable (`preventDefault()`); `*-ed` are notifications. Pairs:
+`sorting/sorted`, `filtering/filtered`, `quickFilterChanging/Changed`, `pageChanging/Changed`,
+`columnPinning/Pinned`, `columnMoving/Moved`, `cellValueChanging/Changed`,
+`rowEditStarted/Ended`, `rowSelecting/Selected`, `rowExpanding/Expanded`, `treeRowExpanding/Expanded`.
+
+---
+
+## Server-side data
+
+```ts
+grid.dataPipelineConfiguration = {
+  filter: async ({ data, grid }) =>
+    fetch('/api/users/filter', {
+      method: 'POST',
+      body: JSON.stringify(grid.filterExpressions),
+    }).then((r) => r.json()),
+};
+```
+
+Built-in pipeline is skipped for whichever operations have a hook. Omit one to keep it in-memory. Hooks fire for both UI and programmatic operations.
+
+---
+
+## Pitfalls — ❌ Wrong vs ✅ Correct
+
+### 1. `new ApexGrid(...)`
+❌ `new ApexGrid({ container, columns, data })`
+✅ Render `<apex-grid .data=${data} .columns=${columns}></apex-grid>`
+
+### 2. Missing registration
+❌ Importing `ApexGrid` without `register()` — `<apex-grid>` is inert.
+✅ `import 'apex-grid/define'` once at startup.
+
+### 3. Importing a theme CSS that no longer exists
+❌ `import 'igniteui-webcomponents/themes/.../bootstrap.css'` + `configureTheme(...)` — obsolete; no effect.
+✅ No import needed — grid self-styles; retheme via `--ag-*`. The only required CSS is host height.
+
+### 4. Stringified attribute
+❌ `<apex-grid columns="[...]">`
+✅ `.columns=${columns}` / `:columns.prop=` / `[columns]=` / `el.columns = ...`
+
+### 5. `column.key` not a `keyof T`
+❌ `{ key: 'fullName' }` when not in `T`
+✅ `cellTemplate: ({ row }) => html\`${row.firstName} ${row.lastName}\``
+
+### 6. String from `cellTemplate`
+❌ `cellTemplate: ({ value }) => \`<b>\${value}</b>\``
+✅ `cellTemplate: ({ value }) => html\`<b>\${value}</b>\``
+
+### 7. Numbers sorted as strings
+❌ `{ key: 'age', sort: true }` (default `type: 'string'`)
+✅ `{ key: 'age', type: 'number', sort: true }`
+
+### 8. Faking date columns
+❌ `type: 'number'` timestamps or string + custom comparer to handle dates.
+✅ `{ key: 'created', type: 'date', format: 'medium' }` — real type; accepts Date/ISO/timestamp.
+
+### 9. Clearing sort/filter
+❌ Rebuilding state by hand to clear it.
+✅ `grid.clearSort()` / `grid.clearFilter()` (optionally per `key`).
+
+### 10. Expecting events from programmatic calls
+❌ `grid.addEventListener('sorted'); grid.sort(...)` — silent.
+✅ Wrap the call yourself, or watch `grid.dataView`.
+
+### 11. Wrong package name
+❌ `import ... from 'apexgrid'` — no such package.
+✅ `import ... from 'apex-grid'`.
+
+---
+
+## New in 3.1–3.3
+
+- **Row pinning**: `rowPinning = { enabled }`, `pinRow(row, 'top'|'bottom')`/`unpinRow(row)`, `pinnedRows` getter, `rowPinning`/`rowPinned` events.
+- **Row reordering**: `rowReordering = { enabled, applyToData?, handle? }`, `moveRow(from, to, position?)`, `rowMoving`/`rowMoved` events (clears on sort).
+- **Inline-edit undo/redo**: `editing.history = { enabled, stackSize? }`, `undo()`/`redo()`/`clearHistory()`, `canUndo`/`canRedo`, `historyChanged` event.
+- **Validators**: `column.validators: Validator[]` + `required`/`min`/`max`/`pattern`/`custom` factories, `cellValidationFailed` event.
+- **Column groups**: `columnGroups = [{ id, headerText }]` + `column.group` (members contiguous within a pin region).
+- **State/schema**: `getState()`/`setState()`/`getSchema()`, `rowId`, `stateChanged` event (`setState` is partial + defensive).
+- **Programmatic (these DO emit events, unlike sort/filter)**: `gotoPage`/`nextPage`/`setPageSize`/…, `setQuickFilter()`, `pinColumn`/`unpinColumn`.
+- **Localization**: `localeText` (`GridLocaleText`), `localize()`, `esLocale` export.
+- **Misc**: `columnMenu`/`columnSeparator`; `exportToCSV`/`exportAs` `source: 'view'|'page'|'selected'|'all'`.
+- Full detail: `references/state-and-features.md`.
+
+---
+
+## Dev-server reminder
+
+ES module imports require an HTTP server — opening with `file://` fails CORS. Use Vite (`npm create vite@latest`) or any static server.

package/SKILL.md

@@ -12,8 +12,8 @@ description: >
   model, and the `dataPipelineConfiguration` hooks for server-side data.
 metadata:
   author: ApexCharts
-  version: "2.0.0"
-  library_version: "3.0.1"
+  version: "2.1.0"
+  library_version: "3.3.0"
   category: data-visualization
   tags: [grid, data-grid, table, web-component, lit, apex-grid]
   docs: https://github.com/apexcharts/apexgrid
@@ -165,9 +165,11 @@ interface ColumnConfiguration<T extends object, K extends keyof T = keyof T> {
   pinned?: 'start' | 'end' | null;         // freeze to a side during horizontal scroll
   reorderable?: boolean;                   // per-column opt-out of drag reorder
   exportable?: boolean;                    // default true; false omits from CSV export
+  group?: string;                          // id of a columnGroups spanning header (§5)
   sort?:   boolean | { caseSensitive?: boolean; comparer?: (a: T[K], b: T[K]) => number };
   filter?: boolean | { caseSensitive?: boolean };
   editable?: boolean;                      // requires grid `editing.enabled`
+  validators?: Validator<T, K>[];          // declarative edit-time validation (§5)
   headerTemplate?:  (ctx: ApexHeaderContext<T>) => TemplateResult | unknown;
   cellTemplate?:    (ctx: ApexCellContext<T, K>) => TemplateResult | unknown;
   editorTemplate?:  (ctx: ApexEditorContext<T, K>) => TemplateResult | unknown;
@@ -276,6 +278,16 @@ grid.sort({ key: 'name', direction: 'ascending' });       // programmatic (silen
 | `quickFilter` (attr `quick-filter`) | `string` | Global substring search across visible columns. |
 | `showQuickFilter` / `showExport` | `boolean` | Toolbar UI toggles for quick-filter input / export menu. |
 | `columnReordering` (attr `column-reordering`) | `boolean` | Drag-reorder headers; per-column opt-out via `reorderable`. |
+| `columnMenu` | `boolean` | Header kebab-menu button. Default `true`; set `false` to hide. |
+| `columnSeparator` (attr `column-separator`) | `boolean` | Persistent header dividers (also the resize handle). Default `true`; theme via `--ag-header-separator`. |
+| `columnGroups` | `ColumnGroupConfiguration[]` | Spanning headers over contiguous columns (join via `column.group`). See `references/state-and-features.md`. |
+| `localeText` | `GridLocaleText` | Partial locale-key → string overrides; ready-made `esLocale` export. Omitted keys fall back to English. |
+| `rowId` | `(row: T) => string \| number` | Stable row-identity resolver so `getState` selection/expansion survives a data reload. |
+| `displayColumns` *(getter)* | `readonly ColumnConfiguration<T>[]` | Columns in visual render order (start-pinned → unpinned → end-pinned). |
+| `hasColumnGroups` / `columnGroupDepth` *(getters)* | `boolean` / `number` | Whether a group header row renders / its depth (0–1). |
+| `pinnedRows` *(getter)* | `{ top: T[]; bottom: T[] }` | Currently pinned rows per band. |
+| `canUndo` / `canRedo` *(getters)* | `boolean` | Undo/redo availability (needs `editing.history.enabled`). |
+| `exportFormats` *(getter)* | `readonly { id, label }[]` | Export menu formats (CSV in the community grid). |
 | `sortExpressions` / `filterExpressions` | `…[]` (get/set) | Current state. To clear, use `clearSort()` / `clearFilter()`. |
 | `selectedRows` / `expandedRows` | `T[]` (get/set) | Snapshots; set to replace (goes through cancellable events). |
 | `rows` *(getter)* | `ApexGridRow<T>[]` | **Currently rendered only** (virtualized). |
@@ -288,18 +300,24 @@ grid.sort({ key: 'name', direction: 'ascending' });       // programmatic (silen
 
 | Property | Shape |
 |---|---|
-| `editing` | `{ enabled, mode?: 'cell' \| 'row', trigger?: 'click' \| 'doubleClick' }` — plus per-column `editable: true` |
+| `editing` | `{ enabled, mode?: 'cell' \| 'row', trigger?: 'click' \| 'doubleClick', history?: { enabled, stackSize? } }` — plus per-column `editable: true` |
 | `selection` | `{ enabled, mode?: 'single' \| 'multiple', showCheckboxColumn? }` |
 | `pagination` | `{ enabled, mode?: 'local' \| 'remote', page?, pageSize?, pageSizeOptions?, totalItems? }` |
 | `tree` | `{ enabled, getDataPath: (row) => string[], groupColumnKey?, defaultExpanded?, childIndent? }` — flat data, hierarchy derived |
 | `expansion` | `{ enabled, detailTemplate: (ctx) => TemplateResult, isExpandable?, showToggleColumn? }` — master-detail |
+| `rowPinning` | `{ enabled }` — sticky top/bottom bands via `pinRow()` / `unpinRow()` |
+| `rowReordering` | `{ enabled, applyToData?, handle? }` — drag/keyboard reorder + `moveRow()`; manual order is mutually exclusive with sort |
 
 ```ts
-grid.editing    = { enabled: true, mode: 'cell', trigger: 'doubleClick' };
+grid.editing    = { enabled: true, mode: 'cell', trigger: 'doubleClick', history: { enabled: true } };
 grid.selection  = { enabled: true, mode: 'multiple', showCheckboxColumn: true };
 grid.pagination = { enabled: true, pageSize: 25 };
+grid.rowPinning    = { enabled: true };
+grid.rowReordering = { enabled: true };
 ```
 
+Declarative validators (`column.validators`), column groups (`columnGroups`), undo/redo, and state persistence (`getState` / `setState` / `getSchema`) are covered in `references/state-and-features.md`.
+
 ### Methods
 
 | Method | Description |
@@ -309,11 +327,18 @@ grid.pagination = { enabled: true, pageSize: 25 };
 | `getColumn(keyOrIndex)` | Find a column. |
 | `updateColumns(col \| col[])` | Merge new fields into existing columns by `key`. Triggers a pipeline run. |
 | `moveColumn(fromKey, toKey, position?)` | Reorder a column (within its pinning group). |
-| `exportToCSV(options?)` / `exportAs(formatId, options?)` | Export the data. CSV is built in. |
+| `pinColumn(key, 'start' \| 'end' \| null)` / `unpinColumn(key)` | Programmatic column pinning → `Promise<boolean>`; emits `columnPinning`/`columnPinned`. |
+| `exportToCSV(options?)` / `exportAs(formatId, options?)` | Export the data. CSV is built in. `options.source`: `'view'`(def)/`'page'`/`'selected'`/`'all'`. |
+| pagination | `gotoPage(n)`, `setPageSize(n)`, `nextPage()`, `previousPage()`, `firstPage()`, `lastPage()` → `Promise<boolean>`; emit `pageChanging`/`pageChanged`. |
+| `setQuickFilter(value)` | Apply global search (`''` clears) → `Promise<boolean>`; emits `quickFilterChanging`/`quickFilterChanged`. |
 | selection | `selectRow`, `deselectRow`, `toggleRowSelection`, `selectAllRows`, `clearSelection`, `isRowSelected` |
 | expansion | `expandRow`, `collapseRow`, `toggleRowExpansion`, `expandAllRows`, `collapseAllRows`, `isRowExpanded` |
 | tree | `expandTreeRow`, `collapseTreeRow`, `toggleTreeRow`, `expandAllTreeRows`, `collapseAllTreeRows`, `isTreeRowExpanded` |
+| row pinning | `pinRow(row, 'top' \| 'bottom')`, `unpinRow(row)` (needs `rowPinning.enabled`) |
+| row reorder | `moveRow(from, to, position?)` (needs `rowReordering.enabled`) |
 | editing | `commitEdit()`, `cancelEdit()` (used with `mode: 'row'`) |
+| undo/redo | `undo()`, `redo()`, `clearHistory()` (needs `editing.history.enabled`) |
+| state | `getState(options?)` → `GridState`, `setState(partial, options?)` → `SetStateResult`, `getSchema()` → `GridSchema` |
 | `ApexGrid.register()` / `ApexGrid.tagName` | Static element registration / `'apex-grid'`. |
 
 ### Events — UI-initiated only
@@ -333,8 +358,20 @@ Every event fires only for operations driven through the grid's own UI; programm
 | `rowSelecting` / `rowSelected` | row selection |
 | `rowExpanding` / `rowExpanded` | master-detail expand |
 | `treeRowExpanding` / `treeRowExpanded` | tree-row expand |
+| `rowPinning` / `rowPinned` | row pin / unpin (also fires for `pinRow()`/`unpinRow()`) |
+| `rowMoving` / `rowMoved` | row reorder (also fires for `moveRow()`) |
+
+**Exceptions to "UI-only".** The dedicated programmatic methods added for pagination (`gotoPage`, `nextPage`, …), quick-filter (`setQuickFilter`), column pinning (`pinColumn` / `unpinColumn`), row pinning (`pinRow` / `unpinRow`), and row reorder (`moveRow`) **do** emit their `*-ing` / `*-ed` pairs (unlike `sort()` / `filter()`, which stay silent).
+
+Single-shot events (no `-ing` pair):
+
+| Event | `event.detail` | Fires when |
+|---|---|---|
+| `cellValidationFailed` | `{ key, rowIndex, data, value, errors: string[] }` | a candidate value is rejected by `column.validators` (keeps editor open) |
+| `historyChanged` | `{ canUndo, canRedo }` | undo/redo stacks change (record / undo / redo / clear) |
+| `stateChanged` | `{ state: GridState }` | restorable state changes (debounced; UI or programmatic incl. `setState`) |
 
-Operand reference, multi-column sort, and server-side hooks: `references/sort-and-filter.md` and `references/data-pipeline.md`.
+Operand reference, multi-column sort, and server-side hooks: `references/sort-and-filter.md` and `references/data-pipeline.md`. Row pinning/reorder, undo/redo, validators, column groups, state/schema, and localization: `references/state-and-features.md`.
 
 ---
 
@@ -389,5 +426,6 @@ Operand reference, multi-column sort, and server-side hooks: `references/sort-an
 | Column types, templates, auto-generation, per-column styling, header/editor templates | `references/columns-and-templates.md` |
 | Sort & filter — operands, expressions, multi-column, quick-filter, events | `references/sort-and-filter.md` |
 | Server-side data hooks (sort/filter/pagination/quickFilter), virtualization, `dataView` | `references/data-pipeline.md` |
+| Row pinning / reordering, undo-redo, validators, column groups, state & schema (`getState`/`setState`/`getSchema`), localization, export source | `references/state-and-features.md` |
 | End-to-end vanilla JS (no Lit `render`) | `references/vanilla-js.md` |
 | Lit, React, Vue, Angular integration | `references/framework-integration.md` |

package/index.js

@@ -17,6 +17,7 @@ export const referenceFiles = [
   'data-pipeline.md',
   'framework-integration.md',
   'sort-and-filter.md',
+  'state-and-features.md',
   'vanilla-js.md',
 ];
 

package/install/claude-code.md

@@ -0,0 +1,19 @@
+# Installing Apex Grid Skill for Claude Code
+
+```bash
+mkdir -p .claude/skills
+cd .claude/skills
+git clone https://github.com/apexcharts/apexgrid-skill.git
+```
+
+Claude Code will automatically detect `SKILL.md` and load it when working on `apex-grid` code.
+
+## Verification
+
+> Build a sortable, filterable Apex Grid for a `User` table with a custom avatar cell template.
+
+Claude should:
+- Register the custom element via `import 'apex-grid/define'` (or `ApexGrid.register()`) at app startup
+- Define a `ColumnConfiguration<User>[]` with `sort: true` and `filter: true` per column, plus the right `type`
+- Return a Lit `html\`...\`` template from `cellTemplate`, not a string
+- Set `.data` and `.columns` as **properties** on the `<apex-grid>` element, not as attributes

package/install/copilot.md

@@ -0,0 +1,22 @@
+# Installing Apex Grid Skill for GitHub Copilot
+
+## VS Code + Copilot Chat
+
+### Option 1: Add as Workspace Context
+
+1. Clone this repository or download `SKILL.md` into your project
+2. In Copilot Chat: `@workspace #file:SKILL.md`
+3. Ask your data-grid question
+
+### Option 2: Custom Instructions
+
+1. Open VS Code Settings (Cmd/Ctrl + ,)
+2. Search for "Copilot Custom Instructions"
+3. Paste the contents of `.cursorrules`
+
+## Verification
+
+Ask Copilot to generate an Apex Grid. It should:
+- Import from `apex-grid` (with a hyphen), not `apexgrid`
+- Register the custom element exactly once at app startup
+- Pass `columns` and `data` via property binding

package/install/cursor.md

@@ -0,0 +1,18 @@
+# Installing Apex Grid Skill for Cursor
+
+```bash
+curl -o .cursorrules https://raw.githubusercontent.com/apexcharts/apexgrid-skill/main/.cursorrules
+```
+
+Restart Cursor or open a new window. Cursor automatically reads `.cursorrules` files in the project root as context.
+
+## For Windsurf
+
+Same approach — Windsurf also reads `.cursorrules`.
+
+## Verification
+
+Ask Cursor to generate an Apex Grid with multi-column sort and a server-side filter pipeline. It should:
+- Set `sortConfiguration: { multiple: true, triState: true }` (or rely on the default)
+- Provide an async `dataPipelineConfiguration.filter` hook that returns the new data array
+- Use property bindings (`.columns=${...}`), not attribute syntax

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apexgrid-skill",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "AI coding skill for the apex-grid web component — structured reference docs that help AI assistants (Claude, Cursor, Copilot, etc.) generate correct apex-grid code.",
   "keywords": [
     "apex-grid",
@@ -39,7 +39,9 @@
   "files": [
     "index.js",
     "SKILL.md",
-    "references"
+    "references",
+    "install",
+    ".cursorrules"
   ],
   "engines": {
     "node": ">=18"

package/references/columns-and-templates.md

@@ -21,7 +21,9 @@ interface BaseColumnConfiguration<T extends object, K extends keyof T = keyof T>
   pinned?: 'start' | 'end' | null;                 // freeze to a side during horizontal scroll
   reorderable?: boolean;                           // per-column opt-out of drag reorder
   exportable?: boolean;                            // default true; false omits from CSV export
+  group?: string;                                  // id of a columnGroups spanning header (state-and-features.md)
   editable?: boolean;                              // requires grid editing.enabled
+  validators?: Validator<T, K>[];                  // edit-time validation (see below)
   sort?: boolean | { caseSensitive?: boolean; comparer?: (a: T[K], b: T[K]) => number };
   filter?: boolean | { caseSensitive?: boolean };
   headerTemplate?: (ctx: ApexHeaderContext<T>) => TemplateResult | unknown;
@@ -156,6 +158,21 @@ interface ApexHeaderContext<T> {
 }
 ```
 
+## Column validators (`validators`) — 3.2+
+
+`column.validators` run before a candidate value is written (inline edit, row-mode, and bulk paste / fill). Each returns an error `string` (reject) or `null` (pass); all run and every message is collected. A failing commit keeps the editor open, marks the cell `aria-invalid`, and emits `cellValidationFailed`. Requires the column to be `editable` and grid `editing.enabled`.
+
+```ts
+import { required, min, max, pattern, custom } from 'apex-grid';
+
+{ 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))] }
+```
+
+Built-in factories: `required(message?)`, `min(limit, message?)`, `max(limit, message?)`, `pattern(regex, message?)`, `custom(fn)`. `min`/`max`/`pattern` pass on empty / non-numeric values — compose with `required`. See `references/state-and-features.md` for the `Validator` / `ValidatorContext` shapes and the `cellValidationFailed` payload.
+
 ## Auto-generation — the fastest demo
 
 The shortest possible "just show me a table" example:

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'`).