apexgrid-skill 2.1.0 → 2.2.0

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.1.0"
-  library_version: "3.3.0"
+  version: "2.2.0"
+  library_version: "3.4.0"
   category: data-visualization
   tags: [grid, data-grid, table, web-component, lit, apex-grid]
   docs: https://github.com/apexcharts/apexgrid
@@ -373,6 +373,24 @@ Single-shot events (no `-ing` pair):
 
 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`.
 
+### Keyboard & accessibility (3.4)
+
+The grid ships full keyboard operation and screen-reader support out of the box; there's nothing to enable. The body uses a **roving-tabindex** focus model: the active cell is the body's single tab stop, so `Tab` moves into and out of the grid in one step, and real focus follows arrow-key navigation (screen readers track cell-to-cell movement).
+
+| Key | Moves / does |
+|---|---|
+| Arrow keys | Move the active cell one cell up / down / left / right |
+| Home / End | Move to the **first / last cell of the current row** |
+| Ctrl/Cmd+Home / Ctrl/Cmd+End | Jump to the grid's first / last cell |
+| PageUp / PageDown | Page-scroll by a viewport |
+| Enter or F2 | Open the active cell's editor (editing is no longer pointer-only) |
+
+Keyboard-driven commit (Enter) or cancel (Escape) returns focus to the cell, so navigation continues from where you left off.
+
+**Editing behavior:** clearing a `number` or `currency` editor now commits `null` (previously it wrote `NaN`). An empty or unparseable numeric input leaves the cell empty rather than poisoning the row.
+
+**Announcements:** sorting, filtering, selection, paging, row pinning, row reorder, expansion, and undo / redo each announce through a localized live region, and the host applies a localized `aria-label` ("Data grid") plus `aria-multiselectable` when multi-row selection is on. The strings are locale keys (`announce.*`, `header.*`, `grid.label`, `editor.rating`); override them via `localeText` (see `references/state-and-features.md`).
+
 ---
 
 ## 6. Pitfalls — ❌ Wrong vs ✅ Correct

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.1.0",
+  "version": "2.2.0",
   "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

@@ -173,6 +173,8 @@ import { required, min, max, pattern, custom } from 'apex-grid';
 
 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.
 
+**Numeric editing (3.4):** clearing a `number` or `currency` editor now commits `null`, not `NaN`. An empty or unparseable numeric input leaves the cell empty instead of writing `NaN` into the row. Editing also opens from the keyboard now (Enter or F2 on the active cell), not only by pointer; see SKILL.md §5 for the full keyboard model. Separately, a spreadsheet-style error value (an object carrying a `#...` code, such as an enterprise formula engine's `#VALUE!`) renders as its code in typed `number` / `currency` columns rather than coercing to `NaN` and showing an empty cell.
+
 ## Auto-generation — the fastest demo
 
 The shortest possible "just show me a table" example:

package/references/state-and-features.md

@@ -1,6 +1,6 @@
 # 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.
+> Everything here landed in **apex-grid 3.1 – 3.4** 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
 
@@ -172,6 +172,8 @@ grid.localize('pagination.summary', { start: 1, end: 25, total: 100 });   // res
 
 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).
 
+**3.4 key changes** (both English and Spanish): the accessibility work added live-region announcement keys (`announce.*`, e.g. `announce.sortedAscending`, `announce.page`, `announce.rowSelected`, `announce.undoOne`), header control / sort-state labels (`header.*`, e.g. `header.sortedAscending`, `header.filterColumn`, `header.columnMenu`), the host label `grid.label` ("Data grid"), and `editor.rating`. The `ai.noAdapter` key was **removed** (drop it from any `localeText` override you kept). `EN_LOCALE` remains the source of truth for the full, current key list.
+
 ## Column menu & column separator
 
 | Property | Type | Default | Notes |