apex-grid 1.1.0 → 3.0.0

package/LICENSE

@@ -1,9 +1,80 @@
-The MIT License (MIT)
+## 📄 License Options for ApexCharts
 
-Copyright (c) 2023 ApexCharts
+ApexCharts is offered under a **dual-license model** to support individuals, startups, and commercial products of all sizes.
 
-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.
+### 🔓 Community License (Free)
 
-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.
+For individuals, non-profits, educators, and small businesses with **less than $2 million USD in annual revenue**.
+
+✅ What’s allowed:
+
+- Personal, educational, or non-profit use
+- Commercial use by small orgs (< $2M annual revenue)
+- Modifications and redistribution (with attribution)
+
+🚫 Not allowed:
+
+- Use by companies or entities over $2M/year revenue
+- Use in competing charting products
+- Sublicensing under different terms
+
+➡ By using ApexCharts under this license, you confirm that **you qualify as a Small Organization**.
+
+---
+
+### 💼 Commercial License (Paid)
+
+Required if **you or your affiliated organization earns $2 million USD or more per year**.
+
+✅ What's included:
+
+- Use in internal tools and commercial applications
+- Modifications and app-level distribution
+- 12-month subscription with updates & support
+
+🚫 Not allowed:
+
+- Redistribution in toolkits, SDKs, or platforms
+- Use by unlicensed developers
+- Competing charting products
+
+---
+
+### 🔄 OEM / Redistribution License (Paid)
+
+Required if you are **embedding ApexCharts into a product or platform used by other people**, such as:
+
+- No-code dashboards
+- Developer platforms
+- Embedded BI tools
+- White-labeled apps or SDKs
+
+✅ What's included:
+
+- Redistribution rights for 1 application or product
+- 12-month subscription with updates & support
+
+✅ OEM **not required** if your app simply renders static charts and users **cannot** configure or interact with them.
+
+---
+
+### ⚠️ License Acceptance
+
+By installing ApexCharts (e.g., via `npm install apexcharts`), you are agreeing to the applicable license based on your usage:
+
+- Community License (if under $2M revenue)
+- Commercial License (if over $2M revenue)
+- OEM License (if redistributing to third-party users)
+
+---
+
+### 🛠 Need a License or Have Questions?
+
+📧 Contact us at [sales@apexcharts.com](mailto:sales@apexcharts.com)  
+📚 Read full license agreements here: [https://apexcharts.com/license](https://apexcharts.com/license)
+
+---
+
+Thank you for supporting ApexCharts! Your licensing helps keep it free and open for individuals and small teams.

package/README.md

@@ -1,16 +1,529 @@
-# Apex data component grid
-[![Node.js CI](https://github.com/apexcharts/apexgrid/actions/workflows/node.js.yml/badge.svg)](https://github.com/apexcharts/apexgrid/actions/workflows/node.js.yml)
-[![Coverage Status](https://coveralls.io/repos/github/apexcharts/apexgrid/badge.svg?branch=master)](https://coveralls.io/github/apexcharts/apexgrid?branch=master)
+# Apex Grid
 
+[![Node.js CI](https://github.com/apexcharts/apex-grid/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/apexcharts/apex-grid/actions/workflows/node.js.yml)
+[![Coverage Status](https://coveralls.io/repos/github/apexcharts/apex-grid/badge.svg?branch=main)](https://coveralls.io/github/apexcharts/apex-grid?branch=main)
+[![npm](https://img.shields.io/npm/v/apex-grid.svg)](https://www.npmjs.com/package/apex-grid)
 
-This is still a **very** early proof of concept for a web component based data grid.
+A Lit-based, framework-agnostic web component data grid. Ships as a single custom element `<apex-grid>` with a rich, opt-in feature set and full TypeScript types.
 
-## Local Development
+## Features
 
-1. Clone the repository.
-2. Run `npm install`
-3. Play and explore the codebase.
+- **Row virtualization** via `@lit-labs/virtualizer` — only ~20 rows in the DOM at any time, regardless of dataset size.
+- **Sorting** — single or multi-column, tri-state (asc / desc / none), per-column comparers.
+- **Filtering** — per-column filter chips with string / number / boolean / date operands, plus a quick-filter (global search) input.
+- **Pagination** — local slicing or remote mode with a `pageChanging` / `pageChanged` event pair; built-in `<apex-grid-paginator>`.
+- **Column pinning** — pin to start or end; visual reordering only, source `columns` array is preserved.
+- **Column reordering** — drag-and-drop with per-column opt-out, constrained to the column's pinning group.
+- **Column resizing** — pointer-driven, with a min-width safeguard.
+- **Inline editing** — cell or row mode, click or double-click trigger, per-column opt-in.
+- **Row selection** — single or multiple, optional checkbox column, full programmatic API.
+- **Row expansion (master-detail)** — opt-in chevron column with a `detailTemplate`.
+- **Tree data (nested rows)** — AG Grid–style `getDataPath` pattern over a flat array.
+- **CSV export** — programmatic method plus an optional toolbar dropdown. (Excel/XLSX export is in `apex-grid-enterprise`.)
+- **Toolbar** — opt-in `<apex-grid-toolbar>` with debounced quick filter and export menu.
+- **Templating** — slot-based templates for cells, headers, editors, and detail panels.
+- **Theming** — styled out-of-the-box; fully customizable through `--ag-*` CSS custom properties (no theme import or build step). Auto-matches an `igniteui-webcomponents` host app when one is present.
+- **Accessibility** — WCAG 2.2 AA semantics (`role="grid"` / `role="treegrid"`, `aria-rowcount`, `aria-colcount`, focus + keyboard navigation).
+- **Provenance-signed npm releases** with OIDC trusted publishing.
 
-## Local demo with Vite
+---
 
-Run `npm start` to open the demo page in `demo/index.html`
+## Quick Start
+
+### One-call setup
+
+```ts
+import { setup } from 'apex-grid';
+
+setup();
+```
+
+That single call registers `<apex-grid>` and adopts a default host stylesheet (`height: 100%; min-height: 240px`). The grid is styled out-of-the-box — no theme CSS import is required.
+
+### Render the grid
+
+```ts
+import { html, render } from 'lit';
+import 'apex-grid/define';
+import type { ColumnConfiguration } from 'apex-grid';
+
+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 },
+  { id: 3, name: 'Grace Hopper', age: 85, subscribed: true },
+];
+
+const columns: ColumnConfiguration<User>[] = [
+  { 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 },
+];
+
+render(
+  html`<apex-grid .data=${data} .columns=${columns}></apex-grid>`,
+  document.getElementById('app')!,
+);
+```
+
+```html
+<style>
+  apex-grid { height: 480px; }
+</style>
+<div id="app"></div>
+```
+
+---
+
+## Manual setup (four steps)
+
+If you'd rather not use `setup()`, this is what it does under the hood. Skipping any step produces a grid that "runs" but renders broken (no borders, no filter UI, or only a few collapsed rows).
+
+### 1. Install
+
+```bash
+npm install apex-grid lit
+```
+
+`igniteui-webcomponents` ships as a transitive dependency — no separate install.
+
+### 2. Register the custom element
+
+```ts
+import 'apex-grid/define';
+```
+
+Equivalent long form:
+
+```ts
+import { ApexGrid } from 'apex-grid';
+ApexGrid.register();
+```
+
+Without this, `<apex-grid>` is an inert unknown element.
+
+### 3. (Optional) Customize the look
+
+The grid is styled out-of-the-box — there is no theme to import. Customize it by overriding the `--ag-*` CSS custom properties on `apex-grid` (or any ancestor); a one-line brand override cascades to every tint:
+
+```css
+apex-grid {
+  --ag-brand: #7c3aed;        /* selection, focus, accents */
+  --ag-brand-strong: #6d28d9; /* hover / pressed */
+  --ag-radius: 12px;          /* outer card radius */
+  --ag-row-h: 40px;           /* row height */
+}
+```
+
+See [`src/styles/_tokens.scss`](src/styles/_tokens.scss) for the full token list (brand, surfaces, text, semantic state colors, typography, spacing, motion).
+
+If you embed the grid alongside `igniteui-webcomponents`, the brand tokens automatically re-tint from the igniteui palette (`--ig-primary-500`) — no configuration needed.
+
+### 4. Size the host
+
+`@lit-labs/virtualizer` requires a **bounded height**. Without one, the virtualizer collapses to its natural content height (~150px) and only a few rows ever render.
+
+```css
+apex-grid {
+  height: 480px;   /* any explicit pixel height; % works if the parent has a height */
+}
+```
+
+> [!TIP]
+> `import 'apex-grid/styles.css'` ships a default rule that sets `height: 100%` with a `min-height: 240px` fallback.
+
+> [!IMPORTANT]
+> **Do not set `display` on `<apex-grid>`.** The component declares `:host { display: grid }` internally for its track layout (header / filter / body). Any consumer rule that sets `display` (including `block`, `flex`, `inline-block`) collapses the grid. If you accidentally do this, the grid emits a one-shot `console.warn` at startup pointing here.
+
+### What success looks like
+
+With the element registered and the host sized, you should see:
+
+- **Visible borders** between rows and columns.
+- **Sort arrows** (↕) next to each header when `sort: true`.
+- A **filter row** below the headers with a "Filter" chip per column when `filter: true`.
+- **Hover state** on rows.
+- **Smooth scrolling** — DevTools shows only ~20 `<apex-grid-row>` elements at any time.
+
+### Troubleshooting
+
+| What you see | Likely cause |
+|---|---|
+| Want a different look / brand color | Step 3 — override the `--ag-*` CSS variables |
+| Only ~3 rows visible regardless of data size | Step 4 — no bounded height, **or** consumer CSS sets `display` on `<apex-grid>` (check console for the warning) |
+| `<apex-grid>` blank tag in DOM | Step 2 — element not registered |
+| Columns shown as literal `[object Object]` | `columns=` used as an attribute — must be a **property** (`.columns=${...}` in Lit, `[columns]=` in Angular, `:columns.prop=` in Vue, `el.columns = ...` in vanilla JS) |
+
+---
+
+## Features in depth
+
+Each feature below is fully opt-in — you only pay for what you turn on. Snippets assume `const grid = document.querySelector('apex-grid')!`.
+
+### Sorting
+
+```ts
+const columns = [
+  { key: 'name', sort: true },                            // UI sort + tri-state
+  { key: 'age',  sort: { direction: 'desc' } },           // initial state
+];
+
+grid.sortConfiguration = { multiple: true, triState: true };
+grid.sort({ key: 'age', direction: 'asc' });
+grid.clearSort();                                          // or grid.clearSort('age')
+```
+
+Events: `sorting` (cancellable), `sorted`.
+
+### Filtering
+
+```ts
+const columns = [
+  { key: 'name', filter: true },                          // UI filter chip
+  { key: 'age',  filter: true, type: 'number' },          // operands by type
+];
+
+import { StringOperands } from 'apex-grid';
+grid.filter({ key: 'name', condition: StringOperands.contains, searchTerm: 'Ada' });
+grid.clearFilter();
+```
+
+Operand classes: `StringOperands`, `NumberOperands`, `BooleanOperands`. Events: `filtering` (cancellable), `filtered`.
+
+### Quick filter (global search)
+
+```ts
+grid.showQuickFilter = true;       // renders the toolbar input
+grid.quickFilter = 'ada';          // or: await grid.setQuickFilter('ada')
+```
+
+Custom matcher via `dataPipelineConfiguration.quickFilter`. Events: `quickFilterChanging` (cancellable), `quickFilterChanged`. Attribute: `show-quick-filter`, `quick-filter`.
+
+### Pagination
+
+```ts
+grid.pagination = {
+  enabled: true,
+  pageSize: 25,
+  pageSizeOptions: [10, 25, 50, 100],
+};
+
+await grid.gotoPage(2);
+await grid.setPageSize(50);
+grid.nextPage(); grid.previousPage(); grid.firstPage(); grid.lastPage();
+```
+
+Remote mode:
+
+```ts
+grid.pagination = { enabled: true, mode: 'remote', pageSize: 25, totalItems: 1280 };
+grid.addEventListener('pageChanged', async (e) => {
+  grid.data = await fetchPage(e.detail.page, e.detail.pageSize);
+});
+```
+
+Properties: `page`, `pageSize`, `pageCount`, `totalItems`, `pageItems`. Events: `pageChanging` (cancellable), `pageChanged`.
+
+### Column pinning
+
+```ts
+const columns = [
+  { key: 'id',   pinned: 'start' },
+  { key: 'name' },
+  { key: 'actions', pinned: 'end' },
+];
+
+await grid.pinColumn('name', 'start');
+await grid.unpinColumn('name');                 // or pinColumn('name', null)
+```
+
+The source `columns` array is **not** reordered — only the visual render order changes. Read `grid.displayColumns` for the render order. Events: `columnPinning` (cancellable), `columnPinned`.
+
+### Column reordering
+
+```html
+<apex-grid column-reordering></apex-grid>
+```
+
+Or programmatic:
+
+```ts
+await grid.moveColumn('email', 'name', 'after');
+```
+
+Per-column opt-out: `{ key: 'id', reorderable: false }`. Reordering is constrained to the column's own pinning group (start / unpinned / end). Events: `columnMoving` (cancellable), `columnMoved`. Attribute: `column-reordering`.
+
+### Inline editing
+
+```ts
+const columns = [
+  { key: 'name', editable: true },
+  { key: 'age',  editable: true, type: 'number' },
+];
+
+grid.editing = { enabled: true, mode: 'cell', trigger: 'doubleClick' };
+
+await grid.editCell(0, 'name');
+await grid.commitEdit();
+grid.cancelEdit();
+```
+
+`mode: 'row'` puts all editable cells in the row into edit together. Properties: `editingCell`, `editingRow`. Events: `cellValueChanging` (cancellable), `cellValueChanged`, plus `rowEditStarted` / `rowEditEnded` in row mode.
+
+### Row selection
+
+```ts
+grid.selection = { enabled: true, mode: 'multiple', showCheckboxColumn: true };
+
+await grid.selectRow(data[0]);
+await grid.toggleRowSelection(data[1]);
+await grid.selectAllRows();
+await grid.clearSelection();
+grid.selectedRows;                  // snapshot
+grid.selectedRows = [data[2]];      // replace selection (goes through `rowSelecting`)
+```
+
+Events: `rowSelecting` (cancellable), `rowSelected`.
+
+### Row expansion (master-detail)
+
+```ts
+grid.expansion = {
+  enabled: true,
+  detailTemplate: ({ data }) => html`<order-summary .order=${data}></order-summary>`,
+  isExpandable: (row) => row.hasDetails,
+};
+
+await grid.expandRow(data[0]);
+await grid.toggleRowExpansion(data[0]);
+await grid.expandAllRows();
+await grid.collapseAllRows();
+grid.expandedRows;                  // snapshot
+```
+
+Events: `rowExpanding` (cancellable), `rowExpanded`.
+
+### Tree data (nested rows)
+
+The data array stays **flat**. The grid derives the hierarchy from a `getDataPath(row)` callback that returns the path from root to that row — AG Grid's "tree data" pattern.
+
+```ts
+type Person = { id: number; name: string; title: string; path: string[] };
+
+const data: Person[] = [
+  { id: 1, name: 'Adrian',  title: 'CEO',     path: ['Adrian'] },
+  { id: 2, name: 'Bryan',   title: 'VP Eng',  path: ['Adrian', 'Bryan'] },
+  { id: 3, name: 'Cara',    title: 'Manager', path: ['Adrian', 'Bryan', 'Cara'] },
+];
+
+grid.tree = {
+  enabled: true,
+  getDataPath: (row) => row.path,
+  defaultExpanded: 1,              // boolean | number — depth to expand
+  groupColumnKey: 'name',          // which column shows the chevron + indent
+  childIndent: 20,                 // px per depth level
+};
+
+await grid.toggleTreeRow(data[0]);
+await grid.expandAllTreeRows();
+```
+
+Methods: `toggleTreeRow`, `expandTreeRow`, `collapseTreeRow`, `expandAllTreeRows`, `collapseAllTreeRows`, `isTreeRowExpanded`. Events: `treeRowExpanding` (cancellable), `treeRowExpanded`. When tree mode is active, the host element advertises `role="treegrid"`.
+
+### CSV export
+
+Programmatic:
+
+```ts
+grid.exportToCSV();                                            // downloads data.csv
+grid.exportToCSV({ filename: 'users', source: 'selected' });
+const text = grid.exportToCSV({ filename: '' });               // no download, returns the string
+```
+
+`source` can be `'view'` (default — post-filter/post-sort), `'page'`, `'selected'`, or `'all'`. Per-column opt-out: `{ key: 'secret', exportable: false }`.
+
+> **XLSX (Excel) export** moved to [`apex-grid-enterprise`](https://www.npmjs.com/package/apex-grid-enterprise) in v3. `<apex-grid-enterprise>` adds `grid.exportToXLSX(...)` and an "Export XLSX" entry to this same toolbar menu. CSV stays free.
+
+Toolbar dropdown:
+
+```html
+<apex-grid show-export></apex-grid>
+```
+
+Renders a download icon in the toolbar's trailing actions area; the menu has an "Export CSV" entry (the enterprise grid adds "Export XLSX"). Toolbar `exportFilename` overrides the default `data` filename. Attribute: `show-export`.
+
+### Toolbar
+
+Rendered automatically above the header row when at least one of `show-quick-filter` or `show-export` is on. CSS parts:
+
+| Part | What |
+|---|---|
+| `toolbar` | Root container |
+| `toolbar-search` | Quick-filter input wrapper |
+| `search-field` | The bordered input field |
+| `search-icon`, `search-input` | Leading icon, input element |
+| `toolbar-actions` | Trailing actions area |
+| `export-trigger` | Export menu button |
+| `export-menu` | Dropdown panel |
+| `export-menu-item` | Menu item |
+
+Search input has a `debounce` attribute (default `200`ms).
+
+### Theming
+
+The grid styles itself through `--ag-*` CSS custom properties — override them on `apex-grid` (or any ancestor) to rebrand; see [`src/styles/_tokens.scss`](src/styles/_tokens.scss) for the full list. When `igniteui-webcomponents` is present, the brand tokens auto-tint from its palette.
+
+Style with CSS parts on the grid, paginator, and toolbar:
+
+```css
+apex-grid::part(paginator) { background: var(--surface-2); }
+apex-grid-toolbar::part(search-input) { font-family: var(--font-mono); }
+```
+
+---
+
+## API Reference
+
+### Properties
+
+| Property | Type | Default | Notes |
+|---|---|---|---|
+| `data` | `T[]` | `[]` | Source records (property only) |
+| `columns` | `ColumnConfiguration<T>[]` | `[]` | Column configuration (property only) |
+| `autoGenerate` | `boolean` | `false` | Infer columns from `data[0]` keys. Attr `auto-generate` |
+| `sortConfiguration` | `GridSortConfiguration` | `{ multiple, triState }` | |
+| `dataPipelineConfiguration` | `DataPipelineConfiguration<T>` | — | Custom sort/filter/pagination hooks |
+| `pagination` | `PaginationConfiguration` | — | |
+| `quickFilter` | `string` | `''` | Attr `quick-filter` |
+| `showQuickFilter` | `boolean` | `false` | Attr `show-quick-filter` |
+| `showExport` | `boolean` | `false` | Attr `show-export` |
+| `columnReordering` | `boolean` | `false` | Attr `column-reordering` |
+| `editing` | `GridEditingConfiguration` | — | |
+| `selection` | `GridSelectionConfiguration` | — | |
+| `expansion` | `GridExpansionConfiguration<T>` | — | |
+| `tree` | `GridTreeConfiguration<T>` | — | |
+| `sortExpressions` | `SortExpression<T>[]` | — | Get/set |
+| `filterExpressions` | `FilterExpression<T>[]` | — | Get/set |
+| `selectedRows` | `T[]` | — | Get/set |
+| `expandedRows` | `T[]` | — | Get/set |
+| `page`, `pageSize`, `pageCount`, `totalItems` | `number` | — | |
+| `pageItems` | `readonly T[]` | — | Currently rendered slice |
+| `dataView` | `readonly T[]` | — | Post-filter, post-sort |
+| `displayColumns` | `readonly ColumnConfiguration<T>[]` | — | Render order (pinned start → unpinned → pinned end) |
+| `editingCell` | `{ rowIndex, columnKey } \| null` | — | |
+| `editingRow` | `number \| null` | — | Row-mode only |
+
+### Methods
+
+```ts
+sort(expr): void
+filter(expr): void
+clearSort(key?): void
+clearFilter(key?): void
+setQuickFilter(value): Promise<boolean>
+
+getColumn(keyOrIndex): ColumnConfiguration<T> | undefined
+updateColumns(columns): void
+pinColumn(key, 'start' | 'end' | null): Promise<boolean>
+unpinColumn(key): Promise<boolean>
+moveColumn(fromKey, toKey, 'before' | 'after'): Promise<boolean>
+
+gotoPage(page): Promise<boolean>
+setPageSize(size): Promise<boolean>
+nextPage(); previousPage(); firstPage(); lastPage()
+
+editCell(rowIndex, columnKey): Promise<boolean>
+editRow(rowIndex): Promise<boolean>
+commitEdit(): Promise<boolean>
+cancelEdit(): void
+
+selectRow(row); deselectRow(row); toggleRowSelection(row)
+selectAllRows(); clearSelection(); isRowSelected(row)
+
+expandRow(row); collapseRow(row); toggleRowExpansion(row)
+expandAllRows(); collapseAllRows(); isRowExpanded(row)
+
+toggleTreeRow(row); expandTreeRow(row); collapseTreeRow(row)
+expandAllTreeRows(); collapseAllTreeRows(); isTreeRowExpanded(row)
+
+exportToCSV(options?): string
+exportAs(formatId, options?): void   // toolbar dispatch; 'csv' (community), 'xlsx' (enterprise)
+```
+
+### Events
+
+All events bubble and are composed across shadow boundaries. Names ending in `-ing` are cancellable.
+
+| Event | Cancellable | Detail |
+|---|---|---|
+| `sorting` / `sorted` | yes / no | `SortExpression<T>[]` |
+| `filtering` / `filtered` | yes / no | `FilterExpression<T>[]` |
+| `quickFilterChanging` / `quickFilterChanged` | yes / no | `{ value, nextValue? }` |
+| `pageChanging` / `pageChanged` | yes / no | `{ page, pageSize, pageCount, totalItems }` |
+| `columnPinning` / `columnPinned` | yes / no | `{ key, previous, next }` / `{ key, pinned }` |
+| `columnMoving` / `columnMoved` | yes / no | `{ key, fromIndex, toKey, position }` / `{ key, fromIndex, toIndex }` |
+| `cellValueChanging` / `cellValueChanged` | yes / no | `{ row, column, value, newValue }` |
+| `rowEditStarted` / `rowEditEnded` | no / no | row context |
+| `rowSelecting` / `rowSelected` | yes / no | `{ added, removed }` |
+| `rowExpanding` / `rowExpanded` | yes / no | row context |
+| `treeRowExpanding` / `treeRowExpanded` | yes / no | row context |
+
+Programmatic `sort()` / `filter()` calls are silent — only UI-initiated changes emit `sorting` / `filtering`.
+
+### Attributes
+
+`auto-generate`, `quick-filter`, `show-quick-filter`, `show-export`, `column-reordering`.
+
+### CSS parts
+
+| Component | Parts |
+|---|---|
+| `<apex-grid-toolbar>` | `toolbar`, `toolbar-search`, `search-field`, `search-icon`, `search-input`, `toolbar-actions`, `export-trigger`, `export-menu`, `export-menu-item` |
+| `<apex-grid-paginator>` | `paginator`, `paginator-size`, `paginator-info`, `paginator-controls`, `paginator-page` |
+| `<apex-grid-cell>` | `cell`, `editor` |
+
+---
+
+## Framework integration
+
+`<apex-grid>` is a standard custom element. Bind properties (not attributes) for `data` / `columns`:
+
+| Framework | Syntax |
+|---|---|
+| Lit | `<apex-grid .data=${data} .columns=${columns}>` |
+| Angular | `<apex-grid [data]="data" [columns]="columns">` (use `CUSTOM_ELEMENTS_SCHEMA`) |
+| Vue | `<apex-grid :data.prop="data" :columns.prop="columns">` |
+| React (19+) | `<apex-grid data={data} columns={columns}>` |
+| Vanilla | `el.data = data; el.columns = columns;` |
+
+---
+
+## Local development
+
+```bash
+git clone https://github.com/apexcharts/apex-grid.git
+cd apex-grid
+npm install
+npm start             # demo at http://localhost:5173
+npm test              # web-test-runner
+npm run lint
+npm run build         # builds dist/ + custom-elements.json + typedoc
+```
+
+## Releasing
+
+Releases are automated by [.github/workflows/publish.yml](.github/workflows/publish.yml):
+
+1. Bump `"version"` in [package.json](package.json) — the single source of truth. The build injects it into `dist/package.json`.
+2. Commit with a message starting with `release:` and the same version, e.g. `release: 2.0.0` or `release: 2.0.0-rc.1`.
+3. Push to `main`.
+
+The workflow then verifies the version triple-match, runs lint + tests + build, publishes `dist/` to npm with `--provenance` (OIDC trusted publishing — no token in secrets), and creates a `vX.Y.Z` git tag and GitHub Release with auto-generated notes. Pre-release versions (containing `-`) publish under the `next` dist-tag; stable versions under `latest`.
+
+Any push whose head commit does not start with `release:` is a no-op for the workflow.
+
+## License
+
+See [LICENSE](LICENSE).

package/components/cell.d.ts

@@ -1,10 +1,15 @@
 import { LitElement } from 'lit';
+import { type StateController } from '../controllers/state.js';
 import type { ApexCellContext, ColumnConfiguration, PropertyType } from '../internal/types.js';
 import type ApexGridRow from './row.js';
 /**
  * Component representing a DOM cell of the Apex grid.
+ *
+ * @csspart cell - The cell host element.
+ * @csspart editor - The editor wrapper rendered while the cell is in edit mode.
  */
 export default class ApexGridCell<T extends object> extends LitElement {
+    #private;
     static get tagName(): "apex-grid-cell";
     static styles: import("lit").CSSResult;
     static register(): void;
@@ -21,11 +26,45 @@ export default class ApexGridCell<T extends object> extends LitElement {
      *
      */
     active: boolean;
+    /**
+     * Whether the cell is currently in edit mode. Set by the parent row from the
+     * editing controller's state so cells re-render on edit state changes.
+     */
+    editing: boolean;
+    state: StateController<T>;
     /**
      * The parent row component holding this cell.
      */
     row: ApexGridRow<T>;
+    protected editorElement: HTMLElement | null;
     protected get context(): ApexCellContext<T>;
+    protected get editingController(): import("../controllers/editing.js").EditingController<T>;
+    protected get isEditing(): boolean;
+    protected get isEditable(): boolean;
+    /**
+     * 1-based column index used to populate `aria-colindex`. Accounts for the
+     * auto-rendered selection + expansion columns ahead of the data columns.
+     */
+    colindex: number;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(): void;
+    protected updated(): void;
+    protected renderDefaultEditor(): import("lit-html").TemplateResult<1>;
+    protected renderEditor(): unknown;
+    /**
+     * Renders the tree affordance — depth-based indent + a chevron toggle (or
+     * leaf spacer) — that prefixes the group cell when {@link ApexGrid.tree}
+     * is enabled. Returns `nothing` for every other cell.
+     */
+    protected renderTreeAffordance(): import("lit-html").TemplateResult<1> | null;
+    /**
+     * Resolves the value to display for the cell. Synthesized tree parents
+     * (those that appear only as a path segment with no backing data) render
+     * their last path segment in the group column and nothing elsewhere.
+     */
+    protected resolveDisplayValue(): unknown;
+    protected renderCellBody(): unknown;
     protected render(): unknown;
 }
 declare global {