apexgrid-skill 1.0.0 → 2.0.0

package/index.js

@@ -17,6 +17,7 @@ export const referenceFiles = [
   'data-pipeline.md',
   'framework-integration.md',
   'sort-and-filter.md',
+  'vanilla-js.md',
 ];
 
 /** Resolve a reference file by its filename. Throws if not in the known list. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apexgrid-skill",
-  "version": "1.0.0",
+  "version": "2.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",

package/references/columns-and-templates.md

@@ -1,5 +1,11 @@
 # Column Configuration & Lit Templates
 
+> **Before you start**: this reference assumes the Quickstart setup from `SKILL.md` is done — element registered and the host element sized (e.g. `setup()`). **No theme CSS import is needed**; the grid self-styles via `--ag-*` CSS variables. Without a sized host, no column configuration will produce a visible grid.
+
+## A note on column widths
+
+If you omit `width`, the column flex-fills the remaining space. With one un-widthed column among several explicit ones, that column **stretches to fill the grid** — including pushing its sort arrow to the far edge of the viewport, which looks like a phantom column. For predictable layouts, set explicit widths on every column.
+
 ## `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.
@@ -7,18 +13,38 @@ Apex Grid is generic over a row type `T extends object`. Every column is typed a
 ```ts
 interface BaseColumnConfiguration<T extends object, K extends keyof T = keyof T> {
   key: K;                                          // REQUIRED — keyof T
-  type?: 'string' | 'number' | 'boolean';          // default 'string'
+  type?: DataType;                                 // default 'string' (see "Column types" below)
   headerText?: string;                             // default: String(key)
   width?: string;                                  // any CSS width unit
   hidden?: boolean;                                // default false
   resizable?: boolean;                             // default false
+  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
+  editable?: boolean;                              // requires grid editing.enabled
   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;
+  editorTemplate?: (ctx: ApexEditorContext<T, K>) => TemplateResult | unknown;
+  // type-specific (ignored unless `type` matches):
+  options?: (V | { value: V; label?: string })[]; // 'select'
+  max?: number;                                    // 'rating' (stars, def 5) / 'progress' (full, def 100)
+  format?: 'short' | 'medium' | 'long' | 'full';   // 'date' (def 'medium')
+  shape?: 'square' | 'circle';                     // 'image' (def 'square')
+  alt?: string;                                    // 'image' alt text
+  currency?: string;                               // 'currency' ISO 4217 (def 'USD')
+  locale?: string;                                 // 'currency' BCP 47 locale
+  badgeVariant?: 'gold' | 'brand' | 'neutral' | 'muted' | ((v) => …);  // 'badge'
+  statusVariant?: 'active' | 'trial' | 'churn' | ((v) => …);           // 'status'
+  showDelta?: boolean;                             // 'sparkline' (def true)
 }
 ```
 
+### Column types (`DataType`)
+
+`'string'` / `'number'` / `'boolean'` are the primitive types driving sort, filter, and the default editor. The rest are presentation renderers over a primitive value (and sort/filter as that value): `'select'` (label from `options`, `<select>` editor), `'rating'` (stars, 0..`max`), `'date'` (locale date via `format`; accepts `Date`/ISO/timestamp; `<input type="date">` editor), `'image'` (`<img>`, `shape`/`alt`), `'currency'` (`Intl.NumberFormat`, `currency`/`locale`), `'avatar'`, `'badge'` (`badgeVariant`), `'progress'` (0..`max`), `'sparkline'` (`number[]`, `showDelta`), `'status'` (`statusVariant`).
+
 Defaults applied on assignment (`DEFAULT_COLUMN_CONFIG`):
 
 ```ts
@@ -33,17 +59,10 @@ Defaults applied on assignment (`DEFAULT_COLUMN_CONFIG`):
 | `'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:
+The table above lists the three **primitive** types. The presentation types (`'select'`, `'rating'`, `'date'`, `'image'`, `'currency'`, `'avatar'`, `'badge'`, `'progress'`, `'sparkline'`, `'status'`) sort and filter as their underlying value. For dates, use the real `'date'` type — it accepts `Date`, ISO strings, or millisecond timestamps, renders a locale date (`format`), and sorts chronologically. No timestamp/comparer workaround needed:
 
 ```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()}` }
+{ key: 'createdAt', type: 'date', format: 'medium', sort: true, filter: true }
 ```
 
 ## Sort configuration per column
@@ -137,16 +156,39 @@ interface ApexHeaderContext<T> {
 }
 ```
 
-## Auto-generation
+## Auto-generation — the fastest demo
+
+The shortest possible "just show me a table" example:
 
 ```ts
-<apex-grid auto-generate .data=${data}></apex-grid>
+import { html, render } from 'lit';
+import { setup } from 'apex-grid';
+setup();
+
+const data = [
+  { id: 1, name: 'Ada',  age: 36 },
+  { id: 2, name: 'Carl', age: 62 },
+];
+
+render(
+  html`<apex-grid auto-generate .data=${data}></apex-grid>`,
+  document.getElementById('app')!,
+);
 ```
 
+> Remember the host CSS — `apex-grid { height: 480px; }` — or you'll see no rows even with `auto-generate`.
+
+**How it works:**
+
 - 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.
 
+**Caveats:**
+
+- `sort` and `filter` default to `false`, so the auto path is read-only. To get sortable / filterable columns from inferred data, run auto-generate first then patch via `grid.updateColumns([{ key: 'name', sort: true, filter: true }, ...])`.
+- Auto-generated columns get no explicit `width` — they flex-fill across the grid. For mixed-type columns that's usually not what you want; assign explicit `columns` instead.
+
 ## Updating columns at runtime
 
 ```ts
@@ -186,6 +228,6 @@ The grid renders a drag handle on the right edge of the column header. Minimum r
 | `{ 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` |
+| `{ key: 'created', type: 'string', sort: { comparer } }` to fake dates | `{ key: 'created', type: 'date', format: 'medium' }` — a real type (accepts `Date`/ISO/timestamp) |
 | `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

@@ -2,24 +2,29 @@
 
 ## How the pipeline runs
 
-When `data`, `columns`, sort state, or filter state changes, Apex Grid runs an async pipeline:
+When `data`, `columns`, sort state, filter state, the quick-filter value, or the page changes, Apex Grid runs an async pipeline:
 
 ```
-data ─► (filter) ─► (sort) ─► dataState ─► virtualizer ─► rendered rows
+data ─► (quickFilter) ─► (filter) ─► (sort) ─► (pagination) ─► virtualizer ─► rendered rows
 ```
 
-By default both stages run in-memory. Override either stage (or both) with `dataPipelineConfiguration`.
+By default every stage runs in-memory. Override any stage with `dataPipelineConfiguration`.
 
 ## `dataPipelineConfiguration`
 
 ```ts
+type DataPipelineParams<T> = { data: T[]; grid: ApexGrid<T>; type: 'sort' | 'filter' | 'quickFilter' | 'pagination' };
+type DataPipelineHook<T>   = (state: DataPipelineParams<T>) => T[] | Promise<T[]>;
+
 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[]>;
+  sort?:        DataPipelineHook<T>;
+  filter?:      DataPipelineHook<T>;   // column filters
+  quickFilter?: DataPipelineHook<T>;   // global search (runs before column filter)
+  pagination?:  DataPipelineHook<T>;   // return the page slice; remote: set pagination.totalItems
 }
 ```
 
-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).
+The grid invokes the matching hook in place of its built-in pipeline stage. Whatever the hook returns becomes the input for the next stage (or the final view). All four hooks are optional — omit a stage to keep it in-memory.
 
 ```ts
 grid.dataPipelineConfiguration = {
@@ -57,7 +62,7 @@ grid.dataPipelineConfiguration = {
 
 ### 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.
+The grid runs the stages in a fixed order: **quick-filter → column filter → sort → pagination**. If your server endpoint does several of these together, do the work in the earliest relevant hook (returning the fully processed array) and omit the later hooks. For server-driven paging, return the current page from the `pagination` hook and set `grid.pagination = { ..., mode: 'remote', totalItems }` so the paginator can compute the page count.
 
 ### Hooks fire on every state change
 

package/references/framework-integration.md

@@ -1,13 +1,46 @@
 # 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.
+`apex-grid` is a standard custom element with no first-party framework wrappers. Every framework consumes it the same way:
 
-## Lit (recommended)
+1. **Register the element + size the host once at app startup** — `setup()` does both (registers `<apex-grid>` and adopts a bounded host height). No theme CSS import is needed; the grid self-styles via `--ag-*` variables.
+2. **Bind `data` and `columns` as properties** (not attributes).
+3. **Listen for `sorting` / `sorted` / `filtering` / `filtered` (and the other UI) events** as standard DOM events.
 
-The most natural host — Lit `html` templates already understand the `.property` and `@event` binding syntax.
+The `setup()` call ideally lives in your application entry file (`main.ts` / `main.js` / `app.module.ts`) so it runs once, not per component.
+
+---
+
+## App-entry setup (all frameworks)
+
+Put this at the top of your application entry point — `src/main.ts` for Vite/Lit/Vue, `src/index.tsx` for React, `src/main.ts` for Angular:
+
+```ts
+import { setup } from 'apex-grid';
+setup();                         // registers <apex-grid> + adopts a bounded host height
+```
+
+No theme import needed — the grid self-styles. Retheme by overriding `--ag-*` CSS variables on `apex-grid`. If you prefer manual control over sizing, call `setup({ hostStyles: false })` (or use `import 'apex-grid/define'`) and add your own rule:
+
+```css
+apex-grid {
+  height: 480px;     /* or whatever fits your layout; + any --ag-* overrides */
+}
+```
+
+The framework examples below assume this app-entry setup is already done.
+
+---
+
+## Lit
+
+The most natural host — Lit `html` templates already understand `.property` and `@event` binding syntax.
 
 ```ts
-import 'apex-grid/define';
+// src/main.ts — done once
+import { setup } from 'apex-grid';
+setup();
+
+// component
 import { html, render } from 'lit';
 import type { ColumnConfiguration } from 'apex-grid';
 
@@ -15,11 +48,11 @@ 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,
+  { key: 'id',         type: 'number',  width: '80px',  sort: true, filter: true },
+  { key: 'name',       type: 'string',  width: '240px', sort: true, filter: true,
     cellTemplate: ({ value }) => html`<strong>${value}</strong>` },
-  { key: 'age', type: 'number', sort: true, filter: true },
-  { key: 'subscribed', type: 'boolean', 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(
@@ -33,15 +66,16 @@ render(
 );
 ```
 
+---
+
 ## React
 
-React 19+ supports custom elements natively, including property binding via `ref` for non-string values. For broad compatibility, use a `useEffect` + `ref` pattern:
+React 19+ supports custom elements natively, including property binding for non-string values. For broad compatibility, use `ref` + `useEffect`:
 
 ```tsx
 import { useEffect, useRef } from 'react';
-import 'apex-grid/define';
+import { html } from 'lit';                              // required for cellTemplate
 import type { ApexGrid, ColumnConfiguration } from 'apex-grid';
-import { html } from 'lit';
 
 type User = { id: number; name: string; age: number; subscribed: boolean };
 
@@ -53,11 +87,11 @@ export function UsersGrid({ data }: { data: User[] }) {
     if (!grid) return;
 
     grid.columns = [
-      { key: 'id',         type: 'number',  sort: true, filter: true },
-      { key: 'name',       type: 'string',  sort: true, filter: true,
+      { key: 'id',         type: 'number',  width: '80px',  sort: true, filter: true },
+      { key: 'name',       type: 'string',  width: '240px', sort: true, filter: true,
         cellTemplate: ({ value }) => html`<strong>${value}</strong>` },
-      { key: 'age',        type: 'number',  sort: true, filter: true },
-      { key: 'subscribed', type: 'boolean', sort: true, filter: true },
+      { key: 'age',        type: 'number',  width: '100px', sort: true, filter: true },
+      { key: 'subscribed', type: 'boolean', width: '140px', sort: true, filter: true },
     ];
 
     const onSorted = (e: Event) => console.log('sorted', (e as CustomEvent).detail);
@@ -65,20 +99,22 @@ export function UsersGrid({ data }: { data: User[] }) {
     return () => grid.removeEventListener('sorted', onSorted);
   }, []);
 
-  // Set data whenever it changes
   useEffect(() => {
-    if (ref.current) ref.current.data = data;
+    if (ref.current) ref.current.data = data;            // set property whenever data changes
   }, [data]);
 
+  // The global `apex-grid { height: ... }` CSS handles sizing.
   // @ts-expect-error — apex-grid is a custom element
-  return <apex-grid ref={ref} style={{ height: '500px', display: 'block' }} />;
+  return <apex-grid ref={ref} />;
 }
 ```
 
-For full TypeScript / JSX intrinsic-element support, declare:
+If you'd rather size per instance instead of globally, replace the global CSS rule with a `style` prop: `style={{ height: '500px', display: 'block' }}`.
+
+For full TypeScript / JSX intrinsic-element support:
 
 ```ts
-// apex-grid.d.ts
+// types/apex-grid.d.ts
 import type { ApexGrid } from 'apex-grid';
 
 declare module 'react' {
@@ -90,24 +126,31 @@ declare module 'react' {
 }
 ```
 
+---
+
 ## 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:
+### Vite plugin config
+
+Tell the Vue compiler that `apex-grid` is a custom element so it 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({
+      template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('apex-') } },
+    }),
   ],
 });
 ```
 
+### Component
+
 ```vue
 <script setup lang="ts">
 import { ref, onMounted } from 'vue';
-import 'apex-grid/define';
-import { html } from 'lit';
+import { html } from 'lit';                              // required for cellTemplate
 import type { ApexGrid, ColumnConfiguration } from 'apex-grid';
 
 type User = { id: number; name: string; age: number; subscribed: boolean };
@@ -116,15 +159,15 @@ 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,
+  { key: 'id',         type: 'number',  width: '80px',  sort: true, filter: true },
+  { key: 'name',       type: 'string',  width: '240px', sort: true, filter: true,
     cellTemplate: ({ value }) => html`<strong>${value}</strong>` },
-  { key: 'age',        type: 'number',  sort: true, filter: true },
-  { key: 'subscribed', type: 'boolean', sort: true, filter: true },
+  { key: 'age',        type: 'number',  width: '100px', sort: true, filter: true },
+  { key: 'subscribed', type: 'boolean', width: '140px', sort: true, filter: true },
 ];
 
 onMounted(() => {
-  grid.value!.columns = columns;
+  grid.value!.columns = columns;                         // set as property after mount
 });
 
 function onSorted(e: CustomEvent) {
@@ -137,22 +180,21 @@ function onSorted(e: CustomEvent) {
     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.
+> Use `:data.prop="data"` to bind as a property. Vue's default `:data="data"` sets an attribute, which becomes the literal string `"[object Object]"` and the grid renders nothing.
+
+---
 
 ## Angular
 
-Add `CUSTOM_ELEMENTS_SCHEMA` to the module / standalone component, then use property binding `[data]="..."` and event binding `(sorted)="..."`:
+Add `CUSTOM_ELEMENTS_SCHEMA` to the component (or module). Use `[data]="..."` for property binding and `(sorted)="..."` for events:
 
 ```ts
-// app.component.ts
 import { Component, CUSTOM_ELEMENTS_SCHEMA, OnInit, ViewChild, ElementRef } from '@angular/core';
-import 'apex-grid/define';
-import { html } from 'lit';
+import { html } from 'lit';                              // required for cellTemplate
 import type { ApexGrid, ColumnConfiguration } from 'apex-grid';
 
 type User = { id: number; name: string; age: number; subscribed: boolean };
@@ -165,9 +207,8 @@ type User = { id: number; name: string; age: number; subscribed: boolean };
     <apex-grid
       #grid
       [data]="data"
-      (sorted)="onSorted($event)"
-      style="height: 500px; display: block;"
-    ></apex-grid>
+      (sorted)="onSorted($event)">
+    </apex-grid>
   `,
 })
 export class UsersGridComponent implements OnInit {
@@ -177,11 +218,11 @@ export class UsersGridComponent implements OnInit {
 
   ngOnInit() {
     this.grid.nativeElement.columns = [
-      { key: 'id',         type: 'number',  sort: true, filter: true },
-      { key: 'name',       type: 'string',  sort: true, filter: true,
+      { key: 'id',         type: 'number',  width: '80px',  sort: true, filter: true },
+      { key: 'name',       type: 'string',  width: '240px', sort: true, filter: true,
         cellTemplate: ({ value }) => html`<strong>${value}</strong>` },
-      { key: 'age',        type: 'number',  sort: true, filter: true },
-      { key: 'subscribed', type: 'boolean', sort: true, filter: true },
+      { key: 'age',        type: 'number',  width: '100px', sort: true, filter: true },
+      { key: 'subscribed', type: 'boolean', width: '140px', sort: true, filter: true },
     ];
   }
 
@@ -191,13 +232,17 @@ export class UsersGridComponent implements OnInit {
 }
 ```
 
+---
+
 ## 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+ |
+| Forgetting to register the element | Top-level `import 'apex-grid/define'` once in the app entry |
+| Importing an Ignite UI theme + `configureTheme(name)` | Obsolete — the grid self-styles; retheme via `--ag-*` CSS variables. No import does anything for appearance |
+| Forgetting `setup()` / no host-height rule for `apex-grid` | `setup()` registers + sizes the host. Or `import 'apex-grid/define'` + `apex-grid { height: ... }` (never set `display` — it overrides the component's `:host { display: grid }`) |
+| Vue: `:data="data"` (attribute, becomes `"[object Object]"`) | `:data.prop="data"`, or set via `ref` in `onMounted` |
+| React: `<apex-grid columns={[...]}>` before React 19 | Use `ref` + `useEffect` to set as property |
 | 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 |
+| Writing string templates for cells | Always `import { html } from 'lit'` and use `html\`...\`` tagged literals |
+| Treating `cellTemplate` as framework-specific JSX | The template runs inside the web component — only Lit `html` works |

package/references/vanilla-js.md

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