apexgrid-skill 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 ApexCharts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# Apex Grid AI Skill
+
+AI coding skill for building UIs with the [`apex-grid`](https://github.com/apexcharts/apexgrid) web component (the Lit-based ApexCharts data grid). Works with Claude Code, Cursor, GitHub Copilot, and any AI coding assistant.
+
+> **Naming heads-up.** The npm package is `apex-grid` (with a hyphen), the custom-element tag is `<apex-grid>`, and the exported class is `ApexGrid<T>`.
+
+## What This Does
+
+AI models routinely get web-component grid code wrong: they treat `<apex-grid>` like a class with a constructor, forget to register the custom element, set `columns` as a stringified attribute, return strings (not Lit `TemplateResult`s) from `cellTemplate`, or expect events from programmatic `sort()` calls. This skill ships structured reference files so the assistant generates correct `apex-grid` code on the first try.
+
+### Coverage
+
+- **Custom-element registration** — `import 'apex-grid/define'` vs `ApexGrid.register()`
+- **Generic `ColumnConfiguration<T>`** — `key`, `type`, templates, `sort`, `filter`
+- **Lit cell & header templates** with the right context shapes
+- **Sort & filter** — programmatic API, UI events, operands, multi-column
+- **Server-side data** — `dataPipelineConfiguration` async hooks
+- **Virtualization** — `grid.rows` vs `grid.dataView` vs `grid.totalItems`
+- **Framework integration** — Lit, React, Vue, Angular
+
+## Installation
+
+### Claude Code
+
+```bash
+mkdir -p .claude/skills
+cd .claude/skills
+git clone https://github.com/apexcharts/apexgrid-skill.git
+```
+
+### Cursor / Windsurf
+
+```bash
+curl -o .cursorrules https://raw.githubusercontent.com/apexcharts/apexgrid-skill/main/.cursorrules
+```
+
+### GitHub Copilot
+
+Reference `SKILL.md` in Copilot Chat: `@workspace #file:SKILL.md`, or paste the contents of `.cursorrules` into Copilot's custom instructions.
+
+### As an npm dependency
+
+```bash
+npm install apexgrid-skill
+```
+
+```js
+import { skillFile, referencePath } from 'apexgrid-skill';
+import { readFile } from 'node:fs/promises';
+
+const skill = await readFile(skillFile, 'utf8');
+const cols  = await readFile(referencePath('columns-and-templates.md'), 'utf8');
+```
+
+## Repository Structure
+
+```
+├── SKILL.md                           # Main entry point
+├── .cursorrules                       # Self-contained Cursor / Windsurf version
+├── references/
+│   ├── columns-and-templates.md       # ColumnConfiguration, types, Lit templates
+│   ├── sort-and-filter.md             # operands, expressions, events, multi-column
+│   ├── data-pipeline.md               # async hooks, server-side, virtualization
+│   └── framework-integration.md       # Lit, React, Vue, Angular
+└── install/
+    ├── claude-code.md
+    ├── cursor.md
+    └── copilot.md
+```
+
+## Links
+
+- [apex-grid GitHub](https://github.com/apexcharts/apexgrid)
+- [npm: apex-grid](https://www.npmjs.com/package/apex-grid)
+- [Lit framework](https://lit.dev)
+- [igniteui-webcomponents](https://www.npmjs.com/package/igniteui-webcomponents) (runtime peer)
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,410 @@
+---
+name: apex-grid
+description: >
+  AI skill for building UIs with the `apex-grid` web component (the Lit-based
+  ApexCharts data grid). Use whenever the user asks to create, configure, or
+  troubleshoot a sortable / filterable / virtualized data table with
+  `<apex-grid>`. Covers the generic `ColumnConfiguration<T>` shape, cell &
+  header templates that return Lit `TemplateResult`s, the
+  `sort` / `filter` / `sorted` / `filtered` events, programmatic
+  `sort()` / `filter()` / `clearSort()` / `clearFilter()` / `updateColumns()`
+  APIs, the `dataPipelineConfiguration` hooks for server-side data, and the
+  one-time `ApexGrid.register()` custom-element registration.
+metadata:
+  author: ApexCharts
+  version: "1.0.0"
+  library_version: ">=0.0.0"
+  category: data-visualization
+  tags: [grid, data-grid, table, web-component, lit, apex-grid]
+  docs: https://github.com/apexcharts/apexgrid
+  npm: apex-grid
+  github: https://github.com/apexcharts/apexgrid
+---
+
+# Apex Grid AI Skill
+
+> **Heads-up on naming.** The npm package is **`apex-grid`** (with a hyphen). The custom-element tag is **`<apex-grid>`**. The exported class is **`ApexGrid<T>`**. There is no `apexgrid` package — using `import ... from 'apexgrid'` will fail.
+
+## 1. Critical Rules
+
+1. **Apex Grid is a Lit web component, not a JS class with a constructor.** You don't `new ApexGrid(...)`. You register the custom element once and then use `<apex-grid>` in the DOM, setting `.data` and `.columns` as JS properties.
+2. **Register the element exactly once at app startup**: either `import 'apex-grid/define'` (auto-registers as a side-effect) or `import { ApexGrid } from 'apex-grid'; ApexGrid.register();`. Without this, the tag renders as an empty inert element.
+3. **`columns` and `data` are properties, not attributes.** Always bind with the property syntax (`.columns=${...}` in Lit, `[columns]="..."` in Angular, `:columns=` in Vue, ref-based in plain JS) — never as a stringified `columns="..."` attribute.
+4. **`column.key` must be a real key of `T`** (the data row type). It is what the grid reads from each row, what sort/filter expressions reference, and what's emitted in events. There is no `field` / `dataIndex` / `accessor` alias.
+5. **`type` defaults to `'string'`.** Set it to `'number'` or `'boolean'` to get the right filter operands and comparer. There is no `'date'` type — use `'number'` (timestamps) or `'string'` (ISO) and a custom `comparer` / `cellTemplate`.
+6. **`sort` and `filter` per-column are `boolean | configObject`.** They are `false` by default — no opt-in, no UI. Set `sort: true` / `filter: true` to enable, or pass a config object for fine-grained control.
+7. **`cellTemplate` and `headerTemplate` must return Lit `TemplateResult`s** (`html\`...\``) — not strings, DOM nodes, or framework-specific JSX. Plain HTML strings render as escaped text.
+8. **Sort/filter events fire on UI-initiated operations only.** Programmatic calls (`grid.sort(...)`, `grid.filter(...)`) do not emit `sorting` / `sorted` / `filtering` / `filtered` events.
+9. **`sorting` and `filtering` events are cancellable** (`event.preventDefault()`) and their `event.detail` is mutable so you can rewrite the expression before it runs.
+10. **For server-side data, set `dataPipelineConfiguration.sort` / `.filter`** — async hooks that receive `{ data, grid, type }` and return the new array. The grid skips its built-in pipeline entirely when a hook is provided for that operation.
+11. **`autoGenerate` is ignored when `columns` is non-empty.** To re-trigger auto-generation after a data swap, set `grid.columns = []` first, then assign the new `data`.
+12. **`grid.rows` only returns currently rendered rows.** The grid uses `@lit-labs/virtualizer`, so off-screen rows are not in the DOM.
+13. **`apex-grid` depends on `igniteui-webcomponents`** for filter/sort UI controls. The package lists it as a runtime dependency — don't try to remove it.
+
+---
+
+## 2. Data Format & Column Configuration
+
+Apex Grid is generic over a row type `T`:
+
+```ts
+interface ColumnConfiguration<T extends object, K extends keyof T = keyof T> {
+  key: K;                                          // REQUIRED — must be a key of T
+  type?: 'string' | 'number' | 'boolean';          // default 'string'
+  headerText?: string;                             // default: the key itself
+  width?: string;                                  // any CSS width
+  hidden?: boolean;                                // default false
+  resizable?: boolean;                             // default false
+  sort?: boolean | { caseSensitive?: boolean; comparer?: (a: T[K], b: T[K]) => number };
+  filter?: boolean | { caseSensitive?: boolean };
+  headerTemplate?: (ctx: ApexHeaderContext<T>) => TemplateResult | unknown;
+  cellTemplate?: (ctx: ApexCellContext<T, K>) => TemplateResult | unknown;
+}
+```
+
+Minimal example:
+
+```ts
+import { html, render } from 'lit';
+import 'apex-grid/define';                         // registers <apex-grid>
+import type { ColumnConfiguration } from 'apex-grid';
+
+type User = { id: number; name: string; age: number; subscribed: boolean };
+
+const data: User[] = [
+  { id: 1, name: 'Ada',  age: 36, subscribed: true  },
+  { id: 2, name: 'Carl', age: 41, subscribed: false },
+];
+
+const columns: ColumnConfiguration<User>[] = [
+  { key: 'id',         type: 'number',  sort: true, filter: true, headerText: 'ID' },
+  { key: 'name',       type: 'string',  sort: true, filter: true },
+  { key: 'age',        type: 'number',  sort: true, filter: true },
+  { key: 'subscribed', type: 'boolean', sort: true, filter: true },
+];
+
+render(
+  html`<apex-grid .data=${data} .columns=${columns}></apex-grid>`,
+  document.getElementById('app')!,
+);
+```
+
+### Column types and filter operands
+
+The `type` field selects which filter operand set is exposed in the filter UI:
+
+| `type` | Operands available |
+|---|---|
+| `'string'` *(default)* | `contains`, `doesNotContain`, `startsWith`, `endsWith`, `equals`, `doesNotEqual`, `empty`, `notEmpty` |
+| `'number'` | `equals`, `doesNotEqual`, `greaterThan`, `lessThan`, `greaterThanOrEqual`, `lessThanOrEqual`, `empty`, `notEmpty` |
+| `'boolean'` | `all`, `true`, `false`, `empty`, `notEmpty` |
+
+Programmatic filter expressions can reference operands by name (`condition: 'contains'`) or by importing them as a function:
+
+```ts
+import { StringOperands } from 'apex-grid';
+
+grid.filter({ key: 'name', condition: StringOperands.contains, searchTerm: 'ada' });
+// or shorthand
+grid.filter({ key: 'name', condition: 'contains', searchTerm: 'ada' });
+```
+
+### Cell & header templates (Lit)
+
+Templates are Lit render callbacks. They receive a context object and must return a `TemplateResult`.
+
+```ts
+const columns: ColumnConfiguration<User>[] = [
+  {
+    key: 'name',
+    cellTemplate: ({ value, row, parent, column }) => html`
+      <strong style="color:#1f4ed8">${value}</strong>
+    `,
+  },
+  {
+    key: 'subscribed',
+    type: 'boolean',
+    cellTemplate: ({ value }) => html`
+      <input type="checkbox" .checked=${value} disabled />
+    `,
+  },
+  {
+    key: 'age',
+    headerTemplate: ({ column }) => html`
+      <em>${column.headerText ?? String(column.key)}</em>
+    `,
+  },
+];
+```
+
+Context shapes:
+
+```ts
+interface ApexCellContext<T, K extends keyof T> {
+  parent: ApexGridCell<T>;        // the cell element
+  row:    ApexGridRow<T>;         // the row element
+  column: ColumnConfiguration<T, K>;
+  value:  T[K];
+}
+
+interface ApexHeaderContext<T> {
+  parent: ApexGridHeader<T>;
+  column: ColumnConfiguration<T>;
+}
+```
+
+### Auto-generated columns
+
+`auto-generate` (or `.autoGenerate=${true}`) infers columns from the first data row's keys. **It is ignored if `columns` is non-empty.** To re-trigger after a data swap:
+
+```ts
+grid.columns = [];                   // reset first
+grid.data = newData;                 // then replace data — columns are inferred
+```
+
+---
+
+## 3. Public API
+
+### Properties
+
+| Property | Type | Default | Notes |
+|---|---|---|---|
+| `data` | `T[]` | `[]` | Row data. Setting it triggers a pipeline run. |
+| `columns` | `ColumnConfiguration<T>[]` | `[]` | Column definitions. Each entry is merged with `DEFAULT_COLUMN_CONFIG`. |
+| `autoGenerate` | `boolean` (attr `auto-generate`) | `false` | Infer columns from data. Ignored when `columns` is non-empty. |
+| `sortConfiguration` | `{ multiple: boolean; triState: boolean }` | `{ true, true }` | Grid-wide sort behaviour. |
+| `dataPipelineConfiguration` | `{ sort?, filter? }` | — | Server-side / async data hooks. |
+| `sortExpressions` | `SortExpression<T>[]` | `[]` | Get/set the active sort state. Setting an empty array is a no-op — use `clearSort()`. |
+| `filterExpressions` | `FilterExpression<T>[]` | `[]` | Get/set the active filter state. Empty-set semantics same as above. |
+| `rows` | `ApexGridRow<T>[]` *(getter)* | — | Currently rendered rows only (virtualized). |
+| `dataView` | `readonly T[]` *(getter)* | — | Data after sort + filter pipeline. |
+| `totalItems` | `number` *(getter)* | — | `dataView.length`. |
+
+### Methods
+
+| Method | Description |
+|---|---|
+| `sort(expr \| expr[])` | Apply a sort. Does **not** fire `sorting` / `sorted` events. |
+| `filter(expr \| expr[])` | Apply a filter. Does **not** fire `filtering` / `filtered` events. |
+| `clearSort(key?)` | Clear all sort state, or just the column with `key`. |
+| `clearFilter(key?)` | Clear all filter state, or just the column with `key`. |
+| `getColumn(keyOrIndex)` | Find a column by `key` or numeric index. |
+| `updateColumns(col \| col[])` | Merge new properties into existing columns by `key`. Triggers a pipeline run. |
+
+### Static
+
+| Member | Description |
+|---|---|
+| `ApexGrid.tagName` | The string `'apex-grid'`. |
+| `ApexGrid.register()` | Registers `<apex-grid>` and all internal sub-components. Idempotent. Either call this once, or import `'apex-grid/define'` for auto-registration. |
+
+---
+
+## 4. Events
+
+Events fire **only** when the user interacts with sort / filter UI. Programmatic `grid.sort(...)` / `grid.filter(...)` calls are silent.
+
+```ts
+import type { ApexGridEventMap } from 'apex-grid';
+
+grid.addEventListener('sorting', (e) => {
+  // CustomEvent<SortExpression<T>>
+  // e.detail is the expression about to be applied — mutate to rewrite, preventDefault to cancel
+  if (e.detail.direction === 'descending') {
+    e.preventDefault();
+  }
+});
+
+grid.addEventListener('sorted', (e) => {
+  // CustomEvent<SortExpression<T>>
+});
+
+grid.addEventListener('filtering', (e) => {
+  // CustomEvent<{ key, expressions, type: 'add'|'modify'|'remove' }>
+});
+
+grid.addEventListener('filtered', (e) => {
+  // CustomEvent<{ key, state: FilterExpression<T>[] }>
+});
+```
+
+| Event | Cancellable | `event.detail` |
+|---|---|---|
+| `sorting` | yes | `SortExpression<T>` (mutable) |
+| `sorted` | no | `SortExpression<T>` |
+| `filtering` | yes | `{ key: keyof T; expressions: FilterExpression<T>[]; type: 'add' \| 'modify' \| 'remove' }` |
+| `filtered` | no | `{ key: keyof T; state: FilterExpression<T>[] }` |
+
+---
+
+## 5. Server-Side / Async Data — `dataPipelineConfiguration`
+
+When sort or filter should run on the server, supply async hooks. Each hook receives `{ data, grid, type }` and returns the new array. **The built-in pipeline is skipped for whichever operations have a hook.**
+
+```ts
+grid.dataPipelineConfiguration = {
+  sort: async ({ data, grid }) => {
+    const expressions = grid.sortExpressions;
+    return fetch('/api/users/sort', {
+      method: 'POST',
+      body: JSON.stringify(expressions),
+    }).then((r) => r.json());
+  },
+  filter: async ({ data, grid }) => {
+    const expressions = grid.filterExpressions;
+    return fetch('/api/users/filter', {
+      method: 'POST',
+      body: JSON.stringify(expressions),
+    }).then((r) => r.json());
+  },
+};
+```
+
+You can supply just `sort`, just `filter`, or both. Anything you don't override falls back to the in-memory pipeline.
+
+---
+
+## 6. Programmatic Sort & Filter
+
+```ts
+import { StringOperands } from 'apex-grid';
+
+// Single sort
+grid.sort({ key: 'name', direction: 'ascending' });
+
+// Multiple (multi-column) sort — works only when sortConfiguration.multiple is true
+grid.sort([
+  { key: 'subscribed', direction: 'descending' },
+  { key: 'age',        direction: 'ascending'  },
+]);
+
+// Filter — by operand name
+grid.filter({ key: 'name', condition: 'contains', searchTerm: 'ad' });
+
+// Filter — by operand object (typed)
+grid.filter({ key: 'name', condition: StringOperands.contains, searchTerm: 'ad' });
+
+// Multiple filters with AND/OR
+grid.filter([
+  { key: 'age', condition: 'greaterThan', searchTerm: 30 },
+  { key: 'age', condition: 'lessThan',    searchTerm: 50, criteria: 'and' },
+]);
+
+// Clear
+grid.clearSort();              // all columns
+grid.clearSort('name');        // just `name`
+grid.clearFilter();
+grid.clearFilter('name');
+```
+
+`SortExpression<T>` and `FilterExpression<T>` are exported from `apex-grid` for typed arrays.
+
+---
+
+## 7. Lifecycle Pattern
+
+```ts
+// 1. Register the custom element ONCE at app startup
+import 'apex-grid/define';
+// — or —
+import { ApexGrid } from 'apex-grid';
+ApexGrid.register();
+
+// 2. Stamp the element into the DOM
+import { html, render } from 'lit';
+render(html`<apex-grid></apex-grid>`, document.getElementById('app')!);
+
+// 3. Set properties (after the element is in the DOM)
+const grid = document.querySelector('apex-grid')!;
+grid.columns = [...];
+grid.data = [...];
+
+// 4. Listen for UI events
+grid.addEventListener('sorted', (e) => console.log(e.detail));
+
+// 5. Optional: programmatic operations
+grid.sort({ key: 'name', direction: 'ascending' });
+
+// 6. Removing the element from the DOM tears down its observers automatically.
+//    There is no destroy() — Lit's disconnectedCallback handles cleanup.
+```
+
+---
+
+## 8. Pitfalls — ❌ Wrong vs ✅ Correct
+
+### 1. Treating it like a class-based JS API
+❌ `const grid = new ApexGrid({ container: '#app', columns, data })` — this is a custom element, not a constructor.
+✅ Render `<apex-grid .data=${data} .columns=${columns}></apex-grid>` and let the DOM instantiate it.
+
+### 2. Forgetting to register the element
+❌ Importing `ApexGrid` but never calling `register()` — `<apex-grid>` renders as an inert tag.
+✅ `import 'apex-grid/define'` once, or `ApexGrid.register()` at app startup.
+
+### 3. Wrong package name
+❌ `import { ApexGrid } from 'apexgrid'` — the package is `apex-grid` (with a hyphen).
+✅ `import { ApexGrid } from 'apex-grid'`.
+
+### 4. Stringified `columns` attribute
+❌ `<apex-grid columns="[...]">` — attributes are strings; `columns` is an object array.
+✅ Property binding: `.columns=${columns}` (Lit), `:columns="columns"` (Vue), `[columns]="columns"` (Angular), or `el.columns = columns` (vanilla).
+
+### 5. `column.key` not a real key of `T`
+❌ `{ key: 'fullName' }` when `User` has only `firstName` / `lastName`.
+✅ Either rename the field on `User` or compute it via `cellTemplate`: `cellTemplate: ({ row }) => html\`${row.firstName} ${row.lastName}\``.
+
+### 6. Returning a string from `cellTemplate`
+❌ `cellTemplate: ({ value }) => \`<strong>\${value}</strong>\`` — renders as escaped text.
+✅ `cellTemplate: ({ value }) => html\`<strong>\${value}</strong>\``.
+
+### 7. Expecting events from programmatic calls
+❌ Listening for `sorting` after calling `grid.sort(...)` — never fires.
+✅ The UI-initiated path fires events; the programmatic path is silent. If you need a side-effect on every change, watch `grid.dataView` or wrap the call yourself.
+
+### 8. `sort: true` without setting `type`
+❌ Sorting numbers as strings: `{ key: 'age', sort: true }` with no `type`.
+✅ `{ key: 'age', type: 'number', sort: true }` — gets the correct comparer and filter operands.
+
+### 9. Looking for a `'date'` column type
+❌ `{ key: 'created', type: 'date' }` — there is no `'date'` type.
+✅ Store dates as numbers (timestamps) with `type: 'number'`, or as ISO strings with a custom `sort.comparer` and a `cellTemplate` that formats:
+```ts
+{
+  key: 'created',
+  type: 'string',
+  sort: { comparer: (a, b) => a.localeCompare(b) },
+  cellTemplate: ({ value }) => html`${new Date(value).toLocaleDateString()}`,
+}
+```
+
+### 10. Calling `clearSort()` to flush an empty array
+❌ `grid.sortExpressions = []` — the setter is a no-op for empty arrays.
+✅ `grid.clearSort()`.
+
+### 11. Querying all rows
+❌ `grid.rows.length === grid.data.length` — false; rows are virtualized.
+✅ Use `grid.totalItems` for the post-pipeline count, or `grid.dataView` for the post-pipeline rows.
+
+### 12. Auto-generating after replacing data
+❌ `grid.data = newData` with `autoGenerate: true` and existing columns — the old columns persist.
+✅ Reset first: `grid.columns = []; grid.data = newData;`.
+
+### 13. Mixing operand keys across types
+❌ `grid.filter({ key: 'age' /* number */, condition: 'contains' /* string operand */ })` — runtime error.
+✅ Match the operand to the column type (or import the typed operand: `NumberOperands.greaterThan`).
+
+### 14. Rendering before `register()` in the same task
+❌ Stamping `<apex-grid>` before the registration import has resolved — the element is upgraded later but properties set before upgrade may be lost.
+✅ Import `'apex-grid/define'` at the top of your entry file, then render.
+
+---
+
+## 9. Reference Routing Table
+
+| Topic | Reference File |
+|---|---|
+| Column configuration, types, templates, auto-generation | `references/columns-and-templates.md` |
+| Sort & filter — UI events, programmatic API, expressions, operands | `references/sort-and-filter.md` |
+| Server-side data pipeline, async hooks, virtualization notes | `references/data-pipeline.md` |
+| Framework integration — Lit, React, Vue, Angular | `references/framework-integration.md` |

package/index.js

@@ -0,0 +1,38 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const packageRoot = dirname(fileURLToPath(import.meta.url));
+
+/** Absolute path to the package root (where SKILL.md lives). */
+export const packageDir = packageRoot;
+
+/** Absolute path to SKILL.md (the top-level skill index). */
+export const skillFile = join(packageRoot, 'SKILL.md');
+
+/** Absolute path to the references/ directory containing per-topic markdown docs. */
+export const referencesDir = join(packageRoot, 'references');
+
+export const referenceFiles = [
+  'columns-and-templates.md',
+  'data-pipeline.md',
+  'framework-integration.md',
+  'sort-and-filter.md',
+];
+
+/** Resolve a reference file by its filename. Throws if not in the known list. */
+export function referencePath(filename) {
+  if (!referenceFiles.includes(filename)) {
+    throw new Error(
+      `Unknown reference file "${filename}". Known files: ${referenceFiles.join(', ')}`,
+    );
+  }
+  return join(referencesDir, filename);
+}
+
+export default {
+  packageDir,
+  skillFile,
+  referencesDir,
+  referenceFiles,
+  referencePath,
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "apexgrid-skill",
+  "version": "1.0.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",
+    "apexgrid",
+    "data-grid",
+    "grid",
+    "table",
+    "web-component",
+    "lit",
+    "ai",
+    "skill",
+    "claude",
+    "cursor",
+    "copilot",
+    "documentation",
+    "reference"
+  ],
+  "author": "ApexCharts <info@apexcharts.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/apexcharts/apexgrid-skill#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/apexcharts/apexgrid-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/apexcharts/apexgrid-skill/issues"
+  },
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./SKILL.md": "./SKILL.md",
+    "./references/*": "./references/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "SKILL.md",
+    "references"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/columns-and-templates.md

@@ -0,0 +1,191 @@
+# Column Configuration & Lit Templates
+
+## `ColumnConfiguration<T, K>`
+
+Apex Grid is generic over a row type `T extends object`. Every column is typed against a key `K extends keyof T` so the cell template's `value` is correctly inferred.
+
+```ts
+interface BaseColumnConfiguration<T extends object, K extends keyof T = keyof T> {
+  key: K;                                          // REQUIRED — keyof T
+  type?: 'string' | 'number' | 'boolean';          // default 'string'
+  headerText?: string;                             // default: String(key)
+  width?: string;                                  // any CSS width unit
+  hidden?: boolean;                                // default false
+  resizable?: boolean;                             // default false
+  sort?: boolean | { caseSensitive?: boolean; comparer?: (a: T[K], b: T[K]) => number };
+  filter?: boolean | { caseSensitive?: boolean };
+  headerTemplate?: (ctx: ApexHeaderContext<T>) => TemplateResult | unknown;
+  cellTemplate?: (ctx: ApexCellContext<T, K>) => TemplateResult | unknown;
+}
+```
+
+Defaults applied on assignment (`DEFAULT_COLUMN_CONFIG`):
+
+```ts
+{ type: 'string', resizable: false, hidden: false, sort: false, filter: false }
+```
+
+## Type field — what it actually does
+
+| `type` | Default sort comparer | Filter operands |
+|---|---|---|
+| `'string'` *(default)* | `String#localeCompare` (case-insensitive unless `caseSensitive: true`) | `contains`, `doesNotContain`, `startsWith`, `endsWith`, `equals`, `doesNotEqual`, `empty`, `notEmpty` |
+| `'number'` | numeric `<` / `>` | `equals`, `doesNotEqual`, `greaterThan`, `lessThan`, `greaterThanOrEqual`, `lessThanOrEqual`, `empty`, `notEmpty` |
+| `'boolean'` | `false < true` | `all`, `true`, `false`, `empty`, `notEmpty` |
+
+There is **no `'date'` type**. For dates:
+
+```ts
+// Option A — store as timestamps
+{ key: 'createdAt', type: 'number', sort: true, filter: true,
+  cellTemplate: ({ value }) => html`${new Date(value).toLocaleDateString()}` }
+
+// Option B — store as ISO strings + custom comparer
+{ key: 'createdAt', type: 'string',
+  sort: { comparer: (a, b) => a.localeCompare(b) },
+  cellTemplate: ({ value }) => html`${new Date(value).toLocaleDateString()}` }
+```
+
+## Sort configuration per column
+
+```ts
+// Boolean shorthand — uses the type-default comparer
+{ key: 'name', sort: true }
+
+// Object form — case-sensitive comparison
+{ key: 'name', sort: { caseSensitive: true } }
+
+// Custom comparer (overrides the type-default)
+{ key: 'priority',
+  type: 'string',
+  sort: { comparer: (a, b) => ['low','standard','high'].indexOf(a) - ['low','standard','high'].indexOf(b) },
+}
+```
+
+The `comparer` signature is fully typed against `T[K]`.
+
+## Filter configuration per column
+
+```ts
+{ key: 'name', filter: true }                              // case-insensitive
+{ key: 'name', filter: { caseSensitive: true } }           // case-sensitive
+```
+
+There is no per-column `defaultOperand` field — operands come from `type`.
+
+## Cell template (`cellTemplate`)
+
+Receives `ApexCellContext<T, K>`:
+
+```ts
+interface BaseApexCellContext<T, K> {
+  parent: ApexGridCell<T>;          // <apex-grid-cell> element
+  row:    ApexGridRow<T>;           // <apex-grid-row> element
+  column: ColumnConfiguration<T, K>;
+  value:  T[K];                     // T[K] — fully typed
+}
+```
+
+```ts
+import { html } from 'lit';
+
+const columns: ColumnConfiguration<User>[] = [
+  // Direct value — no template needed
+  { key: 'id', type: 'number' },
+
+  // Inline emphasis
+  { key: 'name',
+    cellTemplate: ({ value }) => html`<strong>${value}</strong>` },
+
+  // Conditional render with row context
+  { key: 'subscribed', type: 'boolean',
+    cellTemplate: ({ value, row }) => html`
+      <input type="checkbox" .checked=${value} disabled />
+      <small>${row.name}</small>` },
+
+  // Embedded igniteui-webcomponents control
+  { key: 'avatar',
+    cellTemplate: ({ value }) => html`<igc-avatar shape="circle" .src=${value}></igc-avatar>` },
+
+  // Rating widget tied to data type
+  { key: 'satisfaction', type: 'number',
+    cellTemplate: ({ value }) => html`<igc-rating readonly .value=${value}></igc-rating>` },
+];
+```
+
+**Templates must return `TemplateResult`** (the value of an `html\`...\`` literal). Returning a string renders as escaped text.
+
+## Header template (`headerTemplate`)
+
+Receives `ApexHeaderContext<T>`:
+
+```ts
+interface ApexHeaderContext<T> {
+  parent: ApexGridHeader<T>;
+  column: ColumnConfiguration<T>;
+}
+```
+
+```ts
+{
+  key: 'age',
+  headerTemplate: ({ column }) => html`
+    <span style="display:flex;align-items:center;gap:4px;">
+      <span>${column.headerText ?? String(column.key)}</span>
+      <small style="opacity:.6;">(yrs)</small>
+    </span>`,
+}
+```
+
+## Auto-generation
+
+```ts
+<apex-grid auto-generate .data=${data}></apex-grid>
+```
+
+- Reads `Object.keys(data[0])` and creates a column for each, using the value's runtime type to pick `type`.
+- **Skipped entirely if `columns` is non-empty.** Set `grid.columns = []` before swapping data to re-trigger.
+- Late-bound data (e.g. fetched after first render) infers correctly because the watcher re-runs on `data` changes — but only when `columns` is still empty.
+
+## Updating columns at runtime
+
+```ts
+// Replace the whole array (any change re-applies DEFAULT_COLUMN_CONFIG)
+grid.columns = [...newColumns];
+
+// Patch existing columns by key (preserves order, merges fields)
+grid.updateColumns({ key: 'name', hidden: true });
+grid.updateColumns([
+  { key: 'age',  width: '120px' },
+  { key: 'name', headerText: 'Full Name' },
+]);
+```
+
+`updateColumns` triggers the data pipeline (so any sort/filter state is re-applied). It does **not** add new columns — only existing keys are patched.
+
+## Hidden columns
+
+```ts
+{ key: 'internalId', hidden: true }
+```
+
+Column data is still accessible via `grid.dataView` and the cell template's `row` context, but no cell or header is rendered for it. Toggle at runtime via `updateColumns`.
+
+## Resizable columns
+
+```ts
+{ key: 'name', resizable: true, width: '200px' }
+```
+
+The grid renders a drag handle on the right edge of the column header. Minimum resize width is hard-coded to `80px`.
+
+## Common pitfalls
+
+| ❌ | ✅ |
+|---|---|
+| `{ key: 'fullName' }` when `fullName` isn't in `T` | Add to `T`, or compute via `cellTemplate: ({ row }) => html\`${row.firstName} ${row.lastName}\`` |
+| `cellTemplate: ({ value }) => \`<b>\${value}</b>\`` (string) | `cellTemplate: ({ value }) => html\`<b>\${value}</b>\`` |
+| `{ key: 'age', sort: true }` (default `type: 'string'`) | Set `type: 'number'` |
+| `{ key: 'created', type: 'date' }` | No `'date'` type — use timestamp + `'number'` or ISO + custom `comparer` |
+| `auto-generate` with existing columns | Reset `grid.columns = []` first |
+| `updateColumns({ key: 'newField', ... })` to add | `updateColumns` only patches existing — assign a new `columns` array to add |

package/references/data-pipeline.md

@@ -0,0 +1,149 @@
+# Data Pipeline — Server-Side, Async, Virtualization
+
+## How the pipeline runs
+
+When `data`, `columns`, sort state, or filter state changes, Apex Grid runs an async pipeline:
+
+```
+data ─► (filter) ─► (sort) ─► dataState ─► virtualizer ─► rendered rows
+```
+
+By default both stages run in-memory. Override either stage (or both) with `dataPipelineConfiguration`.
+
+## `dataPipelineConfiguration`
+
+```ts
+interface DataPipelineConfiguration<T extends object> {
+  sort?:   (state: { data: T[]; grid: ApexGrid<T>; type: 'sort'   }) => T[] | Promise<T[]>;
+  filter?: (state: { data: T[]; grid: ApexGrid<T>; type: 'filter' }) => T[] | Promise<T[]>;
+}
+```
+
+The grid invokes the matching hook in place of its built-in pipeline stage. Whatever the hook returns becomes the new `dataState` for the next stage (or the final view).
+
+```ts
+grid.dataPipelineConfiguration = {
+  sort: async ({ data, grid }) => {
+    const expr = grid.sortExpressions;
+    const res = await fetch('/api/users/sort', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(expr),
+    });
+    return res.json() as Promise<User[]>;
+  },
+  filter: async ({ data, grid }) => {
+    const expr = grid.filterExpressions;
+    const res = await fetch('/api/users/filter', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(expr),
+    });
+    return res.json() as Promise<User[]>;
+  },
+};
+```
+
+### Hook-only sort, in-memory filter (or vice versa)
+
+Just omit one of the two:
+
+```ts
+grid.dataPipelineConfiguration = {
+  filter: async ({ grid }) => fetchFilteredFromServer(grid.filterExpressions),
+  // sort omitted — uses the built-in in-memory sort on the filtered data the hook returns
+};
+```
+
+### Order of operations
+
+The grid runs **filter first, then sort** — and that ordering is fixed. If your server endpoint sorts and filters together, do both in the `filter` hook (returning the fully sorted+filtered array) and skip the `sort` hook.
+
+### Hooks fire on every state change
+
+The pipeline runs whenever `data`, `columns`, sort state, or filter state changes — including programmatic `sort()` / `filter()` calls. If your server endpoint is expensive, debounce inside the hook:
+
+```ts
+let pending: AbortController | null = null;
+grid.dataPipelineConfiguration = {
+  filter: async ({ grid }) => {
+    pending?.abort();
+    pending = new AbortController();
+    const res = await fetch('/api/users/filter', {
+      method: 'POST',
+      body: JSON.stringify(grid.filterExpressions),
+      signal: pending.signal,
+    });
+    return res.json();
+  },
+};
+```
+
+### Hooks have access to the grid instance
+
+Use it to read the latest sort / filter state, query metadata, or trigger follow-up operations:
+
+```ts
+grid.dataPipelineConfiguration = {
+  sort: async ({ data, grid }) => {
+    const expressions = grid.sortExpressions;
+    const customComparer = grid.getColumn('priority')?.sort;       // ColumnSortConfiguration
+    // ...
+  },
+};
+```
+
+## Virtualization
+
+Apex Grid uses [`@lit-labs/virtualizer`](https://www.npmjs.com/package/@lit-labs/virtualizer) (`<apex-virtualizer>`) for row recycling. **Only currently visible rows + a small overscan are present in the DOM.**
+
+| API | What it returns |
+|---|---|
+| `grid.rows` | `ApexGridRow<T>[]` — only the rendered chunk |
+| `grid.dataView` | `readonly T[]` — full post-pipeline data (all rows) |
+| `grid.totalItems` | `number` — `dataView.length` |
+
+Implications:
+
+- **Don't size the grid based on `grid.rows.length`.** Use `grid.totalItems`.
+- **Don't hold references to `<apex-grid-row>` elements** across scrolls — they get recycled.
+- **DOM-driven row queries** (`document.querySelectorAll('apex-grid-row')`) only see visible rows.
+
+## When the pipeline runs
+
+Internally the grid watches the `'pipeline'` reactive symbol. It runs after:
+
+- `data` is reassigned
+- `columns` is reassigned (or `updateColumns` is called)
+- A sort operation is applied (UI or programmatic)
+- A filter operation is applied (UI or programmatic)
+- Sort / filter state is cleared
+
+It does **not** run when only column properties like `width` / `hidden` / `resizable` change, since those are presentational.
+
+## `dataView` for derived UI
+
+`dataView` is the canonical source of truth for "what's on screen after the pipeline":
+
+```ts
+// React-style consumer outside the grid (e.g. a footer summary)
+const updateSummary = () => {
+  const view = grid.dataView;
+  document.getElementById('count')!.textContent = `${view.length} rows`;
+  document.getElementById('avg')!.textContent =
+    String(view.reduce((s, u) => s + u.age, 0) / view.length);
+};
+
+grid.addEventListener('sorted', updateSummary);
+grid.addEventListener('filtered', updateSummary);
+```
+
+## Common pitfalls
+
+| ❌ | ✅ |
+|---|---|
+| Reading `grid.rows.length` for total count | `grid.totalItems` (or `grid.dataView.length`) |
+| Caching `<apex-grid-row>` references across scrolls | Look them up fresh from `grid.rows` (or operate on `grid.dataView` data) |
+| Re-fetching from the server only on UI events | Hooks fire for both UI and programmatic — debounce / abort inside the hook |
+| Sorting in the `filter` hook expecting it to override the built-in sort | The grid still runs the built-in sort after your filter hook unless you also supply a `sort` hook |
+| Returning a Promise that rejects | Errors propagate; the grid keeps the previous `dataView`. Catch + log inside the hook to surface failures |

package/references/framework-integration.md

@@ -0,0 +1,203 @@
+# Framework Integration — Lit, React, Vue, Angular
+
+`apex-grid` is a standard custom element with no first-party framework wrappers. Every framework consumes it the same way: register the tag once, then bind `data` and `columns` as **properties** (not attributes) and listen for `sorting` / `sorted` / `filtering` / `filtered` events.
+
+## Lit (recommended)
+
+The most natural host — Lit `html` templates already understand the `.property` and `@event` binding syntax.
+
+```ts
+import 'apex-grid/define';
+import { html, render } from 'lit';
+import type { ColumnConfiguration } from 'apex-grid';
+
+type User = { id: number; name: string; age: number; subscribed: boolean };
+
+const data: User[] = [/* … */];
+const columns: ColumnConfiguration<User>[] = [
+  { key: 'id', type: 'number', sort: true, filter: true },
+  { key: 'name', type: 'string', sort: true, filter: true,
+    cellTemplate: ({ value }) => html`<strong>${value}</strong>` },
+  { key: 'age', type: 'number', sort: true, filter: true },
+  { key: 'subscribed', type: 'boolean', sort: true, filter: true },
+];
+
+render(
+  html`<apex-grid
+    .data=${data}
+    .columns=${columns}
+    @sorted=${(e) => console.log('sorted', e.detail)}
+    @filtered=${(e) => console.log('filtered', e.detail)}
+  ></apex-grid>`,
+  document.getElementById('app')!,
+);
+```
+
+## React
+
+React 19+ supports custom elements natively, including property binding via `ref` for non-string values. For broad compatibility, use a `useEffect` + `ref` pattern:
+
+```tsx
+import { useEffect, useRef } from 'react';
+import 'apex-grid/define';
+import type { ApexGrid, ColumnConfiguration } from 'apex-grid';
+import { html } from 'lit';
+
+type User = { id: number; name: string; age: number; subscribed: boolean };
+
+export function UsersGrid({ data }: { data: User[] }) {
+  const ref = useRef<ApexGrid<User> | null>(null);
+
+  useEffect(() => {
+    const grid = ref.current;
+    if (!grid) return;
+
+    grid.columns = [
+      { key: 'id',         type: 'number',  sort: true, filter: true },
+      { key: 'name',       type: 'string',  sort: true, filter: true,
+        cellTemplate: ({ value }) => html`<strong>${value}</strong>` },
+      { key: 'age',        type: 'number',  sort: true, filter: true },
+      { key: 'subscribed', type: 'boolean', sort: true, filter: true },
+    ];
+
+    const onSorted = (e: Event) => console.log('sorted', (e as CustomEvent).detail);
+    grid.addEventListener('sorted', onSorted);
+    return () => grid.removeEventListener('sorted', onSorted);
+  }, []);
+
+  // Set data whenever it changes
+  useEffect(() => {
+    if (ref.current) ref.current.data = data;
+  }, [data]);
+
+  // @ts-expect-error — apex-grid is a custom element
+  return <apex-grid ref={ref} style={{ height: '500px', display: 'block' }} />;
+}
+```
+
+For full TypeScript / JSX intrinsic-element support, declare:
+
+```ts
+// apex-grid.d.ts
+import type { ApexGrid } from 'apex-grid';
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'apex-grid': React.DetailedHTMLProps<React.HTMLAttributes<ApexGrid<any>>, ApexGrid<any>>;
+    }
+  }
+}
+```
+
+## Vue 3
+
+Vue understands property binding for custom elements out of the box. Mark `apex-grid` as a custom element in the compiler config so Vue doesn't try to resolve it as a Vue component:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('apex-') } } }),
+  ],
+});
+```
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue';
+import 'apex-grid/define';
+import { html } from 'lit';
+import type { ApexGrid, ColumnConfiguration } from 'apex-grid';
+
+type User = { id: number; name: string; age: number; subscribed: boolean };
+
+const grid = ref<ApexGrid<User> | null>(null);
+
+const data = ref<User[]>([/* … */]);
+const columns: ColumnConfiguration<User>[] = [
+  { key: 'id',         type: 'number',  sort: true, filter: true },
+  { key: 'name',       type: 'string',  sort: true, filter: true,
+    cellTemplate: ({ value }) => html`<strong>${value}</strong>` },
+  { key: 'age',        type: 'number',  sort: true, filter: true },
+  { key: 'subscribed', type: 'boolean', sort: true, filter: true },
+];
+
+onMounted(() => {
+  grid.value!.columns = columns;
+});
+
+function onSorted(e: CustomEvent) {
+  console.log('sorted', e.detail);
+}
+</script>
+
+<template>
+  <apex-grid
+    ref="grid"
+    :data.prop="data"
+    @sorted="onSorted"
+    style="height: 500px; display: block;"
+  />
+</template>
+```
+
+> Use `:data.prop="data"` (or set via `ref` in `onMounted`) to bind as a property. Vue's default `:data="data"` sets an attribute (a stringified object) which `apex-grid` will not read.
+
+## Angular
+
+Add `CUSTOM_ELEMENTS_SCHEMA` to the module / standalone component, then use property binding `[data]="..."` and event binding `(sorted)="..."`:
+
+```ts
+// app.component.ts
+import { Component, CUSTOM_ELEMENTS_SCHEMA, OnInit, ViewChild, ElementRef } from '@angular/core';
+import 'apex-grid/define';
+import { html } from 'lit';
+import type { ApexGrid, ColumnConfiguration } from 'apex-grid';
+
+type User = { id: number; name: string; age: number; subscribed: boolean };
+
+@Component({
+  selector: 'app-users-grid',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `
+    <apex-grid
+      #grid
+      [data]="data"
+      (sorted)="onSorted($event)"
+      style="height: 500px; display: block;"
+    ></apex-grid>
+  `,
+})
+export class UsersGridComponent implements OnInit {
+  @ViewChild('grid', { static: true }) grid!: ElementRef<ApexGrid<User>>;
+
+  data: User[] = [/* … */];
+
+  ngOnInit() {
+    this.grid.nativeElement.columns = [
+      { key: 'id',         type: 'number',  sort: true, filter: true },
+      { key: 'name',       type: 'string',  sort: true, filter: true,
+        cellTemplate: ({ value }) => html`<strong>${value}</strong>` },
+      { key: 'age',        type: 'number',  sort: true, filter: true },
+      { key: 'subscribed', type: 'boolean', sort: true, filter: true },
+    ];
+  }
+
+  onSorted(e: Event) {
+    console.log('sorted', (e as CustomEvent).detail);
+  }
+}
+```
+
+## Common pitfalls across frameworks
+
+| ❌ | ✅ |
+|---|---|
+| Vue: `:data="data"` (attribute, becomes `"[object Object]"`) | `:data.prop="data"` or set via `ref` in `onMounted` |
+| React: `<apex-grid columns={[...]}>` before React 19 (passes as attribute) | Use `ref` + `useEffect` to set as property, or React 19+ |
+| Angular: missing `CUSTOM_ELEMENTS_SCHEMA` | Add to the component / module schemas |
+| All: forgetting to register the element | Top-level `import 'apex-grid/define'` once |
+| Lit: writing string templates instead of `html` literals | Always import `html` from `lit` and use tagged literals |
+| Treating `cellTemplate` as framework-specific JSX | Always use Lit `html\`...\`` — the template runs inside the web component, not in the host framework |

package/references/sort-and-filter.md

@@ -0,0 +1,203 @@
+# Sort & Filter — Operands, Expressions, Events
+
+## Sort
+
+### Sort expression shape
+
+```ts
+interface BaseSortExpression<T, K extends keyof T> {
+  key: K;                                          // target column
+  direction: 'ascending' | 'descending' | 'none';
+  caseSensitive?: boolean;                         // overrides column config
+  comparer?: (a: T[K], b: T[K]) => number;         // overrides column config
+}
+```
+
+`'none'` is the explicit reset state and only meaningful when `sortConfiguration.triState: true`.
+
+### Programmatic sort
+
+```ts
+grid.sort({ key: 'name', direction: 'ascending' });
+grid.sort({ key: 'age', direction: 'descending' });
+
+// Multi-column (requires sortConfiguration.multiple === true, default true)
+grid.sort([
+  { key: 'subscribed', direction: 'descending' },
+  { key: 'age',        direction: 'ascending' },
+]);
+
+// Override the column comparer for this operation
+grid.sort({
+  key: 'priority',
+  direction: 'ascending',
+  comparer: (a, b) => ['low', 'standard', 'high'].indexOf(a) - ['low', 'standard', 'high'].indexOf(b),
+});
+```
+
+`grid.sort(...)` does **not** fire `sorting` / `sorted` events.
+
+### Reading the active sort state
+
+```ts
+grid.sortExpressions;            // SortExpression<T>[]
+```
+
+The array is in the order operations were applied (insertion order on the underlying `Map`).
+
+### Clearing sort
+
+```ts
+grid.clearSort();                // clear everything
+grid.clearSort('name');          // clear only the `name` column
+```
+
+> **Heads-up:** assigning an empty array (`grid.sortExpressions = []`) is a no-op. Always call `clearSort()` to reset.
+
+### `sortConfiguration`
+
+```ts
+grid.sortConfiguration = {
+  multiple: true,                // default — allow multi-column sort
+  triState: true,                // default — clicking a sorted-asc column twice goes ascending → descending → none
+};
+```
+
+## Filter
+
+### Filter expression shape
+
+```ts
+interface BaseFilterExpression<T, K extends keyof T> {
+  key: K;
+  condition: FilterOperation<T[K]> | OperandKeys<T[K]>;   // operand object or string key
+  searchTerm?: T[K];                                       // optional for unary operands (empty / notEmpty / true / false / all)
+  criteria?: 'and' | 'or';                                 // for combining with previous expression on same column
+  caseSensitive?: boolean;                                 // overrides column config
+}
+```
+
+### Operand sets
+
+```ts
+import { StringOperands, NumberOperands, BooleanOperands } from 'apex-grid';
+```
+
+| Type | Operand keys |
+|---|---|
+| `'string'` | `contains`, `doesNotContain`, `startsWith`, `endsWith`, `equals`, `doesNotEqual`, `empty`, `notEmpty` |
+| `'number'` | `equals`, `doesNotEqual`, `greaterThan`, `lessThan`, `greaterThanOrEqual`, `lessThanOrEqual`, `empty`, `notEmpty` |
+| `'boolean'` | `all`, `true`, `false`, `empty`, `notEmpty` |
+
+Unary operands (no `searchTerm` needed): `empty`, `notEmpty`, `all`, `true`, `false`.
+
+### Programmatic filter
+
+```ts
+// String operand by name
+grid.filter({ key: 'name', condition: 'contains', searchTerm: 'ada' });
+
+// String operand by reference (typed)
+grid.filter({ key: 'name', condition: StringOperands.contains, searchTerm: 'ada' });
+
+// Number operand
+grid.filter({ key: 'age', condition: 'greaterThan', searchTerm: 30 });
+
+// Boolean operand
+grid.filter({ key: 'subscribed', condition: 'true' });
+
+// Unary — no searchTerm
+grid.filter({ key: 'avatar', condition: 'empty' });
+
+// Combined AND / OR
+grid.filter([
+  { key: 'age', condition: 'greaterThan', searchTerm: 30 },
+  { key: 'age', condition: 'lessThan',    searchTerm: 50, criteria: 'and' },
+]);
+grid.filter([
+  { key: 'priority', condition: 'equals', searchTerm: 'high' },
+  { key: 'priority', condition: 'equals', searchTerm: 'standard', criteria: 'or' },
+]);
+```
+
+`grid.filter(...)` does **not** fire `filtering` / `filtered` events.
+
+### Reading the active filter state
+
+```ts
+grid.filterExpressions;          // FilterExpression<T>[]
+```
+
+Combined across columns. To get state for a single column, find by `key`:
+
+```ts
+const ageFilters = grid.filterExpressions.filter((e) => e.key === 'age');
+```
+
+### Clearing filter
+
+```ts
+grid.clearFilter();              // clear everything
+grid.clearFilter('age');         // clear only the `age` column
+```
+
+## Events
+
+```ts
+// UI-initiated sort about to apply — cancellable, mutable
+grid.addEventListener('sorting', (e) => {
+  // e: CustomEvent<SortExpression<T>>
+  if (e.detail.key === 'id') e.preventDefault();        // veto
+  if (e.detail.direction === 'descending')              // rewrite
+    e.detail.direction = 'ascending';
+});
+
+// UI-initiated sort completed
+grid.addEventListener('sorted', (e) => {
+  // e: CustomEvent<SortExpression<T>>
+});
+
+// UI-initiated filter about to apply — cancellable, mutable
+grid.addEventListener('filtering', (e) => {
+  // e: CustomEvent<{ key, expressions, type: 'add'|'modify'|'remove' }>
+});
+
+// UI-initiated filter completed
+grid.addEventListener('filtered', (e) => {
+  // e: CustomEvent<{ key, state: FilterExpression<T>[] }>
+});
+```
+
+| Event | Cancellable | `event.detail` | Fires for programmatic? |
+|---|---|---|---|
+| `sorting` | yes | `SortExpression<T>` (mutable) | no |
+| `sorted` | no | `SortExpression<T>` | no |
+| `filtering` | yes | `{ key, expressions, type }` | no |
+| `filtered` | no | `{ key, state }` | no |
+
+If you need a side-effect on every change regardless of source, watch `grid.dataView` (after `requestUpdate` / via `updated()` in a Lit parent) or wrap your programmatic calls.
+
+## Combining UI + programmatic operations
+
+UI operations and programmatic operations write to the **same underlying state** (the `StateController`). Order matters:
+
+```ts
+// Persisting and restoring state across mounts
+const savedSort = grid.sortExpressions;
+const savedFilter = grid.filterExpressions;
+
+// ... later, after re-mounting
+grid.sort(savedSort);
+grid.filter(savedFilter);
+```
+
+## Common pitfalls
+
+| ❌ | ✅ |
+|---|---|
+| Listening for events on programmatic calls | Wrap the call yourself, or watch `grid.dataView` |
+| `grid.filter({ key: 'age', condition: 'contains' })` (string operand on number column) | Match operand to type — `condition: 'greaterThan'` for number columns |
+| `grid.sortExpressions = []` to clear | `grid.clearSort()` |
+| Multi-column sort with `sortConfiguration.multiple = false` | Either set `multiple: true` or call `grid.sort` with a single expression |
+| Forgetting `searchTerm` on a non-unary operand | Add `searchTerm`, or use a unary operand (`empty` / `notEmpty` / `true` / `false` / `all`) |
+| Mutating `e.detail` in a `sorted` / `filtered` listener | Only `sorting` / `filtering` are cancellable / mutable; the post-events are read-only by design |