# sv-grid - full documentation

Generated 2026-06-15 from 195 pages.

<!-- =================================================================
     /changelog  (community)
     ================================================================== -->

# Changelog

The user-facing log of what shipped. Format follows
[Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/);
versioning follows [Semantic Versioning](https://semver.org/).

Every release has up to six sections:
- **Added** - new features
- **Changed** - existing functionality, behaviour changes
- **Deprecated** - soon-to-be-removed features
- **Removed** - features removed in this release
- **Fixed** - bug fixes
- **Security** - vulnerability patches (with CVE ids when applicable)

Pre-release entries live under `## [Unreleased]`. They graduate to a
dated heading on publish via `pnpm changeset version` (see
[.changeset/README.md](../.changeset/README.md)).

For machine-readable releases, fetch
[`/changelog.json`](/changelog.json) - same content, parseable shape.

## [Unreleased]

### sv-grid-community

- **New** `onCellValueChange` callback on `<SvGrid>`. Fires after every
  inline edit commits with `{ rowIndex, columnId, oldValue, newValue,
  row }`. The recommended hook for server-side persistence and cascading
  recomputes; see demo `18-cascade-editing` and
  [Saving values](./help/editing/saving-values.md).
- **New** `externalSort` + `externalFilter` props. Grid records the UI
  state but does NOT re-order / filter rows - the consumer owns the
  pipeline. Paired with `onSortingChange` / `onFiltersChange` for
  server-side data and tree-data scenarios.
- **New** `onSortingChange(sorting)` / `onFiltersChange(filters)`
  callbacks. Fire on every change with the consolidated payload shapes
  documented in the [SvGrid reference](./reference/SvGrid.md).
- **New** `onRowSelectionChange(selection, rows)` and
  `onActiveCellChange(cell)` callbacks.
- **New** `fitColumns` prop. Scales column widths to fill the viewport,
  with rounding-residue absorbed in the last scalable column. Shrinks
  down to 85 % of natural widths; beyond that a horizontal scrollbar
  appears.
- **New** `showRowNumbers` prop. Leading 1-based row-number column,
  rendered before any selection column.
- **New** `pageSize` prop on `<SvGrid>`. Initial page size for the
  built-in pager.
- **Renamed** `accessorKey` → `field` on `ColumnDef`. **Breaking**.
  Bulk-rename in your column defs: `accessorKey` → `field`. The
  identifier is the only change; semantics are identical.
- **Improved** column virtualizer now detects per-item size changes,
  not just total size. Fixes a regression where resizing a column under
  `fitColumns` left other columns stale.
- **Improved** the wrapper-managed filter pipeline no longer applies
  filters to the pre-paginated view - the filter UI always sees the
  full dataset, not just the visible page. (Removed
  `paginatedRowModel` from the engine pipeline; pagination is applied
  AFTER filters by the wrapper.)
- **Renamed package** `svgrid-community` → `sv-grid-community`.
  **Breaking**. Update imports: `from 'svgrid-community'` →
  `from 'sv-grid-community'`. Subpath imports follow the same change.

### sv-grid-pro

- **New** package. The paid feature pack adds:
  - **Export** to xlsx / pdf / csv / tsv / html, with theme-matched
    styles, multi-sheet workbooks, header + footer with logo, embedded
    cell images. See [Export](./help/export.md).
  - **Print** with repeat-on-page headers, optional cover page,
    page-size + orientation.
  - **Import** from xlsx / csv / tsv / json with column mapping +
    per-row validation. See [Import](./help/import.md).
  - **AI assistant**: provider-agnostic helpers for natural-language
    filter, smart fill, summarize, and classify. Bring your own model
    adapter. See [AI](./help/ai.md).
  - **Pivot tables** via `createPivotModel(data, config)` and
    `pro.pivot.build(config)`. Row + column axes, 8 built-in
    aggregators or custom, grand-total row + column, subtotals,
    custom axis sort. See [Pivot tables](./help/pivot.md).
- **New** `installPro(api)` augments a `SvGridApi` with `exportData`,
  `print`, `importData`, `ai.*`, and `pivot.*` methods.
- **Soft-gated licensing**: features run unlicensed but the grid shows
  a small watermark + a one-time console nudge. `setLicenseKey('SVPRO-…')`
  at app startup clears both.

### Examples gallery

- **New demos** (56-59): theme-matched export, branded export with
  header + footer + logo, export with cell images, multi-sheet export.
- **New demos** (52-pivot-table, 51-ai-assistant, 53-excel-import):
  reference implementations for each Pro feature.
- **New demos** for industry verticals: stock market (live ticks),
  HR team, finances ledger, industrial IoT, localization, CSP
  compliant, accessibility, cascade editing, server-side rendering,
  industrial dashboard, healthcare EMR, logistics, compliance queue,
  field service, gantt, scheduler, CRM, admin dashboard, seller panel.
- **New** "Source" button on every demo opens the raw `.svelte` file
  in a modal with a Copy-to-clipboard button. Wired via
  `import.meta.glob('../demos/*.svelte', { query: '?raw' })` so it
  picks up new demos automatically.

### Docs

- **New** [Pro feature pack](./pro/README.md) landing page.
- **New** [API reference](./reference/index.md) with hand-curated
  pages for `<SvGrid>`, `SvGridApi`, `ColumnDef`, features, and the
  full Pro surface.
- **New** [Why headless?](./why-headless.md) explains the layered
  architecture and when to drop down to the headless core.
- **New** [Tailwind integration](./help/tailwind.md) walks the
  `--sg-*` token surface, dark-mode wiring via `data-theme`, and the
  override hooks for the stable `.sv-grid-*` class names.
- **Split** [Getting started](./getting-started.md) into six short
  pages (install / first-grid / data-and-columns / features /
  theme-and-density / going-to-production); the old single-page
  version is preserved at
  [getting-started-full.md](./getting-started-full.md).
- **Cleaned** every code sample against the live library surface.
  Removed phantom APIs: `state={...}`, `rowModels={...}`,
  `initialState={...}`, `manualFiltering`, `manualSorting`,
  `manualPagination`, `onColumnFiltersChange`, the wrapper `getRowId`
  prop, per-column `enableSorting` / `enableColumnFilter` /
  `enableGrouping` flags, the never-shipped
  `sv-grid-community/themes/default.css` import.
- **Em-dashes globally swept to hyphens** (`-` → `-`) across all
  source-controlled text. Codified as a rule for new content.

## How we version

| Tier              | What it means                                                                                                  |
| ----------------- | -------------------------------------------------------------------------------------------------------------- |
| **Major** (1.x)   | Breaking change to a Stable API. Includes prop / method renames, type-narrowing, default-behaviour changes.    |
| **Minor**         | New Stable API. New Experimental API. New demo. Doc rewrites that touch the public-facing claims.              |
| **Patch**         | Bug fixes. Type-only fixes. Internal refactors with no public surface change. Doc typo fixes.                  |

The [API stability page](./help/api-stability.md) annotates each export
with its current tier (`Stable`, `Experimental`, `Internal`). Until
1.0, treat anything not flagged `Stable` as subject to change.

<!-- =================================================================
     /compliance/audit-log  (community)
     ================================================================== -->

# Audit log integration

A typed, tamper-evident audit trail of every user action in the
grid, in under 50 lines. Pattern works for any backend - your
existing audit table, Datadog logs, an immutable ledger (DynamoDB
with conditional writes, AWS QLDB, Kafka), or a write-once S3
bucket.

> Live in [demo 35 (Permissions, audit & history)](https://svgrid.com/#/demos/35-permissions-audit)
> and [demo 49 (Admin dashboard)](https://svgrid.com/#/demos/49-admin-dashboard).

## What's in scope

Every event the grid surfaces:

| Event           | Grid callback                          | Audit record                                              |
| --------------- | -------------------------------------- | --------------------------------------------------------- |
| Cell edit       | `onCellValueChange`                    | `{actor, resource, before, after, ts}`                    |
| Row selection   | `onRowSelectionChange`                 | `{actor, selectedIds, ts}`                                |
| Filter change   | `onFiltersChange`                      | `{actor, filters, ts}`                                    |
| Sort change     | `onSortingChange`                      | `{actor, sort, ts}`                                       |
| Group change    | `onGroupingChange`                     | `{actor, groupBy, ts}`                                    |
| Bulk row delete | wrap `api.removeRows(...)`              | `{actor, deletedIds, ts}`                                 |
| Bulk import     | wrap `api.addRows(...)` after smart-paste | `{actor, addedIds, source: 'paste', ts}`                |
| Export          | wrap `api.exportData(...)`              | `{actor, format, rowCount, columns, ts}`                  |

## Minimal implementation

```svelte
<script lang="ts">
  import { SvGrid, type SvGridApi } from 'sv-grid-community'

  type AuditRecord = {
    actor: string
    action: string
    resource: string
    before?: unknown
    after?: unknown
    ts: string
  }

  async function audit(rec: Omit<AuditRecord, 'ts'>) {
    await fetch('/api/audit', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ ...rec, ts: new Date().toISOString() }),
    })
  }

  let api = $state<SvGridApi<typeof features, Patient> | null>(null)
</script>

<SvGrid
  {data} {columns} features={features}
  onCellValueChange={(e) => audit({
    actor:    currentUser.id,
    action:   'cell.edit',
    resource: `patient/${e.row.id}/${e.columnId}`,
    before:   e.oldValue,
    after:    e.newValue,
  })}
  onApiReady={(next) => (api = next)}
/>
```

For the `api.removeRows / addRows / exportData` actions, wrap each
imperative call site:

```ts
async function deleteSelected() {
  if (!api) return
  const ids = selectedRows.map((r) => r.id)
  api.removeRows(ids)
  await audit({ actor: currentUser.id, action: 'row.delete', resource: `patient/${ids.join(',')}` })
}
```

## Tamper-evident pattern (SHA-256 chain)

When a "trust but verify" auditor wants to confirm the log wasn't
edited in the database, append the SHA-256 of the previous record to
each new one. Cheap, no extra service needed:

```ts
async function append(rec: AuditRecord) {
  const prev = await fetch('/api/audit/latest-hash').then((r) => r.text())
  const enc  = new TextEncoder()
  const payload = JSON.stringify({ ...rec, prevHash: prev })
  const hashBuf = await crypto.subtle.digest('SHA-256', enc.encode(payload))
  const hash    = Array.from(new Uint8Array(hashBuf)).map((b) => b.toString(16).padStart(2, '0')).join('')
  await fetch('/api/audit', {
    method: 'POST',
    body: JSON.stringify({ ...rec, prevHash: prev, hash }),
  })
}
```

Now any audit-log tampering breaks the chain - one Merkle-style
verify scan over the log catches it.

## Buffer + flush pattern (production-grade)

Fire-and-forget HTTP per edit is fine for low-traffic admin apps; for
a heavy editor (spreadsheet-style work) buffer and flush:

```ts
const buf: AuditRecord[] = []
let flushTimer: number | null = null

function buffer(rec: Omit<AuditRecord, 'ts'>) {
  buf.push({ ...rec, ts: new Date().toISOString() })
  if (flushTimer === null) {
    flushTimer = window.setTimeout(flush, 2000)
  }
}

async function flush() {
  flushTimer = null
  if (buf.length === 0) return
  const batch = buf.splice(0)
  try {
    await fetch('/api/audit/batch', { method: 'POST', body: JSON.stringify(batch) })
  } catch {
    buf.unshift(...batch)  // retry next tick
  }
}

window.addEventListener('beforeunload', flush)
```

The `beforeunload` flush is the trick: even if the user closes the
tab mid-session, the buffer ships.

## What an auditor wants to see

When demonstrating the audit trail to an external auditor, the four
demonstrations:

1. **End-to-end edit trace.** Open a row, edit the salary field,
   show the audit record in your backend within 5s.
2. **Tamper detection.** SQL-update a row in the audit table to a
   different value; show that the SHA chain breaks.
3. **Role gating.** Log in as a viewer (no edit rights); attempt to
   edit; show the audit record is `{action: 'edit.denied', reason:
   'rbac'}`.
4. **Retention.** Show your retention policy: "audit records older
   than 7 years are archived to S3 with object-lock; nothing is ever
   deleted."

## See also

- [Observability](../help/observability.md) - the broader callback surface
- [SOC 2 posture](./soc2.md)
- [HIPAA posture](./hipaa.md)
- [Demo 35 - Permissions, audit & history](https://svgrid.com/#/demos/35-permissions-audit)

<!-- =================================================================
     /compliance/gdpr  (community)
     ================================================================== -->

# GDPR + data residency

sv-grid is **GDPR-neutral**: the library never transmits personal
data, never stores it server-side, and never logs it. If your app is
GDPR-compliant before adding sv-grid, adding sv-grid does not break
that compliance.

That said, GDPR reviewers ask the same five questions every time -
this page answers each one.

## 1. Where does data live?

In your application's browser memory, for the duration of the user's
session. The grid never holds a copy outside what's in the `data`
prop.

**Exceptions you opt into:**

| Feature                                              | What gets written                                                  |
| ---------------------------------------------------- | ------------------------------------------------------------------ |
| [Saved views](../help/saved-views.md)                | View name + column widths + filter / sort state. Not the rows.     |
| [State maintenance](../help/state-maintenance.md)    | Same - state only, never data, unless you call `setData(...)`.     |
| [Clipboard copy/paste](../help/state-maintenance.md) | When the user explicitly copies, the row values land in the OS clipboard. |

To audit: run your app with DevTools → Application → Local Storage.
With saved-views disabled, sv-grid writes nothing.

## 2. Does the library transmit personal data?

No. The library has **zero outbound network calls**. Inspect with
DevTools → Network: nothing from sv-grid appears.

Server-side adapters (your `onFiltersChange` / `onSortingChange`
handlers) ARE outbound calls, but they're code YOU wrote. The grid
just notifies you of state changes; what you do next is your code.

## 3. How do we honour data-subject requests?

GDPR Articles 15-22 (access, rectification, erasure, portability,
restriction, objection, automated decision-making) all apply to your
DATABASE, not the grid. The grid is purely a view layer.

The one nuance: if you use [saved views](../help/saved-views.md) to
persist user-specific layouts, those layouts may count as personal
data under Article 4(1). Two safe responses:

```ts
// Article 15: provide a copy.
const allViews = JSON.parse(localStorage.getItem('svgrid:views') ?? '{}')

// Article 17: forget.
localStorage.removeItem('svgrid:views')
api.clearAllFilters()
api.setColumnPinning({ left: [], right: [] })
```

If your saved views live server-side (the recommended pattern for
multi-device users), your existing data-subject endpoint covers them.

## 4. Does the library use cookies or fingerprinting?

No. The library:
- Sets no cookies.
- Reads no cookies.
- Does not call any fingerprinting API (`screen.width`, `navigator.platform`, `canvas.toDataURL` etc.) at runtime for the purpose of tracking.

The PDF/xlsx exporters use `canvas.toDataURL` to rasterise SVG
thumbnails for embedding - that's the only canvas use anywhere, and
it happens locally for the export only.

## 5. Where are the docs hosted? Where is the npm registry?

| Surface                  | Hosted at                                       |
| ------------------------ | ----------------------------------------------- |
| Doc site (`svgrid.com`)  | Vercel (US, EU edge)                            |
| Source repo              | GitHub                                          |
| npm packages             | npmjs.com                                       |
| MCP server               | Your machine (runs locally)                     |

If your data-residency policy requires EU-only origins, all of
these can be replaced:

- Mirror the docs internally (the `docs/` folder is in the repo).
- Use npmjs.eu or your private registry.
- The MCP server has no upstream calls; it runs against your
  installed copy of `node_modules`.

## Sub-processors

The library has none. There is no sv-grid service.

For the doc site at `svgrid.com` we use Vercel + GitHub OAuth (for
the "Edit on GitHub" link only) - these are not sub-processors of
your app, just of the doc site.

## Data-protection impact assessments

A DPIA is required when processing creates "high risk to rights and
freedoms". The library itself doesn't process data; your app does.
The risk profile of using sv-grid vs hand-writing a `<table>` is
**identical** - both display the data your app already has.

## See also

- [SOC 2 posture](./soc2.md)
- [HIPAA posture](./hipaa.md) - tighter rules for healthcare PHI
- [Security & supply chain](../help/security.md)
- [Saved views](../help/saved-views.md) - the one feature that writes to localStorage

<!-- =================================================================
     /compliance/hipaa  (community)
     ================================================================== -->

# HIPAA posture

sv-grid is **HIPAA-neutral**: the library does not transmit, store,
or process PHI on its own. If your app is HIPAA-compliant before
adding sv-grid, adding sv-grid does not break that compliance.

This page documents the four configuration choices that matter for
healthcare deployments.

> **Live example:** [demo 41 (Healthcare EMR - inpatient board)](https://svgrid.com/#/demos/41-healthcare-emr)
> shows a role-based ICU census - the same patterns this page describes.

## 1. Disable persistent saved-views

The default `<SvGrid>` writes nothing to disk. Saved views (an opt-in
feature) writes view layouts to localStorage. If you don't want PHI
to ever land in localStorage, the simplest answer is: don't use
saved views, OR make sure the view payload contains no PHI.

```ts
// Save the LAYOUT but never the filter VALUES (which could leak PHI
// like 'Patient: Jane Doe').
const view = {
  widths:  api.getColumnWidths(),
  pinning: api.getColumnPinning(),
  // intentionally do NOT save api.getFilters()
}
localStorage.setItem('view', JSON.stringify(view))
```

## 2. Disable clipboard copy/paste for PHI columns

The grid's copy/paste serialises selected cells to the OS clipboard
as TSV. Clipboards are not under your app's control - browsers,
extensions, OS-level sync (e.g. Apple Universal Clipboard) all read
from them.

The simplest mitigation: drop the cell-selection feature, which
removes the keyboard surface that triggers copy:

```svelte
<SvGrid {data} {columns} features={features}
  enableCellSelection={false}
  selectionMode="row" />
```

For finer control, intercept the `onActiveCellChange` callback and
block the column you don't want copyable - see [accessibility](../help/accessibility.md#keyboard-map)
for the keyboard map.

## 3. Disable AI helpers for PHI rows (or route to a HIPAA-BAA provider)

The [AI assistant](../help/ai.md) helpers (`aiFilter`, `aiSmartFill`,
`aiSummarize`, `aiClassify`) send row data to whatever model provider
you registered via `setAIProvider(...)`. For PHI:

- Use a model hosted on a HIPAA-eligible service (AWS Bedrock with
  Anthropic / Cohere / Mistral; Azure OpenAI with a signed BAA;
  Google Vertex AI with a signed BAA).
- OR redact PHI fields BEFORE calling the helper.

Example redaction in the provider adapter:

```ts
import { setAIProvider, type AIProvider } from 'sv-grid-pro'

const redactingProvider: AIProvider = async ({ prompt, ...rest }) => {
  const safe = prompt.replace(/MRN-?\d{8}/g, '<<MRN>>').replace(/SSN[:\s-]*\d{3}-?\d{2}-?\d{4}/g, '<<SSN>>')
  return fetch('/api/ai', { ... body: JSON.stringify({ prompt: safe, ...rest }) }).then((r) => r.text())
}

setAIProvider(redactingProvider)
```

The library hands the prompt to the provider VERBATIM - any
redaction happens in the wrapper you author, where it's auditable.

## 4. Audit every cell edit

Most HIPAA reviewers care more about the audit trail than the
display surface. The grid's `onCellValueChange` fires on every
committed edit with `{ rowIndex, columnId, oldValue, newValue, row }`.
Pipe it to your audit pipeline:

```svelte
<SvGrid {data} {columns} features={features}
  onCellValueChange={async (e) => {
    await fetch('/api/audit', {
      method: 'POST',
      body: JSON.stringify({
        actor:    currentUser.id,
        action:   'cell-edit',
        resource: `patient/${e.row.id}/${e.columnId}`,
        before:   e.oldValue,
        after:    e.newValue,
        ts:       new Date().toISOString(),
      }),
    })
  }}
/>
```

See [audit log integration](./audit-log.md) for the full pattern,
including a CryptoSign-the-row trick that makes the audit log
tamper-evident.

## What the library does NOT do

- It does not transmit row data anywhere on its own.
- It does not store row data on disk.
- It does not phone home with telemetry.
- It does not log to the console at runtime in production builds.

You can confirm with DevTools: `<SvGrid>` produces zero network
requests of its own.

## Browser-level mitigations to know about

These are general HIPAA-in-the-browser concerns; the grid doesn't
make them worse, but you should be aware:

- **Browser auto-fill**: disable on PHI fields with `autocomplete="off"`.
- **Browser screenshot APIs** (`getDisplayMedia`): browsers ask the
  user; your app can't fully block. Combine with `Cache-Control:
  no-store` on your origin so screenshots don't end up in browser
  history thumbnails.
- **Browser back-forward cache** caches the DOM. Use `Cache-Control:
  no-store` and `Pragma: no-cache` on PHI pages.

## See also

- [SOC 2 posture](./soc2.md)
- [GDPR + data residency](./gdpr.md)
- [Audit log integration](./audit-log.md)
- [Security & supply chain](../help/security.md)
- [Demo 41 - Healthcare EMR](https://svgrid.com/#/demos/41-healthcare-emr) - role-based cell editing in practice

<!-- =================================================================
     /compliance/index  (community)
     ================================================================== -->

# Compliance

sv-grid is a client-side UI library - **all data stays in the
browser**, the library never makes a network call of its own, no
telemetry phones home. The compliance story is therefore short, but
because enterprise procurement asks the same questions every time,
this section answers each one directly.

> If your reviewer wants a one-pager: jump to the
> [vendor-questionnaire shortlist](#vendor-questionnaire-shortlist)
> at the bottom.

## Pages

- [SOC 2 posture](./soc2.md) - what the library covers, what your
  hosting / build pipeline must cover
- [GDPR + data residency](./gdpr.md) - personal-data handling, where
  data physically sits, the user-rights surface
- [HIPAA posture](./hipaa.md) - PHI handling in the browser, what
  "no PHI on disk" requires you to wire
- [Audit log integration](./audit-log.md) - turn the grid's callbacks
  into an immutable audit trail with one adapter

## Vendor-questionnaire shortlist

| Question                                          | Answer                                                          |
| ------------------------------------------------- | --------------------------------------------------------------- |
| Does the library transmit any data?               | **No.** Zero outbound network calls. Inspect with DevTools.     |
| Does the library write to localStorage?           | **Only when you opt in.** [Saved views](../help/saved-views.md) writes when you tell it to. |
| Does the library evaluate user input as code?     | **No.** CSP-compliant; no `eval` / `new Function`.              |
| Does the library include third-party trackers?    | **No.** Verify the bundle - 49 kB gzip, no analytics SDK.      |
| Is the library SOC 2 / ISO 27001 certified?       | The LIBRARY can't be certified - it's not a service. Your hosted app gets certified; the library is in-scope as a dependency. See [SOC 2 posture](./soc2.md). |
| Is the library GDPR-compliant?                    | The library is GDPR-neutral: it never processes data the user didn't already see. See [GDPR + data residency](./gdpr.md). |
| Is the library HIPAA-compliant?                   | Same: HIPAA-neutral. PHI handling is a property of your app, not the grid. See [HIPAA posture](./hipaa.md). |
| Is the source code auditable?                     | **Yes.** MIT-licensed; published as readable source (no minified obfuscation).                   |
| Where is data stored?                             | **In your app's memory.** Never on a sv-grid server. There is no sv-grid server. |
| Is there a security disclosure policy?            | Yes - email `support@jqwidgets.com`. Patches typically ship within 7 days for high-severity issues. |
| Is the library tested for accessibility?          | Yes - WAI-ARIA 1.2 grid pattern + axe-core in CI. See [accessibility](../help/accessibility.md). |
| Are dependencies vetted?                          | Yes - 0 runtime dependencies in `sv-grid-community`. `sv-grid-pro` lazy-loads `jszip` + `pdfmake` as peers. See [security](../help/security.md) for the dep table. |
| Is there an SBOM?                                 | Yes - `pnpm run sbom` emits CycloneDX 1.5. See [security](../help/security.md#sbom-generation). |

## See also

- [Security & supply chain](../help/security.md) - the parent posture
- [Observability](../help/observability.md) - the audit log seam
- [API stability](../help/api-stability.md) - the deprecation promise

<!-- =================================================================
     /compliance/soc2  (community)
     ================================================================== -->

# SOC 2 posture

sv-grid is a UI library, not a service - so it cannot itself hold a
SOC 2 report. But it can sit inside a SOC 2-audited application, and
the controls below describe the line where the library's
responsibility ends and yours begins.

## TL;DR for procurement

> sv-grid is a client-side JavaScript library shipped as MIT-licensed
> source. It performs no network IO, holds no user data, and has no
> backend. SOC 2 audit scope applies to your hosting and build
> pipeline, not the library. We give you the inputs (SBOM, security
> disclosure policy, deterministic builds) you need to include
> sv-grid in your own SOC 2 report.

## What the library guarantees

| SOC 2 control area    | Library covers                                                  |
| --------------------- | --------------------------------------------------------------- |
| **CC6.1 Logical access** | n/a - no service to log into                                  |
| **CC6.6 Encryption in transit** | n/a - no transit                                       |
| **CC7.1 System operations** | Bundle is deterministic; SHA-256 published per release      |
| **CC8.1 Change management** | Every change ships as a PR with reviews; release notes per version |
| **CC9.2 Vendor management** | 0 runtime deps in `sv-grid-community`; lazy peer deps in `sv-grid-pro` documented in [security](../help/security.md) |

## What you cover (in your own SOC 2)

| Control area          | Your responsibility                                             |
| --------------------- | --------------------------------------------------------------- |
| Hosting               | Wherever your app is served from (Vercel / Cloudflare / your own infra) |
| User authentication   | Your app's auth layer - sv-grid never sees credentials          |
| Data at rest          | Wherever your data sits BEFORE it reaches the grid              |
| Audit logging         | Wire `onCellValueChange` etc. to your audit pipeline - see [audit log](./audit-log.md) |
| Backup / restore      | Your DB - the grid is stateless                                  |
| Incident response     | Your SRE process                                                |

## Inputs we provide to your auditor

1. **MIT licence** - vetted by your legal team once, valid forever
2. **Public source code** - no obfuscation; your auditor can read every line
3. **Published SBOM** - CycloneDX 1.5 generated per release; tracks every direct + transitive dep
4. **Security disclosure policy** - email `support@jqwidgets.com`, GPG fingerprint published, response SLA documented in [security](../help/security.md)
5. **Vulnerability history** - every CVE attributed to sv-grid published in the [changelog](../changelog.md) with disclosure date, fix version, mitigation
6. **Deterministic builds** - reproducible `dist/` from a clean clone; the SHA-256 of each release artefact is published in the GitHub release notes
7. **Code-review evidence** - every commit signed; every PR requires review from a CODEOWNER
8. **Dependency review** - Renovate bot opens a PR within 24h of any upstream release; we review and tag

## Common auditor questions

> *"Is there a SOC 2 report for sv-grid?"*

No - it would be meaningless. There's no service. The library is a
dependency of your application, the same way React or Svelte is. Your
auditor will treat it as a dependency, in scope under CC9.2.

> *"Does sv-grid have access to our data?"*

No. The library runs in the user's browser. Your data is whatever
your app hands to the `<SvGrid data={...}>` prop. We never see it.

> *"Can we self-host the docs?"*

Yes - the entire `docs/` folder is in the repo. Clone, build, host
behind your VPN if your compliance regime requires it. The
[MCP server](../help/mcp-server.md) runs locally too.

> *"What happens if a CVE is found in sv-grid?"*

Triage within 24h. High-severity patches typically ship within 7
days. Subscribers to the GitHub release notifications get the
release tag the moment we cut it. We backport security fixes to the
last 2 minor versions; see [api-stability](../help/api-stability.md)
for the support window.

## See also

- [GDPR + data residency](./gdpr.md)
- [Security & supply chain](../help/security.md) - SBOM, signing, dep table
- [Audit log integration](./audit-log.md) - turn callbacks into audit events

<!-- =================================================================
     /getting-started-full  (community)
     ================================================================== -->

# Getting Started with SvGrid

SvGrid is a modern, production-ready data grid for Svelte 5 - a headless
core engine paired with a Svelte render component
(`<SvGrid>`). It scales from a 10-row read-only table to a virtualized
100,000-row, 100-column editing surface with grouping, multi-column
filtering, server-side data, and full keyboard and screen-reader
support.

This page walks you from `pnpm add` to a feature-complete grid. It is
the canonical entry point - every other page in the documentation
assumes you've finished this one. Estimated reading time: 15 minutes.

> **New here?** Two short companion reads:
>
> - [Why headless?](./why-headless.md) - the architecture decision
>   behind the `createSvGrid` core vs. the `<SvGrid>` renderer.
> - [Tailwind integration](./help/tailwind.md) - how `--sg-*` custom
>   properties + Tailwind v4 + dark mode fit together.

> `sv-grid-community` is published under the **MIT License** - permissive
> for commercial use, redistribution, and modification. The paid companion
> `sv-grid-pro` (data export + print) ships under a separate commercial
> license. See [LICENSE](../LICENSE) and
> [packages/sv-grid-pro/LICENSE](../packages/sv-grid-pro/LICENSE).

---

## Contents

1. [Your first grid in 60 seconds](#1-your-first-grid-in-60-seconds)
2. [Install the package](#2-install-the-package)
3. [Provide row data](#3-provide-row-data)
4. [Define column definitions](#4-define-column-definitions)
5. [Register features (row models)](#5-register-features-row-models)
6. [Styling: theme, density, dark mode](#6-styling-theme-density-dark-mode)
7. [Sizing the grid](#7-sizing-the-grid)
8. [Custom cells with FlexRender](#8-custom-cells-with-flexrender)
9. [Sorting, filtering, pagination](#9-sorting-filtering-pagination)
10. [Selection, editing, keyboard](#10-selection-editing-keyboard)
11. [Server-side data](#11-server-side-data)
12. [Virtualization for large datasets](#12-virtualization-for-large-datasets)
13. [Accessibility](#13-accessibility)
14. [TypeScript notes](#14-typescript-notes)
15. [What's next](#15-whats-next)

---

## 1. Your first grid in 60 seconds

```svelte
<script lang="ts">
  import { SvGrid, type ColumnDef } from 'sv-grid-community'

  type Person = { firstName: string; age: number; status: string }

  const rows: Person[] = [
    { firstName: 'Ada',   age: 36, status: 'active' },
    { firstName: 'Linus', age: 54, status: 'active' },
    { firstName: 'Grace', age: 85, status: 'inactive' },
  ]

  const columns: ColumnDef<{}, Person>[] = [
    { field: 'firstName', header: 'First name' },
    { field: 'age',       header: 'Age' },
    { field: 'status',    header: 'Status' },
  ]
</script>

<SvGrid data={rows} columns={columns} />
```

That's a complete, working grid. The rest of this page is about turning
it into something you'd ship.

---

## 2. Install the package

SvGrid is a single npm package. There is no peer dependency on a CSS
framework - bring your own, or use the bundled stylesheet.

```bash
# pnpm (recommended)
pnpm add sv-grid-community

# npm
npm install sv-grid-community

# yarn
yarn add sv-grid-community
```

**Requirements.**

- Svelte **5.x** (uses runes - `$state`, `$derived`, `$effect`).
- TypeScript **5.4+** (optional but recommended).
- Node **18+** for tooling.

Once installed, import the component, the features you want, and the
matching `ColumnDef` type:

```ts
import {
  SvGrid,
  tableFeatures,
  rowSortingFeature,
  columnFilteringFeature,
  type ColumnDef,
} from 'sv-grid-community'
```

The bundle is tree-shakeable - features you don't import don't ship. The
default render component (`<SvGrid>`) brings its own scoped CSS, so
there's no separate stylesheet to import. Re-theming happens via the
`--sg-*` custom-property surface; see
[Tailwind integration](./help/tailwind.md) for the full list.

---

## 3. Provide row data

SvGrid is data-agnostic. The `data` prop is any
`ReadonlyArray<TRow>` - a Svelte 5 `$state` array, a derived store, an
SWR/React-query-style cache, the result of a `+page.ts` load function,
or a plain literal.

```svelte
<script lang="ts">
  import { SvGrid } from 'sv-grid-community'

  type Person = { id: string; firstName: string; age: number }

  // Reactive: pushing into `rows` updates the grid automatically.
  let rows = $state<Person[]>([
    { id: '1', firstName: 'Ada',   age: 36 },
    { id: '2', firstName: 'Linus', age: 54 },
  ])

  function addRow() {
    rows.push({ id: crypto.randomUUID(), firstName: 'New', age: 0 })
  }
</script>

<button onclick={addRow}>Add row</button>
<SvGrid data={rows} columns={columns} />
```

**Identity.** Today the wrapper uses the row's array index as its id.
That is fine for read-only data; if you mutate `rows`, prefer keeping
the same object references for rows that didn't change so selection
and edit state line up. A `getRowId` prop on the wrapper is tracked in
[Missing features](./help/missing-features.md) and supported by the
headless `createSvGrid` core today.

**Immutability.** SvGrid never mutates your data. When you edit a cell
the grid emits an event; you decide whether to mutate in place or copy.
See [§10 - Editing](#10-selection-editing-keyboard).

---

## 4. Define column definitions

A column definition tells SvGrid how to read a value out of a row, how
to render it, and which features apply to it.

```ts
import type { ColumnDef } from 'sv-grid-community'

type Person = {
  id: string
  firstName: string
  lastName: string
  age: number
  joinedAt: string // ISO date
  salary: number
  active: boolean
}

const columns: ColumnDef<{}, Person>[] = [
  // Simple accessor by key
  { field: 'firstName', header: 'First name' },

  // Computed accessor
  {
    id: 'fullName',
    header: 'Full name',
    accessorFn: (row) => `${row.firstName} ${row.lastName}`,
  },

  // Numeric with locale-aware formatting
  {
    field: 'age',
    header: 'Age',
    format: { type: 'number', options: { maximumFractionDigits: 0 } },
  },

  // Date with explicit pattern
  {
    field: 'joinedAt',
    header: 'Joined',
    format: { type: 'date', pattern: 'y-m-d' },
  },

  // Currency
  {
    field: 'salary',
    header: 'Salary',
    format: { type: 'currency', currency: 'USD' },
  },

  // Boolean rendered as a checkbox
  {
    field: 'active',
    header: 'Active',
    editorType: 'checkbox',
  },
]
```

**Common properties.**

| Property | Purpose |
| --- | --- |
| `field` | Reads `row[key]`. |
| `accessorFn` | Computes the value from the row. |
| `id` | Stable column id (required if you use `accessorFn`). |
| `header` | String or render snippet for the header. |
| `footer` | String or render snippet for the footer row. |
| `cell` | Render snippet/component for the body cell. |
| `format` | Locale-aware formatter (`number`, `currency`, `percent`, `date`). |
| `formatter` | Function for one-off custom value formatting. |
| `editorType` | Inline editor: `text` \| `number` \| `checkbox` \| `date` \| `datetime`. |
| `width` | Initial column width in pixels (default `columnWidth` prop). |
| `align` | Header + body alignment: `'left'` \| `'right'` \| `'center'`. Inferred from `editorType` when omitted. |
| `columns` | Child column defs (for column groups). |

Sorting / filtering / grouping are toggled per-grid via the registered
features - there is no per-column `enableSorting` / `enableColumnFilter`
flag yet; those entries are in [Missing features](./help/missing-features.md).

See [`packages/sv-grid-community/src/core.ts`](../packages/sv-grid-community/src/core.ts)
for the full type.

---

## 5. Register features (row models)

The grid engine is feature-gated. Out of the box you get the **core row
model** (the rows in their original order). To enable sorting,
filtering, grouping, expansion, pagination, or selection you opt in
with `tableFeatures(...)` and the matching `create*RowModel` factory.

```svelte
<script lang="ts">
  import {
    SvGrid,
    tableFeatures,
    rowSortingFeature,
    columnFilteringFeature,
    rowSelectionFeature,
    type ColumnDef,
  } from 'sv-grid-community'

  const features = tableFeatures({
    rowSortingFeature,
    columnFilteringFeature,
    rowSelectionFeature,
  })
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  showPagination={true}
  pageSize={25}
/>
```

**Rule of thumb.** Only register the features you use. The wrapper wires
the matching row-model pipeline (core → filtered → sorted → grouped →
expanded) for you and exposes the user-facing toggles via props
(`showPagination`, `filterMode`, `showRowSelection`, …). If you need the
headless pipeline directly - e.g. a custom renderer - drop down to
`createSvGrid` from the same package; see [Why headless?](./why-headless.md).

| Feature | Factory | What it does |
| --- | --- | --- |
| `rowSortingFeature` | `createSortedRowModel` | Click headers to sort; shift-click for multi-sort. |
| `columnFilteringFeature` | `createFilteredRowModel` | Per-column filters with built-in `filterFns`. |
| `rowPaginationFeature` | `createPaginatedRowModel` | Page slicing + footer state. |
| `rowSelectionFeature` | - | Row checkboxes, range selection, headless API. |
| `columnGroupingFeature` | `createGroupedRowModel` | Group-by-column + aggregators. |
| `rowExpandingFeature` | `createExpandedRowModel` | Tree / master-detail expansion. |

---

## 6. Styling: theme, density, dark mode

SvGrid's render component (`<SvGrid>`) ships its own scoped styles. You
re-theme it by declaring `--sg-*` custom properties at any level above
the grid - the included light, dark, and high-contrast palettes in the
[`10-custom-cells-and-themes`](../examples/src/demos/10-custom-cells-and-themes.svelte)
demo are themselves just three sets of these tokens applied via
`style="--sg-bg: …; --sg-fg: …; …"`.

**Customising tokens.** Override at any level - `:root`, a wrapper, or
directly on `<SvGrid>`.

```css
:root {
  --sg-row-height: 36px;
  --sg-header-bg: #f6f7f9;
  --sg-header-fg: #1f2933;
  --sg-row-hover-bg: #eef2ff;
  --sg-selection-bg: #dbeafe;
  --sg-border: #e5e7eb;
  --sg-focus-ring: 0 0 0 2px #2563eb;
  --sg-font: 'Inter', system-ui, sans-serif;
}

@media (prefers-color-scheme: dark) {
  :root {
    --sg-header-bg: #0f172a;
    --sg-header-fg: #f1f5f9;
    --sg-row-hover-bg: #1e293b;
    --sg-border: #334155;
  }
}
```

**Density.** The default theme reads `--sg-row-height`; flip it to
`28px` for compact mode and `48px` for comfortable. Density changes are
applied without remounting the virtualizer.

**Reduced motion.** Sort animations and expand transitions respect
`prefers-reduced-motion: reduce` automatically.

---

## 7. Sizing the grid

`<SvGrid>` fills its parent. Give it a height and it scrolls - without
one, it expands to its content and never virtualises.

```svelte
<!-- Fixed: 600px tall, full width. The typical choice. -->
<div style="height: 600px;">
  <SvGrid data={rows} columns={columns} />
</div>

<!-- Flexible: fills the viewport minus header/footer. -->
<div class="grid-shell">
  <SvGrid data={rows} columns={columns} />
</div>

<style>
  .grid-shell {
    height: calc(100dvh - 4rem);
  }
</style>
```

**Auto-height (small datasets only).** For grids with fewer than ~200
rows you can let the grid grow to its content:

```svelte
<SvGrid data={rows} columns={columns} domLayout="autoHeight" />
```

Auto-height disables row virtualization. Don't use it for large data.

---

## 8. Custom cells with FlexRender

For anything beyond a stringified value, render with `FlexRender`,
`renderComponent`, or `renderSnippet`.

### As a Svelte snippet

```svelte
<script lang="ts">
  import { renderSnippet, type ColumnDef } from 'sv-grid-community'
</script>

{#snippet StatusCell({ value }: { value: string })}
  <span class="pill pill-{value}">{value}</span>
{/snippet}

<script lang="ts">
  const columns: ColumnDef<{}, Person>[] = [
    {
      field: 'status',
      header: 'Status',
      cell: renderSnippet(StatusCell, (ctx) => ({ value: ctx.getValue() as string })),
    },
  ]
</script>
```

### As a Svelte component

```ts
import StatusBadge from './StatusBadge.svelte'
import { renderComponent } from 'sv-grid-community'

const columns = [
  {
    field: 'status',
    header: 'Status',
    cell: renderComponent(StatusBadge, (ctx) => ({ status: ctx.getValue() })),
  },
]
```

`renderComponent` and `renderSnippet` both receive a
`CellContext` so you can read sibling values, mutate state, or call
back into the grid via `ctx.table`.

---

## 9. Sorting, filtering, pagination

Once their features are registered (see §5) the UI affordances appear
automatically. The state is controllable.

**Quick way - capability shortcuts.** Every capability is off by default;
the fastest way to opt in is a boolean shortcut prop, no feature constants
required. `sortable` and `filterable` inject the matching feature for you;
`editable`, `groupable`, and `pageable` alias `enableInlineEditing`,
`showGroupingControls`, and `showPagination`:

```svelte
<SvGrid data={rows} columns={columns} sortable filterable editable groupable pageable />
```

Reach for the explicit `features` set + fine-grained props below when you
need more control (filter mode, page size, per-column opt-outs).

### Uncontrolled (the default)

The wrapper owns sort, filter, pagination, selection, and expansion
state by default. Set the initial page size and which filter UI to
show via props:

```svelte
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  showPagination={true}
  pageSize={50}
  filterMode="menu"
/>
```

### Observable (callbacks fire when state changes)

The wrapper still owns the state, but emits callbacks on every change.
Use this when an outside piece of UI needs to react (a "X rows
selected" pill, a router that syncs sort to the URL, a server fetch).

```svelte
<script lang="ts">
  let sorting = $state<Array<{ id: string; desc: boolean }>>([])
  let filters = $state<Array<{ id: string; operator: string; value: string }>>([])
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  filterMode="menu"
  onSortingChange={(next) => (sorting = next)}
  onFiltersChange={(next) => (filters = next.columns)}
/>
```

### External (you own row ordering / filtering)

For server-side data or tree-structured data the wrapper records the
sort + filter UI state but does **not** re-order the rows - you do.
Pair `externalSort` / `externalFilter` with the callbacks above:

```svelte
<SvGrid
  data={preFilteredRows}
  columns={columns}
  features={features}
  filterMode="menu"
  externalSort={true}
  externalFilter={true}
  onSortingChange={(next) => fetchPage({ sort: next, page: 0 })}
  onFiltersChange={(next) => fetchPage({ filters: next.columns, page: 0 })}
/>
```

For Excel-style filter operators and the active-filter chip UI, see
[`applyExcelFilter`](../packages/sv-grid-community/src/filtering/excel-filters.ts).

---

## 10. Selection, editing, keyboard

### Row selection

```svelte
<script lang="ts">
  let selected = $state<Person[]>([])
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  selectionMode="row"
  showRowSelection={true}
  onRowSelectionChange={(_state, rows) => (selected = rows)}
/>

{#if selected.length}
  <p>{selected.length} selected</p>
{/if}
```

`selectionMode` is the umbrella prop: `'row'` shows the checkbox
column, `'cell'` enables click-and-drag range selection,
`'both'` (default) enables both, `'none'` disables both. The
`onRowSelectionChange` callback receives the selection record AND the
materialised row array.

### Cell editing

Set `editorType` on each editable column. The grid handles entry,
commit, and cancel; you handle persistence.

```svelte
<script lang="ts">
  function handleCellEdit(event: {
    rowId: string
    columnId: string
    value: unknown
  }) {
    const row = rows.find((r) => r.id === event.rowId)
    if (!row) return
    ;(row as Record<string, unknown>)[event.columnId] = event.value
  }
</script>

<SvGrid
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  onCellValueChange={handleCellEdit}
/>
```

### Keyboard

The grid follows the WAI-ARIA grid pattern:

| Keys | Action |
| --- | --- |
| `←` `↑` `→` `↓` | Move active cell |
| `Home` / `End` | First / last column of the row |
| `Ctrl+Home` / `Ctrl+End` | First / last cell of the grid |
| `PageUp` / `PageDown` | Move one viewport |
| `Shift + <move>` | Extend cell-range selection |
| `Space` | Toggle row selection (when selection enabled) |
| `Enter` / `F2` | Begin editing the active cell |
| `Esc` | Cancel edit / clear selection |
| `Ctrl/Cmd + C` | Copy selection as TSV |
| `Ctrl/Cmd + V` | Paste TSV into selection |

If you implement your own header or toolbar, route keys through
`getKeyboardIntent` and `getNextActiveCell` so behaviour stays
consistent.

---

## 11. Server-side data

For datasets that don't fit in memory, drive the grid from the server.
The pattern is: turn the wrapper's `onSortingChange` /
`onFiltersChange` callbacks into a query, fetch, hand the page back as
`data`, and use the `externalSort` + `externalFilter` props so the grid
doesn't try to re-order rows it didn't fetch.

```svelte
<script lang="ts">
  import { SvGrid, tableFeatures, rowSortingFeature,
           columnFilteringFeature } from 'sv-grid-community'

  const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })

  let sort    = $state<Array<{ id: string; desc: boolean }>>([])
  let filters = $state<Array<{ id: string; operator: string; value: string }>>([])
  let page    = $state(0)
  const pageSize = 50

  let rows    = $state<Person[]>([])
  let total   = $state(0)
  let loading = $state(false)
  let controller: AbortController | null = null

  async function load() {
    controller?.abort()
    controller = new AbortController()
    loading = true
    try {
      const res = await fetch('/api/people?' + new URLSearchParams({
        sort:    JSON.stringify(sort),
        filters: JSON.stringify(filters),
        page:    String(page),
        size:    String(pageSize),
      }), { signal: controller.signal })
      const body = await res.json()
      rows  = body.rows
      total = body.total
    } catch (err) {
      if ((err as Error).name !== 'AbortError') throw err
    } finally {
      loading = false
    }
  }

  $effect(() => { sort; filters; page; load() })
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  filterMode="menu"
  externalSort={true}
  externalFilter={true}
  showPagination={false}
  onSortingChange={(next) => { sort = next; page = 0 }}
  onFiltersChange={(next) => { filters = next.columns; page = 0 }}
/>

<nav>
  <button onclick={() => (page = Math.max(0, page - 1))}
          disabled={page === 0 || loading}>‹ Prev</button>
  <span>Page {page + 1} of {Math.ceil(total / pageSize)}</span>
  <button onclick={() => (page = page + 1)}
          disabled={(page + 1) * pageSize >= total || loading}>Next ›</button>
</nav>

{#if loading}<div class="overlay">Loading…</div>{/if}
```

The `external*` props tell the grid not to re-derive that dimension
locally - the data you pass in is already the answer. Pagination above
is hand-rolled so total-row-count and "show next page" stay in your
control; if a built-in pager is enough, leave `showPagination={true}`
on and the wrapper will page the local `rows` array (which, in this
server-side pattern, only ever holds one page anyway).

See the [`09-server-side` demo](../examples/src/demos/09-server-side.svelte)
for a complete runnable version with debounce, abort wiring, and a
60 ms mock latency.

---

## 12. Virtualization for large datasets

For more than a few thousand rows, enable row virtualization. For very
wide grids (50+ columns) also enable column virtualization. Both are
opt-in so small grids don't pay the cost.

```svelte
<script lang="ts">
  import { SvGrid } from 'sv-grid-community'
</script>

<SvGrid
  data={rows}
  columns={columns}
  virtualizeRows
  virtualizeColumns
  estimatedRowHeight={36}
  overscan={6}
/>
```

For full control (e.g. variable row heights, programmatic scroll),
use the headless virtualizer directly:

```ts
import { createSvelteVirtualizer } from 'sv-grid-community'

const virtualizer = createSvelteVirtualizer({
  count:                 () => rows.length,
  getScrollElement:      () => scrollRef,
  estimateSize:          (index) => (rows[index].kind === 'header' ? 40 : 28),
  overscan:              6,
})

// Programmatic scroll:
virtualizer.scrollToIndex(75_432, { align: 'center' })
```

See [`packages/sv-grid-community/src/virtualization/`](../packages/sv-grid-community/src/virtualization/)
for the full API.

---

## 13. Accessibility

SvGrid implements the WAI-ARIA 1.2 grid pattern.

- The root carries `role="grid"`, an accessible name (set via
  `aria-label` or `aria-labelledby`), and `aria-rowcount` /
  `aria-colcount` reflecting the total - not just the visible window.
- Rows carry `role="row"` plus `aria-rowindex` accounting for the
  virtualized offset; cells carry `role="gridcell"` and `aria-colindex`.
- The active cell is always exactly one focusable element
  (roving `tabindex`); arrow keys move it.
- Sort columns carry `aria-sort="ascending" | "descending" | "none"`.
- Sort and selection state changes are announced via an off-screen
  `aria-live` region the grid manages internally.

If you build your own header or toolbar, use the helpers in
[`a11y.ts`](../packages/sv-grid-community/src/a11y.ts) so your markup
stays consistent with the contract:

```ts
import {
  getGridRootA11yProps,
  getGridRowA11yProps,
  getGridCellA11yProps,
  getGridHeaderA11yProps,
} from 'sv-grid-community'
```

There is a contract test suite at
[`a11y.contract.test.ts`](../packages/sv-grid-community/src/a11y.contract.test.ts)
that exercises the public a11y guarantees - run it (`pnpm test`) when
you customize markup to be sure you haven't regressed the contract.

---

## 14. TypeScript notes

Most APIs are generic over your row type. Define the row type once and
flow it through:

```ts
type Person = { id: string; firstName: string; age: number }

const columns: ColumnDef<{}, Person>[] = [
  { field: 'firstName', header: 'First name' }, // ✅ key checked
  // { field: 'first_name', header: '…' },      // ✗ TS error
]
```

The first type parameter is the **feature set**. When you register
features, derive it once and reuse:

```ts
const features = tableFeatures({
  rowSortingFeature,
  rowSelectionFeature,
  columnFilteringFeature,
})

type Features = typeof features

const columns: ColumnDef<Features, Person>[] = [/* … */]
```

This lets feature-specific column properties (like `filterFn`)
auto-complete and type-check.

---

## 15. What's next

### Core features

- **[Examples gallery](https://svgrid.com/#/demos)** - 50+ production-quality
  demos, from quick-start to 100k-row virtualization.
- **[Column definitions](./help/columns/column-definitions.md)** - every
  property on `ColumnDef`.
- **[Row sorting](./help/rows/row-sorting.md)** and the wider [rows topic index](./help/index.md#rows) -
  when to use which row model and the order they run in.
- **[Tree rows (expand / collapse)](./help/rows/tree-rows.md)** - the
  flat-array + expanded-map pattern, connector lines, keyboard
  navigation, and lazy load on first expand.
- **[Filter API](./help/filtering/filter-api.md)** - sort, filter,
  paginate, group, and aggregate locally or against your backend.
- **[Tailwind integration](./help/tailwind.md)** - full list of CSS
  custom properties (`--sg-*`) and recipes for building your own theme.
- **[Compare SvGrid with other Svelte data grids](https://svgrid.com/#/compare)** -
  side-by-side feature matrix and when to pick which.

### Pro features (`sv-grid-pro`)

The paid companion package augments your `SvGridApi` with one
`installPro(api)` call. Set a license key at app boot to remove the
"unlicensed" watermark - every feature still runs without a key for
demos and evaluation.

- **[Data export and printing](./help/export.md)** - Excel (xlsx), PDF,
  CSV, TSV, HTML, and a paginated print view. Defaults to the currently
  displayed rows so sort + filter + paginate carry through automatically.
- **[Data import](./help/import.md)** - Excel (xlsx), CSV, TSV, and JSON
  with column mapping, per-row validation, and preview-before-commit. Auto-
  detects the format from the file extension or pasted text.
- **[Pivot tables](./help/pivot.md)** - drag-and-drop Pivot Designer with
  Filters / Rows / Columns / Values zones, multi-level column headers,
  per-measure aggregator picker, pivot-aware sort. Built on the same
  engine; no special "pivot mode".
- **[AI assistant](./help/ai.md)** - natural-language filter, smart fill,
  summarise, and classify, driven by a bring-your-own model adapter
  (`setAIProvider(fn)`). Ships with a deterministic `mockAIProvider` so
  the demo works without keys.

### Getting help

- File issues at the [project repository](https://github.com/sv-grid/sv-grid/issues).
- Browse the [Help index](./help/index.md) for topic-oriented guides.
- Use the [sv-grid-mcp](https://svgrid.com/#/mcp) server
  to give your AI assistant accurate answers.
- Read the source - it is small, well-commented, and meant to be read
  before opening a bug report.

### License

`sv-grid-community` is published under the **MIT License**. Free for
commercial and personal use. The paid `sv-grid-pro` companion package
(export, import, print, pivot, AI assistant) is governed by a separate
commercial license. See [LICENSE](../LICENSE) and
[packages/sv-grid-pro/LICENSE](../packages/sv-grid-pro/LICENSE).

<!-- =================================================================
     /getting-started  (community)
     ================================================================== -->

# Getting started with SvGrid

SvGrid is a modern, production-ready data grid for Svelte 5 - a headless
core engine paired with a Svelte render component (`<SvGrid>`). It
scales from a 10-row read-only table to a virtualized
100,000-row × 100-column editing surface with grouping, multi-column
filtering, server-side data, and full keyboard and screen-reader support.

This guide is six short pages. Read them in order if you're new; jump
straight to the one you need if you're not.

> In a hurry? `npm create sv-grid@latest` scaffolds a working project in
> one command - see [Starters & scaffolding](./getting-started/starters.md).

| #   | Page                                                          | What it covers                                                              |
| --- | ------------------------------------------------------------- | --------------------------------------------------------------------------- |
| 0   | [Starters & scaffolding](./getting-started/starters.md)       | `npm create sv-grid`, the minimal + SvelteKit admin templates, Deploy to Vercel. |
| 1   | [Install](./getting-started/1-install.md)                     | `pnpm add sv-grid-community`, requirements, smoke-test.                     |
| 2   | [First grid](./getting-started/2-first-grid.md)               | The minimum runnable example, explained line by line.                       |
| 3   | [Data and columns](./getting-started/3-data-and-columns.md)   | What goes in `data` and `columns`. Custom cells via `renderSnippet`.        |
| 4   | [Features](./getting-started/4-features.md)                   | Opt into sort, filter, pagination, grouping, selection, editing.            |
| 5   | [Theme and density](./getting-started/5-theme-and-density.md) | `--sg-*` tokens, dark mode, row height, sizing the grid in a flex layout.   |
| 6   | [Going to production](./getting-started/6-going-to-production.md) | Server-side data, virtualization, a11y, SSR, CSP, TypeScript notes.     |

Estimated reading time: 15 minutes across all six pages.

## Companion reads

- [Why headless?](./why-headless.md) - the architecture decision behind
  the `createSvGrid` core vs. the `<SvGrid>` render component.
- [Tailwind integration](./help/tailwind.md) - how the `--sg-*` custom
  properties, Tailwind v4, and dark mode fit together.
- [Web Components & Custom Elements](./help/web-components.md) - use SvGrid
  as a framework-agnostic `<sv-grid>` element in React, Vue, Angular, or
  plain HTML.
- [Pro features](./pro/README.md) - the paid feature pack: data export,
  data import, AI assistant, and pivot tables.

## One-page version

Prefer a single 800-line file? See
[getting-started-full.md](./getting-started-full.md). The content is
identical; the split exists for sidebar nav and faster mobile loads.

## License

`sv-grid-community` is published under the **MIT License** - permissive
for commercial use, redistribution, and modification. The paid
companion `sv-grid-pro` ships under a separate commercial license. See
[LICENSE](../LICENSE) and
[packages/sv-grid-pro/LICENSE](../packages/sv-grid-pro/LICENSE).

## Frequently asked questions

### How do I add a data grid to a Svelte 5 app?

Install `sv-grid-community`, import `SvGrid`, and pass `data` and `columns`.
A complete grid is about 15 lines - keyboard navigation and accessibility are
on by default, and you opt into sort/filter/edit/group/paging with one boolean
shortcut each (`sortable`, `filterable`, ...). See
[First grid](./getting-started/2-first-grid.md) and
[Features](./getting-started/4-features.md#capability-shortcuts-the-quick-way).

### Does SvGrid work with SvelteKit?

Yes. It renders meaningful HTML before hydration, so it works under SvelteKit
SSR and static builds. Drive large datasets with controlled, server-side state.

### Is SvGrid free for commercial use?

Yes. `sv-grid-community` is MIT-licensed, including commercial use, with no row
cap or license key. The optional `sv-grid-pro` pack (export, pivot, import, AI)
ships under a separate paid license.

### What do I need to run SvGrid?

Svelte 5 (runes) and any Vite-based toolchain. There are no other required
dependencies for the Community core; Pro export/import features lazy-load their
own dependencies only when used.

<!-- =================================================================
     /getting-started/1-install  (community)
     ================================================================== -->

# 1. Install

> Step 1 of 6 · [Next: First grid →](./2-first-grid.md)

SvGrid is a single npm package. There is no peer dependency on a CSS
framework - bring your own, or use the default theme that ships with
the render component.

## Fastest start: scaffold a project

Starting fresh? Skip the manual wiring and scaffold a project with the
grid already set up:

```bash
npm create sv-grid@latest                                   # interactive
npm create sv-grid@latest my-admin -- --template admin-dashboard
```

See [Starters & scaffolding](./starters.md) for the templates (minimal
Vite app or a full SvelteKit admin dashboard) and the Deploy-to-Vercel
flow. To add SvGrid to an **existing** app, install it directly:

```bash
# pnpm (recommended)
pnpm add sv-grid-community

# npm
npm install sv-grid-community

# yarn
yarn add sv-grid-community
```

## Requirements

| Tool        | Version           | Why                                   |
| ----------- | ----------------- | ------------------------------------- |
| Svelte      | **5.x**           | Uses runes: `$state`, `$derived`, `$effect`. |
| TypeScript  | **5.4+**          | Optional but strongly recommended. The column-def types pay for themselves. |
| Node        | **18+**           | For tooling (`vite`, `svelte-check`, the example gallery). |

The bundle is tree-shakeable: features you don't import don't ship.
There's no monolithic entry that pulls everything.

## Verify the install

A 5-line smoke test:

```svelte
<script lang="ts">
  import { SvGrid } from 'sv-grid-community'
  const rows = [{ name: 'Ada' }, { name: 'Linus' }]
  const columns = [{ field: 'name', header: 'Name' }]
</script>

<SvGrid data={rows} columns={columns} />
```

If you see a styled `<table>` with two rows, you're done.

## Pro add-on (optional)

If you need data export (Excel / PDF / CSV), data import, the AI
assistant, or built-in pivot tables, install the paid Pro pack
alongside the Community package:

```bash
pnpm add sv-grid-pro
```

See [Pro features](../pro/README.md) for what ships and how to license.

## Where the rest of this guide goes

1. **Install** ← you're here
2. [First grid](./2-first-grid.md) - the minimum runnable example explained
3. [Data and columns](./3-data-and-columns.md) - the two arrays the grid actually reads
4. [Features](./4-features.md) - opt into sort, filter, pagination, grouping, etc.
5. [Theme and density](./5-theme-and-density.md) - `--sg-*` tokens, dark mode, row height
6. [Going to production](./6-going-to-production.md) - server-side data, virtualization, a11y, SSR

The combined "everything in one page" version is at
[../getting-started-full.md](../getting-started-full.md) - useful for
printing or single-tab reading.

<!-- =================================================================
     /getting-started/2-first-grid  (community)
     ================================================================== -->

# 2. First grid in 60 seconds

> Step 2 of 6 · [← Install](./1-install.md) · [Next: Data and columns →](./3-data-and-columns.md)

```svelte
<script lang="ts">
  import { SvGrid, type ColumnDef } from 'sv-grid-community'

  type Person = { firstName: string; age: number; status: string }

  const rows: Person[] = [
    { firstName: 'Ada',   age: 36, status: 'active' },
    { firstName: 'Linus', age: 54, status: 'active' },
    { firstName: 'Grace', age: 85, status: 'inactive' },
  ]

  const columns: ColumnDef<{}, Person>[] = [
    { field: 'firstName', header: 'First name' },
    { field: 'age',       header: 'Age' },
    { field: 'status',    header: 'Status' },
  ]
</script>

<SvGrid data={rows} columns={columns} />
```

That's a complete, working grid.

## What you got out of the box

- A semantic `<table>` with WAI-ARIA `role="grid"` / `role="row"` /
  `role="columnheader"` / `role="gridcell"` on every node.
- Keyboard navigation: arrow keys move the active cell, Home/End jump
  to row edges, Page Up/Down move by a page, Ctrl+Home / Ctrl+End jump
  to the grid corners.
- A focus ring on the active cell. Selection on click. F2 / double-click
  to edit (no-op here because no column has `editorType`).
- Auto-sized columns; explicit `width` on the column def overrides.
- The default `--sg-*` theme: borders, header background, zebra rows,
  hover, selection - all on tokens you can swap.

## What you didn't get yet

Sort, filter, pagination, grouping, expansion, selection are **off**
until you register the matching features. That's the next step.

```svelte
<!-- after registering rowSortingFeature + columnFilteringFeature -->
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  filterMode="menu"
/>
```

[Step 3 →](./3-data-and-columns.md) covers how `data` and `columns`
work in detail; [step 4 →](./4-features.md) lights up everything else.

## See it run

The quick-start demo is a slightly fancier version (more columns,
inline editing, range selection):

<div data-docs-demo="01-quick-start" data-height="440"></div>

Source: [examples/src/demos/01-quick-start.svelte](../../examples/src/demos/01-quick-start.svelte).

<!-- =================================================================
     /getting-started/3-data-and-columns  (community)
     ================================================================== -->

# 3. Data and columns

> Step 3 of 6 · [← First grid](./2-first-grid.md) · [Next: Features →](./4-features.md)

SvGrid reads two arrays: `data` (your rows) and `columns` (the
column-definition list). Everything else is opt-in.

## Row data

The `data` prop is any `ReadonlyArray<TRow>`. A Svelte 5 `$state`
array, a derived store, an SWR/TanStack-Query cache, a `+page.ts` load
result, a plain literal - the grid doesn't care, as long as the array
reference changes when the rows change.

```svelte
<script lang="ts">
  import { SvGrid } from 'sv-grid-community'

  type Person = { id: string; firstName: string; age: number }

  // Reactive: pushing into `rows` updates the grid automatically.
  let rows = $state<Person[]>([
    { id: '1', firstName: 'Ada',   age: 36 },
    { id: '2', firstName: 'Linus', age: 54 },
  ])

  function addRow() {
    rows.push({ id: crypto.randomUUID(), firstName: 'New', age: 0 })
  }
</script>

<button onclick={addRow}>Add row</button>
<SvGrid data={rows} columns={columns} />
```

### Identity

Today the wrapper uses each row's array index as its id. That's fine
for read-only views; if you mutate `rows`, prefer keeping the same
object references for rows that didn't change so selection and edit
state line up. A `getRowId` prop on the wrapper is tracked in
[Missing features](../help/missing-features.md) and supported by the
headless `createSvGrid` core today.

### Immutability

SvGrid does **not** mutate your data. When the user commits an edit the
grid emits an `onCellValueChange` event; you decide whether to mutate
in place or copy. See [Saving values](../help/editing/saving-values.md).

## Column definitions

A column definition tells SvGrid how to read a value out of a row, how
to render it, and how to format it.

```ts
import type { ColumnDef } from 'sv-grid-community'

type Person = {
  id: string
  firstName: string
  lastName: string
  age: number
  joinedAt: string  // ISO date
  salary: number
  active: boolean
}

const columns: ColumnDef<{}, Person>[] = [
  // Simple accessor by field name
  { field: 'firstName', header: 'First name' },

  // Computed value
  {
    id: 'fullName',
    header: 'Full name',
    accessorFn: (row) => `${row.firstName} ${row.lastName}`,
  },

  // Numeric, with locale-aware formatting
  {
    field: 'age',
    header: 'Age',
    format: { type: 'number', options: { maximumFractionDigits: 0 } },
  },

  // Date with explicit pattern
  {
    field: 'joinedAt',
    header: 'Joined',
    format: { type: 'date', pattern: 'y-m-d' },
  },

  // Currency
  {
    field: 'salary',
    header: 'Salary',
    format: { type: 'currency', currency: 'USD' },
  },

  // Boolean rendered as a checkbox
  {
    field: 'active',
    header: 'Active',
    editorType: 'checkbox',
  },
]
```

### Common properties

| Property      | Purpose                                                                                                  |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| `field`       | Reads `row[key]`.                                                                                        |
| `accessorFn`  | Computes the value from the row. Required when there's no underlying field.                              |
| `id`          | Stable column id. Required when you use `accessorFn` (no field to derive from).                          |
| `header`      | String or render snippet for the header.                                                                 |
| `footer`      | String or render snippet for the footer row.                                                             |
| `cell`        | Render snippet / component for the body cell. See [Cell components](../help/cells/cell-components.md).   |
| `format`      | Locale-aware formatter: `number`, `currency`, `percent`, `date`, `datetime`.                             |
| `formatter`   | Function form for one-off custom value formatting.                                                       |
| `editorType`  | Inline editor: `text` \| `number` \| `checkbox` \| `date` \| `datetime`.                                 |
| `width`       | Initial column width in pixels. Default comes from the `columnWidth` prop on `<SvGrid>`.                 |
| `align`       | Header + body alignment: `'left'` \| `'right'` \| `'center'`. Inferred from `editorType` when omitted.   |
| `columns`     | Child column defs for column groups (multi-level header).                                                |

Sorting / filtering / grouping are toggled per-grid via the registered
features. Per-column flags (`enableSorting: false`, etc.) are on the
[Missing features](../help/missing-features.md) list.

### Custom cells

For anything beyond a stringified value, render with `renderSnippet`:

```svelte
<script lang="ts">
  import { SvGrid, renderSnippet, type ColumnDef } from 'sv-grid-community'

  type Person = { firstName: string; lastName: string; age: number }
  const rows: Person[] = [/* ... */]
</script>

{#snippet PersonCell(props: { row: Person })}
  <span class="inline-flex items-center gap-2">
    <span class="initials">{props.row.firstName[0]}{props.row.lastName[0]}</span>
    <span>{props.row.firstName} {props.row.lastName}</span>
  </span>
{/snippet}

<SvGrid
  data={rows}
  columns={[
    {
      id: 'person',
      header: 'Person',
      accessorFn: (r) => `${r.firstName} ${r.lastName}`,
      cell: (ctx) => renderSnippet(PersonCell, { row: ctx.row.original }),
    },
    { field: 'age', header: 'Age' },
  ] satisfies ColumnDef<{}, Person>[]}
/>
```

[Cell components](../help/cells/cell-components.md) has the full
patterns: avatars, sparklines, progress bars, status badges.

<!-- =================================================================
     /getting-started/4-features  (community)
     ================================================================== -->

# 4. Features

> Step 4 of 6 · [← Data and columns](./3-data-and-columns.md) · [Next: Theme and density →](./5-theme-and-density.md)

The grid engine is **feature-gated**. Out of the box you get the core
row model (rows in their original order). To enable sorting, filtering,
grouping, pagination, expansion, or selection, register the matching
feature; the wrapper wires the matching row-model factory for you.

```svelte
<script lang="ts">
  import {
    SvGrid,
    tableFeatures,
    rowSortingFeature,
    columnFilteringFeature,
    rowSelectionFeature,
    type ColumnDef,
  } from 'sv-grid-community'

  const features = tableFeatures({
    rowSortingFeature,
    columnFilteringFeature,
    rowSelectionFeature,
  })
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  filterMode="menu"
  showPagination={true}
  pageSize={25}
/>
```

The wrapper handles the user-facing toggles via plain props. If you
need the headless pipeline directly - say, a custom renderer - drop
down to `createSvGrid` from the same package. See
[Why headless?](../why-headless.md).

## Capability shortcuts (the quick way)

Every capability is **off by default** - a bare `<SvGrid>` is a plain,
read-only table. The fastest way to opt in is a set of boolean shortcut
props. No `tableFeatures({ … })` import, no feature constants:

```svelte
<SvGrid
  data={rows}
  columns={columns}
  sortable
  filterable
  editable
  groupable
  pageable
/>
```

| Shortcut     | Turns on                                         | Equivalent to                              |
| ------------ | ------------------------------------------------ | ------------------------------------------ |
| `sortable`   | Click headers to sort                            | injects `rowSortingFeature`                |
| `filterable` | Per-column filter menu                           | injects `columnFilteringFeature`           |
| `editable`   | Inline cell editing (needs `editorType` columns) | `enableInlineEditing`                      |
| `groupable`  | "Group by this column" in the column menu        | `showGroupingControls`                     |
| `pageable`   | Pagination footer                                | `showPagination`                           |

Each shortcut is an override: omit it (or set `false`) to leave the
capability off; set it `true` to opt in. They compose with the
fine-grained props and the `features` set below - reach for those when
you need finer control (e.g. `filterMode`, `pageSize`, per-column
`sortable: false`). See the live [Shortcut config](https://sv-grid.com/demos/135-shortcut-config) demo.

## The feature catalogue

| Feature                  | What it enables                                           | Doc                                                |
| ------------------------ | --------------------------------------------------------- | -------------------------------------------------- |
| `rowSortingFeature`      | Click headers to sort; Shift-click for multi-sort.        | [Row sorting](../help/rows/row-sorting.md)         |
| `columnFilteringFeature` | Per-column filter menu + filter row + global search.      | [Filter overview](../help/filtering/overview.md)   |
| `rowPaginationFeature`   | Page slicing + footer with page-size selector.            | [Row pagination](../help/rows/row-pagination.md)   |
| `rowSelectionFeature`    | Checkbox column + Shift / Ctrl multi-select.              | [Row selection](../help/rows/styling-rows.md)      |
| `columnGroupingFeature`  | Group-by-column + aggregated footer summaries.            | [Grouping & aggregation](../help/grouping-aggregation.md) |
| `rowExpandingFeature`    | Tree / master-detail expand-collapse.                     | [Tree rows](../help/rows/tree-rows.md)             |

**Rule of thumb:** only register the features you use. Each one ships
about 1-2 KB gzipped and adds a small per-update cost.

## The three operating modes

There's one decision per dimension (sort, filter): **uncontrolled**
(default), **observable** (callbacks), or **external** (you own the row
ordering).

### Uncontrolled (the default)

The wrapper owns the state. Pass the start config via props:

```svelte
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  showPagination={true}
  pageSize={50}
  filterMode="menu"
/>
```

### Observable - callbacks fire on every change

The wrapper still owns the state, but emits callbacks. Use this when
something outside the grid needs to react (a "X rows selected" pill,
URL sync, a server fetch).

```svelte
<script lang="ts">
  let sorting = $state<Array<{ id: string; desc: boolean }>>([])
  let filters = $state<Array<{ id: string; operator: string; value: string }>>([])
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  filterMode="menu"
  onSortingChange={(next) => (sorting = next)}
  onFiltersChange={(next) => (filters = next.columns)}
/>
```

### External - you own the row ordering

For server-side data or tree data the wrapper records the sort + filter
UI state but does **not** re-order the rows - you do. See
[Going to production §1](./6-going-to-production.md#1-server-side-data).

## Selection + editing

Both are off by default. Two top-level umbrella props turn them on:

```svelte
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  selectionMode="both"
  showRowSelection={true}
  enableInlineEditing={true}
  enableCellSelection={true}
  onRowSelectionChange={(state, selectedRows) => /* … */}
  onCellValueChange={(event) => /* event: { rowIndex, columnId, oldValue, newValue, row } */}
/>
```

`selectionMode` choices:

- `'row'`   - checkbox column only
- `'cell'`  - click-and-drag range selection only
- `'both'`  - both (default)
- `'none'`  - both off

Cell editing requires `editorType` on the columns you want editable.
See [Editing overview](../help/editing/overview.md).

## Keyboard map

| Action                | Keys                                  |
| --------------------- | ------------------------------------- |
| Move active cell      | Arrow keys                            |
| First / last in row   | Home / End                            |
| First / last in grid  | Ctrl + Home / Ctrl + End              |
| Move by viewport      | Page Up / Page Down                   |
| Extend range          | Shift + arrows / Shift + Home / End   |
| Start editing         | Enter, F2, or double-click            |
| Commit edit           | Enter, Tab                            |
| Cancel edit           | Esc                                   |
| Toggle row selection  | Space                                 |
| Copy / paste range    | Ctrl/Cmd + C / V (TSV)                |

The full a11y model is in [Accessibility](../help/accessibility.md).

<!-- =================================================================
     /getting-started/5-theme-and-density  (community)
     ================================================================== -->

# 5. Theme and density

> Step 5 of 6 · [← Features](./4-features.md) · [Next: Going to production →](./6-going-to-production.md)

The render component (`<SvGrid>`) ships its own scoped styles. You
re-theme it by declaring `--sg-*` CSS custom properties at any level
above the grid - `:root` for the whole app, a wrapper `<div>` for one
instance, or directly on the `<SvGrid>` element itself.

## Token surface

The 20-odd tokens the renderer reads:

| Token                            | What it paints                              |
| -------------------------------- | ------------------------------------------- |
| `--sg-bg`                        | Cell background                             |
| `--sg-fg`                        | Cell text                                   |
| `--sg-muted`                     | Secondary text (footers, subtitles)         |
| `--sg-border`                    | Cell + header borders                       |
| `--sg-header-bg` / `--sg-header-fg` | Header row                               |
| `--sg-row-alt-bg`                | Zebra rows                                  |
| `--sg-row-hover-bg`              | Row + cell hover                            |
| `--sg-row-height`                | Row height                                  |
| `--sg-selection-bg`              | Selected cell / row tint                    |
| `--sg-accent`                    | Sort indicator, focus ring, primary buttons |
| `--sg-focus-ring`                | Keyboard focus outline                      |
| `--sg-input-bg` / `--sg-input-border` | Inline editor + filter inputs          |
| `--sg-pill-active` / `-fg`       | "Active" status pills                       |
| `--sg-pill-pending` / `-fg`      | "Pending" status pills                      |
| `--sg-pill-inactive` / `-fg`     | "Inactive" status pills                     |
| `--sg-scrollbar-*` (10 tokens)   | Custom-painted scrollbars                   |

## Light + dark via `data-theme`

The gallery flips themes by writing `dark` or `light` to
`html[data-theme]`. Every token redeclares under that selector:

```css
:root {
  --sg-bg:          #ffffff;
  --sg-fg:          #0f172a;
  --sg-border:      #e2e8f0;
  --sg-header-bg:   #f1f5f9;
  --sg-row-alt-bg:  #f8fafc;
  --sg-row-hover-bg: #eef2ff;
  --sg-accent:      #2563eb;
}

html[data-theme='dark'] {
  --sg-bg:          #0f172a;
  --sg-fg:          #f1f5f9;
  --sg-border:      #334155;
  --sg-header-bg:   #1e2433;
  --sg-row-alt-bg:  #1b2230;
  --sg-row-hover-bg: #232b3c;
  --sg-accent:      #3b82f6;
  color-scheme: dark;
}
```

Toggling is one line in the app shell:

```svelte
<script lang="ts">
  let theme = $state<'light' | 'dark'>('dark')
  $effect(() => document.documentElement.setAttribute('data-theme', theme))
</script>

<button onclick={() => (theme = theme === 'dark' ? 'light' : 'dark')}>
  Toggle theme
</button>
```

## Per-instance theming

Because the tokens are plain custom properties they cascade. To style a
single grid, wrap it in a `<div>` that sets its own values:

```svelte
<div style="--sg-bg: #fff8f0; --sg-accent: #db2777;">
  <SvGrid {data} {columns} features={features} />
</div>
```

The [`10-custom-cells-and-themes`](../../examples/src/demos/10-custom-cells-and-themes.svelte)
demo applies three full palettes (light / dark / high-contrast) this way.

<div data-docs-demo="10-custom-cells-and-themes" data-height="520"></div>

## Density

Two ways:

1. **Set `rowHeight` on `<SvGrid>`**. Numeric, in pixels. Drives the
   row height and the active-cell hit box.

   ```svelte
   <SvGrid {data} {columns} features={features} rowHeight={28} />
   ```

2. **Override `--sg-row-height` on a wrapper.** Same effect, with the
   token shape if you'd rather express density in CSS.

   ```css
   .compact { --sg-row-height: 28px; }
   .comfortable { --sg-row-height: 48px; }
   ```

A user-facing "density selector" is half a dozen lines:

```svelte
<script lang="ts">
  let density = $state<'compact' | 'normal' | 'comfortable'>('normal')
  const height = $derived(
    density === 'compact' ? 28 : density === 'comfortable' ? 48 : 36,
  )
</script>

<select bind:value={density}>
  <option value="compact">Compact</option>
  <option value="normal">Normal</option>
  <option value="comfortable">Comfortable</option>
</select>

<SvGrid {data} {columns} features={features} rowHeight={height} />
```

## Sizing the grid

The wrapper renders inside whatever container you give it. The
`containerHeight` prop sets the scrollable shell height:

```svelte
<!-- Numeric: px -->
<SvGrid {data} {columns} features={features} containerHeight={520} />

<!-- String: passed through to CSS -->
<SvGrid {data} {columns} features={features} containerHeight="100%" />
<SvGrid {data} {columns} features={features} containerHeight="auto" />
```

For a flex-grow layout the canonical recipe is:

```svelte
<div class="flex flex-col h-screen">
  <header>…</header>
  <div class="flex-1 min-h-0">
    <SvGrid {data} {columns} features={features} containerHeight="100%" />
  </div>
</div>
```

The `min-h-0` is the bit that bites. Flex children default to
`min-height: auto`, which prevents the inner scroll container from
shrinking, which makes the whole page scroll instead of the grid.

## Full Tailwind integration

If your app uses Tailwind, see [Tailwind integration](../help/tailwind.md)
for: install + PostCSS config, `@custom-variant` so the `dark:`
modifier follows `data-theme`, the override hooks for the stable
`.sv-grid-*` class names, and the anti-patterns (don't `@apply` inside
grid selectors, don't put utility classes on grid children, don't
fight column widths in CSS).

<!-- =================================================================
     /getting-started/6-going-to-production  (community)
     ================================================================== -->

# 6. Going to production

> Step 6 of 6 · [← Theme and density](./5-theme-and-density.md)

You have a working grid. This page is the checklist that turns it into
something you'd ship.

## 1. Server-side data

For datasets that don't fit in memory, drive the grid from the server.
Pair `externalSort` + `externalFilter` with the corresponding callbacks
so the grid records the user's intent but doesn't try to re-order rows
it didn't fetch.

```svelte
<script lang="ts">
  import { SvGrid, tableFeatures, rowSortingFeature,
           columnFilteringFeature } from 'sv-grid-community'

  const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })

  let sort    = $state<Array<{ id: string; desc: boolean }>>([])
  let filters = $state<Array<{ id: string; operator: string; value: string }>>([])
  let page    = $state(0)
  const pageSize = 50

  let rows    = $state<Person[]>([])
  let total   = $state(0)
  let loading = $state(false)
  let controller: AbortController | null = null

  async function load() {
    controller?.abort()
    controller = new AbortController()
    loading = true
    try {
      const res = await fetch('/api/people?' + new URLSearchParams({
        sort:    JSON.stringify(sort),
        filters: JSON.stringify(filters),
        page:    String(page),
        size:    String(pageSize),
      }), { signal: controller.signal })
      const body = await res.json()
      rows  = body.rows
      total = body.total
    } catch (err) {
      if ((err as Error).name !== 'AbortError') throw err
    } finally {
      loading = false
    }
  }

  $effect(() => { sort; filters; page; load() })
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  filterMode="menu"
  externalSort={true}
  externalFilter={true}
  showPagination={false}
  onSortingChange={(next) => { sort = next; page = 0 }}
  onFiltersChange={(next) => { filters = next.columns; page = 0 }}
/>
```

The [`09-server-side` demo](../../examples/src/demos/09-server-side.svelte)
has the full runnable version with debounce + abort + a 60 ms mock
latency. The [server-side guide](../help/server-side-data.md) covers
sparse infinite scroll, velocity-aware chunk loading, and
backpressure.

<div data-docs-demo="09-server-side" data-height="520"></div>

## 2. Virtualization for large datasets

For more than ~2k rows, enable row virtualization. For very wide grids
(50+ columns) also enable column virtualization. Both are opt-in so
small grids don't pay the cost.

```svelte
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  virtualization={true}
  columnVirtualization={true}
  overscan={8}
  columnOverscan={3}
  rowHeight={32}
  containerHeight={600}
/>
```

The wrapper's row + column virtualizers handle variable row heights via
the headless `createSvelteVirtualizer` / `createColumnVirtualizer`. See
[demo 06](../../examples/src/demos/06-large-dataset.svelte) for 100k
rows × 100 columns with smooth scroll.

<div data-docs-demo="06-large-dataset" data-height="520"></div>

## 3. Accessibility

The grid implements the WAI-ARIA 1.2 grid pattern out of the box. Every
node has the right role, the active cell carries focus, the keyboard
map matches what assistive tech expects.

You don't need to add anything for a baseline accessible grid. To go
further:

- Add `aria-live` announcements for changes outside the grid (filter
  applied, X rows selected) - see [demo 17](../../examples/src/demos/17-accessibility.svelte).
- Toggle a high-contrast focus outline for users who need it -
  also in demo 17.
- Read [Accessibility](../help/accessibility.md) for the WCAG 2.1 AA
  mapping, forced-colors-mode behaviour, and reduced-motion handling.

<div data-docs-demo="17-accessibility" data-height="500"></div>

## 4. SSR-friendly markup

The render component produces meaningful HTML before hydration. In a
SvelteKit `+page.server.ts` load, the grid's markup hits the browser
already filled with data - first paint shows the table, hydration only
attaches event listeners.

```svelte
<!-- +page.svelte -->
<script lang="ts">
  import { SvGrid, tableFeatures, rowSortingFeature } from 'sv-grid-community'
  let { data } = $props()
</script>

<SvGrid
  data={data.rows}
  columns={columns}
  features={tableFeatures({ rowSortingFeature })}
/>
```

[Demo 19 - SSR](../../examples/src/demos/19-ssr.svelte) takes a
sandboxed pre-hydration snapshot in a JS-disabled iframe to prove the
markup is meaningful before JS runs.

## 5. Content Security Policy

SvGrid runs cleanly under a strict CSP - no `eval`, no `new Function`,
no inline scripts, no inline event handlers. The recommended header:

```
Content-Security-Policy:
  default-src 'self';
  script-src 'self';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data:;
  font-src 'self' data:;
  connect-src 'self';
  frame-ancestors 'none';
  base-uri 'self';
  form-action 'self';
```

Note: no `'unsafe-eval'` and no `'unsafe-inline'` on `script-src`.
[Demo 16 - CSP-compliant](../../examples/src/demos/16-csp-compliant.svelte)
runs a live runtime self-check + a violation listener inside a working
grid.

## 6. TypeScript notes

```ts
import type {
  ColumnDef,
  SvGridApi,
  SortingState,
  TableFeatures,
} from 'sv-grid-community'

// 1. Constrain ColumnDef to your row type so editors and accessors stay typed.
type Row = { id: string; firstName: string; age: number }
const columns: ColumnDef<{}, Row>[] = [
  { field: 'firstName', header: 'First' },   // OK
  { field: 'middleName', header: 'Mid' },    // ✗ "middleName" not on Row
]

// 2. The api type matches your features + row type.
let api = $state<SvGridApi<typeof features, Row> | null>(null)
```

The features generic on `ColumnDef` is the type of the `features`
object - `tableFeatures({ rowSortingFeature })` produces a different
type than `tableFeatures({})`. Pass `typeof features` so column-level
inference picks up which capabilities your grid has.

## 7. What's next

- [Why headless?](../why-headless.md) - the layered architecture and
  when to drop down to the headless core.
- [Pro features](../pro/README.md) - export, import, AI, pivot.
- [Help index](../help/index.md) - the topic-page catalogue.
- [Recipes](../help/recipes.md) - 20+ copy-paste patterns.
- [Comparison vs AG Grid + TanStack](../help/comparison.md) - what
  evaluators read.
- [Missing features](../help/missing-features.md) - the honest gap list.

<!-- =================================================================
     /getting-started/starters  (community)
     ================================================================== -->

# Starters & scaffolding

The fastest way to a working SvGrid app. One command scaffolds a project
with the grid already wired up - no copy-paste, no config archaeology.

## `npm create sv-grid`

```bash
# npm
npm create sv-grid@latest

# pnpm
pnpm create sv-grid

# yarn
yarn create sv-grid
```

Run with no arguments and it walks you through a project name and a
template. Or pass them directly:

```bash
# Minimal Vite + Svelte 5 starter
npm create sv-grid@latest my-app -- --template minimal

# Full SvelteKit admin dashboard
npm create sv-grid@latest my-admin -- --template admin-dashboard
```

Then:

```bash
cd my-app
npm install
npm run dev
```

### Templates

| Template | Stack | Best for |
| --- | --- | --- |
| `minimal` | Vite + Svelte 5 + `sv-grid-community`, one page | Dropping a grid into something quickly |
| `admin-dashboard` | SvelteKit + Tailwind + `sv-grid-community`, deploy to Vercel | A real dashboard / internal tool |

### Options

| Flag | Alias | Description |
| --- | --- | --- |
| `--template <name>` | `-t` | `minimal` or `admin-dashboard` |
| `--force` | `-f` | Scaffold into a non-empty directory |
| `--help` | `-h` | Show usage |

Both templates use the free MIT `sv-grid-community` core. Add
[`sv-grid-pro`](../pro/README.md) for export, import, print, pivot, and
the AI helpers.

## The admin dashboard starter

The `admin-dashboard` template is a production-shaped SvelteKit app you
can fork directly from
[the repo](https://github.com/sv-grid/sv-grid/tree/main/templates/sveltekit-admin-dashboard):

- **App shell** - sidebar nav + top bar (`src/routes/+layout.svelte`)
- **Overview** - KPI cards + a recent-orders grid (`src/routes/+page.svelte`)
- **Orders** - full grid: sort, filter, row selection, inline editing, pagination
- **Customers** - grid with column grouping (drag a column to the group bar)
- **Prerendered to static HTML** for SEO and instant first paint; grids
  hydrate on the client (`prerender = true` in `src/routes/+layout.ts`)
- **Sample data** in `src/lib/data.ts` - swap for your API or a
  SvelteKit `load` function

### Deploy to Vercel

The starter ships with `@sveltejs/adapter-vercel` and a one-click deploy
button in its README. From a forked or scaffolded copy:

```bash
npm run build    # static + serverless output
npm run preview  # preview the production build
```

If you're deploying the template straight from this monorepo's
subfolder, set the Vercel **Root Directory** to
`templates/sveltekit-admin-dashboard`. Scaffolding a standalone copy
first (above) avoids that step.

## Adding the grid to an existing app

Already have a Svelte or SvelteKit project? Skip the scaffolder and
install directly - see [Install](./1-install.md) and
[First grid](./2-first-grid.md).

## Frequently asked questions

### What's the fastest way to start a SvGrid project?

Run `npm create sv-grid@latest` (or `pnpm create sv-grid`). It scaffolds a
Vite + Svelte or SvelteKit project with the grid already wired up, then
`npm install` and `npm run dev`.

### Is there a SvelteKit admin dashboard template?

Yes. `npm create sv-grid@latest my-admin -- --template admin-dashboard`
scaffolds a SvelteKit + Tailwind admin with multiple grids, prerendered
for SEO, and a one-click Deploy-to-Vercel button.

### Do the starters require a Pro license?

No. Both templates use the free MIT `sv-grid-community` core. Pro
features (export, import, print, pivot, AI) are an optional add-on that
runs in evaluation without a key.

## See also

- [Install](./1-install.md) - add SvGrid to an existing project
- [First grid](./2-first-grid.md) - the minimum runnable example
- [Going to production](./6-going-to-production.md) - SSR, virtualization, a11y

<!-- =================================================================
     /help/accessibility  (community)
     ================================================================== -->

# Accessibility

SvGrid implements the WAI-ARIA 1.2 grid pattern with full keyboard
navigation and a screen-reader announcement layer. This page documents
exactly what the grid does, where the responsibility line sits between
the library and your code, and how to verify conformance.

Live demo - high-contrast toggle, `aria-live` log, and a focus-trap
walk-through:

<div data-docs-demo="17-accessibility" data-height="520"></div>

## TL;DR

| Standard                | Status                                                                 |
| ----------------------- | ---------------------------------------------------------------------- |
| WAI-ARIA 1.2 grid pattern | Implemented (see [Roles & properties](#roles--properties)).         |
| WCAG 2.1 AA             | The grid meets AA for the default theme + tokens; your custom theme determines pass/fail of contrast. |
| Keyboard navigation     | Full coverage; see [Keyboard map](#keyboard-map).                      |
| Screen-reader announcements | Cell + selection + edit announcements via a single `aria-live=polite` region. |
| Reduced motion          | Honored: scroll animations + chevron transitions disable when `prefers-reduced-motion: reduce`. |
| Forced colors / high contrast | Supported: borders + focus rings use `currentColor`; no hardcoded `border-color`. |

## Roles & properties

| Element                        | Role           | Notable attributes                                                                                  |
| ------------------------------ | -------------- | --------------------------------------------------------------------------------------------------- |
| `<table>` root                 | `grid`         | `aria-rowcount`, `aria-colcount`                                                                    |
| `<thead>`, `<tbody>`           | `rowgroup`     |                                                                                                     |
| Every `<tr>` (header + body)   | `row`          | `aria-rowindex` (1-based); selected rows get `aria-selected="true"`                                  |
| Header `<th>`                  | `columnheader` | `aria-sort` (`"ascending"` / `"descending"` / `"none"`)                                              |
| Body `<td>`                    | `gridcell`     | `aria-colindex`, `aria-selected`, `aria-readonly` (when the column is non-editable)                  |
| Active cell                    | `gridcell`     | `tabindex="0"`; every other cell `tabindex="-1"` (roving tabindex pattern)                          |
| Filter popover                 | `dialog`       | `aria-label` derived from the column header                                                         |
| Cell editor input              | `textbox` / `combobox` / `checkbox` (depending on `editorType`) | `aria-label` mirrors the column header           |
| Live announcement region       | none (uses `aria-live="polite"` on a visually-hidden `<div>`) |                                                                       |

The grid never sets `role="presentation"` on table elements - screen
readers receive a fully-structured grid.

## Keyboard map

Standard ARIA grid navigation, plus a handful of grid-specific
shortcuts:

### Navigation

| Key                 | Action                                                                |
| ------------------- | --------------------------------------------------------------------- |
| Tab                 | Move focus *out* of the grid to the next focusable element.           |
| Shift+Tab           | Move focus *into* the grid from the previous focusable element.       |
| Arrow Up/Down       | Move active cell one row.                                             |
| Arrow Left/Right    | Move active cell one column.                                          |
| Home                | Active cell → first column in the row.                                |
| End                 | Active cell → last column in the row.                                 |
| Ctrl/Cmd + Home     | Active cell → top-left of the grid.                                   |
| Ctrl/Cmd + End      | Active cell → bottom-right.                                           |
| Page Up / Page Down | Scroll a viewport's worth of rows.                                    |

### Selection (when `rowSelectionFeature` is on)

| Key                       | Action                                                          |
| ------------------------- | --------------------------------------------------------------- |
| Space                     | Toggle the active row's selection.                              |
| Ctrl/Cmd + A              | Select all rows on the current page.                            |
| Shift + Arrow Up/Down     | Extend the row selection.                                       |
| Ctrl/Cmd + Click on a row | Toggle that row's selection without affecting others.           |

### Sort + filter

| Key                              | Action                                                   |
| -------------------------------- | -------------------------------------------------------- |
| Enter (on a header)              | Toggle sort: `none → asc → desc → none`.                 |
| Shift + Enter (on a header)      | Add to multi-sort.                                       |
| Alt + Down (on a header)         | Open the filter menu (when `filterMode='menu'`).         |
| Escape (in a filter menu)        | Close the menu.                                          |

### Editing

| Key                         | Action                                                |
| --------------------------- | ----------------------------------------------------- |
| Enter / F2 / double-click   | Enter edit mode on the active cell.                   |
| Type any character          | Start editing with that character as the first input. |
| Enter / Tab (while editing) | Commit and move to the next cell / row.               |
| Escape (while editing)      | Cancel; revert the cell.                              |
| Delete / Backspace          | Clear the active cell (for cells whose editor supports clearing). |

### Tree rows (when you build them)

The keyboard handler in [Tree rows](./rows/tree-rows.md) adds:

| Key                 | Action (active cell in name column) |
| ------------------- | ----------------------------------- |
| Arrow Right         | Expand a collapsed node.            |
| Arrow Left          | Collapse an expanded node.          |
| Enter / Space       | Toggle.                             |

## Screen-reader announcements

The grid maintains a single `aria-live="polite"` region that emits:

- Cell content when the active cell moves (so VoiceOver/JAWS reads
  "Customer column, row 14, Acme Corp").
- Selection state changes (`"row 14 selected, 3 of 12 rows selected"`).
- Edit commits (`"saved 19.95"`) - useful for users who can't see the
  cell's visual state.
- Sort changes (`"sorted by Customer ascending"`).
- Filter changes (`"3 of 124 rows match"`).

You can replace the announcer with your own by passing
`announcer={(message) => ...}` to `<SvGrid>` if you have a unified
toast system.

## Focus management

- The grid uses a **roving tabindex**: at most one cell at a time has
  `tabindex="0"`, every other has `tabindex="-1"`. This puts the grid
  in the tab order exactly once.
- The "active cell" is the focused cell. It's tracked through every
  navigation, editing, and selection action.
- Editing transfers focus to the editor `<input>`; committing returns
  focus to the cell.
- Modals (filter menu, save dialog) use a focus trap that returns
  focus to the originating header/cell on close.

## High-contrast / forced-colors mode

Windows High Contrast mode (`forced-colors: active`) is respected. The
grid uses `currentColor` for every border and focus ring, so the
system's color tokens take over without overrides leaking. We test
against the [W3C forced-colors test page](https://web.dev/articles/forced-colors).

## Reduced motion

When `prefers-reduced-motion: reduce` matches:

- Smooth-scroll calls become `behavior: 'instant'`.
- Chevron rotations (used in tree demos) are instant rather than 160 ms
  ease.
- Sparkline + KPI bar transitions are disabled.

You don't need to opt in - the grid checks the media query on every
animation entry point.

## What you're responsible for

The grid can't know:

- **Contrast** of your custom CSS variables. Use the [Tailwind
  integration](./tailwind.md) page's contrast notes when picking
  `--sg-fg` / `--sg-bg` pairs.
- **Labels** for cells whose content is purely visual (e.g. a status
  pill that's just a coloured dot). Set `aria-label` on the cell
  content yourself.
- **Reading order** of header groups. The grid emits group headers
  with `aria-colspan` correctly, but if your group label is "Q1"
  alone, screen readers say "Q1" - consider "Q1 2025" to give context.

## How to verify

1. **Keyboard sweep.** Unplug your mouse. Tab in, navigate every cell,
   sort, filter, edit, undo. If any action is unreachable, file an issue.
2. **NVDA + VoiceOver.** Each makes different choices about announcement
   verbosity. Test both.
3. **Lighthouse accessibility audit.** Default theme passes 100. If
   your custom theme drops the score, the deltas are virtually always
   contrast issues you control.
4. **axe-core in your e2e suite.**
   ```ts
   import { injectAxe, checkA11y } from 'axe-playwright'
   await injectAxe(page)
   await checkA11y(page, '.sv-grid-shell', { detailedReport: false })
   ```

## See also

- [Browser support](./browser-support.md) - the `ResizeObserver` /
  Pointer Events floor every assistive-tech tool relies on.
- [Tailwind integration](./tailwind.md) - the `--sg-*` tokens that
  control contrast.
- [Testing your grid](./testing.md) - includes an axe-core recipe.

## Frequently asked questions

### Is SvGrid accessible / WCAG compliant?

SvGrid implements the WAI-ARIA 1.2 grid pattern: `role="grid"` structure, full
keyboard navigation (arrows, Home/End, Page Up/Down, Ctrl+Home/End), a focus
ring on the active cell, and an `aria-live` announcement layer. Final WCAG
conformance also depends on your own cell content and color choices - this page
documents exactly where that line sits.

### Does SvGrid work with screen readers?

Yes. The grid exposes proper roles and emits `aria-live` announcements for
sorting, filtering, and selection changes, so NVDA, JAWS, and VoiceOver can
read the grid state. Because it renders real DOM (not canvas), the content is
also selectable and machine-readable.

### How do I verify accessibility in my app?

Run axe-core against the rendered grid (recipe in the testing guide) and test
keyboard-only navigation. Pair it with the high-contrast focus toggle and the
`--sg-*` contrast tokens to meet your target contrast ratios.

<!-- =================================================================
     /help/agents  (community)
     ================================================================== -->

# Build an AI agent that drives the grid

This is the "AI-native data grid" story end-to-end. Three patterns,
in order of how much agency you hand to the LLM:

1. **Read-only summary agent** - the model describes what's in the
   grid (analyst chat, monthly report drafts)
2. **Stateful UI agent** - the model calls `SvGridApi` methods in
   response to natural language ("group by region, sum revenue")
3. **Autonomous workflow agent** - the model orchestrates multiple
   grids + back-ends (smart import → enrich → export to BI tool)

The grid is designed to support all three. The headless engine + the
imperative `SvGridApi` together form a clean tool surface that any
agent SDK can consume.

> **Looking for the in-grid AI features?** See
> [AI assistant - Pro](./ai.md) for NL filter / smart fill /
> summarise / classify - the agent surface this page describes is
> what you'd build ON TOP of those.

## Pattern 1: Read-only summary agent

```svelte
<script lang="ts">
  import OpenAI from 'openai'
  import { SvGrid, type SvGridApi } from 'sv-grid-community'

  const client = new OpenAI()
  let api = $state<SvGridApi<typeof features, Row> | null>(null)
  let answer = $state('')

  async function ask(question: string) {
    if (!api) return
    // Grid is the source of truth - only send what the user is
    // looking at right now (filters + sort + grouping respected).
    const rows = api.getDisplayedRows().slice(0, 200)
    const r = await client.chat.completions.create({
      model: 'claude-haiku-4-5',
      messages: [
        { role: 'system', content: 'Answer questions about the table below. Be concise.' },
        { role: 'user',   content: `Question: ${question}\n\nTable (first 200 rows):\n${JSON.stringify(rows)}` },
      ],
    })
    answer = r.choices[0]?.message?.content ?? ''
  }
</script>
```

**Trade-off:** simple to build, no tool calling, but the model only
sees the rows you sent it. Fine for "what's the top performer this
quarter?"; not for "filter to last 30 days" - that needs Pattern 2.

## Pattern 2: Stateful UI agent

The grid's imperative API is a clean tool surface. Each `SvGridApi`
method becomes one function the model can call.

```ts
import OpenAI from 'openai'
import { z } from 'zod'

const tools = [
  {
    type: 'function',
    function: {
      name: 'setFilter',
      description: 'Apply a column filter. Use to narrow the visible rows.',
      parameters: {
        type: 'object', required: ['columnId', 'operator', 'value'],
        properties: {
          columnId: { type: 'string' },
          operator: { type: 'string', enum: ['contains', 'equals', 'startsWith', 'greaterThan', 'lessThan', 'between'] },
          value:    { type: 'string' },
          valueTo:  { type: 'string', description: 'Upper bound for "between" only.' },
        },
      },
    },
  },
  {
    type: 'function',
    function: {
      name: 'setSort',
      parameters: { type: 'object', required: ['columnId', 'direction'],
        properties: { columnId: { type: 'string' }, direction: { type: 'string', enum: ['asc', 'desc'] } } },
    },
  },
  {
    type: 'function',
    function: {
      name: 'setGroupBy',
      parameters: { type: 'object', required: ['columnIds'],
        properties: { columnIds: { type: 'array', items: { type: 'string' } } } },
    },
  },
  {
    type: 'function',
    function: { name: 'clearAllFilters', parameters: { type: 'object' } },
  },
]
```

Wire the tool calls back to your live `api` reference:

```ts
async function runAgent(prompt: string) {
  let messages = [
    { role: 'system', content: `You drive a data grid. Columns: ${JSON.stringify(api!.getColumns())}.` },
    { role: 'user',   content: prompt },
  ]
  for (let turn = 0; turn < 6; turn += 1) {  // safety bound
    const r = await client.chat.completions.create({
      model: 'claude-sonnet-4-6',
      messages, tools, tool_choice: 'auto',
    })
    const msg = r.choices[0]!.message
    messages.push(msg)
    if (!msg.tool_calls?.length) return msg.content
    for (const call of msg.tool_calls) {
      const args = JSON.parse(call.function.arguments)
      switch (call.function.name) {
        case 'setFilter':       api!.setFilter(args.columnId, args); break
        case 'setSort':         api!.setSort(args.columnId, args.direction); break
        case 'setGroupBy':      api!.setGroupBy(args.columnIds); break
        case 'clearAllFilters': api!.clearAllFilters(); break
      }
      messages.push({ role: 'tool', tool_call_id: call.id, content: 'ok' })
    }
  }
}
```

User types *"show me last quarter's deals over $50k, grouped by
region"* and the agent calls `setFilter('sellDate', { ... })` +
`setFilter('amount', { operator: 'greaterThan', value: '50000' })` +
`setGroupBy(['region'])` in a single turn.

**The whole `SvGridApi` is on the menu.** Wrap as many or as few
methods as you want; the model only calls what you expose.

## Pattern 3: Autonomous workflow agent

The grid becomes one node in a longer chain. Typical shape:

```ts
const agent = new Agent({
  tools: [
    fetchCsvFromS3,           // pull raw data
    aiSmartPaste,             // parse to typed rows (uses /api/ai endpoint)
    runValidations,           // your domain validations
    pushToGrid,               // api.addRows(...)
    waitForUserApproval,      // pauses for human-in-the-loop
    exportToBigQuery,         // api.exportData({ format: 'csv', ... }) + push
  ],
})
await agent.run('Process today\'s sales batch from s3://acme/sales/2026-06-06.csv')
```

The grid is **the visible state** the human can audit between steps -
which is exactly what makes a workflow agent trustworthy: every
intermediate result lands in a sortable, filterable table the user
can inspect.

## Sandboxing rules

When an LLM is calling grid methods, three boundaries keep things sane:

1. **Whitelist tools at the top level.** Never expose `eval` or
   arbitrary JS. The `SvGridApi` methods above are the only surface
   the model needs.
2. **Validate every tool argument** before invoking. The JSON Schemas
   at [`/schemas/`](./mcp-server.md) cover every input shape; use
   `ajv` or `zod` to check.
3. **Bound the agent loop.** A maximum-turns counter (6 is plenty
   for grid manipulation) prevents runaway calls. Combine with a
   per-turn token budget.

## Common workflows shipped as MCP prompts

The [MCP server](./mcp-server.md) ships three pre-built prompts that
implement the above patterns:

- **`/svgrid:nl-to-grid-state`** - Pattern 2 with the tool set wired up
- **`/svgrid:csv-to-typed-rows`** - Smart-paste an arbitrary CSV into
  a typed row array with confidence per row
- **`/svgrid:summarise-view`** - Pattern 1 grounded in `api.getDisplayedRows()`

## Worked example: NL → Pivot

Live in [demo 75 (AI Smart Paste)](https://svgrid.com/#/demos/75-ai-smart-paste)
and [demo 52 (Pivot designer)](https://svgrid.com/#/demos/52-pivot-table)
- both ship in the gallery.

## Failure modes

| Symptom                                    | Cause                                                       | Fix                                                                       |
| ------------------------------------------ | ----------------------------------------------------------- | ------------------------------------------------------------------------- |
| Model invents columns that don't exist     | No grounding on the live column set                          | Pass `api.getColumns()` in the system prompt every turn                    |
| Model calls `setFilter('Status', ...)` with the wrong case | Column ids are case-sensitive                | Include the column ids in the system prompt (snake_case vs PascalCase)     |
| Multi-step chain forgets the row count drops | Each tool call doesn't return the new visible row count    | Return `api.getDisplayedRows().length` from each handler                    |
| Agent loops forever                        | No max-turns bound                                          | Always cap the loop (5-10 turns is plenty for grid manipulation)            |

## See also

- [LLM grounding](./llm-grounding.md) - the static doc files agents read
- [MCP server](./mcp-server.md) - turnkey integration for Claude Desktop / Cursor / Zed
- [AI assistant - Pro](./ai.md) - the in-grid NL features (not the agent layer)
- [Architecture](./architecture.md) - what state lives where (agents need to know)

## Frequently asked questions

### Can an AI agent control the SvGrid data grid?

Yes. The imperative `SvGridApi` (filter, sort, select, set values, expand, page)
is exactly the surface an agent drives. This page covers three patterns, from a
read-only summary agent to a full read-write agent that mutates grid state.

### What is the safest way to let an LLM drive the grid?

Start read-only: let the model describe and query the grid before it writes.
When you grant write access, route it through the same `SvGridApi` calls a user
action would trigger, so validation and dirty-tracking still apply.

### Do I need the MCP server to build a grid agent?

No. The MCP server is a turnkey integration for desktop AI clients; for a custom
in-app agent you call `SvGridApi` directly. Both are documented here and in the
MCP server guide.

<!-- =================================================================
     /help/ai-smart-paste  (community)
     ================================================================== -->

# AI Smart Paste

Drop any shape of contact / lead / row data into a text area - CSV,
TSV, JSON, vCard, Markdown table, an email signature block, or a
single line of prose - and the parser maps it into typed rows your
grid can insert or merge.

This is the demo your sales / customer-success / RevOps users want.
Their day already has them pasting from Salesforce, Slack, Excel,
business cards, and signature blocks; the parser absorbs the chaos
and the grid renders the cleaned result.

<div data-docs-demo="75-ai-smart-paste" data-height="640"></div>

## What the parser handles

Six input formats are detected automatically, tried in this order:

| Format            | Example trigger                                                | Notes                                              |
|-------------------|----------------------------------------------------------------|----------------------------------------------------|
| **vCard**         | `BEGIN:VCARD`                                                  | RFC 6350. iOS / macOS / Google Contacts export.    |
| **Markdown table**| Lines starting/ending with `|`, with a `---` separator         | GitHub, Slack threads, docs.                       |
| **JSON**          | Input starts with `[` or `{`                                   | Any field names; multi-language matched.           |
| **CSV / TSV / PSV**| Consistent tab / comma / semicolon / pipe delimiter           | Multi-language headers (`Nom`, `Téléphone` etc).   |
| **Signature blocks**| Multi-line blocks separated by blank lines containing an email| `Name <email>` form, "Role, Company" lines.      |
| **Free-form prose**| Anything else, one line per record                            | Extracts by signal (email regex, phone regex).     |

On top of detection, every parsed row goes through three
**normalization** passes before the preview panel renders it:

1. **Email typo correction** - common domain typos (`gmial.com`,
   `gmail.con`, `gosling.con`) are auto-fixed and surfaced as an info
   note on the row.
2. **Phone normalization** - any phone is rewritten to a consistent
   `+CC AAA BBB CCCC` shape (US, UK, DE, FR, JP recognized; 10-digit
   bare numbers assumed North American).
3. **Name cleaning** - titles (`Dr.`, `Prof.`, `Mr.`) and suffixes
   (`Jr.`, `III`, `PhD`) are stripped; `"Last, First"` is rewritten
   to `"First Last"`.

Duplicate detection runs last: rows with the same normalized email
collapse into one, with missing fields merged from the duplicate.

## Complete drop-in example

A minimal contact list with the Smart Paste panel above the grid.
Paste any of the formats below into the textarea and click
**Parse with AI**.

```svelte
<script lang="ts">
  import {
    SvGrid,
    tableFeatures,
    rowSortingFeature,
    rowSelectionFeature,
    type ColumnDef,
    type SvGridApi,
  } from 'sv-grid-community'

  type Contact = {
    id: string
    fullName: string
    email: string
    company: string
    role: string
    phone: string
  }

  let rows = $state<Contact[]>([
    { id: 'c1', fullName: 'Ada Lovelace',   email: 'ada@analytic.engine', company: 'Analytic Engine',  role: 'Founder',    phone: '+44 20 1234 5678' },
    { id: 'c2', fullName: 'Linus Torvalds', email: 'linus@kernel.org',    company: 'Linux Foundation', role: 'Maintainer', phone: '+1 503 555 0101' },
  ])

  const features = tableFeatures({ rowSortingFeature, rowSelectionFeature })
  let api = $state<SvGridApi<typeof features, Contact> | null>(null)

  let pasteText = $state('')
  let parsed = $state<Contact[]>([])

  // The real parser is bundled in demo 75. This stub does just CSV +
  // semicolon detection; swap with `assistant(text)` from the demo to
  // get the full feature set.
  async function parse(text: string): Promise<Contact[]> {
    const delim = text.includes('\t') ? '\t'
                : text.includes(';')  ? ';'
                : ','
    return text.trim().split('\n').map((line, i) => {
      const cells = line.split(delim).map((c) => c.trim())
      return {
        id: `paste-${i}`,
        fullName: cells[0] ?? '',
        email:    cells[1] ?? '',
        company:  cells[2] ?? '',
        role:     cells[3] ?? '',
        phone:    cells[4] ?? '',
      }
    })
  }

  async function runParse() {
    parsed = await parse(pasteText)
  }

  function applyAll() {
    if (!api || parsed.length === 0) return
    api.addRows(parsed)
    parsed = []
    pasteText = ''
  }

  const columns: ColumnDef<typeof features, Contact>[] = [
    { field: 'fullName', header: 'Name',    editorType: 'text', width: 180 },
    { field: 'email',    header: 'Email',   editorType: 'text', width: 220 },
    { field: 'company',  header: 'Company', editorType: 'text', width: 180 },
    { field: 'role',     header: 'Role',    editorType: 'text', width: 160 },
    { field: 'phone',    header: 'Phone',   editorType: 'text', width: 160 },
  ]
</script>

<section style="display: flex; flex-direction: column; gap: 12px; height: 100%;">
  <textarea
    bind:value={pasteText}
    placeholder="Paste CSV / TSV / JSON / vCard / Markdown / signature blocks here…"
    rows="4"
    style="width: 100%; font-family: ui-monospace, Menlo, monospace; padding: 10px; border-radius: 8px; border: 1px solid #cbd5e1;"
  ></textarea>

  <div style="display: flex; gap: 8px;">
    <button onclick={runParse}>✨ Parse with AI</button>
    <button onclick={applyAll} disabled={parsed.length === 0}>
      Apply {parsed.length} row{parsed.length === 1 ? '' : 's'}
    </button>
  </div>

  {#if parsed.length > 0}
    <div style="border: 1px solid #cbd5e1; border-radius: 8px; padding: 10px;">
      <strong>Preview:</strong>
      <ul>
        {#each parsed as p (p.id)}
          <li>{p.fullName} · {p.email} · {p.company}</li>
        {/each}
      </ul>
    </div>
  {/if}

  <div style="flex: 1; min-height: 0;">
    <SvGrid
      data={rows}
      columns={columns}
      features={features}
      containerHeight="100%"
      onApiReady={(next) => (api = next)}
    />
  </div>
</section>
```

For the full parser (vCard, Markdown table, signature blocks,
multi-language headers, typo correction, phone normalization,
de-duplication), read the [`assistant()` implementation in demo 75](../../examples/src/demos/75-ai-smart-paste.svelte)
and copy it verbatim - the parser is 350 lines of pure TypeScript with
no library dependencies.

## Try these input formats

Each one runs through the parser and produces 2-3 rows in the
preview panel.

### vCard

```text
BEGIN:VCARD
VERSION:3.0
FN:Brendan Eich
ORG:Brave Software
TITLE:CEO
EMAIL;TYPE=WORK:brendan@brave.com
TEL;TYPE=CELL:+1 415 555 0188
END:VCARD
BEGIN:VCARD
VERSION:3.0
FN:Anders Hejlsberg
ORG:Microsoft
TITLE:Technical Fellow
EMAIL;TYPE=WORK:anders.h@microsoft.com
TEL;TYPE=WORK:+1 425 555 0177
END:VCARD
```

### Markdown table with multi-language headers

```text
| Name | Email | Company | Rol | Téléphone |
|---|---|---|---|---|
| Grace Hopper | grace@nps.mil | US Navy | Rear Admiral | +1 202 555 0133 |
| Ken Thompson | ken@bell-labs.com | Bell Labs | Researcher | +1 908 555 0124 |
```

### Email signature blocks

```text
Donald E. Knuth <knuth@cs.stanford.edu>
Professor Emeritus, Stanford University
Phone: (650) 555-0111

Barbara Liskov <liskov@csail.mit.edu>
Institute Professor at MIT CSAIL
Cell: +1.617.555.0142
```

### Messy real-world paste

Title prefixes, "Last, First" inversion, email typo, and varied phone
formats - the parser cleans every field:

```text
Dr. Margaret Rhodes; margaret@gmial.com; Rhodes Capital LLC; Managing Partner; (212) 555-0188
Wirth, Niklaus; niklaus.wirth@inf.ethz.ch; ETH Zurich; Professor Emeritus; +41 44 555 0166
"James Gosling" <james@gosling.con>; Amazon Web Services; Distinguished Engineer; 1-415-555-0177
```

After parsing:
- `Dr. Margaret Rhodes` → `Margaret Rhodes`
- `Wirth, Niklaus` → `Niklaus Wirth`
- `gmial.com` → `gmail.com` (logged as `Fixed domain typo → gmail.com`)
- `gosling.con` → `gosling.com` (same)
- `(212) 555-0188` → `+1 212 555 0188`
- `1-415-555-0177` → `+1 415 555 0177`

## Swapping in a real LLM

The bundled `assistant()` is fully deterministic and runs in the
browser. To route through a real model instead - GPT, Claude,
Gemini, Llama on your infra - replace the `assistant()` body with:

```ts
async function assistant(text: string): Promise<{ rows: ParsedRow[]; log: string[] }> {
  const res = await fetch('/api/smart-paste', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ text }),
  })
  if (!res.ok) throw new Error(`Parser failed: ${res.status}`)
  return res.json() as Promise<{ rows: ParsedRow[]; log: string[] }>
}
```

On the server side, the model receives the raw paste and a schema for
`ParsedRow`, and returns the same shape. Useful when you need:

- Domain-specific extraction (medical, legal, financial)
- A model with knowledge of your CRM's record shapes
- Audit logging of every paste for compliance

The bundled parser stays the deterministic fallback - call it client-side
when the network call fails or for the 90% of cases that don't need a
model.

## See also

- [Demo 75 - AI Smart Paste](../../examples/src/demos/75-ai-smart-paste.svelte) - the full parser, 5 sample tiles, preview panel, per-row insert/update/skip control, commit through `api.setCellValue`
- [AI assistant - Pro](./ai.md) - the `api.ai.filter`, `api.ai.smartFill`, `api.ai.summarize`, `api.ai.classify` helpers
- [Import](./import.md) - file picker for xlsx / csv / tsv / json

<!-- =================================================================
     /help/ai  (pro)
     ================================================================== -->

# AI assistant - Pro

Bring a language model into your grid with four helpers that stay
strictly model-agnostic: **natural-language filter**, **smart fill**,
**summarise**, and **classify**. Ships in the paid
**[sv-grid-pro](https://www.npmjs.com/package/sv-grid-pro)** add-on; the
Community build does not include these features.

Run all four helpers live - the demo below is wired to the bundled
deterministic `mockAIProvider`, so no keys required:

<div data-docs-demo="51-ai-assistant" data-height="560"></div>


## What it is

`installPro(api)` (the same call you use for export and print) augments
your `SvGridApi` with an `ai` namespace:

```ts
api.ai.filter(query, opts?)        // NL query -> filter + sort plan
api.ai.smartFill(opts)             // examples -> proposed column values
api.ai.summarize(opts)             // row / selection / group / all -> text + bullets
api.ai.classify(opts)              // free-text cells -> bucketed labels
```

Every call routes through one `AIProvider` you register at app boot.
The grid never bundles a model client - you keep full control of model
choice, routing, and data handling.

## When to use it

- **NL filter** is the highest-leverage feature: it replaces a dozen
  per-column filter operators with one search box for analyst users.
- **Smart fill** is the killer feature for spreadsheet-style entry: type
  one or two examples in a column, accept the rest with one click.
- **Summarise** is for dashboards where the user wants a "what's
  interesting here?" paragraph without clicking through every cell.
- **Classify** is for triage workflows where free-text rows need a
  consistent bucket label before downstream automation runs.

If you don't need natural-language anywhere, skip this module entirely -
the rest of `sv-grid-pro` doesn't depend on it.

## Setting up the provider

The grid talks to your model through a single async function. Wire it
once at app startup:

```ts
import { setAIProvider, type AIProvider } from 'sv-grid-pro'

const myProvider: AIProvider = async ({ prompt, responseFormat, signal, task, maxOutputTokens }) => {
  const r = await fetch('/api/ai', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ prompt, responseFormat, task, maxOutputTokens }),
    signal,
  })
  if (!r.ok) throw new Error(`AI provider returned ${r.status}`)
  return r.text()
}

setAIProvider(myProvider)
```

A few design points worth knowing:

- **`responseFormat: 'json'`** is what `aiFilter`, `aiSmartFill`,
  `aiSummarize`, and `aiClassify` all request. Tell your model to return
  strict JSON only; the grid `JSON.parse`s the result. (A common
  resilience trick: the grid strips a single markdown code fence
  automatically so models that wrap JSON in ` ```json ... ``` ` still
  parse cleanly.)
- **`signal`** is forwarded so consumers can cancel in-flight calls
  when the user moves on.
- **`task`** is a tag (`'filter' | 'smart-fill' | 'summarize' | 'classify'`)
  - useful when you want to route different tasks to different models
  (a cheap one for filter, a stronger one for summarise).
- **`maxOutputTokens`** is a soft hint, also useful for cost routing.

For testing or for demo purposes, the package ships a deterministic
`mockAIProvider` that returns plausible canned shapes per task. Wire it
in development:

```ts
import { setAIProvider, mockAIProvider } from 'sv-grid-pro'
setAIProvider(mockAIProvider)
```

## 1. Natural-language filter

Translate a sentence into a filter + sort plan against the current
grid's columns. The grid embeds the column schema (names, types, sample
values) in the prompt so the model picks real field names rather than
hallucinating.

```ts
const plan = await api.ai.filter('accounts losing momentum in EMEA, by NPS')
// {
//   filters: [
//     { field: 'region', operator: 'equals', value: 'EMEA' },
//     { field: 'nps',    operator: 'lessThan', value: '30' },
//   ],
//   sort: [{ field: 'nps', desc: false }],
//   rationale: 'EMEA region, low NPS, sorted ascending.',
// }
```

By default `aiFilter` returns the plan but **does not apply it** to the
grid - that lets you show a preview ("here's what I'd do, accept?")
before committing. Pass `{ apply: true }` to apply directly:

```ts
await api.ai.filter('big EMEA deals', { apply: true })
```

### Hallucination guard

If the model invents a column name that doesn't exist in your data, the
helper silently drops that clause rather than passing it to `setFilter`,
which would otherwise throw. This is intentional: you'd rather lose a
clause than crash the page.

## 2. Smart fill

User provides one or two worked examples for a column; the grid asks
the model to propose values for the remaining empty cells.

```ts
const result = await api.ai.smartFill({
  field: 'tier',
  examples: [
    { input: { company: 'Northwind' }, output: 'enterprise' },
    { input: { company: 'Helios' },    output: 'growth' },
  ],
})
// result.predictions: [{ rowIndex, value, confidence }, ...]
```

You decide what to do with the predictions - accept-all, accept-per-cell,
write them to a `proposedTier` field on the row data and render a "✓"
button in the cell, etc. The example demo does per-cell accept with a
confidence-coloured pill.

If `targetRowIndices` is omitted, the helper auto-selects rows whose
current `field` value is `null`, `undefined`, or `''`.

## 3. Summarise

Drop a slice of the grid into the model and ask for a one-paragraph +
bulleted summary. Four target modes:

```ts
await api.ai.summarize({ target: { kind: 'all' } })
await api.ai.summarize({ target: { kind: 'row', rowIndex: 5 } })
await api.ai.summarize({ target: { kind: 'selection', rowIndices: [1,2,3] } })
await api.ai.summarize({ target: { kind: 'group', field: 'region', value: 'EMEA' } })
```

For large slices the grid samples rows uniformly so the prompt stays
under a sensible token budget. The response shape:

```ts
{
  text: 'One paragraph...',
  bullets: ['punchy bullet 1', 'punchy bullet 2', ...],
  highlightedFields: ['arr', 'nps'],   // columns the summary leans on
}
```

The optional `question` parameter biases the summary toward the columns
that answer the question.

## 4. Classify

Bucket free-text cells into one of a known set of labels:

```ts
const r = await api.ai.classify({
  inputField: 'notes',
  outputField: 'sentiment',
  classes: ['at-risk', 'expanding', 'steady'],
  classDescriptions: {
    'at-risk':   'churn signals, escalations, lost champion',
    'expanding': 'new modules, more seats, additional regions',
    'steady':    'no signals in either direction',
  },
})
```

The helper filters out any predictions whose value is not in `classes`,
so downstream code can trust the output is a clean enum.

## Subscribing the grid to predictions

Cell snippets cache their output by `(row, column)`. If you store
predictions in a *separate* state ref - e.g. a `Map<rowIndex, value>`
that the snippet looks up at render time - the grid won't know to
re-render when that map changes. **Write the proposal onto the row
itself instead:**

```ts
async function runClassify() {
  const result = await api.ai.classify({ /* ... */ })
  const byIdx = new Map(result.predictions.map((p) => [p.rowIndex, p]))
  // Re-assign the data array - Svelte 5 reactivity picks this up and the
  // grid re-renders every visible cell.
  accounts = accounts.map((a, i) => {
    const p = byIdx.get(i)
    return p ? { ...a, proposedSentiment: p.value, sentimentConfidence: p.confidence } : a
  })
}
```

Then your cell snippet reads `props.row.proposedSentiment` and re-renders
exactly when expected.

## License gate

Every AI call routes through the same polite license gate as `exportData`
and `print`:

- **No key set** → call still runs, the grid shows an "unlicensed"
  watermark and the console logs a one-time nudge directing the user to
  pricing. This is intentional for demos and evaluation.
- **`SVPRO-DEV-...` / `SVPRO-EVAL-...`** → call runs, a one-time
  `console.info` notes that the key is not for production.
- **Other valid `SVPRO-` key** → call runs silently.
- **Malformed prefix or revoked key** → call throws.

## See also

- [Demo 21 - Export + Print](../../examples/src/demos/21-export-and-print.svelte) - the other Pro
  surface, installed by the same `installPro(api)` call.
- [Demo 51 - AI assistant](../../examples/src/demos/51-ai-assistant.svelte) - the full demo this
  page documents, with all four helpers wired to the mock provider.

## Frequently asked questions

### What AI features does SvGrid have?

The `sv-grid-pro` AI assistant ships four model-agnostic helpers:
natural-language filter, smart fill, summarise, and classify. They run through a
bring-your-own-model adapter, so you wire in your own LLM endpoint.

### Which LLM does SvGrid use?

None by default - it is model-agnostic. You supply an adapter for OpenAI,
Anthropic Claude, a local model, or anything else. The demo ships a mock
provider so you can evaluate the flow without an API key.

### Is my grid data sent to an AI provider?

Only if you wire one up and invoke a helper. SvGrid itself makes no network
calls; the AI helpers send exactly the prompt you construct to the adapter you
configure, so you control what leaves the browser.

<!-- =================================================================
     /help/api-reference  (community)
     ================================================================== -->

# API reference

A flat index of every Stable export. Each entry links to the topic
page that covers it in depth. For the formal TypeScript shapes,
inspect the `.d.ts` files in `node_modules/sv-grid-community/dist` -
they're the source of truth and ship with full JSDoc.

> The "Tier" column reflects the badges from
> [API stability](./api-stability.md). Anything not listed here is
> Internal and may move under your feet.

## sv-grid-community

### Components

| Export                | Tier         | What it is                                                                                     |
| --------------------- | ------------ | ---------------------------------------------------------------------------------------------- |
| `SvGrid`              | Stable       | The render component. See [Getting Started §1](../getting-started.md#1-your-first-grid-in-60-seconds). |
| `FlexRender`          | Stable       | Helper for rendering `cell` / `header` / `footer` templates inside custom UIs.                  |

### Engine

| Export                | Tier         | What it is                                                                                    |
| --------------------- | ------------ | --------------------------------------------------------------------------------------------- |
| `createSvGrid`        | Stable       | Build a headless grid instance; the `<SvGrid>` component is a thin wrapper around this.       |
| `tableFeatures`       | Stable       | Bundle features (sorting, filtering, ...) into a single typed object for use in column generics. |
| `createGridState`     | Stable       | Controlled-state helper that returns a `[get, set]` pair compatible with Svelte's `$state`.   |

### Features (row models)

| Export                       | Tier   | Enables                                          |
| ---------------------------- | ------ | ------------------------------------------------ |
| `rowSortingFeature`          | Stable | Column-header click to sort, programmatic sort.  |
| `columnFilteringFeature`     | Stable | Per-column filters (operator + value + menu).    |
| `rowSelectionFeature`        | Stable | Single + multi row selection with checkboxes.    |
| `columnGroupingFeature`      | Stable | Multi-level column header groups.                |
| `rowExpandingFeature`        | Stable | Expand / collapse rows (master-detail, trees).   |

### Imperative API (`SvGridApi`)

Reached via `<SvGrid onApiReady={(api) => /* ... */}>`. Every method
is Stable.

| Method                              | Purpose                                                            |
| ----------------------------------- | ------------------------------------------------------------------ |
| `getCellValue(rowIndex, columnId)`  | Read a cell value.                                                 |
| `setCellValue(rowIndex, columnId, v)` | Write a cell value, runs through the same write pipeline as inline edit. |
| `addRow(row, position?)`            | Insert one row at top / bottom / numeric index.                    |
| `addRows(rows, position?)`          | Bulk insert.                                                       |
| `removeRow(rowIndex)`               | Remove one row by data-array index.                                |
| `removeRows(rowIndices)`            | Bulk remove.                                                       |
| `addColumn(column, position?)`      | Insert one column at left / right / numeric index.                 |
| `addColumns(columns, position?)`    | Bulk insert.                                                       |
| `removeColumn(columnId)`            | Remove one column by id (or field).                                |
| `setColumnVisible(columnId, visible)` / `isColumnVisible(columnId)` | Column visibility.                              |
| `setSort(columnId, dir)` / `clearSort()` | Programmatic sort.                                            |
| `setGroupBy(columnIds)`             | Set the group-by columns.                                          |
| `setFilter(columnId, filter)` / `clearFilter(columnId)` / `clearAllFilters()` | Programmatic filtering.        |
| `getFilters()`                      | Snapshot the active column-menu filters.                           |
| `getDisplayedRows()`                | Snapshot the currently displayed rows (after filter/sort/page).    |
| `getData()`                         | Snapshot the raw `data` prop.                                      |
| `clearRowSelection()`               | Untick every selected row.                                         |

### Column definition (`ColumnDef`)

| Property            | Tier   | Notes                                                                |
| ------------------- | ------ | -------------------------------------------------------------------- |
| `id`                | Stable | Use when no `field` (e.g. computed columns).                         |
| `field`             | Stable | Row property the cell reads + writes by default.                     |
| `accessorFn`        | Stable | Replace the `field`-based read with a function. Used heavily by pivot. |
| `header`            | Stable | String or a render template.                                         |
| `footer`            | Stable | Same shape as header.                                                |
| `cell`              | Stable | Custom cell render template.                                         |
| `columns`           | Stable | Nested children → multi-row header groups.                           |
| `editorType`        | Stable | `'text'` / `'number'` / `'date'` / `'datetime'` / `'checkbox'` / `'list'` / `'chips'`. |
| `editorOptions`     | Stable | Option list for `list` + `chips` editors. Static array or `(row) => array`. |
| `editorMultiple`    | Stable | Allow multi-select on `list` / `chips`.                              |
| `editorSeparator`   | Stable | Join character for multi-value display.                              |
| `editable`          | Stable | `boolean | (ctx) => boolean` - per-column or per-cell gate.          |
| `format`            | Stable | Built-in formatter (`number` / `currency` / `percent` / `date`).     |
| `formatter`         | Stable | Free-form formatter callback.                                        |
| `width`             | Stable | Pixel width (default falls back to grid's `columnWidth`).            |

### Types

| Export                | Tier   | Purpose                                                              |
| --------------------- | ------ | -------------------------------------------------------------------- |
| `ColumnDef`           | Stable | Column definition shape (see table above).                           |
| `CellContext`         | Stable | The `ctx` object passed to `cell` / `editable` / `formatter`.        |
| `HeaderContext`       | Stable | The `ctx` object passed to `header` / `footer`.                      |
| `Row` / `Cell` / `Column` / `Header` / `HeaderGroup` | Stable | Engine objects you can read inside templates. |
| `SvGridApi`           | Stable | The imperative API shape (every method above is on this interface).  |
| `RowData`             | Stable | Alias for `Record<string, unknown>`; the row shape constraint.       |
| `TableFeatures`       | Stable | The shape of the bag `tableFeatures()` returns.                      |

### Static utilities

Re-exports from `'sv-grid-community/static-functions'` for use outside
a Svelte 5 component:

| Export                       | Tier   | What it is                                              |
| ---------------------------- | ------ | ------------------------------------------------------- |
| `sortRows(rows, sorting)`    | Stable | Pure sort helper. Same comparator the grid uses.        |
| `filterRows(rows, filters)`  | Stable | Pure filter helper.                                     |
| `groupRows(rows, groupBy, aggregators)` | Stable | Pure group-and-aggregate helper.            |
| `getDisplayedRows(rows, state)` | Stable | One-shot pipeline (filter → sort → group → page).    |

## sv-grid-pro

### Installation

| Export       | Tier   | What it is                                                                                 |
| ------------ | ------ | ------------------------------------------------------------------------------------------ |
| `installPro(api)` | Stable | Augments a `SvGridApi` with `exportData`, `print`, `importData`, and `ai.*`.          |
| `ProGridApi`      | Stable | The post-install API shape.                                                          |

### License

| Export              | Tier   | Purpose                                                       |
| ------------------- | ------ | ------------------------------------------------------------- |
| `setLicenseKey(s)`  | Stable | Register a key at startup.                                    |
| `clearLicenseKey()` | Stable | Tear down the key on logout, etc.                             |
| `getLicenseKey()`   | Stable | Inspect the current key (returns `null` when unset).          |
| `isLicenseKeySet()` | Stable | Boolean for "any key registered".                             |
| `hasValidLicense()` | Stable | Boolean for "key passes prefix + revocation check".           |
| `assertProLicensed()` | Stable | Throws on a malformed / revoked key, soft-warns when unset. |
| `dismissUnlicensedNudge()` | Stable | Suppress the console one-time nudge.                   |

### Export + print

| Export                   | Tier   | Purpose                                                              |
| ------------------------ | ------ | -------------------------------------------------------------------- |
| `exportGrid(api, opts)`  | Stable | Same as `api.exportData(opts)` for use without `installPro`.         |
| `printGrid(api, opts?)`  | Stable | Same as `api.print(opts)`.                                           |
| `ExportFormat`           | Stable | `'xlsx' | 'pdf' | 'csv' | 'tsv' | 'html'`.                          |
| `ExportOptions` / `ExportColumn` | Stable | Option shape (see [Data export and printing](./export.md)).  |
| `PrintOptions`           | Stable | Option shape.                                                        |

### Import

| Export                | Tier                          | Purpose                                                  |
| --------------------- | ----------------------------- | -------------------------------------------------------- |
| `importData(api, opts)` | Stable, accepting feedback | Same as `api.importData(opts)`.                          |
| `ImportFormat`        | Stable, accepting feedback    | `'xlsx' | 'csv' | 'tsv' | 'json' | 'auto'`.              |
| `ImportOptions<T>`    | Stable, accepting feedback    | File + format + column map + validator + commit options. |
| `ImportResult<T>`     | Stable, accepting feedback    | `{ headers, rows, errors, skipped, total, format }`.     |
| `ImportColumnMap`     | Stable, accepting feedback    | `Record<sourceHeader, targetField | null>`.              |
| `ImportRowError`      | Stable, accepting feedback    | `{ rowIndex, field, message }`.                          |
| `ImportValidator<T>`  | Stable, accepting feedback    | `(row, i) => Array<{ field, message }>`.                 |

### AI assistant

| Export                | Tier                       | Purpose                                                                   |
| --------------------- | -------------------------- | ------------------------------------------------------------------------- |
| `setAIProvider(fn)`   | Stable, accepting feedback | Register the BYO model adapter.                                           |
| `getAIProvider()` / `hasAIProvider()` | Stable, accepting feedback | Inspect registration.                                          |
| `mockAIProvider`      | Experimental               | Deterministic canned shapes per task; for demos + tests only.             |
| `AIProvider`          | Stable, accepting feedback | `(req: AIRequest) => Promise<string>`.                                    |
| `AIRequest`           | Stable, accepting feedback | `{ prompt, responseFormat, signal, task, maxOutputTokens }`.              |
| `AITask`              | Stable, accepting feedback | `'filter' | 'smart-fill' | 'summarize' | 'classify'`.                    |
| `aiFilter`            | Stable, accepting feedback | NL query → filter/sort plan (with optional `apply`).                      |
| `AIFilterOptions` / `AIFilterResult` / `AIFilterClause` / `AISortClause` | Stable, accepting feedback | Shapes.                  |
| `aiSmartFill`         | Stable, accepting feedback | Examples → predicted values for empty cells.                              |
| `AISmartFillOptions` / `AISmartFillResult` / `AISmartFillExample` | Stable, accepting feedback | Shapes.                |
| `aiSummarize`         | Stable, accepting feedback | Row / selection / group / all → text + bullets + highlighted fields.      |
| `AISummarizeOptions` / `AISummarizeTarget` / `AISummary` | Stable, accepting feedback | Shapes.                            |
| `aiClassify`          | Stable, accepting feedback | Free-text cells → bucketed labels.                                        |
| `AIClassifyOptions` / `AIClassifyResult` | Stable, accepting feedback | Shapes.                                       |

## Subpath exports

Both packages support fine-grained imports so you only pay for what
you use:

```ts
import { setAIProvider } from 'sv-grid-pro/ai'
import { importData } from 'sv-grid-pro/import'
import { exportGrid } from 'sv-grid-pro/export'
import { printGrid } from 'sv-grid-pro/print'
```

The `package.json` `exports` map lists the supported paths.

## See also

- [API stability](./api-stability.md) - what the tiers mean + semver
  policy.
- [Error reference](./errors.md) - every typed error this surface
  throws.
- [Testing and quality](./testing-and-quality.md) - the unit-test
  coverage backing each entry above.

<!-- =================================================================
     /help/api-stability  (community)
     ================================================================== -->

# API stability & semver policy

The promise SvGrid makes to you about which exports you can lean on,
how breaking changes are communicated, and how long deprecated APIs
stick around.

## Semver, applied

SvGrid follows [semver](https://semver.org/) strictly **for everything
exported from the package root**:

```ts
import { SvGrid, tableFeatures, /* ... */ } from 'sv-grid-community'
```

Anything reached via `'sv-grid-community/internal'` or a deeper path is
**not** covered. We may rename, reshape, or remove those between any
two minor releases.

| Change                                              | Bump      |
| --------------------------------------------------- | --------- |
| Remove or rename a top-level export                 | major     |
| Remove an existing public prop                      | major     |
| Change the meaning of an existing prop / option     | major     |
| Tighten a public TypeScript type (becomes stricter) | major     |
| Add a new optional prop / option / export           | minor     |
| Loosen a TypeScript type (becomes wider)            | minor     |
| Fix a bug that produces a different output value    | patch (documented in the changelog) |
| Internal refactor with no observable change         | patch     |

## Stability tiers

Every public symbol is labelled in its JSDoc. The badges that show up
in the API reference (and at the top of each topic page):

| Badge          | Meaning                                                                            |
| -------------- | ---------------------------------------------------------------------------------- |
| **Stable**     | Covered by the semver promise. We will not break you between majors.               |
| **Stable, accepting feedback** | Same semver protection as Stable. We're collecting feedback on the shape; if it changes it will be in a major. |
| **Experimental** | May change in any minor release. Use only when you can absorb churn.              |
| **Deprecated** | Still works. Will be removed in a future major. The doc + the `@deprecated` JSDoc tag say which release. |
| **Internal**   | Not part of the public API. Imports may break in any release.                      |

The TypeScript types double as the source of truth: every Stable export
has explicit `@public` JSDoc; every Internal one has `@internal`.
Internal symbols are excluded from the published `.d.ts`.

## Current stability map

The package surface as of the current shipping version:

### `sv-grid-community`

| Surface                              | Tier              |
| ------------------------------------ | ----------------- |
| `<SvGrid>` component + every prop on it | Stable           |
| `createSvGrid`, `tableFeatures`      | Stable            |
| `renderSnippet`                      | Stable            |
| `rowSortingFeature`, `columnFilteringFeature`, `rowSelectionFeature`, `columnGroupingFeature`, `rowExpandingFeature` | Stable |
| `SvGridApi` (the imperative API)     | Stable            |
| Header-cell render snippets          | Stable, accepting feedback |
| Column-group multi-row headers       | Stable (since v1.x) |
| `createGridState`                    | Stable            |
| Anything imported via a deep path (`/internal`, `/test-utils`) | Internal |

### `sv-grid-pro`

| Surface                              | Tier              |
| ------------------------------------ | ----------------- |
| `installPro`, `ProGridApi`           | Stable            |
| `exportGrid`, `ExportOptions`        | Stable            |
| `printGrid`, `PrintOptions`          | Stable            |
| `importData`, `ImportOptions`, `ImportResult` | Stable, accepting feedback |
| `setAIProvider`, `AIProvider`        | Stable, accepting feedback |
| `aiFilter`, `aiSmartFill`, `aiSummarize`, `aiClassify` + their option types | Stable, accepting feedback |
| `mockAIProvider`                     | Experimental - we may rename or expand the shape |
| License helpers (`setLicenseKey`, etc.) | Stable          |

## Deprecation lifecycle

When something Stable is about to go away:

1. The JSDoc gets `@deprecated since vX.Y` with a one-line pointer to
   the replacement.
2. The TypeScript declaration starts emitting a deprecation warning
   (most editors render it as struck-through autocomplete).
3. The next **minor** release ships with the deprecation in place but
   the old API still working.
4. The next **major** release removes the old API.
5. The deprecation entry stays in the changelog under a "Removed in
   vN" heading for the version that removed it.

In practice this means **at least one minor release** between marking
something deprecated and removing it - often two.

## Release cadence

- **Patch releases** ship on demand, sometimes weekly, sometimes
  monthly. Every bug fix that doesn't change the shape goes here.
- **Minor releases** ship roughly monthly. Every new feature lands in
  a minor.
- **Major releases** ship at most twice a year. Major version skips
  (jumping from v2 to v4) happen only if a major change is so
  invasive the bridge isn't worth the maintenance cost.

The changelog ([`CHANGELOG.md`](../../CHANGELOG.md)) is canonical.
Every release has a dated entry with three sections: Breaking,
Features, Fixes. Breaking changes carry a migration paragraph.

## What "stable" doesn't promise

- **CSS class names**. We use `.sv-grid-*` consistently, but they're
  not part of the semver contract. Override them at your peril.
- **DOM structure**. The grid emits whatever markup it needs to.
  Querying `tbody tr td:first-child` from your test is your
  responsibility, not ours.
- **Console messages**. Warning text is editorial; we may reword.
  Error class names + types ARE stable - the
  [error reference](./errors.md) is the canonical list.
- **Bundler output paths**. The published package exposes the
  `exports` map; importing from a non-mapped path may break at any
  time.

## Deprecation log

The single source of truth for what's been marked deprecated, when,
why, and what to use instead. Read top-down for newest first; agents
can parse this table directly.

| Symbol                           | Deprecated since | Removal target | Replacement                                              | Reason                                              |
| -------------------------------- | ---------------- | -------------- | -------------------------------------------------------- | --------------------------------------------------- |
| `<SvGrid filterMode="row">`      | v1.4             | v2.0           | `filterMode="menu"` + `showFilterRow={true}` if you really want both | The two modes were mutually exclusive in the type but both rendered when set; the split makes the intent explicit |
| `mockAIProvider` named export    | v1.6             | v2.0           | `import { mockAIProvider } from 'sv-grid-pro/test-utils'` | Test helpers are moving out of the production bundle |
| `ColumnDef.cellClassRules`       | v1.3             | v2.0           | `cellClass: (ctx) => Record<string, boolean>`            | One field is enough; the rules format was unnecessary indirection |
| `<SvGrid onCellClick>`           | v1.5             | v2.0           | `onActiveCellChange` + your own click handler            | The grid intercepts click already for selection / editing; surfacing it as a prop double-fires |

Empty section means "no current deprecations" - we'd link the
previous-version deprecation log in the changelog.

### Format your own integrations can parse

Every entry follows the same six-column shape so an LLM or an
upgrade-assistant script can read this table and propose
edits. The pattern is:

```
| <symbol> | <version deprecated> | <version removed> | <replacement> | <reason> |
```

When v2 ships, the "Removed in v2" entries move to the changelog
under a `### Removed` section and out of this table.

## Long-term support

- **Currently shipping major** (v1.x) - all releases supported with bug
  fixes + security patches.
- **Previous major** (when v2 ships, v1 enters LTS) - security
  patches only, for **12 months** after v2.0.0.
- **Older majors** - no support.

For Pro customers, our support contract may extend LTS beyond 12
months on a case-by-case basis - contact `sales@jqwidgets.com`.

## See also

- [API reference](./api-reference.md) - every export with its tier
  badge.
- [Error reference](./errors.md) - the stable error class + message
  inventory.
- [Migrating from AG Grid](./migrating-from-ag-grid.md) - if you're
  coming from a previous-generation grid.

<!-- =================================================================
     /help/architecture  (community)
     ================================================================== -->

# Architecture overview

A one-page mental model that should let you reason about every other
topic in the docs. SvGrid is a strict three-layer system - if you know
which layer a piece of code lives in, you know what it can and cannot
do.

## The three layers

```
┌─────────────────────────────────────────────────────────────┐
│  Layer 3  │  <SvGrid> render component (Svelte 5)           │
│           │  - DOM, scroll, virtualization, editor popovers │
│           │  - keyboard handlers, pointer events            │
│           │  - sticks the headless engine to a viewport     │
├───────────┼─────────────────────────────────────────────────┤
│  Layer 2  │  Headless engine (createSvGrid)                 │
│           │  - column model + row model pipeline            │
│           │  - sort, filter, group, paginate, expand        │
│           │  - aggregators, accessors, comparators          │
│           │  - 100% pure functions, no DOM                  │
├───────────┼─────────────────────────────────────────────────┤
│  Layer 1  │  Your data + your column definitions            │
│           │  - the only thing YOU author                    │
│           │  - plain TypeScript: arrays, objects, types     │
└───────────┴─────────────────────────────────────────────────┘
```

Layer 1 is yours. Layer 2 is `sv-grid-community` minus the renderer.
Layer 3 is the `<SvGrid>` component everyone uses by default.

**You can use Layer 2 without Layer 3.** That's the headless promise:
if you want to render the grid yourself - in Tailwind cards, a print
PDF template, a custom virtualization layer - import `createSvGrid`
and read the state directly.

## Data flow on every render

```
raw data ──► engine pipeline ──► visible rows ──► renderer
   (you)        (Layer 2)         (Layer 2 out)    (Layer 3)
                    │
                    ▼
            ┌────────────────────────────┐
            │ 1. coreRowModel            │  shape data into Row objects
            │ 2. filteredRowModel        │  apply column + global filters
            │ 3. sortedRowModel          │  apply sort spec
            │ 4. groupedRowModel         │  apply groupBy + aggregators
            │ 5. expandedRowModel        │  flatten expanded groups
            │ 6. paginatedRowModel       │  slice the visible page
            └────────────────────────────┘
```

Every "feature" you register in `tableFeatures({ ... })` plugs one or
more row models into this pipeline. Disable a feature and that stage
no-ops. The pipeline runs once per state change, **not per scroll
frame** - virtualization is purely a presentational concern.

## The two APIs you'll use

### Declarative (the `<SvGrid>` props)

99% of consumers stop here. You author `data`, `columns`, and `features`,
then handle events from props:

```svelte
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  onCellValueChange={handleChange}
  onActiveCellChange={handleFocus}
/>
```

### Imperative (`SvGridApi`)

For toolbars, ribbons, keyboard shortcuts that need to drive the grid,
ask for the API via `onApiReady`:

```svelte
<SvGrid
  ...
  onApiReady={(api) => {
    api.setSort('name', 'asc')
    api.setFilter('region', { operator: 'equals', value: 'EMEA' })
  }}
/>
```

See the [API reference](./api-reference.md) for the full surface.

## State ownership

Two questions decide where each piece of state lives:

| Question                                   | Lives in                  |
| ------------------------------------------ | ------------------------- |
| Does it change row content or cell values? | **Your component** (`$state`) - hand the new array down to `data`. |
| Is it a column/grid setting (sort, filter, group, page)? | **The engine** owns it. Use `api.setSort(...)` etc., or pass an initial state. |
| Is it a visual concern (column widths, hover)? | **The renderer** owns it. The grid manages this internally. |

This split is deliberate: the engine is dataless, so it can't "lose"
your rows. Your component is rendererless, so it can't accidentally
mutate DOM nodes during a sort.

## Where each topic page sits

| Topic                                | Layer  | Why                                                                       |
| ------------------------------------ | ------ | ------------------------------------------------------------------------- |
| [Column definitions](./columns/column-definitions.md) | 1      | Pure types you author.                                       |
| [Row data](./rows/row-data.md)       | 1      | Your input.                                                               |
| [Row sorting](./rows/row-sorting.md) | 2      | Engine row-model.                                                         |
| [Filtering overview](./filtering/overview.md) | 2 + 3 | Engine for the pipeline; renderer for the popovers + filter row.       |
| [Row pagination](./rows/row-pagination.md) | 2     | Engine slice.                                                            |
| [Editing](./editing/overview.md)     | 3      | DOM editors live in the renderer.                                         |
| [Tree rows](./rows/tree-rows.md)     | 1 + 3 | You derive `visibleRows`; the renderer indents + draws chevrons.          |
| [Pivot tables](./pivot.md)           | 1 + 2 | You build the pivot engine; the renderer uses standard nested headers.    |
| [AI assistant](./ai.md)              | 2     | Pure helpers; the renderer never sees them.                              |
| [Export / import](./export.md), [import](./import.md) | 2 + 3 | Helpers + browser-side file IO.                              |

## Why this matters for shipping

- **You can test Layer 2 without a DOM.** Every engine helper is a
  pure function. Vitest in node, no jsdom required. See
  [Testing your grid](./testing.md).
- **You can swap Layer 3.** If your design system has its own table
  primitive, drop `<SvGrid>` and read from `createSvGrid()` directly.
- **Layer 2 is the public API surface.** Imports, exports, and types
  are versioned per the [API stability](./api-stability.md) policy.
  The renderer's CSS classes are NOT - override them at your peril.

## Where the layers physically live

| Layer | Source path                                       | Build output                         |
| ----- | ------------------------------------------------- | ------------------------------------ |
| 1     | Your app                                          | n/a                                  |
| 2     | `packages/sv-grid-community/src/core.ts` + row-models | `dist/index.js` (~13 kB gzip)    |
| 3     | `packages/sv-grid-community/src/SvGrid.svelte`    | bundled with the engine (~49 kB gzip total) |
|       | `packages/sv-grid-pro/src/{export,print,import,ai}.ts` | `sv-grid-pro/dist/*` (lazy-loaded peers) |

## See also

- [Why headless?](../why-headless.md) - the design rationale for the
  Layer 2 / Layer 3 split.
- [API reference](./api-reference.md) - every export with its layer
  noted.
- [Performance benchmarks](./benchmarks.md) - numbers from each layer
  in isolation.

## Frequently asked questions

### How is SvGrid architected?

As three strict layers: a headless core engine (state + row-model pipeline), a
Svelte render component (`<SvGrid>`) that draws the DOM, and your application
code. Knowing which layer a piece of code lives in tells you what it can and
cannot do.

### What does "headless" mean for SvGrid?

The core engine computes sorting, filtering, grouping, and selection state
without rendering anything. You can drive your own markup with it, or drop in the
batteries-included `<SvGrid>` component that renders on top of the same engine.

### Can I use the engine without the SvGrid component?

Yes. Use `createSvGrid` and the row-model factories directly to build a custom
rendering layer. The render component is optional sugar over the same public
engine API.

<!-- =================================================================
     /help/benchmarks  (community)
     ================================================================== -->

# Performance benchmarks

Headline numbers from the regression suite. Every figure below is from
the same hardware + browser configuration, re-measured on each release;
the script that produces them lives in
`packages/sv-grid-community/scripts/bench.ts` and is checked in.

Live load - 100k rows x 100 columns with row + column virtualization:

<div data-docs-demo="06-large-dataset" data-height="500"></div>

## Test rig

| Component | Spec                                      |
| --------- | ----------------------------------------- |
| CPU       | Apple M2 (8-core), 10W TDP                |
| RAM       | 16 GB LPDDR5                              |
| Browser   | Chrome 131 (release channel)              |
| Display   | 1 page worth of cells visible at any time |
| Throttle  | None - the regression run isn't throttled, but we also publish a separate "4x slow-down" line below for each scenario |

Numbers are the median of 5 runs after a warm-up pass. We track the
**95th percentile of frame time** during scroll rather than mean FPS -
the former catches jank that mean averages smooths over.

## Bundle size

Production build, gzipped, measured on the `dist/` output:

| Surface                             | Brotli | gzip   | Notes                                  |
| ----------------------------------- | ------ | ------ | -------------------------------------- |
| `sv-grid-community` (full)          | 41 kB  | 49 kB  | One import covers the entire renderer  |
| Headless engine (no `<SvGrid>`)     | 11 kB  | 13 kB  | If you bring your own renderer         |
| `sv-grid-pro` core                  | 7 kB   | 8 kB   | Export + print + import + AI shells    |
| `sv-grid-pro` AI module only        | 4 kB   | 5 kB   | Imported via `'sv-grid-pro/ai'`        |
| `sv-grid-pro` import module only    | 5 kB   | 6 kB   | Imported via `'sv-grid-pro/import'`    |
| Peer: `jszip`                       | 30 kB  | 35 kB  | Loaded on first `xlsx` export *or* import |
| Peer: `pdfmake` + vfs               | ~200 kB| ~280 kB| Loaded on first `pdf` export only      |

Tree-shaking is friendly: importing `{ SvGrid, tableFeatures }`
without `rowSortingFeature` doesn't pull the sort module.

## First paint

100k synthetic rows, 9 columns, default density, no virtualization
override. Measured from `mount()` to the first row painting:

| Scenario                          | Time (ms) |
| --------------------------------- | --------- |
| 10 rows × 9 cols                  | 4         |
| 1,000 rows × 9 cols               | 14        |
| 10,000 rows × 9 cols              | 38        |
| 100,000 rows × 9 cols (virtualized) | 82      |
| 100,000 rows × 100 cols (row + col virtualization) | 110 |

The slope is sub-linear because virtualization caps the rendered cell
count regardless of dataset size.

## Scroll performance

Sustained vertical scroll, 60 px/frame, measured as the 95th
percentile frame time:

| Scenario                              | p95 frame | Equivalent FPS |
| ------------------------------------- | --------- | -------------- |
| 100k rows × 9 cols                    | 8 ms      | ~120 fps        |
| 100k rows × 100 cols (col virt)       | 11 ms     | ~90 fps         |
| 100k rows × 9 cols, custom cell snippets w/ sparklines | 14 ms | ~70 fps |
| 100k rows × 9 cols, **4x CPU throttle** | 22 ms   | ~45 fps         |

Horizontal scroll on a 100-column grid stays under 12 ms p95 because
the column virtualizer is identical machinery.

## Sort, filter, group

In-memory operations on 100k rows:

| Operation                             | Time (ms) |
| ------------------------------------- | --------- |
| Sort 100k rows by one column          | 18        |
| Sort 100k rows by 3 columns (multi-sort) | 28     |
| Filter 100k rows (one operator)       | 9         |
| Filter 100k rows (5 operators ANDed)  | 17        |
| Group 100k rows by 2 columns + 3 aggregators | 36 |
| Pivot 100k facts → 4 row dims × 2 col dims × 3 measures (see demo 52) | 62 |

The sort path uses a stable comparator built per-column to keep
allocations down; the filter pipeline short-circuits on the first
failing predicate.

## Memory

Heap snapshot at idle, 100k rows × 9 columns loaded, after a full
scroll pass:

- ~22 MB heap (the Row objects + the visible-cell pool).
- Virtualization keeps the rendered DOM under ~600 `<td>` nodes
  regardless of dataset size.
- No retained references when the grid unmounts - the cleanup path is
  exercised by the unmount test in `svgrid.behavior.test.ts`.

## Server-side / chunked loading

Demo [33. Server-side infinite scroll](https://svgrid.com/#/demos/33-server-infinite) covers the chunked-load path. Numbers from that demo:

| Scenario                                         | Result                                  |
| ------------------------------------------------ | --------------------------------------- |
| Initial paint, sparse 100k-row dataset           | 110 ms to first chunk visible           |
| Scroll 50,000 rows in 1.5 s (fast wheel-flick)   | 16 chunk requests cancelled mid-flight  |
| Sort 100k server-side rows                       | round-trip dominated by the mock latency (50-140 ms) |

## AI helpers

End-to-end timings against the bundled `mockAIProvider`:

| Helper          | Median time (ms) |
| --------------- | ---------------- |
| `aiFilter`      | 350-750 (mock latency dominated) |
| `aiSmartFill` (50 rows) | 400-900 |
| `aiSummarize`   | 350-750          |
| `aiClassify` (20 rows)  | 400-750  |

Against a real model the latency is provider-side. The grid's own
prompt-build + result-parse work stays under ~6 ms even for 1000-row
classify jobs.

## Import / export

| Operation                            | Time   |
| ------------------------------------ | ------ |
| Parse CSV, 10k rows × 9 cols         | 28 ms  |
| Parse xlsx, 10k rows × 9 cols        | 140 ms (jszip unzip-dominated) |
| Export CSV, 10k rows × 9 cols        | 18 ms  |
| Export xlsx, 10k rows × 9 cols       | 220 ms |
| Export PDF, 1k rows × 9 cols (pdfmake) | 700 ms |

## Reproducing locally

```bash
git clone https://github.com/sv-grid/sv-grid
cd sv-grid
pnpm install
pnpm bench       # runs the suite, prints the same table
pnpm bench --json > my-results.json  # for trend tracking
```

The bench script also produces a comparison table against the previous
run if you pass `--baseline=path/to/prev.json`. Regressions over 10%
fail CI on the main branch.

## What we *don't* claim

- "Smoothest grid on the market" - that depends entirely on what your
  cells render. A sparkline + currency formatter in every cell costs
  more than a number, and we don't pretend otherwise.
- "Zero allocations during scroll" - the virtualizer recycles DOM
  nodes but cell snippets still allocate. The numbers above include
  real-world snippets (status pills, mini-bars).
- Single-thread performance > 1M rows. For >1M, do the heavy lifting
  on the server and feed chunks through the [server-side infinite
  scroll pattern](https://svgrid.com/#/demos/33-server-infinite).

## See also

- [Browser support](./browser-support.md) - the matrix the benchmarks
  ran against.
- [Testing and quality](./testing-and-quality.md) - the coverage
  thresholds that gate every release.

## Frequently asked questions

### How fast is SvGrid?

It virtualizes both rows and columns, so only the visible window is in the DOM -
a 100,000-row × 100-column grid scrolls smoothly. The numbers on this page come
from a checked-in regression suite re-measured on every release, not marketing
estimates.

### How many rows can SvGrid handle?

Client-side, 100k+ rows scroll smoothly thanks to virtualization. For millions
of rows, page or chunk from the server (see Server-side data). The DOM only ever
holds the visible window regardless of total row count.

### Is SvGrid faster than AG Grid or TanStack Table?

It ships a much smaller bundle (~42 KB gzipped for the full render component,
or ~7.5 KB for the headless core) and virtualizes by default. Raw scroll
performance is comparable for typical workloads; the bigger practical win is
bundle size and a Svelte-native runtime with no framework bridge.

<!-- =================================================================
     /help/browser-support  (community)
     ================================================================== -->

# Browser & runtime support

The shipping target matrix. If your environment isn't listed, assume
unsupported until you've validated the linked feature surfaces below.

## Browsers

| Browser           | Version | Status      | Notes                                                                 |
| ----------------- | ------- | ----------- | --------------------------------------------------------------------- |
| Chrome / Chromium | 100+    | Supported   | Primary development target. Tested every release.                     |
| Edge              | 100+    | Supported   | Same Chromium base as Chrome.                                         |
| Firefox           | 100+    | Supported   | Tested every release. The custom scrollbar paints natively.           |
| Safari (macOS)    | 15.4+   | Supported   | Pointer Events shim landed in 15.4 - older Safari hits edge cases.    |
| Safari (iOS)      | 15.4+   | Supported   | Touch UX known limitations - see "Mobile" below.                      |
| Opera             | 86+     | Supported   | Chromium-based.                                                       |
| IE 11             | n/a     | Unsupported | Not feasible: Svelte 5 itself requires modern JS.                     |
| Old WebViews      | varies  | Best-effort | Anything with `ResizeObserver` + ES2020 syntax should work.           |

The lower bound is **the oldest version with native `ResizeObserver`,
`IntersectionObserver`, Pointer Events, and `Object.hasOwn`**. SvGrid
uses these directly; we don't polyfill in the package.

## JavaScript baseline

SvGrid is built and shipped as **ESM only** with ES2020 syntax. The
published bundle assumes:

- `const`, `let`, arrow functions, classes, async/await, `??`, `?.`
- `Promise`, `Map`, `Set`, `WeakMap`, `Symbol`
- `Array.prototype.flatMap`, `Object.fromEntries`, `Object.hasOwn`
- `globalThis`

If you need to ship to a baseline lower than ES2020, transpile
`sv-grid-community` in your own build (Vite, Rollup, esbuild). The
package source contains no syntax above ES2022.

## DOM APIs

The grid uses these browser APIs directly:

| API                                  | Where                                                                     | Polyfillable?       |
| ------------------------------------ | ------------------------------------------------------------------------- | ------------------- |
| `ResizeObserver`                     | Auto-resizing the grid container + column widths                          | Yes (`resize-observer-polyfill`) |
| `IntersectionObserver`               | Virtualization viewport check                                             | Yes                              |
| Pointer Events (`pointerdown`/`-up`) | Selection, fill handle, column resize                                     | Yes                              |
| `Element.scrollTo({ behavior })`     | Programmatic row scroll, smooth-scroll API                                | Yes                              |
| `URL.createObjectURL`                | Export (xlsx, pdf, csv, tsv, html)                                        | Required             |
| `Blob`, `File`                       | Export + import                                                           | Required             |
| `document.execCommand('copy')` *or* `Clipboard API` | Copy/paste cell selection (graceful fallback)         | Either               |

If you're shipping to a sandboxed environment where some of these are
locked down, see the [CSP guidance](./security.md#csp-guidance) section
on the security page.

## Node / SSR

SvGrid is SSR-compatible. The render component does nothing on the
server beyond emitting the wrapper markup with an `aria-busy` shell -
the data + interactions hydrate on the client. Demo
[19. Server-side rendering](https://svgrid.com/#/demos/19-ssr)
shows a sandboxed pre-hydration snapshot.

### Tested SSR runtimes

| Runtime       | Version | Status     |
| ------------- | ------- | ---------- |
| Node.js       | 18 LTS+ | Supported  |
| Bun           | 1.0+    | Supported  |
| Deno          | 1.40+   | Supported  |
| SvelteKit     | 2.x     | Supported  |
| Astro         | 4.x+    | Supported  |
| Cloudflare Workers (with SvelteKit adapter) | latest | Supported (no FS access from the grid) |

### What the grid does NOT do on the server

- No `window` / `document` access in module initialisation.
- No event listeners.
- No `ResizeObserver` / `IntersectionObserver`.
- No `localStorage`.
- No virtualization (server emits a placeholder shell; client takes
  over on hydration).

If you see a "lifecycle_function_unavailable" error from Svelte during
SSR, that's coming from a custom cell snippet of yours - not from the
grid. Guard `document` / `window` reads inside an `onMount` or
`$effect`.

## Build tools

| Tool          | Version | Status     |
| ------------- | ------- | ---------- |
| Vite          | 5+      | Recommended. Tested with vite 5, 6, and 7. |
| Rollup        | 4+      | Supported. SvGrid is published as ESM and is tree-shakeable. |
| esbuild       | 0.20+   | Supported. |
| Webpack       | 5+      | Supported with `experiments.outputModule` or a CJS-compatible Svelte loader. |
| Turbopack     | n/a     | Untested. Should work given ESM compatibility. |

Tree-shaking works at the named-export granularity - `import { SvGrid,
tableFeatures } from 'sv-grid-community'` pulls in only the surfaces
you reference. Each feature module (sorting, filtering, etc.) is its
own export.

## Mobile

Mobile browsers render the grid correctly but the UX makes the
following compromises:

- **Touch drag selection** is supported on Pointer-Event browsers but
  doesn't show the same handles as desktop.
- **Cell editing** opens the native keyboard; multi-cell paste from the
  iOS clipboard works via the standard `Clipboard API`.
- **Column resize** is awkward on screens narrower than ~600 CSS pixels
  because the resize handles are 4 px wide. Configure pinned columns
  for narrow screens instead.
- **Pinned columns** are supported and recommended for mobile.

For a mobile-first workflow, prefer a card list view at smaller
viewports and switch to the grid above an `md` breakpoint.

## See also

- [Security & supply chain](./security.md) - including a CSP-friendly
  config snippet.
- [Performance benchmarks](./benchmarks.md) - measured throughput on a
  documented machine.
- [Testing and quality](./testing-and-quality.md) - the test suite and
  what it covers.

<!-- =================================================================
     /help/cells/cell-components  (community)
     ================================================================== -->

# Cell components

For any cell whose content is more than a string, use `cell:` with
`renderSnippet` or `renderComponent`.
<div data-docs-demo="10-custom-cells-and-themes" data-height="540"></div>

## Snippet

```svelte
<script lang="ts">
  import { renderSnippet, type ColumnDef } from 'sv-grid-community'

  const columns: ColumnDef<{}, Person>[] = [
    {
      field: 'status',
      header: 'Status',
      cell: (ctx) => renderSnippet(Pill, { value: String(ctx.getValue()) }),
    },
  ]
</script>

{#snippet Pill(p: { value: string })}
  <span class="pill pill-{p.value}">{p.value}</span>
{/snippet}
```

Snippets are the right choice when the renderer is local to the page and
small.

## Component

```ts
import StatusBadge from './StatusBadge.svelte'
import { renderComponent } from 'sv-grid-community'

{
  field: 'status',
  cell: (ctx) => renderComponent(StatusBadge, { status: ctx.getValue() }),
}
```

Components are the right choice when the renderer is reused across
multiple grids, has its own state, or needs lifecycle hooks.

## CellContext

The argument the grid passes to your `cell` callback:

```ts
type CellContext<TData> = {
  cell: Cell<TData>
  row: Row<TData>
  column: Column<TData>
  table: SvGrid<TData>
  getValue: () => unknown
}
```

- `getValue()` - the accessed value (post-`field` / `accessorFn`).
- `row.original` - the raw `TData` object.
- `row.getAllCells()` - every cell in the row, for sibling reads.
- `column.columnDef` - the original `ColumnDef`.
- `table` - the headless grid instance, with state and actions.

## Inline string

If your cell content is a plain string and you just want to format it, use
`format` or `formatter` - not `cell`. See
[Text formatting](./text-formatting.md).

## Performance

Cell renderers run once per visible cell on each grid update. For large
virtualized grids, keep them cheap:

- avoid `JSON.stringify`
- avoid `new Date()` per cell - pre-compute formatters at module scope
- avoid creating new objects inside the snippet template

## Common patterns

- **Avatar + name** - return a snippet that pulls first/last name from
  `ctx.row.original`. See demo 10.
- **Status pill** - class-derived background. See demo 10.
- **Inline progress bar** - `<div role="progressbar" aria-valuenow>`. See demo 10.
- **Hyperlink** - `<a href="/people/{ctx.row.original.id}">{ctx.getValue()}</a>`.

## See also

- [Custom header components](../columns/custom-header-components.md)
- [demos/10-custom-cells-and-themes.svelte](../../../examples/src/demos/10-custom-cells-and-themes.svelte)

<!-- =================================================================
     /help/cells/cell-data-types  (community)
     ================================================================== -->

# Cell data types

The `editorType` field on a column tags the column with a type. This drives
three different behaviours:
<div data-docs-demo="01-quick-start" data-height="540"></div>

| Effect | Driven by `editorType` |
| ------ | --------------------- |
| Which inline editor opens on `F2` / double-click | yes - `text` / `number` / `date` / `datetime` / `checkbox` |
| Which sort comparator is used | yes - `number` and `date`/`datetime` pick non-default `sortFns` |
| Which filter operators the column menu offers | yes - text / number / date / checkbox sets differ |

## Setting it

```ts
const columns: ColumnDef<{}, Person>[] = [
  { field: 'firstName',  header: 'First',    editorType: 'text' },
  { field: 'age',        header: 'Age',      editorType: 'number' },
  { field: 'joinedAt',   header: 'Joined',   editorType: 'date' },
  { field: 'startTime',  header: 'Start',    editorType: 'datetime' },
  { field: 'active',     header: 'Active',   editorType: 'checkbox' },
]
```

Even if you do not enable inline editing, set `editorType` so sort and
filter behave correctly for the column's data type. A `number` column
without `editorType` sorts as lexical strings.

## Built-in types

| `editorType` | accepted value space |
| ------------ | -------------------- |
| `'text'`     | strings |
| `'number'`   | numbers (or numeric strings) |
| `'date'`     | ISO date strings (`YYYY-MM-DD`) or `Date` |
| `'datetime'` | ISO datetime strings or `Date` |
| `'checkbox'` | booleans |

## Custom types

There is no plug-in "register a new cell data type" API. To use a custom
type:

- Render with a custom `cell` (see [Cell components](./cell-components.md))
- Sort with a custom value through `accessorFn` that normalises to a
  comparable primitive
- Filter with a custom operator UI in your own header component

## Editor value parsing

The editor receives a string from the DOM and converts to the canonical
value before commit. The implementation lives in
[`parseEditorValue`](../../../packages/sv-grid-community/src/editors/cell-editors.ts).

```ts
import { parseEditorValue } from 'sv-grid-community'

parseEditorValue('number',   '42')      // 42
parseEditorValue('number',   'abc')     // NaN - caller should reject
parseEditorValue('checkbox', 'true')    // true
parseEditorValue('date',     '2026-05-27')  // '2026-05-27'
```

## See also

- [Provided cell editors](../editing/provided-editors.md)
- [Filter conditions](../filtering/filter-conditions.md)

<!-- =================================================================
     /help/cells/cell-text-selection  (community)
     ================================================================== -->

# Cell text selection

By default the grid has **cell-range selection** (drag across cells, range
highlight, copy as TSV). Standard browser text-selection inside a cell is
**not** the default - clicking-and-dragging across a cell creates a range
selection, not a text selection.
<div data-docs-demo="04-selection-copy-paste" data-height="540"></div>

## Enable browser text selection

If your users need to copy a substring from a single cell (e.g. an email
address that's wider than the cell), turn off cell-range selection for
that part of the grid. The simplest scope is "everywhere":

```svelte
<SvGrid
  {data} {columns} features={{}}
  selectionMode="row"            <!-- disables cell-range, keeps row selection -->
/>
```

Or surgically, per cell, render the value in a `<span>` whose `user-select`
overrides the grid's:

```ts
{
  field: 'email',
  cell: (ctx) => renderSnippet(SelectableEmail, { value: String(ctx.getValue()) }),
}
```

```svelte
{#snippet SelectableEmail(p: { value: string })}
  <span style="user-select: text;">{p.value}</span>
{/snippet}
```

## Copy current value

`Ctrl/Cmd+C` with a cell range selection copies all selected cells as TSV.
With a single cell, the value is copied as a TSV scalar (no tab, no
newline).

To copy *just the displayed text* of a single cell without entering range
selection, switch to a `selectionMode="row"` and use the row checkbox
column + `Ctrl/Cmd+C` to copy entire rows.

## Gotchas

- A grid in `selectionMode='cell'` swallows mouse selection inside cells -
  drag *only* creates a rectangle selection, never a browser text selection.
- A grid in `selectionMode='both'` (default) does too - the cell selection
  layer takes precedence.

## See also

- [Selection demo](../../../examples/src/demos/04-selection-copy-paste.svelte)
- [Custom cells](./cell-components.md)

<!-- =================================================================
     /help/cells/conditional-formatting  (community)
     ================================================================== -->

# Conditional formatting

Conditional formatting colors a cell by its value. SvGrid ships it as a
declarative engine prop, `conditionalFormats`, so you describe the rules once
and the grid paints every cell - no per-cell `cell` snippet required.

It goes beyond the `cellClass(ctx)` callback (which only toggles static CSS
classes): color scales and data bars need a value computed against the
column's min/max range, which the engine does for you.

```svelte
<script lang="ts">
  import { SvGrid, type ColumnDef, type ConditionalFormat } from 'sv-grid-community'

  type Row = { rep: string; revenue: number; score: number }

  const conditionalFormats: ConditionalFormat<Row>[] = [
    { type: 'dataBar', columns: ['revenue'], color: '#3b82f6' },
    { type: 'colorScale', columns: ['score'], min: '#fca5a5', mid: '#fde68a', max: '#86efac' },
  ]
</script>

<SvGrid {data} {columns} {conditionalFormats} />
```

## Format kinds

### `colorScale` - gradient fill

A 2-stop (`min`/`max`) or 3-stop (`min`/`mid`/`max`) gradient mapped across the
column's value range. Fix the scale with `minValue`/`maxValue` to make rows
comparable.

```ts
{ type: 'colorScale', columns: ['score'], min: '#fca5a5', mid: '#fde68a', max: '#86efac', minValue: 0, maxValue: 100 }
```

### `dataBar` - in-cell bar

An in-cell horizontal bar proportional to the value. Diverging data (can go
negative) gets `negativeColor`. `showValue: false` hides the text and shows the
bar alone.

```ts
{ type: 'dataBar', columns: ['revenue'], color: '#3b82f6', negativeColor: '#ef4444' }
```

### `iconSet` - threshold icons

An icon chosen by ascending `thresholds` (n thresholds => n+1 buckets). Built-in
sets: `'arrows'`, `'traffic'`, `'triangles'`. `iconOnly: true` hides the number.

```ts
// growth < 0 -> down, 0..10 -> flat, >= 10 -> up
{ type: 'iconSet', columns: ['growth'], set: 'arrows', thresholds: [0, 10] }
```

### `rule` - style on a predicate

Apply `background` / `color` / `fontWeight` when `when(ctx)` returns true. The
predicate receives the typed row, so you can key off other fields.

```ts
{ type: 'rule', columns: ['churn'], when: ({ value }) => Number(value) >= 20,
  background: '#fee2e2', color: '#991b1b', fontWeight: 700 }
```

## Scoping and precedence

- `columns: [...]` limits a format to those column ids. Omit it to apply to
  every column.
- Formats are evaluated in array order; **later entries win** on conflict, so
  list general formats first and specific overrides last.
- Empty / non-numeric cells are skipped by the numeric formats (color scale,
  data bar, icon set) and never count toward a column's min/max.

## Notes

- The color-scale fill and data bar render as layers behind the text, so they
  survive app stylesheets that force the cell background.
- The resolver is exported as `resolveCellFormat(value, row, columnId, formats,
  stat)` if you want to compute the same result yourself.

See the live [Conditional formatting](https://sv-grid.com/demos/141-conditional-formatting)
demo.

<!-- =================================================================
     /help/cells/expressions  (community)
     ================================================================== -->

# Expressions

SvGrid does not ship a formula / expression language for cells. Computed
values are JavaScript - either via `accessorFn` or inside a `cell`
callback.
<div data-docs-demo="83-spreadsheet-formulas" data-height="540"></div>

## Per-cell computation

```ts
{
  id: 'totalCost',
  header: 'Total',
  accessorFn: (row) => row.unitPrice * row.quantity,
  format: { type: 'currency', currency: 'USD' },
}
```

`accessorFn` runs every time the row's value is needed (display, sort,
filter, copy). The result is treated as a plain value of the resulting
type, so `format` / `formatter` / `editorType` all apply.

## Cross-row aggregation

For computed columns that depend on **other rows** (running total, rank,
delta-from-mean), do the computation **before** you pass data into the
grid - derive a new array with the aggregate fields baked in:

```svelte
<script lang="ts">
  const sourceRows = await fetchOrders()
  const total = sourceRows.reduce((s, r) => s + r.amount, 0)
  const rows = sourceRows.map((r) => ({
    ...r,
    shareOfTotal: r.amount / total,
  }))
</script>

<SvGrid data={rows} {columns} features={features} />
```

The grid's row pipeline runs **per row** - it does not give you a hook for
"emit a derived column that needs the whole array".

## Formula language

A spreadsheet-style formula language (cells like `=A1+B2`) is **not** in the
SvGrid community build. There is no formula parser or formula editor. If you
need spreadsheet-style cells, that's a separate library - wire its output
into a column's `accessorFn`.

## See also

- [Column definitions](../columns/column-definitions.md)
- [Server-side guide](../../getting-started.md#11-server-side-data) - for aggregates the server is better at than the client.

<!-- =================================================================
     /help/cells/getting-values  (community)
     ================================================================== -->

# Getting values

You get cell values in three ways depending on context.
<div data-docs-demo="04-selection-copy-paste" data-height="540"></div>

## Inside a column definition

`field` does the obvious thing - `row[key]`:

```ts
{ field: 'firstName', header: 'First' }
```

Use `accessorFn` for anything computed:

```ts
{
  id: 'fullName',
  header: 'Full name',
  accessorFn: (row) => `${row.firstName} ${row.lastName}`,
}
```

## Inside a cell renderer

A `cell` callback receives a `CellContext`:

```ts
{
  field: 'salary',
  header: 'Salary',
  cell: (ctx) => {
    const value = ctx.getValue()          // unknown
    const row   = ctx.row.original         // your TData
    const all   = ctx.row.getAllCells()    // array of Cell
    return /* renderSnippet / string / etc. */
  },
}
```

`ctx.row.original` is the **raw row object** you passed in - handy when
you want sibling values without going through accessors.

## From outside the grid

After `onApiReady`:

```ts
const v = api.getCellValue(rowIndex, columnId)
api.setCellValue(rowIndex, columnId, newValue)
```

`rowIndex` is the index in the **source data array**, not the post-pipeline
displayed index.

## Reading by row id

There is no `api.getCellValueByRowId(rowId, columnId)` helper today. If you
need that, walk `api.getData()`:

```ts
function valueByRowId(api: SvGridApi<{}, Person>, rowId: string, col: string) {
  const data = api.getData()
  const idx = data.findIndex((r) => r.id === rowId)
  return idx === -1 ? undefined : api.getCellValue(idx, col)
}
```

## See also

- [Cell components](./cell-components.md)
- [Accessing rows](../rows/accessing-rows.md)

<!-- =================================================================
     /help/cells/highlighting-changes  (community)
     ================================================================== -->

# Highlighting changes

There is no built-in "flash on change" highlight. You build it with a
diff against a frozen snapshot of the data.
<div data-docs-demo="11-stock-market" data-height="540"></div>

## Dirty cells while editing

Demo 5 ([demos/05-inline-editing.svelte](../../../examples/src/demos/05-inline-editing.svelte))
does this:

```svelte
<script lang="ts">
  // svelte-ignore state_referenced_locally
  let initial = rows.map((r) => ({ ...r }))
  let dirty = $state<Record<string, true>>({})

  $effect(() => {
    if (!api) return
    const snap = api.getData()
    const next: Record<string, true> = {}
    for (let i = 0; i < snap.length; i++) {
      const a = snap[i]!
      const b = initial[i]
      if (!b) continue
      for (const key of Object.keys(a)) {
        if ((a as any)[key] !== (b as any)[key]) {
          next[`${a.id}.${key}`] = true
        }
      }
    }
    dirty = next
  })
</script>
```

To make the dirty marker visible in the grid, render an indicator inside a
custom `cell`:

```ts
{
  field: 'salary',
  cell: (ctx) => renderSnippet(MaybeDirty, {
    value: ctx.getValue(),
    isDirty: dirty[`${ctx.row.original.id}.salary`] === true,
  }),
}
```

```svelte
{#snippet MaybeDirty(p: { value: unknown; isDirty: boolean })}
  <span class="inline-flex items-center gap-1">
    {p.value}
    {#if p.isDirty}<span class="h-1.5 w-1.5 rounded-full bg-amber-500"></span>{/if}
  </span>
{/snippet}
```

## Flash on value change (live data)

For live-update grids (stock tickers, queue dashboards):

```svelte
<script lang="ts">
  let lastValues = new Map<string, unknown>()
  let flashing = $state<Record<string, true>>({})

  function onCellSeen(key: string, value: unknown) {
    if (lastValues.has(key) && lastValues.get(key) !== value) {
      flashing[key] = true
      setTimeout(() => { delete flashing[key] }, 500)
    }
    lastValues.set(key, value)
  }
</script>
```

Drive the flash from your cell renderer the same way. Use `prefers-
reduced-motion` to disable the animation for users who opt out.

## See also

- [Cell components](./cell-components.md)
- [demos/05-inline-editing.svelte](../../../examples/src/demos/05-inline-editing.svelte)

<!-- =================================================================
     /help/cells/sparklines  (community)
     ================================================================== -->

# Sparklines

A sparkline is a tiny, word-sized chart drawn inside a single cell. SvGrid
renders them as a first-class column type: set `sparkline` on a column whose
value is an array of numbers and the grid paints an inline SVG. No chart
library, no custom cell snippet.

```svelte
<script lang="ts">
  import { SvGrid, type ColumnDef } from 'sv-grid-community'

  type Row = { product: string; revenue: number[] }

  const columns: ColumnDef<{}, Row>[] = [
    { field: 'product', header: 'Product' },
    { field: 'revenue', header: 'Trend', sparkline: { type: 'line' } },
  ]
</script>

<SvGrid {data} {columns} />
```

## Value shape

The cell value is an array of numbers. A comma- or space-separated string
works too (`"1, 2, 3"`), so server payloads that send a CSV string render
without massaging. Non-finite entries are dropped; an empty array renders
nothing.

## Chart types

| `type`      | Looks like                                   |
| ----------- | -------------------------------------------- |
| `'line'`    | A single polyline with an end-point dot (default) |
| `'area'`    | A line plus a translucent fill to the baseline |
| `'bar'`     | One column per value, scaled to the row's min..max |
| `'winloss'` | Fixed-height up/down bars - sign only (W/L streaks) |

## Options (`SparklineConfig`)

| Option          | Default                  | Notes                                              |
| --------------- | ------------------------ | -------------------------------------------------- |
| `type`          | `'line'`                 | One of the four above.                             |
| `color`         | `var(--sg-accent)`       | Stroke (line/area) or positive fill (bar/winloss). |
| `negativeColor` | `#ef4444`                | Fill for negative bars / losses.                   |
| `width`         | `88`                     | SVG width in px.                                   |
| `height`        | `22`                     | SVG height in px.                                  |
| `min` / `max`   | derived from the row     | Fix the value scale so rows are comparable.        |
| `lineWidth`     | `1.5`                    | Stroke width (line/area).                          |
| `lastPoint`     | `true`                   | Draw the end-cap dot on line/area.                 |

```ts
// Green/red diverging bars on a column that can go negative:
{ field: 'delta', sparkline: { type: 'bar', color: '#16a34a', negativeColor: '#ef4444' } }

// Comparable rows: pin every sparkline to the same 0..100 scale:
{ field: 'score', sparkline: { type: 'area', min: 0, max: 100 } }
```

## Notes

- A custom `cell` renderer wins if both `cell` and `sparkline` are set.
- Sparklines are decorative SVG with an `aria-label` summarising the series
  (point count + last value). For a screen-reader-friendly exact readout,
  pair the chart column with a plain numeric column.
- The geometry helper is exported as `buildSparkline(values, config)` if you
  want to render the same chart outside a grid cell.

See the live [Sparkline cells](https://sv-grid.com/demos/140-sparkline-cells)
demo.

<!-- =================================================================
     /help/cells/styling-cells  (community)
     ================================================================== -->

# Styling cells

Cells render as `<td>` and pick up the same CSS variable tokens as the rest
of the grid.
<div data-docs-demo="62-conditional-styling" data-height="540"></div>

## Default look

```css
table[role='grid'] td {
  border: 1px solid var(--sg-border);
  padding: 0.4rem 0.6rem;
  vertical-align: middle;
}
```

Override at `:root` or on the grid host.

## Per-cell styling

`ColumnDef` accepts a `cellClass` field. It can be:

- a **string** (or array of strings) - applied to every `<td>` in
  this column;
- a **function** - called per cell with the standard `CellContext`,
  returning a string, array, or `Record<string, boolean>`.

```ts
{
  field: 'salary',
  format: { type: 'currency', currency: 'USD' },
  cellClass: (ctx) => {
    const v = Number(ctx.getValue())
    if (v > 100_000) return 'cell-money-high'
    if (v <  20_000) return 'cell-money-low'
    return ''
  },
}
```

```css
:global(td.cell-money-high) { color: #16a34a; font-weight: 600; }
:global(td.cell-money-low)  { color: #b91c1c; }
```

The class is added to the existing `sv-grid-cell` class (other
modifiers like `sv-grid-cell-active`, `sv-grid-cell-editing`,
`data-align`, `data-pinned` still apply). Use `:global(...)` in
scoped Svelte styles since the cell lives outside the component
hash.

For row-level conditional styling, use the wrapper's
`rowClass={({ row }) => ...}` prop - same shape, scoped to the `<tr>`.
See [Styling rows](../rows/styling-rows.md).

## Right-align numbers

A common rule of thumb is "numbers right, everything else left". Target by
`editorType`:

```css
table[role='grid'] td[data-editor-type='number'] {
  text-align: right;
  font-variant-numeric: tabular-nums;
}
```

(`data-editor-type` is set by the grid - verify by inspecting an element
in your devtools; if the attribute is not present in your build, fall back
to wrapping the value in a `<span class="tabular-nums">`.)

## Highlighting the active cell

The currently-active cell carries `aria-selected="true"` and matches the
focus-ring custom property:

```css
table[role='grid'] td[aria-selected='true'] {
  box-shadow: inset 0 0 0 2px var(--sg-accent);
}
```

## Edit-mode cell

While a cell is being edited, it carries `data-editing="true"` and renders
an `<input>` inside:

```css
table[role='grid'] td[data-editing='true'] {
  padding: 0;
}
table[role='grid'] td[data-editing='true'] input {
  width: 100%;
  height: 100%;
  padding: 0.4rem 0.6rem;
  border: 0;
  outline: none;
  background: var(--sg-bg);
}
```

## See also

- [Highlighting changes](./highlighting-changes.md)
- [Cell components](./cell-components.md)

<!-- =================================================================
     /help/cells/text-formatting  (community)
     ================================================================== -->

# Text formatting

The `format` field on a column produces locale-aware formatted strings
without you writing a renderer.
<div data-docs-demo="13-finances" data-height="540"></div>

## Number

```ts
{ field: 'count', header: 'Count',
  format: { type: 'number', options: { maximumFractionDigits: 0 } } }
```

`options` is `Intl.NumberFormatOptions`. Combine with `locales` for
non-default locales:

```ts
{ field: 'count', header: 'Anzahl',
  format: { type: 'number', locales: 'de-DE', options: { maximumFractionDigits: 0 } } }
```

## Currency

```ts
{ field: 'salary', header: 'Salary',
  format: { type: 'currency', currency: 'USD' } }
```

`currency` is an ISO 4217 code; if omitted, USD is used.

## Percent

```ts
// values are fractions (0.42 → 42%)
{ field: 'utilization', header: 'Util',
  format: { type: 'percent' } }

// values are 0–100 (42 → 42%)
{ field: 'progress', header: 'Progress',
  format: { type: 'percent', valueIsPercentPoints: true } }
```

## Date / datetime

```ts
{ field: 'joinedAt', header: 'Joined',
  format: { type: 'date', pattern: 'y-m-d' } }

{ field: 'updatedAt', header: 'Updated',
  format: { type: 'datetime', pattern: 'medium' } }
```

Built-in patterns:

| pattern | shorthand for |
| ------- | ------------- |
| `'d'`   | short numeric date |
| `'D'`   | long date |
| `'y-m-d'` | year-month-day |
| `'short'` \| `'medium'` \| `'long'` | `dateStyle` / `timeStyle` presets |

Combine `pattern` with `options` to override individual fields.

## Custom formatter

For anything `format` cannot express, use `formatter`:

```ts
{
  field: 'temperature',
  header: 'Temp',
  formatter: ({ value }) => `${Number(value).toFixed(1)}°C`,
}
```

`formatter` runs **after** the accessor and **before** the cell renderer.
Its return value is what gets displayed and copied to the clipboard.

## Order of precedence

When a column has both, the resolution order is:

1. `field` / `accessorFn` produces the value
2. If `cell` is set, it renders - `format` / `formatter` are ignored
3. Otherwise `formatter` runs if set
4. Otherwise `format` runs if set
5. Otherwise the value is rendered as `String(value)`

## See also

- [Cell components](./cell-components.md) - when `format` is not enough.
- [`cell-formatting.ts`](../../../packages/sv-grid-community/src/cell-formatting.ts)

<!-- =================================================================
     /help/cells/tooltips  (community)
     ================================================================== -->

# Tooltips

There is no built-in tooltip API on `ColumnDef`. Use the standard `title`
attribute, an accessible `<dialog>`, or any popover library - wired
through a custom cell renderer.

## With `title` (no JS, screen-reader friendly)

```ts
{
  field: 'description',
  cell: (ctx) => renderSnippet(EllipsisCell, {
    value: String(ctx.getValue() ?? ''),
  }),
}
```

```svelte
{#snippet EllipsisCell(p: { value: string })}
  <span title={p.value} class="block truncate">{p.value}</span>
{/snippet}
```

`title` is the safest default: screen readers announce it; mouse users see
a tooltip; keyboard users see it on focus (when wrapped in a focusable
element).

## With a popover library

Pass a component instead of a snippet:

```ts
import TooltipCell from './TooltipCell.svelte'
import { renderComponent } from 'sv-grid-community'

{
  field: 'description',
  cell: (ctx) => renderComponent(TooltipCell, {
    value: String(ctx.getValue() ?? ''),
    tip: ctx.row.original.fullDescription,
  }),
}
```

## Header tooltips

The same pattern, but via the `header:` field - see
[Custom header components](../columns/custom-header-components.md).

## Gotchas

- The grid's column-menu popover and the cell-edit overlay use top-layer
  z-indices around 100. Your tooltip should be either lower (so it slides
  under those overlays when both open) or higher with a click-outside
  dismissal.
- A long tooltip inside an Excel-style filter dropdown can occlude the
  filter input. Detach the tooltip from cells inside an open filter menu.

## See also

- [Cell components](./cell-components.md)

<!-- =================================================================
     /help/cells/view-refresh  (community)
     ================================================================== -->

# View refresh

The grid renders reactively - it does **not** have a `refresh()` method,
because it doesn't need one. To make the grid re-display, change the data
that drives it.

## Forcing a refresh

| You want | Do this |
| -------- | ------- |
| Re-display every row | Reassign `data` to a new array (`rows = [...rows]`). |
| Re-display one row | Mutate the row through a `$state` array, or call `api.setCellValue(...)`. |
| Re-apply sort / filter / page | Update the controlled state slice (or reassign the data). |
| Re-render a single cell | The grid's renderer keys on the cell's `cellId`. Changing the underlying value re-renders the cell. |

## When the grid does NOT re-render

If you mutate a row object **deeply** without going through `$state` -
e.g. `someExternalRef.salary = 50000` where `someExternalRef` is an object
held outside the grid - Svelte 5 will not know to update.

Two safe patterns:

```svelte
<script lang="ts">
  let rows = $state<Person[]>(initial)

  // ✅ via $state proxy
  rows[0]!.salary = 50_000

  // ✅ via array reassignment
  rows = rows.map((r, i) => (i === 0 ? { ...r, salary: 50_000 } : r))

  // ✅ via API
  api?.setCellValue(0, 'salary', 50_000)
</script>
```

## Refresh-after-async

For data fetched asynchronously, the array reassignment is the canonical
trigger:

```svelte
<script lang="ts">
  let rows = $state<Person[]>([])
  $effect(() => { fetchRows().then((next) => (rows = next)) })
</script>
```

## See also

- [Row data](../rows/row-data.md)
- [Accessing rows](../rows/accessing-rows.md)

<!-- =================================================================
     /help/charts  (community)
     ================================================================== -->

# Integrated charts

SvGrid can chart its own data with no external charting library. Two pieces:

- **`SvGridChart`** - a component that renders a `ChartSpec` as inline SVG
  (bar, line, area, pie, scatter / bubble) with axes, hover tooltips, a
  clickable legend that toggles series (or pie slices) on and off, reference
  lines, a time axis, and a visually-hidden data table for screen readers.
- **`rowsToChartSpec(rows, opts)`** - aggregates flat rows (group by a
  category field, reduce a value field) into a `ChartSpec`, with optional
  sorting and top-N + "Other" bucketing.

Feed it `api.getDisplayedRows()` and the chart reflects the grid's current,
filtered, sorted data - the "chart from the grid" enterprise feature.

```svelte
<script lang="ts">
  import { SvGrid, SvGridChart, rowsToChartSpec, type SvGridApi } from 'sv-grid-community'

  let api: SvGridApi<F, Row> | null = null
  let displayed = $state<Row[]>(rows)
  const sync = () => (displayed = (api?.getDisplayedRows() as Row[]) ?? rows)

  const spec = $derived(
    rowsToChartSpec(displayed, { type: 'bar', category: 'region', value: 'revenue', reduce: 'sum' }),
  )
</script>

<SvGrid {data} {columns} {features} sortable filterable
  onApiReady={(a) => { api = a; sync() }}
  onFiltersChange={sync} onSortingChange={sync} />

<SvGridChart {spec} />
```

## `rowsToChartSpec`

| Option        | Meaning                                                  |
| ------------- | -------------------------------------------------------- |
| `type`        | `'bar' \| 'line' \| 'area' \| 'pie' \| 'scatter'`       |
| `category`    | Field whose distinct values become the x-axis / slices.  |
| `value`       | Numeric field, **or an array of fields** (one series each). |
| `series`      | Pivot field: one series per distinct value of it.        |
| `reduce`      | `'sum'` (default), `'avg'`, or `'count'`.                |
| `stacked`     | Stack the series instead of grouping them.               |
| `stacked100`  | Stack to 100% - each category normalized to its total.   |
| `sort`        | `'value-desc' \| 'value-asc' \| 'category' \| 'none'`.   |
| `topN`        | Keep the top N categories, bucket the rest into "Other". |
| `otherLabel`  | Label for the bucket (default `'Other'`).                |
| `width` / `height` | SVG viewBox size.                                  |

Three multi-series shapes:

```ts
rowsToChartSpec(rows, { type: 'bar', category: 'region', value: 'revenue' })            // 1 series
rowsToChartSpec(rows, { type: 'bar', category: 'region', value: ['revenue', 'cost'] })  // 2 series
rowsToChartSpec(rows, { type: 'bar', category: 'region', value: 'sales', series: 'product' }) // pivot
```

## Building a spec yourself

`SvGridChart` takes any `ChartSpec`. Per-series `type` and `axis` give you combo
charts and a secondary Y axis; `stacked` stacks bars/areas; `innerRadius` turns a
pie into a donut; `yAxisTitle` / `y2AxisTitle` / `xAxisTitle` label the axes.
Negative values drop below a zero baseline automatically, and `null` / `NaN`
values break the line (a gap) instead of dropping it to zero.

```ts
const spec: ChartSpec = {
  type: 'bar',
  stacked: false,
  categories: ['Q1', 'Q2', 'Q3', 'Q4'],
  series: [
    { label: 'Revenue', values: [120, 140, 90, 180] },                 // bars, left axis
    { label: 'Margin %', values: [0.31, 0.28, 0.22, 0.35], type: 'line', axis: 'right' }, // line, right axis
  ],
}
// donut:  { type: 'pie', innerRadius: 0.6, categories, series: [...] }
```

The geometry helper `buildChart(spec)` is exported too, if you want the raw SVG
primitives for a custom renderer.

## Reference / target lines

`referenceLines` draws horizontal goal / average / SLA lines across the plot.
Each entry stretches the axis domain so the line is always in view:

```ts
const spec: ChartSpec = {
  type: 'bar', categories: ['Q1', 'Q2', 'Q3', 'Q4'],
  series: [{ label: 'Revenue', values: [120, 140, 90, 180] }],
  referenceLines: [{ value: 150, label: 'Target', axis: 'left', color: '#ef4444', dashed: true }],
}
```

## 100% stacked

`stacked100: true` (implies `stacked`) normalizes each category to its own
total, so the axis runs 0..100% and every column fills the plot height -
ideal for reading composition / share. Tooltips and labels still show the
original values.

## Scatter / bubble

`type: 'scatter'` plots two numeric measures against each other. Each series
carries `points: [{ x, y, r?, label? }]`; an optional `r` becomes the bubble
radius (scaled across the data). One series per group colours the points.

```ts
const spec: ChartSpec = {
  type: 'scatter', categories: [],
  xAxisTitle: 'Spend', yAxisTitle: 'Revenue',
  series: [
    { label: 'EMEA', values: [], points: [{ x: 12_000, y: 80_000, r: 18, label: 'Ada' }] },
    { label: 'APAC', values: [], points: [{ x: 30_000, y: 140_000, r: 33, label: 'Grace' }] },
  ],
}
```

## Horizontal bars

`orientation: 'horizontal'` swaps the axes: categories run down the left, bars
grow rightward. It suits long category labels (rep names, product names) that
would otherwise crowd / rotate on a vertical x-axis. Grouped, stacked, 100%,
data labels, and reference lines (which become vertical) all work. Only applies
when every series is a bar - combo / line / area fall back to vertical.

```ts
const spec: ChartSpec = {
  type: 'bar', orientation: 'horizontal',
  categories: ['Ada', 'Grace', 'Margaret', 'Linus'],
  series: [{ label: 'Revenue', values: [120, 90, 140, 80] }],
  referenceLines: [{ value: 110, label: 'Avg' }],   // drawn as a vertical line
}
```

## Time axis

`xType: 'time'` treats `categories` as dates: x positions are spaced by actual
time (irregular gaps render proportionally, not evenly) and the axis shows real
date ticks. Works with line / area / bar.

```ts
rowsToChartSpec(rows, { type: 'line', category: 'date', value: 'sessions', series: 'channel' })
// then: spec.xType = 'time'
```

## Interactivity

`SvGridChart` is interactive by default:

- **Unified tooltip + crosshair** - hovering a category column shows a vertical
  crosshair and a single tooltip listing **every** series' value at that
  category (with color swatches), so multi-series and combo charts read at a
  glance. Pie slices keep a per-slice tooltip.
- **Legend toggle + isolate** - clicking a legend chip hides/shows that series
  (or pie slice); **double-clicking** isolates it (shows only that one, click
  again to restore). Hovering a chip dims the others. The chart re-scales to
  the visible data; colors stay stable.
- **Scatter tooltip** - hovering a bubble shows its x / y (and label).
- **Legend overflow** - a wide pivot (many series) collapses the legend to the
  first 10 chips with a "+N more" toggle, so it never floods the chart.
- **Data labels** - `dataLabels` draws the value on each bar / point / slice.
- **Drill-down** - `onSelect({ category, series, value })` fires when a bar /
  point / slice is clicked. Wire it to `api.setFacetFilter(...)` to filter the
  grid to the clicked category - the "click the chart to drill the grid" loop.

```svelte
<SvGridChart {spec}
  dataLabels                                  // value labels on each element
  formatValue={(v) => `$${compact(v)}`}       // tooltips, labels, AND Y-axis ticks
  onSelect={(s) => api.setFacetFilter('region', [s.category])} // drill the grid
  legend={true}                               // clickable legend; default true
  interactive={false}                         // opt out of tooltips + toggling
/>
```

`formatValue` is applied to tooltips, data labels, **and the Y-axis ticks**, so
they stay consistent - keep it compact (e.g. `$2M`, not `$2,000,000`).

## Export

Download the rendered chart as a standalone SVG or a PNG. Pass the chart's
wrapper element (or its `<svg>`):

```svelte
<div bind:this={chartEl}><SvGridChart {spec} /></div>

<button onclick={() => downloadChartSvg(chartEl, 'chart.svg')}>SVG</button>
<button onclick={() => downloadChartPng(chartEl, 'chart.png', { scale: 2 })}>PNG</button>
```

`chartToSvgString` / `chartToPngBlob` return the data if you want to upload it
instead. The export inlines the live theme colors, so it matches what's on
screen.

## Notes

- Pure SVG - no canvas, no dependency, SSR-safe, and it inherits the grid's
  `--sg-*` theme tokens.
- **Accessible** - every chart renders a visually-hidden `<table>` of the same
  data, wired to the SVG via `aria-describedby`, so screen readers get the
  numbers, not just "chart".
- For a richer charting stack (zoom, tooltips, dozens of types) you can still
  pipe `getDisplayedRows()` into Chart.js or a web component - see demos
  `73-chartjs-sync` and `77-smart-chart`. `SvGridChart` is the
  batteries-included option.

See the live [Integrated charts](https://sv-grid.com/demos/147-integrated-charts)
demo, or the [Chart wizard panel](https://sv-grid.com/demos/152-chart-wizard) -
a pick-a-chart dialog whose type-gallery thumbnails are themselves live
`SvGridChart` previews.

<!-- =================================================================
     /help/collaboration  (community)
     ================================================================== -->

# Real-time collaboration

Two people (or two AI agents) on the same grid: **presence** (who's here and
where their cursor is) and **live edits** (a change in one client appears in
every other). SvGrid packages this as a headless controller over a pluggable
transport - the only infrastructure-specific piece.

```ts
import { createCollaboration, broadcastChannelTransport } from 'sv-grid-community'

const collab = createCollaboration({
  user: { id: myId, name: 'Ada', color: '#ef4444' },
  transport: broadcastChannelTransport('my-grid-room'),
  onPeersChange: (peers) => renderCursors(peers),
  onRemoteEdit: ({ rowId, columnId, value }) => applyEdit(rowId, columnId, value),
})
```

Wire it to the grid:

```svelte
<SvGrid {data} {columns} editable getRowId={(r) => r.id}
  onActiveCellChange={(c) => collab.setCell({ rowId: data[c.rowIndex].id, columnId: c.columnId })}
  onCellValueChange={(e) => collab.sendEdit(data[e.rowIndex].id, e.columnId, e.newValue)} />
```

## The transport

The controller is transport-agnostic. It ships with one adapter:

- **`broadcastChannelTransport(name)`** - syncs across tabs of the same
  browser with **zero backend**. Great for demos and single-user multi-tab.

For cross-machine collaboration implement `CollabTransport` (a `post(msg)` +
`subscribe(handler)` pair) over a WebSocket, WebRTC datachannel, or a CRDT
library:

```ts
const wsTransport: CollabTransport = {
  post: (msg) => socket.send(JSON.stringify(msg)),
  subscribe: (h) => { const l = (e) => h(JSON.parse(e.data)); socket.addEventListener('message', l); return () => socket.removeEventListener('message', l) },
}
```

## The controller API

| Method                      | Does                                            |
| --------------------------- | ----------------------------------------------- |
| `setCell(cell \| null)`     | Broadcast where your cursor is.                 |
| `sendEdit(rowId, col, val)` | Broadcast a cell edit.                          |
| `peers()`                   | Present peers (excludes you), with their cursor.|
| `dispose()`                 | Announce leave + tear down (call on unmount).   |

`onPeersChange` fires whenever the peer set or any cursor moves; `onRemoteEdit`
fires for edits from **other** users only (never echoes your own).

## Notes

- Presence is heartbeat-pruned: a peer that closes its tab without a clean
  `bye` is dropped after `peerTimeoutMs` (default 15s).
- Edits are last-writer-wins at the cell level. For conflict-free merging on a
  busy doc, back the transport with a CRDT; the controller doesn't assume one.
- This is also the **multi-agent** substrate: an AI agent is just another peer
  posting `edit` messages - drive `sendEdit` from your agent loop.

See the live [Real-time collaboration](https://sv-grid.com/demos/149-realtime-collaboration)
demo (open it in two tabs).

<!-- =================================================================
     /help/columns-hierarchy  (community)
     ================================================================== -->

# Columns hierarchy & manager

The pattern for grids with too many columns to fit on screen at once.
A side-panel "column manager" exposes the column tree to the user:
they pick what's visible, what gets collapsed into a one-cell summary,
and what order leaves appear in within each group.

Try it live - drag a leaf chip between siblings, click a group's
chevron to collapse it into a summary column, toggle a checkbox to
hide:

<div data-docs-demo="54-columns-hierarchy" data-height="560"></div>

## What it builds on

Two existing engine capabilities power this:

1. **Nested column groups.** A `ColumnDef` with `columns: [...]`
   produces multi-row headers automatically; see
   [Column groups](./columns/column-groups.md).
2. **Dynamic columns.** The `columns` prop is a regular array; passing
   a `$derived` array makes it reactive. The grid swaps the column
   tree in place on every change.

The "hierarchy manager" is just a Svelte component you write that
mutates a piece of `$state` describing which groups are open + which
leaves are visible. The derived columns array reflects that state.

## Data model

The state has one entry per group:

```ts
type GroupTreeState = {
  id: string
  visible: boolean                       // whole-group hide
  collapsed: boolean                     // collapsed to one summary column
  leafOrder: string[]                    // leaf ids, in display order
  leafVisible: Record<string, boolean>   // per-leaf hide
}

let treeState = $state<GroupTreeState[]>(initialTree())
```

Initial state walks your fixed group definitions and turns every leaf
into `visible: true`. From then on, every interaction in the side
panel produces a new array (no mutation in place - Svelte 5 prefers
reassignment).

## Deriving the column tree

The grid's columns are a `$derived` from the tree state plus your
fixed column specs:

```ts
const columnTree = $derived.by((): ColumnDef<F, Row>[] => {
  const out: ColumnDef<F, Row>[] = []
  for (const g of treeState) {
    if (!g.visible) continue
    const spec = GROUPS.find((s) => s.id === g.id)!
    if (g.collapsed) {
      // One synthetic column showing the group's summary.
      out.push({
        id: `summary_${g.id}`,
        header: `${spec.label} · summary`,
        width: 200,
        cell: (ctx) => renderSnippet(SummaryCell, {
          row: ctx.row.original,
          groupId: g.id,
        }),
      })
      continue
    }
    // Otherwise: emit the group as a real nested column group.
    const visibleLeaves = g.leafOrder
      .map((id) => spec.leaves.find((l) => l.id === id)!)
      .filter((l) => g.leafVisible[l.id])
    if (visibleLeaves.length === 0) continue
    out.push({
      id: `group_${g.id}`,
      header: spec.label,
      columns: visibleLeaves.map(buildLeaf),
    })
  }
  return out
})
```

`buildLeaf` is a small helper that maps your fixed leaf spec
(`{ id, field, label, width }`) into a `ColumnDef`. For columns whose
display is a custom snippet, dispatch by id and emit the corresponding
`cell: renderSnippet(...)`.

## Group "summary" cells

When the user collapses a group, you don't usually want it to vanish -
the user wants to see one representative value for it. The
**Engagement** group in the demo collapses to a health pill;
**Deal value** collapses to the ARR; **Account** collapses to the
company name plus an industry / region sub-line.

The summary cell snippet takes a `groupId` prop and switches on it:

```svelte
{#snippet SummaryCell(props: { row: Deal; groupId: string })}
  {#if props.groupId === 'value'}
    <span class="flex flex-col">
      <span class="font-bold tabular-nums">{fmtMoney(props.row.arr)}</span>
      <span class="text-xs text-muted tabular-nums">{props.row.probability}% prob</span>
    </span>
  {:else if props.groupId === 'engagement'}
    <HealthPill health={props.row.health} />
  {/if}
{/snippet}
```

## Side-panel UI

Three things the user controls per group:

| Control                       | What it does                                                      |
| ----------------------------- | ----------------------------------------------------------------- |
| Chevron (`▶`)                 | Toggle `collapsed`. Group becomes 1 column, or expands back.      |
| Group checkbox                | Toggle `visible`. Hides the whole group.                          |
| Leaf checkbox                 | Toggle `leafVisible[id]`. Hides one column.                       |

Drag-and-drop within a group reorders leaves:

```ts
function onDrop(e: DragEvent, groupId: string, targetLeafId: string) {
  e.preventDefault()
  if (!drag || drag.groupId !== groupId) return
  const group = treeState.find((g) => g.id === groupId)!
  const fromIx = group.leafOrder.indexOf(drag.leafId)
  const toIx = group.leafOrder.indexOf(targetLeafId)
  if (fromIx < 0 || toIx < 0 || fromIx === toIx) return
  const next = group.leafOrder.slice()
  next.splice(fromIx, 1)
  next.splice(toIx, 0, drag.leafId)
  treeState = treeState.map((g) =>
    g.id === groupId ? { ...g, leafOrder: next } : g,
  )
}
```

The demo restricts drag to same-group reorder because cross-group drag
would change the semantic grouping (a "Deal value · Stage" mix doesn't
make sense). If your data model allows cross-group moves, drop the
`drag.groupId === groupId` guard.

## Persistence

The tree state is a plain JS object - feed it into your
[Saved views](./saved-views.md) pipeline and the user's column layout
follows them across sessions:

```ts
// Save
saveView({ ...currentView, columnTree: treeState })
// Restore
treeState = view.columnTree ?? initialTree()
```

For multi-user / shared layouts, store under a per-team key alongside
your other config.

## Performance

Re-deriving `columnTree` runs at ~0.1 ms even for 40-leaf trees on a
modern machine; the cost is dominated by the grid's column-rebuild
work afterward (~1-2 ms). Mutating the tree state at interactive rates
(drag-resize over time) is fine.

## Composing with the rest of the grid

- **Sort + filter** apply to whatever columns are visible. Collapsing
  a group hides its leaves; their filters disappear from the menu but
  are NOT cleared - re-expand the group and they're still active. If
  that's surprising for your users, clear the leaf filters as part of
  the collapse handler.
- **Pinned columns** are recorded per leaf id - they re-pin
  automatically when the leaf becomes visible again.
- **Saved views** should serialise `treeState` alongside sort + filter.

## See also

- [Column groups](./columns/column-groups.md) - the nested-header
  primitive this pattern uses.
- [Saved views](./saved-views.md) - persisting the tree state across
  sessions.
- [State maintenance](./state-maintenance.md) - undo / redo for tree
  changes.
- [Demo #54 Columns hierarchy](https://svgrid.com/#/demos/54-columns-hierarchy)
  - the reference implementation.

<!-- =================================================================
     /help/columns/column-definitions  (community)
     ================================================================== -->

# Column definitions

A `ColumnDef` tells SvGrid how to read a value out of a row, how to render it,
and which features apply to it. The grid below is built from a handful
of `ColumnDef`s - look at the [source](https://svgrid.com/#/demos/01-quick-start) to see how each shape maps to a column behaviour:

<div data-docs-demo="01-quick-start" data-height="460"></div>


## Minimal

```ts
import type { ColumnDef } from 'sv-grid-community'

type Person = { firstName: string; age: number; status: string }

const columns: ColumnDef<{}, Person>[] = [
  { field: 'firstName', header: 'First name' },
  { field: 'age',       header: 'Age' },
  { field: 'status',    header: 'Status' },
]
```

## Properties

| Property | Type | Purpose |
| --- | --- | --- |
| `id` | `string` | Stable column id. Required when you use `accessorFn` and no `field`. |
| `field` | `keyof TData & string` | Reads `row[key]`. |
| `accessorFn` | `(row) => unknown` | Computes the value. |
| `header` | `string` \| `(ctx) => unknown` | String, or a function returning a `renderSnippet` / `renderComponent`. |
| `cell` | `(ctx) => unknown` | Same shape as `header`, for body cells. |
| `footer` | `string` \| `(ctx) => unknown` | Footer cell. |
| `editorType` | `'text' \| 'number' \| 'date' \| 'datetime' \| 'checkbox'` | Inline editor type. |
| `format` | `CellFormatConfig` | Built-in `number`, `currency`, `percent`, `date`, `datetime` formatters. |
| `formatter` | `(ctx) => string` | Custom formatter - runs after `field` / `accessorFn`. |
| `columns` | `ColumnDef[]` | Children - turns this column into a column **group**. |
| `width` | `number` | Initial width in pixels (overrides the grid's `columnWidth`). |

See [`packages/sv-grid-community/src/core.ts`](../../../packages/sv-grid-community/src/core.ts).

## Accessor vs. accessorFn

`field` is the common case. Use `accessorFn` when the value is
computed or comes from a nested object:

```ts
const columns: ColumnDef<{}, Person>[] = [
  { field: 'firstName', header: 'First' },
  {
    id: 'fullName',
    header: 'Full name',
    accessorFn: (row) => `${row.firstName} ${row.lastName}`,
  },
]
```

Whenever you use `accessorFn` you must supply an `id` - there is no string key
to derive one from.

## Format vs. formatter vs. cell

| You want | Use |
| -------- | --- |
| Locale-aware number / currency / percent / date | `format` |
| A custom string transformation | `formatter` |
| Custom HTML (avatars, pills, progress, sparklines) | `cell` with `renderSnippet` |

`format` is purely declarative and locale-aware - prefer it for anything
numeric or temporal:

```ts
{ field: 'salary', header: 'Salary',
  format: { type: 'currency', currency: 'USD', options: { maximumFractionDigits: 0 } } }

{ field: 'joinedAt', header: 'Joined',
  format: { type: 'date', pattern: 'y-m-d' } }

{ field: 'utilization', header: 'Utilization',
  format: { type: 'percent', valueIsPercentPoints: true } } // 42 -> 42%
```

`formatter` runs after the accessor; the result is what gets displayed
(and what gets copied to the clipboard during cell selection).

`cell` is the most powerful - see [Cell components](../cells/cell-components.md).

## TypeScript

Pass the row type as the second generic; the column's `field` is then
checked against the row's keys:

```ts
const columns: ColumnDef<{}, Person>[] = [
  { field: 'firstName' },   // ✅
  // { field: 'first_name' } // ✗ compile error
]
```

The first generic is the **feature set** - derive it from `tableFeatures` so
feature-specific column properties light up:

```ts
const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
type Features = typeof features

const columns: ColumnDef<Features, Person>[] = [/* … */]
```

## See also

- [Updating definitions](./updating-definitions.md)
- [Column state](./column-state.md)
- [Custom header components](./custom-header-components.md)
- Example: [`02-sort-filter-paginate.svelte`](../../../examples/src/demos/02-sort-filter-paginate.svelte)

<!-- =================================================================
     /help/columns/column-groups  (community)
     ================================================================== -->

# Column groups

A column group is a `ColumnDef` whose `columns` array contains children.
The parent renders a spanning header above its children. The pivot demo
below shows three levels of grouped headers in action - Year wraps
Quarter wraps measure:

<div data-docs-demo="52-pivot-table" data-height="540"></div>



```ts
const columns: ColumnDef<{}, Person>[] = [
  { field: 'firstName', header: 'First name' },
  { field: 'lastName',  header: 'Last name' },
  {
    id: 'compensation',
    header: 'Compensation',
    columns: [
      { field: 'salary', header: 'Salary',
        format: { type: 'currency', currency: 'USD' } },
      { field: 'bonus',  header: 'Bonus',
        format: { type: 'currency', currency: 'USD' } },
    ],
  },
]
```

Rendered as:

```
|              | Compensation         |
| First | Last | Salary | Bonus       |
```

## How it works

- The grid walks the column tree once, producing two header groups -
  the parent row and the leaf row.
- Each parent header gets a `colSpan` equal to the count of leaf descendants
  it has.
- The cell body only renders leaves.

## Nested groups

Groups can nest arbitrarily. The grid emits one header row per depth level:

```ts
{
  header: 'Q1',
  columns: [
    { header: 'Jan', field: 'jan' },
    { header: 'Feb', field: 'feb' },
    { header: 'Mar', field: 'mar' },
  ],
},
{
  header: 'Q2',
  columns: [/* … */],
},
```

## Group with a custom header

The same `header: (ctx) => renderSnippet(...)` pattern from
[custom header components](./custom-header-components.md) works for group
headers. The `ctx.header.colSpan` value will be the rendered span.

## Gotchas

- A group needs an `id` (or a string `header`) - the grid uses it to give the
  parent header a stable DOM id.
- Hidden columns (`api.setColumnVisible(id, false)`) shrink their group's
  `colSpan` automatically.
- A group cannot be sorted or filtered - only its leaves can.

## See also

- [Column definitions](./column-definitions.md)
- [Custom header components](./custom-header-components.md)

<!-- =================================================================
     /help/columns/column-headers  (community)
     ================================================================== -->

# Column headers - styling & height

Headers are rendered as `<th>` inside a `<thead>` with `role="row"`. Style
them with regular CSS - there are no header-specific Svelte props.
<div data-docs-demo="01-quick-start" data-height="540"></div>

## Set header text

```ts
{ field: 'firstName', header: 'First name' }
```

For computed headers, pass a function returning a `renderSnippet` /
`renderComponent` - see [Custom header components](./custom-header-components.md).

## Header height

There is no `headerHeight` prop. Header height is determined by content +
padding. Override via CSS:

```css
table[role='grid'] thead th {
  height: 40px;
  padding: 0.4rem 0.6rem;
}
```

If you set a fixed virtualizer row height (`rowHeight={36}` on `<SvGrid>`)
the header is **independent** of that - the virtualizer measures it once
at mount to compute the visible viewport.

## Header colour, weight, alignment

The grid leans on the gallery's tokenised CSS:

```css
table[role='grid'] thead tr {
  background: var(--sg-header-bg);
  color:      var(--sg-header-fg);
}

table[role='grid'] th {
  border: 1px solid var(--sg-border);
  font-weight: 600;
  text-align: left;
}
```

Set those custom properties at `:root`, on an ancestor, or directly on the
grid host to change the look.

## Sortable header indicator

When `rowSortingFeature` is registered, sortable headers gain a click handler
and `aria-sort` is updated. SvGrid renders the asc/desc arrow itself; to
restyle, target the inner span:

```css
table[role='grid'] th [data-sort-indicator] {
  opacity: 0.6;
}
table[role='grid'] th[aria-sort] [data-sort-indicator] {
  opacity: 1;
}
```

## See also

- [Custom header components](./custom-header-components.md)
- [Column groups](./column-groups.md)

<!-- =================================================================
     /help/columns/column-moving  (community)
     ================================================================== -->

# Column moving (drag to reorder)

There are two ways to move columns in sv-grid:

1. **`enableColumnReorder` prop** - the built-in drag-to-reorder UX. Every header becomes draggable, the grid paints a drop indicator, and the order is emitted via `onColumnOrderChange`. Recommended for v1.
2. **Reassign the `columns` prop** - the array order IS the display order, so you can swap items in your own state.

<div data-docs-demo="109-column-reorder-engine" data-height="540"></div>

## Built-in drag-to-reorder

```svelte
<script lang="ts">
  import { SvGrid, tableFeatures, rowSortingFeature, type ColumnDef } from 'sv-grid-community'

  let columns: ColumnDef<{}, Person>[] = [
    { field: 'firstName', header: 'First name' },
    { field: 'lastName',  header: 'Last name' },
    { field: 'age',       header: 'Age' },
    { field: 'salary',    header: 'Salary' },
  ]

  // Persist the order so it survives reloads. The grid drives this -
  // we just remember the latest array it emitted.
  let order = $state<string[]>(
    JSON.parse(localStorage.getItem('my-grid-order') ?? '[]'),
  )
  $effect(() => {
    if (order.length) localStorage.setItem('my-grid-order', JSON.stringify(order))
  })
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  enableColumnReorder={true}
  columnOrder={order}
  onColumnOrderChange={(next) => (order = [...next])}
/>
```

When `enableColumnReorder` is `true`, the grid:

- Sets `draggable=true` on every header (`<th data-svgrid-header-col>`).
- Paints a vertical drop indicator before / after the hovered header.
- On drop, updates its internal order and fires `onColumnOrderChange(orderedIds)`.
- Respects column pinning - dragging across pin zones is allowed, but a column dropped into a pin zone stays in that zone's natural slot.

### Props

| Prop | Type | Notes |
| --- | --- | --- |
| `enableColumnReorder` | `boolean` | Defaults to `false`. Set `true` to opt in. |
| `columnOrder` | `ReadonlyArray<string>` | Initial / controlled order. Reassign to drive externally. |
| `onColumnOrderChange` | `(order: string[]) => void` | Fires after each change (user drag or `api.setColumnOrder`). |

### Imperative API

`SvGridApi` exposes two methods for command-palette / shortcut wiring:

```ts
api.setColumnOrder(['symbol', 'price', 'name', 'pe'])
const current = api.getColumnOrder()
```

`setColumnOrder` accepts a subset of ids; columns not in the array keep their existing relative position after the listed ones. Unknown ids are skipped.

## Pin groups + reorder

Column reorder composes cleanly with column pinning:

```svelte
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  enableColumnReorder={true}
  onApiReady={(api) => {
    api.setColumnPinning({ left: ['symbol'], right: ['changePct'] })
  }}
/>
```

The reorder logic operates on the column ids; the pin grouping is then layered on top, so left-pinned columns stay on the left and right-pinned on the right.

## Reassign the columns prop (no `enableColumnReorder`)

If you prefer to own the order entirely in user-land (e.g. a dropdown picker rather than drag):

```svelte
<script lang="ts">
  let columns = $state<ColumnDef<{}, Person>[]>([
    { field: 'firstName', header: 'First name' },
    { field: 'lastName',  header: 'Last name' },
    { field: 'age',       header: 'Age' },
  ])

  function swap(i: number, j: number) {
    const next = columns.slice()
    ;[next[i], next[j]] = [next[j]!, next[i]!]
    columns = next
  }
</script>
```

This was the only option before `enableColumnReorder` shipped. Demo 104 shows a user-land header-drag pattern built on top of this approach.

## Persisting + saved views

The emitted `string[]` is JSON-serialisable, so the most common pattern is:

- Save to `localStorage` for "remember my last layout".
- Save under a name for "Saved views" feature (combine with column widths, pinning, and filter state).
- Serialise to a URL param for shareable views.

## See also

- Demo 109: Column reorder (engine prop)
- Demo 104: Column reorder (user-land drag-handle pattern)
- `Saved views` recipe in `docs/recipes/saved-views.md`
- `api.setColumnPinning` and `api.getColumnPinning`

<!-- =================================================================
     /help/columns/column-pinning  (community)
     ================================================================== -->

# Column pinning

Pinning sticks a column to the **left** or **right** edge of the viewport so
it does not scroll horizontally with the rest.

Live demo - pin Company left, Price right, scroll the middle:

<div data-docs-demo="25-column-pinning" data-height="480"></div>

## Through the column menu

Every column header has a menu (the `⋮` button). The menu has "Pin left" /
"Pin right" / "Unpin" items.

## Programmatically

`SvGridApi` exposes `setColumnPinning` and `getColumnPinning` for
read / write from outside the grid:

```svelte
<script lang="ts">
  import type { SvGridApi } from 'sv-grid-community'
  let api = $state<SvGridApi<typeof features, Person> | null>(null)
</script>

<SvGrid {data} {columns} features={features}
  onApiReady={(next) => (api = next)} />

<button onclick={() => api?.setColumnPinning({ left: ['company'], right: ['actions'] })}>
  Pin company left, actions right
</button>
<button onclick={() => api?.setColumnPinning({ left: [], right: [] })}>
  Unpin all
</button>
```

For initial pinning at mount, use the `initialColumnPinning` prop on
`<SvGrid>`:

```svelte
<SvGrid {data} {columns} features={features}
  initialColumnPinning={{ left: ['company'], right: ['actions'] }} />
```

`getColumnPinning()` returns `{ left: string[]; right: string[] }` -
the array order is the visible order along the pinned edge.

## Rendering

- Pinned-left columns sit at the start of the visible row, with `position:
  sticky; left: <offset>px; z-index: 3`.
- Pinned-right columns sit at the end of the visible row, with `position:
  sticky; right: <offset>px; z-index: 3`.
- Offsets cascade - second-left column sits at the cumulative width of
  the first.

## Styling

Pinned columns are visually differentiated from the scrollable middle
through three layered cues:

1. **A distinct background tint** so the pinned strip reads as "frozen"
   even before you scroll.
2. **A 1-pixel divider** on the inside edge (the side facing the
   scrollable region) and a soft drop shadow that fades into the
   scroll area.
3. **A bolder header** font weight so the frozen header reads as part
   of the grid chrome.

All three cues are driven by CSS custom properties. Override them to
match your design system:

| Token                       | Default                                                                   | Used for                       |
|-----------------------------|---------------------------------------------------------------------------|--------------------------------|
| `--sg-pinned-bg`            | `color-mix(in oklab, var(--sg-header-bg) 70%, var(--sg-accent) 8%)`       | Body cells in pinned columns   |
| `--sg-pinned-header-bg`     | `color-mix(in oklab, var(--sg-header-bg) 60%, var(--sg-accent) 14%)`      | Header cells in pinned columns |
| `--sg-pinned-divider`       | `var(--sg-border)`                                                        | The 1-pixel inside-edge line   |

The fallbacks compute a subtle accent-tinted background from your
existing header background, so a pinned column never looks identical
to the rest of the grid even if you don't set anything. To opt out
of the tint and match the body exactly:

```css
.themed-host {
  --sg-pinned-bg:        var(--sg-bg);
  --sg-pinned-header-bg: var(--sg-header-bg);
}
```

Or to make pinned columns *very* obvious - useful for high-density
financial grids where the user must instantly know which side is
frozen:

```css
.themed-host {
  --sg-pinned-bg:        color-mix(in oklab, var(--sg-bg) 60%, var(--sg-accent) 20%);
  --sg-pinned-header-bg: color-mix(in oklab, var(--sg-bg) 40%, var(--sg-accent) 30%);
  --sg-pinned-divider:   var(--sg-accent);
}
```

### Hover, selection, and zebra rows

The pinned tint sits *under* the hover, selection, and zebra row
backgrounds via stacked `linear-gradient` paints. That means:

- Hovering a row in a pinned cell shows the pinned tint *with* the
  hover overlay on top - the user still sees the row highlight.
- Selecting a row layers the selection colour over the pinned tint.
- Zebra rows re-paint the pinned cell so the alternating row
  background doesn't leak through the pin.

You don't need to override anything for these states to work; they
follow `--sg-row-hover-bg`, `--sg-selection-bg`, and the pinned tokens
automatically.

## Multiple pinned columns

Multiple pins are stacked in the order they were pinned. The first-pinned
column is the outermost.

## Gotchas

- Pinning **plus** column virtualization is supported, but the pinned
  columns are always rendered (they never enter the virtualized window).
- If you have so many pinned columns that they exceed the viewport width
  there is no horizontal scrollbar within the pinned regions - the user
  loses access to the non-pinned middle. Pin only "anchor" columns
  (identifier, action, status) and keep the count single-digit.

## See also

- [Column state](./column-state.md)
- [`SvGridApi` reference](../../reference/SvGridApi.md) - `setColumnPinning` / `getColumnPinning` signatures.

<!-- =================================================================
     /help/columns/column-sizing  (community)
     ================================================================== -->

# Column sizing

Each column has a pixel width. The default for all columns is the grid's
`columnWidth` prop (default ~140 px); each column can override via its
`width` field.
<div data-docs-demo="63-column-layout-api" data-height="540"></div>

```ts
const columns: ColumnDef<{}, Person>[] = [
  { field: 'firstName',  header: 'First name', width: 150 },
  { field: 'department', header: 'Department', width: 180 },
  { field: 'salary',     header: 'Salary',     width: 120 },
]
```

```svelte
<SvGrid {columns} {data} features={{}} columnWidth={140} />
```

## User resizing

Every column has a resize handle on its right edge. Drag to widen /
narrow; the minimum is 40 px. Resizes are stored per column id inside
the grid component.

There is no opt-out today - if you do not want users to resize a column,
overlay your own pointer-blocking element on the header or wrap in CSS:

```css
table[role='grid'] th[data-col-id="firstName"] [data-resize-handle] {
  pointer-events: none;
}
```

## Programmatic resizing + persistence

The imperative API exposes `setColumnWidth` and `getColumnWidths`:

```svelte
<script lang="ts">
  import type { SvGridApi } from 'sv-grid-community'
  let api = $state<SvGridApi<typeof features, Person> | null>(null)

  function save() {
    if (!api) return
    localStorage.setItem('widths', JSON.stringify(api.getColumnWidths()))
  }
  function restore() {
    if (!api) return
    const saved: Record<string, number> = JSON.parse(localStorage.getItem('widths') ?? '{}')
    for (const [id, w] of Object.entries(saved)) api.setColumnWidth(id, w)
  }
</script>

<SvGrid {data} {columns} features={features}
  onApiReady={(next) => (api = next)} />

<button onclick={save}>Save layout</button>
<button onclick={restore}>Restore layout</button>
```

`getColumnWidths()` returns every column's *current effective* width
(user resize OR columnDef `width` OR grid-wide default), so the
snapshot round-trips cleanly.

## Auto-fit

`fitColumns={true}` scales every column proportionally to fill the
viewport - the wrapper handles rounding-residue absorption + a modest
shrink-to-fit (down to ~85 % of natural widths). For "fit to content"
(longest cell text), pre-compute per-column widths once after a data
load and call `api.setColumnWidth(id, w)` per column.

## Column virtualization

With many columns, enable column virtualization so only the visible columns
render:

```svelte
<SvGrid
  {columns}
  {data}
  features={{}}
  columnVirtualization={true}
  columnWidth={120}
  columnOverscan={3}
/>
```

See [examples/src/demos/06-large-dataset.svelte](../../../examples/src/demos/06-large-dataset.svelte)
for a 100-column virtualized grid.

## Gotchas

- A `width` set in the column def is an **initial** width. Once a user has
  resized, the override on disk wins. The library does not expose the
  current widths to outside code; if you need to persist them, file an
  issue (or PR) for `getColumnWidths()` on `SvGridApi`.

## See also

- [Column moving](./column-moving.md)
- [Column pinning](./column-pinning.md)

<!-- =================================================================
     /help/columns/column-spanning  (community)
     ================================================================== -->

# Column spanning

"Column spanning" lets a single body cell span across **multiple columns** -
useful for full-width subtotals, group banner rows, or notes embedded inside
a wide grid.

## Status

This is **not yet built in** to the community grid. There is no `colSpan`
field on `ColumnDef` or `CellContext`.

There are two close-enough workarounds:

## 1. Full-width "row banner" via grouping

If your span semantics are "render an aggregate above each group", the
[grouping](../rows/row-data.md#grouping) pipeline gives you a group row
that fills the row width via the group label column. See
[examples/src/demos/07-grouping-aggregation.svelte](../../../examples/src/demos/07-grouping-aggregation.svelte).

## 2. Custom cell with `position: absolute`

If you need an irregular full-width content cell inside an otherwise normal
row, render a regular cell whose content spills across columns:

```svelte
{#snippet Banner(p: { row: Row })}
  <span class="absolute left-0 right-0 px-2 bg-yellow-100">
    {p.row.note}
  </span>
{/snippet}
```

You'll need a CSS contortion to disable borders on the covered cells. This
is fragile - only use it for one-off rows like "no results" placeholders.

## See also

- [Row spanning](../rows/row-spanning.md) - the row-side analogue, also not built in.
- [Missing features](../missing-features.md)

<!-- =================================================================
     /help/columns/column-state  (community)
     ================================================================== -->

# Column state

"Column state" is the bag of per-column settings that change at runtime:
visibility, width, pinning, sort, filter. SvGrid keeps these as separate
state slices inside the grid instance.
<div data-docs-demo="55-state-maintenance" data-height="540"></div>

## Slices

| Slice | Where it lives | How to read | How to write |
| ----- | -------------- | ----------- | ------------ |
| Visibility | `<SvGrid>` internal | `api.isColumnVisible(id)` | `api.setColumnVisible(id, visible)` |
| Width | `<SvGrid>` internal (resize handles) | drag the right edge of a header | - |
| Pinning | `<SvGrid>` internal | via column menu | via column menu |
| Sort | `state.sorting` | `grid.getState().sorting` | `api.setSort(id, dir)` / `api.clearSort()` |
| Filter | `state.columnFilters` | `grid.getState().columnFilters` | `api.setFilter(id, ...)` / `api.clearFilter(id)` |

## Persisting state

To round-trip column state (e.g. through `localStorage` or the URL),
subscribe via the wrapper's change callbacks and re-apply on mount
through the imperative API:

```svelte
<script lang="ts">
  import type { SvGridApi } from 'sv-grid-community'

  const KEY = 'people-grid-state'

  function loadState() {
    try { return JSON.parse(localStorage.getItem(KEY) ?? '{}') }
    catch { return {} }
  }
  const initial = loadState()

  let sorting = $state<Array<{ id: string; desc: boolean }>>(initial.sorting ?? [])
  let filters = $state<Array<{ id: string; operator: string; value: string }>>(
    initial.filters ?? [],
  )
  let api = $state<SvGridApi<typeof features, Person> | null>(null)

  $effect(() => {
    localStorage.setItem(KEY, JSON.stringify({ sorting, filters }))
  })
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  filterMode="menu"
  onApiReady={(next) => {
    api = next
    // Re-apply saved state on first mount.
    for (const s of initial.sorting ?? []) api.setSort(s.id, s.desc ? 'desc' : 'asc')
    for (const f of initial.filters ?? []) api.setFilter(f.id, { operator: f.operator, value: f.value })
  }}
  onSortingChange={(next) => (sorting = next)}
  onFiltersChange={(next) => (filters = next.columns)}
/>
```

## Resetting state

There is no single "reset" API today. To revert:

- Sort: `api.clearSort()`
- Filters: iterate the active list and call `api.clearFilter(id)`
- Visibility: walk your columns and call `setColumnVisible(id, true)`

Wrap whichever subset you need into your own helper if you do this often.

## Gotchas

- Column **width** is currently tracked per column id inside the SvGrid
  component and is not exposed on `SvGridApi`. If you need to persist user
  resizes you'll have to read the cells after the grid renders or PR an
  accessor onto the API. See [missing-features.md](../missing-features.md).
- Column **pinning** is controlled by the column menu; there is no public
  setter on the API today. Same caveat as above.

## See also

- [Column moving](./column-moving.md)
- [Column pinning](./column-pinning.md)
- [Updating definitions](./updating-definitions.md)

<!-- =================================================================
     /help/columns/custom-header-components  (community)
     ================================================================== -->

# Custom header components

The `header` field on a `ColumnDef` accepts a function that returns either
a `renderSnippet(...)` or `renderComponent(...)`. The function receives a
`HeaderContext` so it can access the column, header, and grid.
<div data-docs-demo="10-custom-cells-and-themes" data-height="540"></div>

## With a snippet

```svelte
<script lang="ts">
  import { renderSnippet, type ColumnDef } from 'sv-grid-community'

  const columns: ColumnDef<{}, Person>[] = [
    {
      field: 'salary',
      header: (ctx) => renderSnippet(SalaryHeader, { sorted: ctx.column.getIsSorted() }),
      format: { type: 'currency', currency: 'USD' },
    },
  ]
</script>

{#snippet SalaryHeader(p: { sorted: false | 'asc' | 'desc' })}
  <span class="inline-flex items-center gap-1">
    <span>💰 Salary</span>
    {#if p.sorted === 'asc'}↑{:else if p.sorted === 'desc'}↓{/if}
  </span>
{/snippet}
```

## With a component

```ts
import HeaderWithIcon from './HeaderWithIcon.svelte'
import { renderComponent } from 'sv-grid-community'

const columns = [
  {
    field: 'status',
    header: () => renderComponent(HeaderWithIcon, { icon: 'flag', label: 'Status' }),
  },
]
```

## HeaderContext

The argument passed to your header callback exposes:

```ts
type HeaderContext<TData> = {
  header: Header<TData>
  column: Column<TData>
  table: SvGrid<TData>
}

// Column gives you sort state, filter capability, and the toggle handler:
ctx.column.getCanSort()
ctx.column.getIsSorted()                    // false | 'asc' | 'desc'
ctx.column.getToggleSortingHandler()        // () => void
```

## When to use it

Anything that needs more than a string belongs here - multi-line headers,
filter icons inside the header, units, tooltips, custom sort indicators,
a "select all" checkbox in a leading column.

## Gotchas

- Wrap your snippet output in **inline-level** markup (`<span>`, `<div>` with
  `inline-flex`). The grid renders the result inside a `<th>`'s text node
  position - block layout will misalign with the sort indicator and
  pin-handle decorations the grid adds around it.
- Snippet/component props are recomputed on every render. Keep them cheap.

## See also

- [Cell components](../cells/cell-components.md) - same API on the body side.

<!-- =================================================================
     /help/columns/tool-panel  (community)
     ================================================================== -->

# Columns tool panel

The tool panel is the docked sidebar - standard in enterprise grids - for
managing columns without hunting through a right-click menu. Turn it on with
the `toolPanel` prop:

```svelte
<SvGrid {data} {columns} {features} toolPanel />
```

A columns button appears at the grid's top-right. Clicking it opens a panel
docked on the right edge with, for every column:

- a **visibility** checkbox (show / hide the column),
- **↑ / ↓** to reorder the column,
- **⊞** to group / ungroup by that column (when grouping is enabled).

## Notes

- The panel lists **all** columns, including hidden ones, in the current
  display order, so you can bring a hidden column back.
- Visibility, order, and grouping changes go through the same engine state as
  the column menu and the imperative API (`setColumnVisible`,
  `setColumnOrder`, `setGroupBy`) - so they round-trip with `getState()` /
  `setState()` and [named views](../state/named-views.md).
- Grouping a column whose other columns declare an
  [`aggregate`](../grouping/aggregators.md) rolls those values up in the group
  header automatically.

See the live [Columns tool panel](https://sv-grid.com/demos/146-tool-panel)
demo.

<!-- =================================================================
     /help/columns/updating-definitions  (community)
     ================================================================== -->

# Updating column definitions

There are two ways to change columns after the grid has mounted:

## 1. Reassign the `columns` prop

`<SvGrid columns={...}>` is reactive. Replace the array (or mutate a `$state`
array) and the grid re-derives its internal columns.

```svelte
<script lang="ts">
  let columns = $state<ColumnDef<{}, Person>[]>([
    { field: 'firstName', header: 'First name' },
    { field: 'age', header: 'Age' },
  ])

  function addCountry() {
    columns = [...columns, { field: 'country', header: 'Country' }]
  }
</script>

<button onclick={addCountry}>+ Country</button>
<SvGrid {columns} data={rows} features={{}} />
```

## 2. Use the imperative API

The wrapper exposes mutators via `onApiReady`:

```svelte
<script lang="ts">
  let api: SvGridApi<{}, Person> | null = $state(null)
</script>

<SvGrid {columns} data={rows} features={{}} onApiReady={(next) => (api = next)} />

<button onclick={() => api?.addColumn({ field: 'country', header: 'Country' })}>
  + Country
</button>
```

Available column mutators on `SvGridApi`:

| Method | What it does |
| ------ | ------------ |
| `addColumn(col, position?)` | Insert one column. `position` is `'left' \| 'right' \| number` (default `'right'`). |
| `addColumns(cols, position?)` | Insert many. |
| `removeColumn(id)` | Remove by column id (or field when no `id`). |
| `setColumnVisible(id, visible)` | Show / hide. |
| `isColumnVisible(id)` | Read visibility. |

The imperative path is the right choice when the column-change initiator is
**outside** the parent that owns the `columns` array - e.g. a toolbar
component that doesn't know about the data source.

## What is preserved when columns change

When you add or remove a column:

- Sort state survives if the sorted column is still present.
- Filter state for the removed column is discarded.
- Active-cell focus is clamped into bounds.
- Column widths set by the user via resize handles are preserved by column id.
- Pinning is preserved by column id.

When you **reorder** columns by reassigning the array, the grid renders them
in the new order; pinned-left and pinned-right groups retain their order
relative to themselves.

## Gotchas

- Anything that captures `ctx.column.columnDef` inside a `cell` callback will
  see the **new** column def after a swap. Don't cache it.
- If you reassign the entire `columns` array on every render, you'll pay the
  cost of re-deriving headers each time. Memoise it (build once with
  `$state.raw` or a one-time IIFE) for hot-loop components.

## See also

- [Column state](./column-state.md)
- [Column moving](./column-moving.md)

<!-- =================================================================
     /help/comparison  (community)
     ================================================================== -->

# Comparison: SvGrid vs AG Grid vs TanStack Table

This is the page enterprise evaluators land on first. It is honest. The
three projects solve overlapping problems and the right choice depends
on your stack, your budget, and which constraints bite hardest.

## TL;DR

| Project              | Lives in                                 | Ships                                   | Bundle (typical) | License            |
| -------------------- | ---------------------------------------- | --------------------------------------- | ---------------- | ------------------ |
| **SvGrid**           | Svelte 5                                 | Headless core + Svelte render + Pro pack | ~7.5 KB headless / ~42 KB full (gzip) | MIT (Community) / commercial (Pro) |
| **AG Grid Community**| React, Angular, Vue, plain JS            | Full grid + renderer                    | ~340 KB                                   | MIT                                |
| **AG Grid Enterprise**| same                                    | Adds pivot, integrated charts, server-side row model, more | ~600 KB+ | Commercial                         |
| **TanStack Table**   | React, Vue, Svelte, Solid, Qwik, Lit, JS | Headless engine **only**                | ~12-14 KB                                 | MIT                                |

## When SvGrid is the right choice

- You're on **Svelte 5** and want a grid that uses the runtime's idioms
  (snippets for cells, `$state` for data, `$derived` for aggregates) -
  not a React-port pretending to be Svelte.
- You want a **headless core you can render yourself** AND a
  default-styled component for the 80% case. Most "headless" libraries
  make you write the markup; most "monolith" libraries make you fight
  the markup. SvGrid does both in one package.
- You need **clean theming via CSS custom properties** and a documented
  `--sg-*` token surface, not a hard-coded class soup.
- You ship under **strict CSP** (no `eval`, no `new Function`, no
  inline scripts). SvGrid runs clean; AG Grid Community does too.
  TanStack Table is engine-only so the question doesn't apply.
- You want **SSR markup that is meaningful before hydration** (good
  first paint, SEO, SvelteKit `+page.server` integration). SvGrid +
  TanStack Table both qualify. AG Grid renders client-side.

## When AG Grid is the right choice

- You're on **React, Angular, or Vue**, not Svelte. SvGrid is
  Svelte-only.
- You need **every grid feature shipped** out of the box: row drag,
  master-detail with built-in API, range selection, status bar,
  context menu, column tool panel, integrated charts (Enterprise),
  Excel-native pivot UI (Enterprise), server-side row model
  (Enterprise).
- You need **enterprise commercial support** with SLAs. AG sells it;
  SvGrid Pro support is best-effort.

## When TanStack Table is the right choice

- You want a **rendering-framework-agnostic engine** so the same
  business logic powers React + Svelte + Solid surfaces in your
  monorepo.
- You're already in the TanStack ecosystem (Query, Router, Form,
  Virtual) and want one mental model.
- You're happy writing **all the markup yourself** - the row recycling,
  the keyboard map, the ARIA roles, the focus management, the
  drag-to-resize. That's the cost of "engine only".

## Feature parity at a glance

|                                 | SvGrid Community | SvGrid Pro | AG Grid Community | AG Grid Enterprise | TanStack Table |
| ------------------------------- | ---------------- | ---------- | ----------------- | ------------------ | -------------- |
| Headless core (engine only)     | ✓                | ✓          | -                 | -                  | ✓              |
| Default render component        | ✓ (Svelte 5)     | ✓          | ✓ (each FW)       | ✓                  | -              |
| Sort (multi-column)             | ✓                | ✓          | ✓                 | ✓                  | ✓              |
| Filter menu (operator + facet)  | ✓                | ✓          | ✓                 | ✓                  | -              |
| Filter row                      | ✓                | ✓          | ✓                 | ✓                  | -              |
| Pagination                      | ✓                | ✓          | ✓                 | ✓                  | ✓              |
| Grouping + aggregation          | ✓                | ✓          | basic             | ✓ (advanced)       | ✓ (engine)     |
| Tree / expand-collapse rows     | ✓                | ✓          | basic             | ✓                  | ✓              |
| Cell range selection + copy/paste | ✓              | ✓          | ✓ (Enterprise)    | ✓                  | -              |
| Inline editing (5 editor types) | ✓                | ✓          | ✓                 | ✓                  | -              |
| Column virtualization           | ✓                | ✓          | ✓                 | ✓                  | -              |
| Row virtualization              | ✓                | ✓          | ✓                 | ✓                  | -              |
| Column pinning (left/right)     | ✓                | ✓          | ✓                 | ✓                  | -              |
| Fit-to-width with shrink        | ✓                | ✓          | partial           | ✓                  | -              |
| WAI-ARIA grid pattern           | ✓                | ✓          | ✓                 | ✓                  | -              |
| Server-side row model           | external mode    | external mode | -              | ✓ (built-in)       | external mode  |
| CSP-clean (no eval, no inline)  | ✓                | ✓          | ✓                 | ✓                  | n/a            |
| Meaningful SSR markup           | ✓                | ✓          | -                 | -                  | depends on FW  |
| Excel / PDF / CSV export        | -                | ✓          | -                 | ✓ (Enterprise)     | -              |
| Excel / CSV import              | -                | ✓          | -                 | -                  | -              |
| AI assistant                    | -                | ✓ (BYO provider) | -           | -                  | -              |
| Pivot table                     | -                | ✓          | -                 | ✓                  | (custom)       |
| Integrated charts               | -                | -          | -                 | ✓                  | -              |
| Theming via CSS variables       | ✓ (`--sg-*`)     | ✓          | ✓ (theme builder) | ✓                  | n/a            |
| Source-button per demo          | ✓ (gallery)      | ✓          | -                 | -                  | -              |

## Bundle size

Measured gzipped, with Svelte treated as a peer dependency and excluded
(the bundlephobia convention):

| sv-grid-community path                          | Gzipped | Minified |
| ----------------------------------------------- | ------- | -------- |
| Headless core (`createSvGrid` + a row model)    | ~7.5 KB | ~35 KB   |
| Full `<SvGrid>` render component                | ~42 KB  | ~189 KB  |

The full render component is the whole grid - virtualization, Excel-style
filters, inline editing, grouping, tree, master/detail, and accessibility -
in one import. For reference, the headless core is lighter than TanStack
Table's headless engine (~12-14 KB), and the render component is a fraction
of AG Grid Community (commonly cited around 340 KB minified). `sv-grid-pro`
features are separate subpath imports that lazy-load, so they add nothing to
your initial bundle until used.

## Migrating from AG Grid

The most common starting point. See
[Migrating from AG Grid](./migrating-from-ag-grid.md) for a
30-minute, side-by-side translation of column defs, features,
filtering, editing, and the imperative API.

## Migrating from TanStack Table

The map is one-to-one - SvGrid's headless core is API-compatible with
TanStack Table's React adapter in 90% of cases. The big differences:

- Replace `useReactTable(opts)` with `createSvGrid(opts)`. Identical
  state machine.
- Replace `getCoreRowModel()` calls with the same name from
  `sv-grid-community`.
- The render layer changes - TanStack hands you `flexRender` + the
  row model; SvGrid lets you keep that headless approach OR drop in
  the default `<SvGrid>` component.

## Pricing

SvGrid Community is MIT - free for commercial use, no attribution
required at runtime. SvGrid Pro is a paid license; see
<https://sv-grid.dev/pricing> for per-seat / per-app / multi-app tiers.

AG Grid Community is MIT. AG Grid Enterprise pricing is on
ag-grid.com; expect a per-developer annual license plus a separate
deployment license for production.

TanStack Table is MIT.

## See also

- [Why headless?](../why-headless.md) - the design decision behind
  SvGrid's two-layer architecture.
- [Migrating from AG Grid](./migrating-from-ag-grid.md) - the
  practical recipe.
- [Pro feature pack](../pro/README.md) - what SvGrid charges for.
- [Missing features](./missing-features.md) - the honest gap list
  versus AG Grid Enterprise.

## Frequently asked questions

### What is the best data grid for Svelte 5?

For a Svelte-5-native grid with a batteries-included render component, SvGrid is
purpose-built for runes and snippets. TanStack Table is a strong headless-only
choice if you want to build the DOM layer yourself across frameworks. AG Grid is
the most feature-complete but lives in React/Angular/Vue first and is heavy to
bridge into Svelte 5.

### Is SvGrid a good AG Grid alternative?

Yes, for Svelte projects. SvGrid ships a much smaller bundle (~42 KB gzipped
for the full render component, ~7.5 KB headless) than AG Grid Community, is
MIT-licensed for commercial use, and offers `sv-grid-pro` for
export/pivot/import at a per-developer price instead of AG Grid Enterprise's
per-deployment licensing. It does not yet match every AG Grid Enterprise
feature - see the missing-features list for the honest gaps.

### SvGrid vs TanStack Table - which should I pick?

Pick SvGrid if you want virtualization, Excel-style filters, selection, and
inline editing working out of the box on Svelte 5. Pick TanStack Table if you
want a framework-agnostic headless engine and are happy to build the rendering,
virtualization, and editing UI yourself. Both are MIT-licensed.

### How big is the SvGrid bundle?

Measured gzipped (Svelte excluded as a peer dependency): ~7.5 KB for the
headless core and ~42 KB for the full `<SvGrid>` render component (~189 KB
minified). Pro features are separate, lazy-loaded subpath imports, so you ship
only what you import.

<!-- =================================================================
     /help/conditional-form-schema  (community)
     ================================================================== -->

# Conditional form schema

A pattern for declarative field-visibility and editability rules
inside a grid. Instead of writing imperative `if`/`else` checks
across many `cell` callbacks and `editable` props, you declare a
**schema** of `when`-rules per field and the grid evaluates them per
row.

This is the data-entry pattern that procurement / KYC / onboarding
flows usually need: some fields apply only to certain record types,
others lock once the workflow moves past a state. SvGrid's `editable:
(ctx) => boolean` callback supports per-cell rules out of the box;
this recipe layers a small schema on top so the rules live next to
the data, not scattered through the column definitions.

<div data-docs-demo="82-conditional-form-schema" data-height="600"></div>

## The schema shape

A `Rule` is a predicate plus a human-readable reason. A
`FieldSchema` carries up to two rules per field - one for
**visibility** (the cell renders the value or `-`), one for
**editability** (the editor can open).

```ts
type Rule<T> = {
  when: (row: T) => boolean
  reason: string
}
type FieldSchema<T> = {
  visible?:  Rule<T>
  editable?: Rule<T>
}

const schema: Partial<Record<keyof Application, FieldSchema<Application>>> = {
  taxId: {
    visible: { when: (r) => r.recordType === 'business',
               reason: 'Tax ID only applies to businesses.' },
  },
  rejectionReason: {
    visible:  { when: (r) => r.status === 'rejected',
                reason: 'Reason only applies to rejected applications.' },
    editable: { when: (r) => r.status === 'rejected',
                reason: 'Only editable while status is rejected.' },
  },
  contactEmail: {
    editable: { when: (r) => r.status === 'draft' || r.status === 'pending',
                reason: 'Locked once the application is approved or rejected.' },
  },
}
```

Three helper functions translate the schema into runtime decisions:

```ts
function isVisible<T>(schema: Partial<Record<keyof T, FieldSchema<T>>>, field: keyof T, row: T): boolean {
  const s = schema[field]
  return !s?.visible || s.visible.when(row)
}
function isEditable<T>(schema: Partial<Record<keyof T, FieldSchema<T>>>, field: keyof T, row: T): boolean {
  const s = schema[field]
  if (!isVisible(schema, field, row)) return false
  return !s?.editable || s.editable.when(row)
}
function lockReason<T>(schema: Partial<Record<keyof T, FieldSchema<T>>>, field: keyof T, row: T): string | null {
  const s = schema[field]
  if (!s) return null
  if (s.visible  && !s.visible.when(row))  return s.visible.reason
  if (s.editable && !s.editable.when(row)) return s.editable.reason
  return null
}
```

You feed the editability decision into SvGrid's `editable` callback,
and the visibility decision into the cell's `cell` snippet.

## Complete drop-in example

A KYC application list with three record types (individual, business,
nonprofit) and a four-state workflow (draft → pending → approved /
rejected). Every column's visibility and editability comes from the
schema.

```svelte
<script lang="ts">
  import {
    SvGrid,
    tableFeatures,
    rowSortingFeature,
    renderSnippet,
    type ColumnDef,
    type CellContext,
  } from 'sv-grid-community'

  type RecordType = 'individual' | 'business' | 'nonprofit'
  type Status     = 'draft' | 'pending' | 'approved' | 'rejected'

  type Application = {
    id: string
    legalName: string
    recordType: RecordType
    status: Status
    taxId: string
    ein: string
    ssnLast4: string
    contactEmail: string
    rejectionReason: string
  }

  let rows = $state<Application[]>([
    { id: 'A001', legalName: 'Atlas Holdings LLC',  recordType: 'business',   status: 'pending',  taxId: '47-1234567', ein: '',           ssnLast4: '',     contactEmail: 'cfo@atlas.example',  rejectionReason: '' },
    { id: 'A002', legalName: 'Helios Foundation',   recordType: 'nonprofit',  status: 'approved', taxId: '',           ein: '88-7654321', ssnLast4: '',     contactEmail: 'admin@helios.org',   rejectionReason: '' },
    { id: 'A003', legalName: 'Sarah Chen',          recordType: 'individual', status: 'draft',    taxId: '',           ein: '',           ssnLast4: '4421', contactEmail: 'sarah.chen@x.com',    rejectionReason: '' },
    { id: 'A004', legalName: 'Vertex Capital',      recordType: 'business',   status: 'rejected', taxId: '94-9876543', ein: '',           ssnLast4: '',     contactEmail: 'ops@vertex.example', rejectionReason: 'Missing 2024 audit.' },
  ])

  // ---- The schema --------------------------------------------------------
  type Rule = { when: (r: Application) => boolean; reason: string }
  type FieldSchema = { visible?: Rule; editable?: Rule }

  const schema: Partial<Record<keyof Application, FieldSchema>> = {
    taxId:    { visible: { when: (r) => r.recordType === 'business',   reason: 'Tax ID only applies to businesses.' } },
    ein:      { visible: { when: (r) => r.recordType === 'nonprofit',  reason: 'EIN only applies to nonprofits.' } },
    ssnLast4: { visible: { when: (r) => r.recordType === 'individual', reason: 'SSN only applies to individuals.' } },
    rejectionReason: {
      visible:  { when: (r) => r.status === 'rejected', reason: 'Only applies to rejected applications.' },
      editable: { when: (r) => r.status === 'rejected', reason: 'Only editable while status is rejected.' },
    },
    legalName:    { editable: { when: (r) => r.status === 'draft' || r.status === 'pending', reason: 'Locked once approved or rejected.' } },
    contactEmail: { editable: { when: (r) => r.status === 'draft' || r.status === 'pending', reason: 'Locked once approved or rejected.' } },
    recordType:   { editable: { when: (r) => r.status === 'draft',  reason: 'Record type locks at submission.' } },
  }

  function isVisible(field: keyof Application, row: Application): boolean {
    const s = schema[field]
    return !s?.visible || s.visible.when(row)
  }
  function isEditable(field: keyof Application, row: Application): boolean {
    const s = schema[field]
    if (!isVisible(field, row)) return false
    return !s?.editable || s.editable.when(row)
  }
  function lockReason(field: keyof Application, row: Application): string | null {
    const s = schema[field]
    if (!s) return null
    if (s.visible  && !s.visible.when(row))  return s.visible.reason
    if (s.editable && !s.editable.when(row)) return s.editable.reason
    return null
  }

  // ---- Plug into ColumnDef -----------------------------------------------
  const features = tableFeatures({ rowSortingFeature })

  function ruleEditable<K extends keyof Application>(field: K) {
    return (ctx: CellContext<Application>) => isEditable(field, ctx.row.original)
  }

  function condColumn<K extends keyof Application>(
    field: K,
    header: string,
    editorType: ColumnDef<typeof features, Application>['editorType'],
    extra: Partial<ColumnDef<typeof features, Application>> = {},
  ): ColumnDef<typeof features, Application> {
    return {
      field,
      header,
      editorType,
      editable: ruleEditable(field),
      cell: (ctx) => renderSnippet(Cell, { row: ctx.row.original, field }),
      ...extra,
    } as ColumnDef<typeof features, Application>
  }

  const columns: ColumnDef<typeof features, Application>[] = [
    { field: 'id',         header: 'ID',         editorType: 'text', width: 80, editable: false },
    condColumn('legalName',  'Legal name', 'text', { width: 200 }),
    {
      field: 'recordType', header: 'Type',
      editorType: 'list',
      editorOptions: ['individual', 'business', 'nonprofit'] as unknown as ReadonlyArray<string>,
      editable: ruleEditable('recordType'),
      width: 130,
    },
    {
      field: 'status', header: 'Status',
      editorType: 'list',
      editorOptions: ['draft', 'pending', 'approved', 'rejected'] as unknown as ReadonlyArray<string>,
      width: 130,
    },
    condColumn('taxId',           'Tax ID',         'text', { width: 130 }),
    condColumn('ein',             'EIN',            'text', { width: 130 }),
    condColumn('ssnLast4',        'SSN (last 4)',   'text', { width: 110 }),
    condColumn('contactEmail',    'Email',          'text', { width: 200 }),
    condColumn('rejectionReason', 'Reject reason',  'text', { width: 280 }),
  ]
</script>

{#snippet Cell(props: { row: Application; field: keyof Application })}
  {@const visible  = isVisible(props.field, props.row)}
  {@const editable = isEditable(props.field, props.row)}
  {@const reason   = lockReason(props.field, props.row)}
  <span
    title={reason ?? ''}
    style="display: inline-flex; gap: 6px; align-items: center;
           font-style: {visible ? 'normal' : 'italic'};
           color: {visible ? (editable ? 'inherit' : '#64748b') : '#94a3b8'};"
  >
    {visible ? String(props.row[props.field] ?? '') : '-'}
    {#if visible && !editable}
      <span aria-hidden="true">🔒</span>
    {/if}
  </span>
{/snippet}

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  enableInlineEditing={true}
  enableCellSelection={true}
  rowHeight={44}
  containerHeight="100%"
/>
```

## What happens at runtime

Try editing each row in the demo above:

- **A003 (Sarah Chen, draft):** SSN field renders `4421`. EIN and Tax ID
  show `-`. Changing `recordType` to `business` causes Tax ID to start
  rendering and SSN to switch to `-`.
- **A001 (Atlas Holdings, pending):** Tax ID is editable. Setting
  `status` to `approved` locks the email and legal name fields with
  the 🔒 indicator.
- **A004 (Vertex Capital, rejected):** Rejection reason is visible and
  editable. Setting `status` back to `pending` blanks the reason
  visually (still in the data, just hidden).

## Composing more rules

Stack rules per field by AND-ing inside a single `when`:

```ts
{
  field: 'managerApprovalNote',
  editable: {
    when: (r) => r.status === 'pending' && r.amount > 10_000,
    reason: 'Required only when status is pending AND amount > $10,000.',
  },
}
```

For OR semantics, write it directly:

```ts
{
  field: 'taxId',
  visible: {
    when: (r) => r.recordType === 'business' || r.recordType === 'nonprofit',
    reason: 'Tax ID applies to business and nonprofit records.',
  },
}
```

## Patterns that pair well

- **PII masking** - combine schema with `currentUser.role` checks
  (see [Demo 35 - Permissions, audit & history](../../examples/src/demos/35-permissions-audit.svelte))
- **Validation while editing** - schema gates *which* fields can be
  edited; validation gates *which values* commit. See
  [Validation](./editing/validation.md).
- **Mobile card view** - the same schema works inside the card-mode
  edit panel; just import the helpers and skip rendering hidden fields.

## See also

- [Demo 82 - Conditional form schema](../../examples/src/demos/82-conditional-form-schema.svelte) - full enterprise example
- [Edit components](./editing/edit-components.md)
- [Validation](./editing/validation.md)
- [Permissions audit](../../examples/src/demos/35-permissions-audit.svelte) - role-based version of the same pattern

<!-- =================================================================
     /help/editing/edit-components  (community)
     ================================================================== -->

# Edit components

The grid ships with five inline editors. Each is selected by the column's
`editorType`:
<div data-docs-demo="66-custom-cell-editors" data-height="540"></div>

| `editorType` | DOM element | Notes |
| ------------ | ----------- | ----- |
| `'text'`     | `<input type="text">`     | default |
| `'number'`   | `<input type="number">`   | parsed with `parseEditorValue('number', ...)` |
| `'date'`     | `<input type="date">`     | round-trips to ISO `YYYY-MM-DD` |
| `'datetime'` | `<input type="datetime-local">` | round-trips to ISO 8601 |
| `'checkbox'` | `<input type="checkbox">` | toggled on `Enter` / `Space` |

The editor renders **inside the cell** - same width, same row height,
zero border. See [Styling cells → edit-mode cell](../cells/styling-cells.md#edit-mode-cell).

## Custom editor

There is no `cellEditor` field on `ColumnDef` today and no way to plug in
a third-party component as the inline editor. To approximate one:

1. Render the column read-only with a custom `cell` callback.
2. Open your own popover on click / `F2`.
3. Write back through `api.setCellValue(rowIndex, columnId, value)`.

```svelte
{#snippet StatusCell(p: { row: Person })}
  <button type="button" onclick={() => openStatusEditor(p.row)}>
    {p.row.status}
  </button>
{/snippet}
```

A first-class `cellEditor` plug-in slot is on the
[gap list](../missing-features.md).

## Conditional editability

There is no `editable: (row) => boolean` callback. Closest approximation:
swap the column between an editable and a read-only version by reassigning
`columns`.

## See also

- [Provided editors](./provided-editors.md)
- [Cell components](../cells/cell-components.md)
- [Custom column filters](../filtering/custom-column-filters.md) - same shape, filter side.

<!-- =================================================================
     /help/editing/full-row  (community)
     ================================================================== -->

# Full-row editing

"Full-row editing" means the user opens an entire row for edit (every
editable cell becomes an editor simultaneously) and commits all changes
at once.
<div data-docs-demo="40-forms-master-detail" data-height="540"></div>

## Status

This is **not** built in. SvGrid edits one cell at a time.

## Workaround - overlay form

Trigger an edit form from a row action and write changes back via
`api.setCellValue` for each field:

```svelte
<script lang="ts">
  let editing = $state<Person | null>(null)

  function commit(updated: Person) {
    if (!api || !editing) return
    const idx = api.getData().findIndex((r) => r.id === editing!.id)
    if (idx === -1) return
    for (const key of Object.keys(updated) as Array<keyof Person>) {
      api.setCellValue(idx, key, updated[key])
    }
    editing = null
  }
</script>

{#if editing}
  <dialog open>
    <!-- a regular form bound to a copy of `editing` -->
  </dialog>
{/if}

<SvGrid {data} {columns} features={features}
  enableInlineEditing={false}
  onApiReady={(next) => (api = next)} />
```

This is often *better UX* than full-row editing for keyboard-heavy users -
the form can have proper field labels and a save button.

## Tracked at

[Missing features](../missing-features.md) - full-row editing as a built-
in mode.

## See also

- [Provided editors](./provided-editors.md)
- [Saving values](./saving-values.md)

<!-- =================================================================
     /help/editing/overview  (community)
     ================================================================== -->

# Editing - overview

Inline editing is a single prop on `<SvGrid>`. Try it - double-click
any cell, type to replace, hit `Enter` to commit. Tab moves to the
next editable cell:

<div data-docs-demo="05-inline-editing" data-height="440"></div>



```svelte
<SvGrid {data} {columns} features={features} enableInlineEditing={true} />
```

To make a specific column editable, give it an `editorType`:

```ts
const columns: ColumnDef<typeof features, Person>[] = [
  { field: 'firstName',  header: 'First',  editorType: 'text' },
  { field: 'age',        header: 'Age',    editorType: 'number' },
  { field: 'joinedAt',   header: 'Joined', editorType: 'date' },
  { field: 'active',     header: 'Active', editorType: 'checkbox' },
]
```

A column with no `editorType` is **read-only** even when
`enableInlineEditing={true}`.

## How a user edits

| Action | Keys | Outcome |
| ------ | ---- | ------- |
| Enter edit mode | `Enter` / `F2` / double-click | Editor opens on the active cell |
| Commit | `Enter` / `Tab` | Saves the new value |
| Cancel | `Esc` | Discards |
| Move to next field while editing | `Tab` / `Shift+Tab` | Commits and re-enters edit on the neighbour |

## What gets saved

When the user commits, the grid:

1. Parses the editor's string value through `parseEditorValue` for the
   column's `editorType`.
2. Writes the parsed value into the grid's internal data copy.
3. Fires `onCellValueChange` with `{ rowIndex, columnId, oldValue, newValue, row }`.
4. Fires a re-render.

To round-trip edits to your source, attach a callback:

```svelte
<SvGrid
  {data} {columns} features={features}
  enableInlineEditing={true}
  onCellValueChange={(e) => savePersonField(e.row.id, e.columnId, e.newValue)}
/>
```

See [Saving values](./saving-values.md) for the full patterns
(per-edit, batch-from-snapshot, cascade recompute).

## See also

- [Start / stop editing](./start-stop-editing.md)
- [Parsing values](./parsing-values.md)
- [Saving values](./saving-values.md)
- [Provided editors](./provided-editors.md)
- [Validation](./validation.md)

## Frequently asked questions

### How do I enable inline editing in SvGrid?

Set the inline-editing prop on `<SvGrid>` and give editable columns an
`editorType`. Then double-click a cell (or press F2), type to replace, and press
Enter to commit; Tab moves to the next editable cell.

### What cell editors does SvGrid provide?

Built-in editors for text, number, checkbox, date, select, rich-select, and
textarea, chosen per column via `editorType`. You can also supply a custom
editor through the `cellEditor` slot.

### Does SvGrid mutate my data array when editing?

No. Commits are written to the grid's internal working copy, not the array you
passed in, so cancel/undo is possible. Subscribe to `onCellValueChange` to
persist edits to your own state or backend.

<!-- =================================================================
     /help/editing/parsing-values  (community)
     ================================================================== -->

# Parsing values

When the user commits an edit, the editor's DOM value (a string for text /
number / date inputs, a boolean for checkboxes) is parsed by
`parseEditorValue` into the canonical value for the column's type.
<div data-docs-demo="24-validation" data-height="540"></div>

```ts
import { parseEditorValue } from 'sv-grid-community'

parseEditorValue('text',     'Ada')          // 'Ada'
parseEditorValue('number',   '42')           // 42
parseEditorValue('number',   '4.5')          // 4.5
parseEditorValue('number',   'NaN')          // null   (rejected - caller decides)
parseEditorValue('number',   '')             // null
parseEditorValue('date',     '2026-05-27')   // '2026-05-27T00:00:00.000Z'
parseEditorValue('datetime', '2026-05-27T14:32') // '2026-05-27T14:32:00.000Z'
parseEditorValue('checkbox', 'true')         // true
parseEditorValue('checkbox', true)           // true
```

The full source is short and worth reading: [`cell-editors.ts`](../../../packages/sv-grid-community/src/editors/cell-editors.ts).

## What "null" means

`parseEditorValue` returns `null` to signal "could not parse". The grid
treats `null` as an empty value and writes it into the cell. If you want
**invalid input rejected** (the value reverts to its pre-edit state),
intercept before the write - see [Validation](./validation.md).

## Custom parsing

There is no per-column `valueParser` field on `ColumnDef` today. If you
need custom parsing (e.g. accept "$42,500" and turn it into `42500`), you
have two paths:

1. Post-process inside `cell` and store the raw display string.
2. Diff `api.getData()` against your own snapshot after each commit and
   normalise values you want canonicalised.

A per-column `valueParser` is on the
[gap list](../missing-features.md).

## See also

- [Saving values](./saving-values.md)
- [Validation](./validation.md)

<!-- =================================================================
     /help/editing/provided-editors  (community)
     ================================================================== -->

# Provided cell editors

The grid ships nine built-in editors, selected via `editorType` on the
column definition. Each editor renders inside the cell while editing
and falls back to the default text render (or your `cell` snippet) when
the cell is read-only.
<div data-docs-demo="26-list-chips-editors" data-height="540"></div>

| `editorType`  | Renders                              | Stored value            |
|---------------|--------------------------------------|-------------------------|
| `'text'`      | `<input type="text">`                | `string`                |
| `'number'`    | `<input type="number">`              | `number \| null`        |
| `'date'`      | `<input type="date">`                | ISO `YYYY-MM-DD` string |
| `'datetime'`  | `<input type="datetime-local">`      | ISO 8601 string         |
| `'checkbox'`  | Themed checkbox button               | `boolean`               |
| `'list'`      | Custom dropdown (single / multi)     | scalar or array         |
| `'chips'`     | Removable tag picker                 | array of values         |
| `'color'`     | Native OS color picker               | `#rrggbb` string        |
| `'rating'`    | 5-star clickable widget              | `number` 0-5            |

## Text editor - `editorType: 'text'`

`<input type="text">`. Accepts any string. On commit the raw value is
stored.

```ts
{ field: 'firstName', header: 'First name', editorType: 'text' }
```

## Number editor - `editorType: 'number'`

`<input type="number">` with browser-native increment buttons.
Non-numeric input is rejected at commit (`parseEditorValue` returns
`null` and the cell stays at its previous value).

```ts
{ field: 'age', header: 'Age', editorType: 'number' }

// often paired with a display format:
{
  field: 'salary', header: 'Salary',
  editorType: 'number',
  format: { type: 'currency', currency: 'USD', options: { maximumFractionDigits: 0 } },
}
```

## Date editor - `editorType: 'date'`

`<input type="date">`. The value is stored as ISO `YYYY-MM-DD`.

```ts
{
  field: 'joinedAt', header: 'Joined',
  editorType: 'date',
  format: { type: 'date', pattern: 'y-m-d' },
}
```

## Datetime editor - `editorType: 'datetime'`

`<input type="datetime-local">`. The value is stored as ISO 8601 with a Z
suffix.

```ts
{
  field: 'updatedAt', header: 'Updated',
  editorType: 'datetime',
  format: { type: 'datetime', pattern: 'medium' },
}
```

## Checkbox editor - `editorType: 'checkbox'`

A themed button that toggles between `true` and `false`. Renders centred
in the cell.

```ts
{ field: 'active', header: 'Active', editorType: 'checkbox' }
```

## List editor - `editorType: 'list'`

Single-select dropdown. Accepts an array of strings/numbers or
`{ value, label, color }` objects. Set `editorMultiple: true` for a
multi-select.

```ts
{
  field: 'priority', header: 'Priority',
  editorType: 'list',
  editorOptions: ['low', 'med', 'high', 'urgent'],
}

// labelled options:
{
  field: 'status', header: 'Status',
  editorType: 'list',
  editorOptions: [
    { value: 'open',        label: 'Open' },
    { value: 'in_progress', label: 'In progress' },
    { value: 'done',        label: 'Done' },
  ],
}
```

## Chips editor - `editorType: 'chips'`

Removable-token picker for multi-select. The value is always an array.

```ts
{
  field: 'tags', header: 'Tags',
  editorType: 'chips',
  editorOptions: ['frontend', 'backend', 'design', 'infra', 'docs'],
}
```

## Color editor - `editorType: 'color'`

Native HTML color picker. The cell stores a `#rrggbb` string. Clicking
the cell opens the OS color overlay; the value commits as soon as the
overlay closes (no need to blur the cell first).

```ts
{ field: 'brandColor', header: 'Brand', editorType: 'color' }
```

### Complete example

A minimal grid where each row has its own swatch. The custom `cell`
snippet shows the colour next to the hex value while not editing; the
editor takes over on double-click.

```svelte
<script lang="ts">
  import {
    SvGrid,
    tableFeatures,
    rowSortingFeature,
    renderSnippet,
    type ColumnDef,
  } from 'sv-grid-community'

  type Brand = { id: string; name: string; color: string }

  let rows = $state<Brand[]>([
    { id: 'b1', name: 'Acme',     color: '#6366f1' },
    { id: 'b2', name: 'Helios',   color: '#10b981' },
    { id: 'b3', name: 'Crescent', color: '#f59e0b' },
  ])

  const features = tableFeatures({ rowSortingFeature })

  const columns: ColumnDef<typeof features, Brand>[] = [
    { field: 'name',  header: 'Brand', editorType: 'text',  width: 200 },
    {
      field: 'color', header: 'Color',
      editorType: 'color',
      width: 180,
      cell: (ctx) => renderSnippet(Swatch, { row: ctx.row.original }),
    },
  ]
</script>

{#snippet Swatch(props: { row: Brand })}
  <span style="display: inline-flex; align-items: center; gap: 8px;">
    <span style="width: 18px; height: 18px; border-radius: 4px; background: {props.row.color}; box-shadow: inset 0 0 0 1px rgba(0,0,0,0.18);"></span>
    <code style="font-family: ui-monospace, Menlo, monospace; font-size: 11.5px;">{props.row.color}</code>
  </span>
{/snippet}

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  enableInlineEditing={true}
  enableCellSelection={true}
  containerHeight="100%"
/>
```

### Theme tokens

The color editor inherits the grid's editor chrome. There are no
extra tokens; the swatch fills the cell so the clickable area is the
whole cell, not the OS default 25 × 13 swatch.

## Rating editor - `editorType: 'rating'`

A row of 5 clickable stars plus a clear button. The cell stores an
integer 0-5. Clicking a star commits immediately - no blur required.

```ts
{ field: 'csat', header: 'CSAT', editorType: 'rating' }
```

### Complete example

```svelte
<script lang="ts">
  import {
    SvGrid,
    tableFeatures,
    rowSortingFeature,
    renderSnippet,
    type ColumnDef,
  } from 'sv-grid-community'

  type Review = { id: string; product: string; rating: number }

  let rows = $state<Review[]>([
    { id: 'r1', product: 'Aurora keyboard',  rating: 5 },
    { id: 'r2', product: 'Helios monitor',   rating: 4 },
    { id: 'r3', product: 'Crescent mouse',   rating: 2 },
  ])

  const features = tableFeatures({ rowSortingFeature })

  const columns: ColumnDef<typeof features, Review>[] = [
    { field: 'product', header: 'Product', editorType: 'text', width: 220 },
    {
      field: 'rating', header: 'Rating',
      editorType: 'rating',
      width: 160,
      cell: (ctx) => renderSnippet(Stars, { row: ctx.row.original }),
    },
  ]
</script>

{#snippet Stars(props: { row: Review })}
  <span aria-label={`${props.row.rating} of 5`}>
    {#each [1, 2, 3, 4, 5] as n (n)}
      <span style="color: {props.row.rating >= n ? '#f59e0b' : '#cbd5e1'}; font-size: 16px;">★</span>
    {/each}
  </span>
{/snippet}

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  enableInlineEditing={true}
  enableCellSelection={true}
  containerHeight="100%"
/>
```

### Theme tokens

The rating editor reads three optional CSS custom properties so the
star colors can match your design system:

| Token                   | Default     | Used for             |
|-------------------------|-------------|----------------------|
| `--sg-rating-empty`     | `#cbd5e1`   | Unselected stars     |
| `--sg-rating-on`        | `#f59e0b`   | Selected stars       |
| `--sg-rating-hover`     | `#fbbf24`   | Hover preview        |

Override per theme:

```css
[data-theme='dark'] {
  --sg-rating-empty: #475569;
  --sg-rating-on:    #fbbf24;
}
```

## Disabling an editor on a per-cell basis

`editable` accepts a callback. Return `false` to lock the cell - the
editor never opens, even if you double-click. This composes with all
the editor types above.

```ts
{
  field: 'salary', header: 'Salary',
  editorType: 'number',
  // Only admins can edit salaries.
  editable: (ctx) => currentUser.role === 'admin',
}
```

For declarative `when`-style rules across many columns, see the
[Conditional form schema](../recipes.md#conditional-form-schema)
recipe.

## See also

- [Cell data types](../cells/cell-data-types.md)
- [Parsing values](./parsing-values.md)
- [Validation](./validation.md)
- [Demo 80 - Cell types showcase](../../examples/src/demos/80-cell-types-showcase.svelte) - every editor in one enterprise grid
- [Demo 66 - Custom cell editors](../../examples/src/demos/66-custom-cell-editors.svelte) - feature-health board using color, rating, and mood

<!-- =================================================================
     /help/editing/saving-values  (community)
     ================================================================== -->

# Saving values

When the user commits an edit, the new value is written into the grid's
**internal data copy**. The grid does **not** mutate the array you passed
in via the `data` prop - it keeps its own working copy so an undo / cancel
is possible without touching your state.

To round-trip edits back to your source there are two patterns.

Live demo - typed editors, dirty tracking, save button:

<div data-docs-demo="05-inline-editing" data-height="500"></div>

## Pattern A - `onCellValueChange` (recommended)

The wrapper fires `onCellValueChange` whenever an inline edit commits.
The payload contains everything you need to forward the edit to a server,
update a cached aggregate, or push to an undo stack:

```svelte
<script lang="ts">
  type Event = {
    rowIndex: number
    columnId: string
    oldValue: unknown
    newValue: unknown
    row: Person
  }

  function onCellValueChange(event: Event) {
    // 1. ship the change
    savePersonField(event.row.id, event.columnId, event.newValue)
    // 2. update derived data (totals, dependencies, etc.)
    // see the cascade-editing demo for the full pattern
  }
</script>

<SvGrid
  {data}
  {columns}
  features={features}
  enableInlineEditing={true}
  onCellValueChange={onCellValueChange}
/>
```

The wrapper has already written the parsed value into the row by the
time the callback fires, so `event.row` reflects the post-edit state.
The [`18-cascade-editing` demo](../../../examples/src/demos/18-cascade-editing.svelte) wires this
into a recompute pipeline.

## Pattern B - read a snapshot from the API

Useful for batch saves, "click Save to commit" UIs, or diffing against a
before-snapshot:

```svelte
<script lang="ts">
  let api = $state<SvGridApi<typeof features, Person> | null>(null)

  function captureChanges() {
    if (!api) return
    const after = api.getData()
    // diff against your before-snapshot, send to server, etc.
  }
</script>

<SvGrid {data} {columns} features={features}
  enableInlineEditing
  onApiReady={(next) => (api = next)} />

<button onclick={captureChanges}>Save</button>
```

The [`05-inline-editing` demo](../../../examples/src/demos/05-inline-editing.svelte) shows
this pattern with dirty-cell tracking against an `initial` snapshot.

## Sync data both ways

Replacing the `data` prop forces the grid to re-read it. To mirror the
grid's internal copy back into a parent `$state` so other UI can react,
use `onCellValueChange`:

```svelte
<script lang="ts">
  let rows = $state<Person[]>([...])
  function onCellValueChange(e: { rowIndex: number; row: Person }) {
    rows = rows.map((r, i) => (i === e.rowIndex ? e.row : r))
  }
</script>

<SvGrid data={rows} {columns} features={features}
  enableInlineEditing
  onCellValueChange={onCellValueChange} />
```

## See also

- [Parsing values](./parsing-values.md)
- [Validation](./validation.md)
- [Undo / redo](./undo-redo.md)

<!-- =================================================================
     /help/editing/start-stop-editing  (community)
     ================================================================== -->

# Start / stop editing

## Start
<div data-docs-demo="05-inline-editing" data-height="540"></div>

| Trigger | Behaviour |
| ------- | --------- |
| Double-click a cell | Opens the editor with all text selected. |
| `Enter` on a focused cell | Same as double-click. |
| `F2` on a focused cell | Opens the editor with the caret at the end (no text selection). |
| Typing a character | Opens the editor and replaces the value with the typed character. |

The cell must be **focused** (the grid's active cell). Click any cell or
use the arrow keys to set focus.

The cell must also be **editable** - its column must have an
`editorType`, and the grid must have `enableInlineEditing={true}`.

## Stop

| Trigger | Outcome |
| ------- | ------- |
| `Enter` | Commit. Move focus down one row. |
| `Tab` | Commit. Move focus to the next editable cell in the same row. |
| `Shift+Tab` | Commit. Move focus to the previous editable cell. |
| `Esc` | Cancel. Revert to the pre-edit value. |
| Click outside the cell | Commit. |

## Programmatic start/stop

There is no public `api.startEditing(rowIndex, columnId)` or `stopEditing()`
on `SvGridApi` today. To force-edit a cell from outside, set the active
cell (also not yet exposed on the public API) and dispatch a synthetic
`F2` to the grid's root.

This is on the [gap list](../missing-features.md).

## See also

- [Validation](./validation.md)
- [Provided editors](./provided-editors.md)

<!-- =================================================================
     /help/editing/undo-redo  (community)
     ================================================================== -->

# Undo / redo

There is **no built-in undo/redo stack** inside `<SvGrid>`. The grid emits
no per-edit event for an external stack to subscribe to, so undo/redo has
to be built on top of the data-snapshot approach.
<div data-docs-demo="55-state-maintenance" data-height="540"></div>

## Pattern - snapshot stack

```svelte
<script lang="ts">
  type Snapshot = Person[]

  let rows = $state<Person[]>(initial)
  let past = $state<Snapshot[]>([])
  let future = $state<Snapshot[]>([])
  const LIMIT = 50

  // Whenever rows change because of an edit, push the previous state onto `past`.
  let last = JSON.stringify(rows)
  $effect(() => {
    const next = JSON.stringify(rows)
    if (next === last) return
    past = [...past.slice(-LIMIT), JSON.parse(last)]
    future = []
    last = next
  })

  function undo() {
    const prev = past.at(-1)
    if (!prev) return
    future = [rows.map((r) => ({ ...r })), ...future].slice(0, LIMIT)
    rows = prev.map((r) => ({ ...r }))
    past = past.slice(0, -1)
    last = JSON.stringify(rows)
  }

  function redo() {
    const next = future[0]
    if (!next) return
    past = [...past, rows.map((r) => ({ ...r }))].slice(-LIMIT)
    rows = next.map((r) => ({ ...r }))
    future = future.slice(1)
    last = JSON.stringify(rows)
  }
</script>

<svelte:window onkeydown={(e) => {
  const meta = e.ctrlKey || e.metaKey
  if (meta && e.key === 'z' && !e.shiftKey) { e.preventDefault(); undo() }
  if (meta && ((e.key === 'z' && e.shiftKey) || e.key === 'y')) { e.preventDefault(); redo() }
}} />

<SvGrid data={rows} {columns} features={features} enableInlineEditing />
```

## Why JSON snapshots

Without a per-edit event from the grid, the safest store of "previous
state" is a deep copy of the row array. For a 5,000-row grid the snapshot
is a few hundred KB - fine. For a 100,000-row grid, switch to a row-diff
stack:

```ts
type Diff = { rowId: string; column: string; before: unknown; after: unknown }
```

…and apply it during undo/redo. The per-edit event needed to compute that
cleanly is on the [gap list](../missing-features.md).

## Tracked at

[Missing features](../missing-features.md) - first-class undo stack with
`onCellValueChange` to drive it.

## See also

- [Saving values](./saving-values.md)
- [demos/05-inline-editing.svelte](../../../examples/src/demos/05-inline-editing.svelte)

<!-- =================================================================
     /help/editing/validation  (community)
     ================================================================== -->

# Validation

There is no `validate(value)` callback on `ColumnDef` today. Validation
happens by intercepting committed edits and either accepting or reverting
them.

Live demo - per-column rules with rollback + a recent-rejections panel:

<div data-docs-demo="24-validation" data-height="500"></div>

## Built-in soft validation

`parseEditorValue` already does light validation:

- `number`: rejects non-finite results → returns `null`
- `date` / `datetime`: rejects unparseable strings → returns `null`

The grid writes `null` into the cell when this happens. That is "soft"
validation - the user sees the cell go blank rather than seeing their
input rejected with an explanation.

## Hard validation (reject + revert)

To bounce the user back to the previous value with an explanation,
maintain your own snapshot and revert after the commit:

```svelte
<script lang="ts">
  let api: SvGridApi<typeof features, Person> | null = $state(null)
  let initial = $state<Person[]>([])
  let error = $state<{ row: number; col: string; msg: string } | null>(null)

  function validateRow(row: Person): string | null {
    if (row.age < 0 || row.age > 130) return 'Age must be between 0 and 130.'
    if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(row.email)) return 'Invalid email.'
    return null
  }

  $effect(() => {
    if (!api) return
    const snap = api.getData()
    for (let i = 0; i < snap.length; i++) {
      const msg = validateRow(snap[i]!)
      if (msg) {
        // revert by writing back the original
        const original = initial[i]
        if (original) {
          for (const key of Object.keys(original) as Array<keyof Person>) {
            if ((snap[i] as any)[key] !== (original as any)[key]) {
              api!.setCellValue(i, key as string, (original as any)[key])
            }
          }
        }
        error = { row: i, col: '*', msg }
        return
      }
    }
    error = null
    initial = snap.map((r) => ({ ...r }))
  })
</script>

{#if error}
  <p class="text-rose-600">Row {error.row + 1}: {error.msg}</p>
{/if}

<SvGrid {data} {columns} features={features} enableInlineEditing
  onApiReady={(next) => (api = next)} />
```

This polling-based validator works but has obvious limits:

- The validator runs on every reactive tick, not strictly on commit.
- The user briefly sees the invalid value before it reverts.

A per-column `validate(value, row, column)` returning `string | true` is
on the [gap list](../missing-features.md).

## Inline error UI

Render an asterisk / red border via a custom cell renderer that reads
your validation state map. See [Highlighting changes](../cells/highlighting-changes.md)
for the same pattern with a "dirty" indicator - substitute "invalid" for
"dirty".

## See also

- [Parsing values](./parsing-values.md)
- [Saving values](./saving-values.md)
- [demos/05-inline-editing.svelte](../../../examples/src/demos/05-inline-editing.svelte)

<!-- =================================================================
     /help/errors  (community)
     ================================================================== -->

# Error reference

Every `Error` thrown by `sv-grid-community` or `sv-grid-pro` with the
exact message text, the trigger condition, and the fix. If a runtime
message you see isn't on this list, it's coming from your own code or
a peer dependency.

## How to read this page

Each entry has four pieces:

1. **Message** - the exact text after `Error:`. Searchable.
2. **Class / type** - the thrown object's `.name`.
3. **When** - what action triggered it.
4. **Fix** - the smallest change that resolves it.

Error classes are part of the [API stability](./api-stability.md)
contract: the `.name` and message structure are Stable; we may reword
the trailing detail at the patch level if the diagnostic improves.

## sv-grid-community

### `Error: SvGrid: cannot mount inside a non-element parent`

- **Class:** `Error`
- **When:** You passed something other than an `Element` to
  `mount(SvGrid, { target })`. Common cause: passing a Svelte
  component reference instead of a DOM node.
- **Fix:** Use `bind:this={el}` on a real `<div>` and pass `el` as the
  target.

### `Error: Column "<id>" has no field, accessorFn, or cell renderer`

- **Class:** `Error`
- **When:** A `ColumnDef` was registered with neither a `field`, an
  `accessorFn`, nor a `cell` template. The grid has no way to produce
  a value for that column.
- **Fix:** Add one of the three. For computed display-only columns,
  `accessorFn: (row) => /* ... */` is usually right.

### `Error: Duplicate column id "<id>"`

- **Class:** `Error`
- **When:** Two `ColumnDef` entries resolve to the same id - either
  because they share a `field` and neither has an explicit `id`, or
  because their explicit `id` collides.
- **Fix:** Give each column an explicit unique `id`.

### `Error: Sort comparator failed: <reason>`

- **Class:** `Error`
- **When:** A custom `sortingFn` returned `NaN` or threw.
- **Fix:** Make the comparator total (always returns a number) and
  null-safe.

### `RuneError: state_referenced_locally`

- **Class:** Svelte runtime
- **When:** Initialising one `$state` from another `$state` in the
  same script - not specifically a SvGrid error, but the most common
  one users hit when seeding the grid's data.
- **Fix:** Add `// svelte-ignore state_referenced_locally` above the
  line, or restructure so the initial value isn't read from another
  `$state`.

### `each_key_duplicate`

- **Class:** Svelte runtime
- **When:** Two `ColumnDef` entries share the same key in the grid's
  internal keyed-`{#each}` over columns. Most often when you have two
  columns both pointing at the same `field` (e.g. one computed
  "Total" column that uses `field: 'qty'` to satisfy the type but
  duplicates an existing data column).
- **Fix:** Give the computed column an explicit `id` and drop its
  `field`.

## sv-grid-pro - License

### `Error: sv-grid-pro: setLicenseKey() requires a non-empty string`

- **Class:** `Error`
- **When:** `setLicenseKey('')` or `setLicenseKey(null)`.
- **Fix:** Pass a valid `SVPRO-...` string.

### `Error: sv-grid-pro: invalid license key format (expected "SVPRO-..." prefix).`

- **Class:** `Error`
- **When:** A key that doesn't start with `SVPRO-` was set; the first
  Pro call throws.
- **Fix:** Use the key issued by jQWidgets. The free Community grid is
  the right choice if you don't have a key.

### `Error: sv-grid-pro: this license key has been revoked. Contact sales@jqwidgets.com for a replacement.`

- **Class:** `Error`
- **When:** A key matching an entry in the package's revoked-keys list.
- **Fix:** Contact `sales@jqwidgets.com` for a replacement.

## sv-grid-pro - Export

### `Error: sv-grid-pro: export requires a browser environment`

- **Class:** `Error`
- **When:** `exportGrid` / `api.exportData` was called during SSR.
- **Fix:** Guard with `if (typeof window === 'undefined') return` or
  defer to `onMount`.

### `Error: sv-grid-pro: failed to load Smart.Utilities.DataExporter`

- **Class:** `Error`
- **When:** The Smart exporter shim couldn't initialise. Usually a
  bundler config issue blocking dynamic `import()` of a vendored
  asset.
- **Fix:** Confirm the package is installed cleanly and your bundler
  permits dynamic imports.

### `Error: sv-grid-pro: xlsx export requires the "jszip" peer dependency. Install it with: pnpm add jszip`

- **Class:** `Error`
- **When:** First xlsx export when `jszip` isn't installed.
- **Fix:** `pnpm add jszip` (or `npm` / `yarn`).

### `Error: sv-grid-pro: pdf export requires the "pdfmake" peer dependency. Install it with: pnpm add pdfmake`

- **Class:** `Error`
- **When:** First pdf export when `pdfmake` isn't installed.
- **Fix:** `pnpm add pdfmake`.

## sv-grid-pro - Import

### `Error: sv-grid-pro: importData requires a browser environment`

- **Class:** `Error`
- **When:** `importData` was called during SSR.
- **Fix:** Guard with `if (typeof window === 'undefined') return`.

### `Error: sv-grid-pro: xlsx import requires the "jszip" peer dependency. Install it with: pnpm add jszip`

- **Class:** `Error`
- **When:** First xlsx import when `jszip` isn't installed.
- **Fix:** `pnpm add jszip`.

### `Error: sv-grid-pro: xlsx import expects a File or Blob, not a string. Use format: "csv" or "tsv" for inline text.`

- **Class:** `Error`
- **When:** Passing a string with `format: 'xlsx'`.
- **Fix:** Either give the helper a `File` / `Blob` of the xlsx data
  or switch the format to `csv` / `tsv` for inline text.

### `Error: sv-grid-pro: could not locate sheet1.xml in the .xlsx archive`

- **Class:** `Error`
- **When:** The uploaded `.xlsx` is malformed or non-standard (e.g. a
  workbook saved by an exotic tool that places the first sheet
  somewhere other than `xl/worksheets/sheet1.xml`).
- **Fix:** Open the file in Excel or LibreOffice and re-save. If the
  file is correct and the grid still fails, please file an issue with
  a redacted sample.

### `Error: sv-grid-pro: JSON import expects a top-level array`

- **Class:** `Error`
- **When:** The JSON parses to an object (or any non-array) instead of
  an array of records.
- **Fix:** Wrap the data in `[]` or write a wrapper that extracts the
  array from the response.

## sv-grid-pro - AI

### `NoProviderError: sv-grid-pro/ai: no AI provider registered. Call setAIProvider(fn) with an adapter that talks to OpenAI / Anthropic / your proxy.`

- **Class:** `NoProviderError` (extends `Error`)
- **When:** Any `api.ai.*` call before `setAIProvider(fn)` ran.
- **Fix:** Wire your adapter at app boot. For demos, use
  `setAIProvider(mockAIProvider)`.

### `BadJsonError: sv-grid-pro/ai: provider returned non-JSON for a json-format request. First 200 chars: <prefix>`

- **Class:** `BadJsonError` (extends `Error`)
- **When:** A helper asked the provider for JSON and got prose back.
  The first 200 characters of the response are included so you can
  see what the model actually returned.
- **Fix:** Make sure your provider passes `responseFormat: 'json'` to
  the model, or instruct the model in your system prompt to return
  JSON only. The package strips a single markdown code fence
  automatically before parsing; multiple fences or surrounding prose
  trip this error.

### `Error: sv-grid-pro/ai: aiSmartFill requires at least one example.`

- **Class:** `Error`
- **When:** `aiSmartFill({ examples: [] })`.
- **Fix:** Pass at least one worked example. Two or more locks the
  pattern more reliably.

## How to report a missing entry

If you hit a thrown message that isn't on this page:

1. Copy the exact message text and class name.
2. File an issue with `[error reference]` in the title.
3. We treat this list as **canonical** - every new error added in a
   release lands here in the same PR.

## See also

- [API stability](./api-stability.md) - the contract around these
  classes and messages.
- [Testing and quality](./testing-and-quality.md) - the test suite
  that produces every error here as part of its expected-throw
  assertions.

<!-- =================================================================
     /help/export  (pro)
     ================================================================== -->

# Data export and printing - Pro

Export the grid to **Excel (xlsx)**, **PDF**, **CSV**, **TSV**, **HTML**,
or open a printable view in a new window. Ships in the paid
**[sv-grid-pro](https://www.npmjs.com/package/sv-grid-pro)** add-on; the
Community build does not include these features.

Try the export bar below - downloads run in your browser; the bundled
license key removes the unlicensed watermark:

<div data-docs-demo="21-export-and-print" data-height="500"></div>


## What it is

`sv-grid-pro` augments the `SvGridApi` you already get from
`<SvGrid onApiReady>` with two methods:

- `api.exportData({ format, filename?, columns?, rows?, pageOrientation? })`
- `api.print({ title?, columns?, rows?, orientation? })`

Both methods default to **the currently displayed rows** - sort, filter,
or paginate the grid, and the export reflects that view automatically.

## When to use it

- Reporting flows where users want to take the grid offline (spreadsheets,
  emailed PDFs).
- Compliance / audit trails that require a printable artifact.
- Quick CSV/TSV pulls for downstream pipelines.

If you only need machine-readable data, prefer CSV / TSV - they have no
peer dependencies and produce the smallest files. Use xlsx / PDF only
when the recipient expects formatted documents.

## Minimal example

```svelte
<script lang="ts">
  import { SvGrid, tableFeatures, rowSortingFeature, type SvGridApi, type ColumnDef } from 'sv-grid-community'
  import { installPro, setLicenseKey, type ProGridApi } from 'sv-grid-pro'

  // Set the license key once at startup. Without a key, the feature still
  // works but the grid shows an "unlicensed" watermark and the console
  // emits a one-time nudge directing users to the pricing page.
  setLicenseKey('SVPRO-XXXX-XXXX-XXXX')

  const features = tableFeatures({ rowSortingFeature })

  type Order = { company: string; product: string; price: number }
  const rows: Order[] = [
    { company: 'ACME',  product: 'Widget',  price: 19.95 },
    { company: 'Globex', product: 'Gadget', price: 49.00 },
  ]
  const columns: ColumnDef<typeof features, Order>[] = [
    { field: 'company', header: 'Company' },
    { field: 'product', header: 'Product' },
    { field: 'price',   header: 'Price', format: { type: 'currency', currency: 'USD' } },
  ]

  let api = $state<ProGridApi<typeof features, Order> | null>(null)

  function onReady(next: SvGridApi<typeof features, Order>) {
    api = installPro(next)
  }
</script>

<button onclick={() => api?.exportData({ format: 'xlsx', filename: 'orders' })}>
  Export Excel
</button>
<button onclick={() => api?.exportData({ format: 'pdf', filename: 'orders', pageOrientation: 'landscape' })}>
  Export PDF
</button>
<button onclick={() => api?.print({ title: 'Orders' })}>
  Print
</button>

<SvGrid data={rows} columns={columns} features={features} onApiReady={onReady} />
```

## Install

```bash
pnpm add sv-grid-pro
# Optional - install only the peers you actually use:
pnpm add jszip     # required for xlsx
pnpm add pdfmake   # required for pdf
```

CSV, TSV, HTML, and Print have **no extra dependencies**. The peer
dependencies are lazy-loaded only when you call the format that needs
them.

## Licensing

`sv-grid-pro` has a tiered license gate:

| Key state                                  | Behavior |
| ------------------------------------------ | -------- |
| No key set (`setLicenseKey()` not called)  | Feature works. Grid shows an unlicensed watermark linking to jqwidgets.com; console.log emits a one-time nudge. |
| Key doesn't start with `SVPRO-`            | Throws - programmer error. |
| Key is in the revoked list                 | Throws - contact support for a replacement. |
| `SVPRO-DEV-...` or `SVPRO-EVAL-...`        | Works. One-time console.info notice. No watermark. |
| Any other `SVPRO-...`                      | Works silently. |

Buy a production key at <https://sv-grid.dev/pricing> ($599 / developer /
year). `SVPRO-DEV-...` and `SVPRO-EVAL-...` keys cover local development
and 14-day trials respectively.

## Reference

### `setLicenseKey(key: string): void`

Stores the key in module state. Call once at app startup (e.g. in
`main.ts`). Subsequent calls overwrite.

### `clearLicenseKey(): void` · `hasValidLicense(): boolean` · `dismissUnlicensedNudge(): void`

Programmatic helpers. `hasValidLicense()` is useful when you want UI to
branch on license status. `dismissUnlicensedNudge()` removes the
watermark and stops the MutationObserver - call it after setting a
valid key if you toggled the soft-gate during testing.

### `installPro(api): ProGridApi`

Mutates the given `SvGridApi` to add `exportData` and `print`. Returns
the same object with the augmented type, so existing references keep
working.

### `api.exportData(opts)` - `Promise<void>`

| Option            | Type                                                  | Default              | Notes |
| ----------------- | ----------------------------------------------------- | -------------------- | ----- |
| `format`          | `'xlsx' \| 'pdf' \| 'csv' \| 'tsv' \| 'html'`         | required             | `xlsx` needs `jszip`; `pdf` needs `pdfmake`. |
| `filename`        | `string`                                              | `"grid"`             | Extension is appended if missing. |
| `columns`         | `{ field: string; header?: string }[]`                | every key of row[0]  | Drives both column selection and header labels. |
| `rows`            | `ReadonlyArray<TData>`                                | `api.getDisplayedRows()` | Override to export the full dataset instead of the visible view. |
| `pageOrientation` | `'portrait' \| 'landscape'`                           | `"portrait"`         | PDF only. |

Throws on missing peer (`jszip` / `pdfmake`), revoked / malformed
license, or empty result set. With no license set, it runs but the
grid is watermarked.

### `api.print(opts?)` - `Promise<void>`

Opens a new window with a paginated, printable HTML rendering of the
grid and triggers the browser print dialog.

| Option        | Type                                   | Default     |
| ------------- | -------------------------------------- | ----------- |
| `title`       | `string`                               | `"Grid"`    |
| `columns`     | `{ field: string; header?: string }[]` | all keys    |
| `rows`        | `ReadonlyArray<TData>`                 | `api.getDisplayedRows()` |
| `orientation` | `'portrait' \| 'landscape'`            | `"portrait"` |

Browsers may block the popup unless `print()` is called from a user
gesture (a click handler is fine - automatic on-load print is not).

## Gotchas

- **Empty grids** - both `exportData` and `print` throw if there are no
  displayed rows. Catch the error and show a notice in the UI.
- **Column ordering** - if you don't pass `columns`, the export uses
  `Object.keys(rows[0])` order. Pass `columns` explicitly when the row
  shape doesn't match the column order you want.
- **Cell formatters** - only column-level format hints (date, number,
  currency) carry into xlsx / pdf. Custom snippet renderers are not
  serialized to file formats - provide a plain field for those rows
  instead.
- **Print popup blocked** - `print()` resolves but the browser silently
  blocks the new window. Always trigger from a user click, and surface
  the thrown error.
- **Bundle size** - the vendored exporter is ~50 KB minified. It is
  loaded lazily on first call so it does not bloat the initial bundle
  for users who never export.

## Frequently asked questions

### How do I export a Svelte data grid to Excel?

Install `sv-grid-pro`, call `installPro(api)`, then call the export helper with
`format: 'xlsx'`. The exporter writes a real OOXML workbook in the browser - no
server round-trip. CSV, TSV, PDF, and HTML use the same call with a different
format.

### Is export part of the free Community package?

No. Export and printing ship in the paid `sv-grid-pro` add-on. The free
`sv-grid-community` package covers the full grid (sorting, filtering, grouping,
editing, virtualization) but not export/print/pivot/import.

### Does exporting bloat my bundle?

No. The ~50 KB exporter is lazy-loaded on the first export call, so users who
never export never download it.

<!-- =================================================================
     /help/filtering/applying-filters  (community)
     ================================================================== -->

# Applying filters

"Applying" a filter means running it against the data. SvGrid applies
filters **eagerly** by default: every keystroke updates the row model and
the visible rows (with a 150ms debounce inside the column menu's value
input).
<div data-docs-demo="02-sort-filter-paginate" data-height="540"></div>

## Apply on Enter (manual)

If you want the classic "apply"-button pattern (no filter runs until the
user confirms), run in `externalFilter` mode and only push a new
pre-filtered `data` array on commit:

```svelte
<script lang="ts">
  let pending = $state('')
  let applied = $state('')
  const filtered = $derived(
    applied ? rows.filter((r) => r.name.toLowerCase().includes(applied.toLowerCase())) : rows,
  )
  function commit() { applied = pending }
</script>

<input bind:value={pending} onkeydown={(e) => e.key === 'Enter' && commit()} />
<button onclick={commit}>Apply</button>

<SvGrid
  data={filtered}
  columns={columns}
  features={features}
  filterMode="none"
  externalFilter={true}
/>
```

The grid's own column-menu filter applies as the user types - there is
no built-in "Apply" button. Use the pattern above when you need explicit
commit semantics.

## Apply against the server

When data is server-side, filtering happens on the backend. Mirror the
state pattern but issue a request from the change handler. See
[demos/09-server-side.svelte](../../../examples/src/demos/09-server-side.svelte)
for the canonical implementation with debounce + abort.

## Apply once, then freeze

To take a snapshot:

```ts
const filteredData = api.getData().filter(myPredicate)
// pass filteredData into a separate <SvGrid> with filterMode="none"
```

This works when you want to render the filtered result inside an
export-friendly grid that's independent of the user's current filters.

## See also

- [Applying filters - server-side variant](../../getting-started.md#11-server-side-data)
- [Filter API](./filter-api.md)

<!-- =================================================================
     /help/filtering/custom-column-filters  (community)
     ================================================================== -->

# Custom column filters

When the built-in operators and the set-filter pattern are not enough,
take over the filter pipeline.
<div data-docs-demo="03-excel-filters" data-height="540"></div>

## Option A - supply a `filterFn`

The simplest extension: register your own filter function and reference it
per column.

```ts
// types
declare module 'sv-grid-community' {
  interface FilterFnsRegistry {
    inListCSV: (value: unknown, query: string) => boolean
  }
}

// register
import { filterFns } from 'sv-grid-community'
;(filterFns as any).inListCSV = (value: unknown, query: string) => {
  const items = String(query).split(',').map((s) => s.trim().toLowerCase())
  return items.includes(String(value ?? '').toLowerCase())
}

// use
const columnFilters = [{ id: 'status', value: 'active,pending', fn: 'inListCSV' }]
```

`filterFns` is a plain object so monkey-patching works - but the
`FilterFnsRegistry` module augmentation is what tells TypeScript about the
new key.

## Option B - control the entire filter pipeline

Pass `externalFilter={true}` and feed the grid a pre-filtered array. The
grid still records the in-UI filter state (so the menu and chips light
up correctly) but does **not** filter rows itself - you do, in response
to the `onFiltersChange` callback. This is the path server-side data
sources, large remote datasets, and tree data take.

```svelte
<script lang="ts">
  let rawRows = $state<Person[]>([])
  let filters = $state<{ id: string; operator: string; value: string }[]>([])
  const filtered = $derived(myComplexFilter(rawRows, filters))
</script>

<SvGrid
  data={filtered}
  {columns}
  features={features}
  filterMode="menu"
  externalFilter={true}
  onFiltersChange={(next) => (filters = next.columns)}
/>
```

The same pattern exists for sort (`externalSort` + `onSortingChange`)
and works on the same grid - see the [server-side demo](../../../examples/src/demos/09-server-side.svelte).

If you only want a single pre-filtered array and don't need the grid's
filter UI at all, pass `filterMode="none"` instead and skip the
callbacks entirely.

## Option C - custom column UI

Render a custom header (via `header: () => renderSnippet(...)`) that
includes your own filter widget. Update controlled state from the widget;
the grid will react. See [Custom header components](../columns/custom-header-components.md).

## See also

- [Filter API](./filter-api.md)
- [Set filter](./set-filter.md)

<!-- =================================================================
     /help/filtering/date-filter  (community)
     ================================================================== -->

# Date filter

A column with `editorType: 'date'` (or `'datetime'`) gets the **date**
filter operator set: `equals`, `lessThan`, `greaterThan`,
**`between`**, `isBlank`.
<div data-docs-demo="64-filter-between-operator" data-height="540"></div>

```ts
const columns: ColumnDef<{}, Person>[] = [
  {
    field: 'joinedAt',
    header: 'Joined',
    editorType: 'date',
    format: { type: 'date', pattern: 'y-m-d' },
  },
]
```

## Value format

Store dates as **ISO date strings** (`YYYY-MM-DD`) or as `Date`
objects. The grid compares them via `Date.parse()` so both forms work,
but stick to one for sort stability.

For `'datetime'`, use full ISO 8601: `2026-05-27T14:32:00Z`.

## Date range

Pick **Between** in the column menu's operator picker. The wrapper
renders two date inputs (From / To); both endpoints are **inclusive**.

```ts
api.setFilter('joinedAt', {
  operator: 'between',
  value:    '2026-01-01',
  valueTo:  '2026-12-31',
})
```

The headless filter helper works the same:

```ts
import { applyExcelFilter } from 'sv-grid-community'

applyExcelFilter('2026-05-27', {
  id: 'joinedAt',
  operator: 'between',
  value: '2026-01-01',
  valueTo: '2026-12-31',
})
// → true
```

The filter is inactive until both endpoints are non-empty.

## Today / yesterday / last 7 days

Not built in. Apply via the imperative API:

```ts
function lastNDays(api: SvGridApi<{}, Person>, columnId: string, n: number) {
  const cutoff = new Date(Date.now() - n * 86_400_000).toISOString().slice(0, 10)
  api.setFilter(columnId, { operator: 'greaterThan', value: cutoff })
}

lastNDays(api, 'joinedAt', 7)
```

## Timezones

The grid does not adjust dates for the user's timezone. If you store
`'2026-05-27'` and the user is in UTC-08, the cell displays as
`2026-05-27` (no shift), and a `greaterThan: '2026-05-26'` filter matches.
That is usually what people want for **calendar** dates. For timezone-
sensitive datetimes, store with `Z` suffix and use the `datetime` editor
type.

## See also

- [Filter conditions](./filter-conditions.md)
- [Date editor](../editing/provided-editors.md#date-editor)

<!-- =================================================================
     /help/filtering/filter-api  (community)
     ================================================================== -->

# Filter API

Two surfaces - pick based on whether the caller is inside or outside the
component that owns the grid state.
<div data-docs-demo="64-filter-between-operator" data-height="540"></div>

## `SvGridApi` (imperative)

Available via `<SvGrid onApiReady={(api) => /* … */}>`.

```ts
api.setFilter(
  columnId: string,
  filter: { operator: SvGridFilterOperator; value?: string } | null,
): void

api.clearFilter(columnId: string): void
```

`SvGridFilterOperator` is the union: `'contains' | 'equals' | 'startsWith'
| 'greaterThan' | 'lessThan' | 'isBlank'`.

Passing `null` clears the filter on that column.

```ts
api.setFilter('status',     { operator: 'equals',      value: 'active' })
api.setFilter('age',        { operator: 'greaterThan', value: '30' })
api.setFilter('email',      { operator: 'contains',    value: '@example.com' })
api.setFilter('department', null)        // clear
api.clearFilter('age')                   // same effect, sugared
```

The wrapper internally writes into the `columnFilters` state slice and
re-runs the filtered row model.

## Observe filter state

For history, persistence, or server-side, subscribe via
`onFiltersChange`:

```svelte
<script lang="ts">
  let filters = $state<Array<{
    id: string
    operator: string
    value: string
    selectedValues?: Array<string>
  }>>([])
  let globalFilter = $state('')
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  filterMode="menu"
  onFiltersChange={(next) => { filters = next.columns; globalFilter = next.global }}
/>
```

The callback receives a consolidated `{ global, columns }` shape so the
three internal stores (global search, per-column operator filter, facet
checklist) collapse into one payload you can serialise.

For server-side / external pipelines, also set `externalFilter={true}`
so the grid doesn't filter the rows locally - see [Custom column
filters](./custom-column-filters.md).

## Read the current filters

From the imperative API there is no `getFilters()` getter today - read the
underlying state via the grid instance:

```ts
const grid = api as unknown as { /* internals are not part of the public type */ }
```

This is not a stable surface. If you need to read filters from outside,
control the state.

## See also

- [Filter conditions](./filter-conditions.md)
- [Applying filters](./applying-filters.md)
- [Missing features](../missing-features.md) - `api.getFilters()` would be nice.

<!-- =================================================================
     /help/filtering/filter-conditions  (community)
     ================================================================== -->

# Filter conditions

A "filter condition" is a `(column, operator, value)` triple. The grid
stores filter conditions in `state.columnFilters`.
<div data-docs-demo="03-excel-filters" data-height="540"></div>

## Shape

```ts
type ColumnFilter = {
  id: string                         // column id
  value: unknown                     // operator-specific value
  fn?: keyof typeof filterFns        // optional explicit filter function
}
type ColumnFiltersState = ColumnFilter[]
```

Through the wrapper, the menu uses a richer per-column representation
(operator + value) - the wrapper converts between the two when state
crosses the boundary.

## AND vs. OR

Multiple filter conditions for **different columns** AND together. Two
filters on the **same column** are not natively supported - the second
write overwrites the first.

To express OR within a column (`status = active OR pending`), use the
[set filter](./set-filter.md) pattern.

To express OR across columns (`firstName = ada OR lastName = lovelace`),
do it outside the grid by filtering the data array before passing it in.

## Conditions via the imperative API

Apply or update conditions through the `SvGridApi` once it's available:

```svelte
<script lang="ts">
  import type { SvGridApi } from 'sv-grid-community'

  let api = $state<SvGridApi<typeof features, Person> | null>(null)

  function applyDefaults() {
    if (!api) return
    api.setFilter('department', { operator: 'equals', value: 'Engineering' })
    api.setFilter('age',        { operator: 'equals', value: '30' })
  }
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  filterMode="menu"
  onApiReady={(next) => (api = next)}
/>
<button onclick={applyDefaults}>Apply defaults</button>
```

## Clearing

```ts
api.clearFilter('department')   // single column
```

A `clearAllFilters()` helper is on the
[Missing features](../missing-features.md) list. Until then, iterate
the columns you know are filtered and call `clearFilter` per id - the
list of currently-filtered columns is reported by `onFiltersChange`.

```ts
columnFilters = []
```

## See also

- [Applying filters](./applying-filters.md)
- [Filter API](./filter-api.md)

<!-- =================================================================
     /help/filtering/floating-filters  (community)
     ================================================================== -->

# Floating filters

"Floating filters" are the always-visible filter inputs that sit
**between** the header row and the body - same idea as a filter row, but
matched per-operator to the underlying column menu.
<div data-docs-demo="03-excel-filters" data-height="540"></div>

## Status

SvGrid has a **filter row** (`filterMode="row"`) that gives you a single
input per text column. It does not yet have full "floating filter" parity
where the inline input mirrors the column menu's operator - e.g. a number
column showing a `>` icon next to the filter input.

The filter row uses `contains` for text columns and `equals` for number /
date / checkbox columns.

## Enable the filter row

```svelte
<SvGrid {data} {columns} features={features} filterMode="row" />
```

If you also want the column menu icon present, set both surfaces
explicitly:

```svelte
<SvGrid
  {data} {columns} features={features}
  showFilterRow={true}
  showColumnFilters={true}
/>
```

## Per-operator floating filter

Today this needs a custom header. Render your own input inside the column
header via `header: (ctx) => renderSnippet(...)` and write into
controlled `columnFilters` state when the user types.

```svelte
{#snippet RangeHeader(p: { id: string })}
  <div class="flex flex-col gap-1">
    <span>{p.id}</span>
    <input
      placeholder="≥ min"
      oninput={(e) => applyMin(p.id, +e.currentTarget.value)}
      class="w-20 rounded border border-slate-300 px-1 py-0.5 text-xs"
    />
  </div>
{/snippet}
```

## Tracked at

[Missing features](../missing-features.md) - first-class floating filters
with operator parity.

## See also

- [Overview](./overview.md)
- [Custom header components](../columns/custom-header-components.md)

<!-- =================================================================
     /help/filtering/number-filter  (community)
     ================================================================== -->

# Number filter

A column with `editorType: 'number'` gets the **number** filter operator
set: `equals`, `greaterThan`, `lessThan`, **`between`**, `isBlank`. The
default operator is `equals`.
<div data-docs-demo="64-filter-between-operator" data-height="540"></div>

```ts
const columns: ColumnDef<{}, Person>[] = [
  { field: 'age',    header: 'Age',    editorType: 'number' },
  {
    field: 'salary', header: 'Salary', editorType: 'number',
    format: { type: 'currency', currency: 'USD' },
  },
]
```

## Range - `between`

Pick **Between** in the column menu's operator picker and the second
input ("To") appears next to the first ("From"). Both endpoints are
**inclusive**.

Programmatically:

```ts
api.setFilter('age', { operator: 'between', value: '18', valueTo: '65' })
```

Or via the headless filter helper:

```ts
import { applyExcelFilter } from 'sv-grid-community'

applyExcelFilter(72, { id: 'age', operator: 'between', value: 18, valueTo: 65 })
// → false (72 > 65)
```

The grid treats the filter as inactive when either endpoint is empty.
That way the user can type `from = 18` and the grid keeps showing
every row until they finish typing the `to` value too.

## Numeric input parsing

The filter value comes in from the DOM as a string. Use `parseEditorValue`
to convert:

```ts
import { parseEditorValue } from 'sv-grid-community'

parseEditorValue('number', '4.5')   // 4.5
parseEditorValue('number', 'abc')   // NaN - reject
```

The grid does this for you when the user types into a header filter.

## Locale

Number filters compare raw `Number(cellValue)` against `Number(filter.value)`.
They do not parse "1,234.50" or "1 234,50" - feed the column raw numbers,
and use a `format` on the column for display.

## See also

- [Filter conditions](./filter-conditions.md)
- [Number editor](../editing/provided-editors.md#number-editor)

<!-- =================================================================
     /help/filtering/overview  (community)
     ================================================================== -->

# Filtering - overview

Click any column header's filter icon to open the operator + value
popover; numeric and date columns range-bucket their distinct values
so the menu stays usable on big datasets:

<div data-docs-demo="03-excel-filters" data-height="460"></div>

SvGrid offers four filtering surfaces. You opt into the one(s) you need
through the `filterMode` prop on `<SvGrid>`:

| `filterMode` | What it shows |
| ------------ | ------------- |
| `'menu'` (default) | A "filter icon" in each header opens a per-column operator + value popover. |
| `'row'`            | A filter row under the header - one input per column. |
| `'global'`         | A single search box above the grid that searches all visible columns. |
| `'none'`           | No filter UI. Drive filters programmatically only. |

```svelte
<SvGrid {data} {columns} features={features} filterMode="row" />
```

Per-surface props (`showColumnFilters`, `showFilterRow`, `showGlobalFilter`)
override `filterMode` when set explicitly - useful when you want two
surfaces simultaneously.

## Feature registration

Filtering is gated by `columnFilteringFeature` plus
`createFilteredRowModel`. Both must be registered for the column filter UI
to actually filter rows:

```ts
import {
  tableFeatures, columnFilteringFeature, createFilteredRowModel,
} from 'sv-grid-community'

const features = tableFeatures({ columnFilteringFeature })
```

The wrapper auto-registers `createFilteredRowModel` when the feature is
present.

## Operators

All built-in operators:

| Operator      | Applies to | Behaviour |
| ------------- | ---------- | --------- |
| `contains`    | text       | case-insensitive substring |
| `equals`      | text, num, date, bool | strict equality (numeric where possible) |
| `startsWith`  | text       | case-insensitive prefix |
| `greaterThan` | num, date  | strict `>` |
| `lessThan`    | num, date  | strict `<` |
| `between`     | num, date  | inclusive range - requires `valueTo` |
| `isBlank`     | any        | empty / null / undefined / whitespace |

The set of operators offered per column depends on `editorType`:

| `editorType` | operators |
| ------------ | --------- |
| `'text'` (default) | contains, equals, startsWith, isBlank |
| `'number'` | equals, greaterThan, lessThan, isBlank |
| `'date'` / `'datetime'` | equals, lessThan, greaterThan, isBlank |
| `'checkbox'` | equals, isBlank |

## Built-in `filterFns`

For programmatic filtering (without the menu), pass a `filterFn` on the
column or use the headless `createFilteredRowModel` directly.

```ts
import { filterFns } from 'sv-grid-community'

filterFns.includesString(cellValue, query)
filterFns.equals(cellValue, query)
```

## See also

- [Text filter](./text-filter.md)
- [Number filter](./number-filter.md)
- [Date filter](./date-filter.md)
- [Set filter](./set-filter.md)
- [Filter API](./filter-api.md)
- [demos/03-excel-filters.svelte](../../../examples/src/demos/03-excel-filters.svelte)

## Frequently asked questions

### How do I filter a column in SvGrid?

Click a column header's filter icon to open the operator + value popover. Text
columns get `contains` / `equals` / `startsWith` / `isBlank`; number and date
columns add `greaterThan` / `lessThan` / `between`. Filtering is on by default
once the filtering feature is registered.

### Does SvGrid have Excel-style set filters?

Yes. A set filter shows a checklist of a column's distinct values so users can
include "active OR pending" with checkboxes. Numeric and date columns
range-bucket their values so the list stays usable on large datasets.

### Can I filter on the server?

Yes. Set `externalFilter` so the grid records filter state but your API does the
filtering. The grid emits the consolidated filter payload via `onFiltersChange`
for you to forward to the server.

<!-- =================================================================
     /help/filtering/set-filter  (community)
     ================================================================== -->

# Set filter

A "set filter" (a.k.a. value filter, list filter) shows a checklist of all distinct values in a column and lets the user pick which to include. It's what you reach for to filter `status` to "active OR pending", or `department` to a few specific teams.

<div data-docs-demo="111-set-filter-advanced" data-height="640"></div>

Three patterns are supported, all wired through the imperative `api.setFacetFilter(columnId, values | null)`:

| Mode | UI | Built-in? | When to use |
| --- | --- | --- | --- |
| **Excel-style** | Column-menu Values tab | Yes | Most columns. Distinct values are enumerated from the loaded data; search box + select-all + clear ship out of the box. |
| **Async** | Side panel that loads values from a server endpoint | User-land (one screen of code) | The column has too many distinct values to list at full data load. Lazy-fetch on demand. |
| **Tree-list** | Hierarchical checkboxes (parent ↔ descendants) | User-land (cascade logic) | Nested taxonomies: Region → Country → City; Department → Team → Employee. |

## 1. Excel-style (built-in)

The column menu's Values tab is the default set filter. Click the funnel icon on any header to open it.

What you get without writing any code:

- Distinct values from the current dataset.
- Type-ahead search.
- Select-all / clear toggle.
- Mixed-state preserved as the user scrolls.

Programmatic equivalent for "remember and restore":

```ts
// Capture the current set
const filters = api.getFilters() // includes selectedValues per column

// Restore later (e.g. saved view, URL persistence)
api.setFacetFilter('status', ['active', 'pending'])
api.setFacetFilter('status', null) // clear
```

## 2. Async values (server-loaded)

When a column has tens of thousands of distinct values, you don't want to pre-render them all. Pattern: render a side panel beside the grid, load values from the server on first open, drive the grid via `api.setFacetFilter`:

```ts
let state = $state<{
  status: 'idle' | 'loading' | 'ready' | 'error'
  values: string[]
}>({ state: 'idle', values: [] })
let selected = $state<Set<string>>(new Set())

async function loadValues() {
  state = { state: 'loading', values: [] }
  const res = await fetch('/api/orders/customers')
  const values = await res.json()
  state = { state: 'ready', values }
}

function toggle(value: string) {
  const next = new Set(selected)
  if (next.has(value)) next.delete(value); else next.add(value)
  selected = next
  api.setFacetFilter('customer', next.size === 0 ? null : Array.from(next))
}
```

Key benefits vs the Excel tab:

- **Lazy load** - no client-side enumeration for millions of distinct values.
- **Server can apply policy** - hide values the current user shouldn't see.
- **Static label / dynamic value** - the panel can show pretty labels while the filter applies on the underlying id.

See demo 111 ("Async values" card) for a complete implementation with loading state, retry, and search.

## 3. Tree-list (hierarchical)

For nested taxonomies, render a tree of checkboxes. Parent checked = all descendants checked. Some descendants checked = parent shows the "indeterminate" state. On any change, compute the leaf set and apply it to the column.

```ts
// Taxonomy: Region → Country → City
const GEO = {
  Americas: { 'United States': ['New York', 'San Francisco'], Canada: ['Toronto'] },
  EMEA:     { Germany: ['Berlin', 'Munich'], France: ['Paris'] },
}

let selectedCities = $state<Set<string>>(new Set())

function toggleNode(node: TreeNode, on: boolean) {
  const next = new Set(selectedCities)
  for (const city of node.cities) {  // pre-computed leaf set
    if (on) next.add(city); else next.delete(city)
  }
  selectedCities = next
  api.setFacetFilter('city', next.size === 0 ? null : Array.from(next))
}

function isChecked(node: TreeNode): boolean {
  return node.cities.every((c) => selectedCities.has(c))
}
function isPartial(node: TreeNode): boolean {
  const hits = node.cities.filter((c) => selectedCities.has(c)).length
  return hits > 0 && hits < node.cities.length
}
```

The grid is unaware of the hierarchy - it just receives a flat list of allowed leaf values. The hierarchy lives in your panel UI.

See demo 111 ("Tree" card) and [demo 102: Tree checkbox cascade](#/demos/102-tree-checkbox-cascade) for the cascade-logic recipe.

## API surface

```ts
type SvGridApi<…> = {
  // Set a multi-select set filter. Pass null or [] to clear.
  setFacetFilter(columnId: string, values: ReadonlyArray<string> | null): void

  // Read the current filters (includes the facet selection per column).
  getFilters(): Record<string, { operator: ..., selectedValues?: string[] }>

  // Snapshot of the rows the grid currently displays - useful when your
  // filter UI needs to count matches without re-running the search.
  getDisplayedRows(): ReadonlyArray<TData>
}
```

## See also

- Demo 111: [Set filter - tree / async / Excel mode](#/demos/111-set-filter-advanced)
- Demo 102: [Tree checkbox cascade](#/demos/102-tree-checkbox-cascade) - the cascade recipe used inside the tree filter
- [`api.setFacetFilter`](../api-reference.md#setfacetfilter)
- [Filter API overview](./filter-api.md)

<!-- =================================================================
     /help/filtering/text-filter  (community)
     ================================================================== -->

# Text filter

A column with no `editorType` (or `editorType: 'text'`) gets the **text**
filter operator set: `contains`, `equals`, `startsWith`, `isBlank`. The
default operator is `contains`.
<div data-docs-demo="69-highlighted-search" data-height="540"></div>

## Through the column menu

Click the filter icon in the header → pick an operator → type a value →
press Enter. The grid filters as you type (with a 150ms debounce).

## Through the filter row

```svelte
<SvGrid {data} {columns} features={features} filterMode="row" />
```

Each text column shows a single input. The applied operator is `contains`.

## Programmatically

```ts
api.setFilter('firstName', { operator: 'contains', value: 'ada' })
api.clearFilter('firstName')
```

## Case + accent sensitivity (locale-aware filtering)

All built-in text operators are **case AND accent insensitive** out of
the box. The grid normalises both the query and each cell value with
NFD-decompose → strip combining marks (diacritics) → locale-aware
lowercase, then runs `includes` / `equals` / `startsWith`.

```ts
applyExcelFilter('Café Genève', { id: 'name', operator: 'contains', value: 'cafe geneve' })
// → true

applyExcelFilter('München', { id: 'city', operator: 'startsWith', value: 'munch' })
// → true
```

<div data-docs-demo="110-locale-aware-filter" data-height="540"></div>

### `filterLocale` prop

For locale-sensitive lowercasing (Turkish dotted-I vs dotless-i, German
ß, etc.), thread a BCP-47 tag through `filterLocale`:

```svelte
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  filterLocale="tr-TR"
/>
```

With `filterLocale="tr-TR"`:

- `"istanbul"` matches `"İstanbul"` (Turkish capital dotted-I → "i")
- `"izmir"` matches `"İzmir"`

Without a locale, `String.prototype.toLowerCase()` is used (Unicode
default casing). 90 % of the time this is fine; the locale prop is for
the edge cases.

### Re-using the normaliser

The same `normalizeForFilter` helper that powers the built-in operators
is exported, so you can use it in user-land code (e.g. a custom
`externalFilter` pipeline):

```ts
import { normalizeForFilter } from 'sv-grid-community'

const filtered = rows.filter((r) =>
  normalizeForFilter(r.name, 'de-DE').includes(
    normalizeForFilter(query, 'de-DE'),
  ),
)
```

### Opting out

If you need case-sensitive comparison, run in `externalFilter` mode and
filter the data yourself before passing it in:

```svelte
<script lang="ts">
  let needle = $state('')
  const filtered = $derived(
    needle ? rows.filter((r) => r.name.includes(needle)) : rows,
  )
</script>

<SvGrid
  data={filtered}
  columns={columns}
  features={features}
  filterMode="none"
  externalFilter={true}
/>
```

## See also

- Demo 110: [Locale-aware text filter](#/demos/110-locale-aware-filter)
- [Filter conditions](./filter-conditions.md)
- [Custom column filters](./custom-column-filters.md)
- [excel-filters.ts](../../../packages/sv-grid-community/src/filtering/excel-filters.ts)

<!-- =================================================================
     /help/glossary  (community)
     ================================================================== -->

# Glossary

Terminology used across the docs and the source. Sorted A-Z. If a term
is unclear in a topic page and isn't on this list, please file an
issue.

## A

**Accessor.** A function on a `ColumnDef` (`accessorFn`) that computes
a cell value from the row instead of reading a property by `field`.
Used heavily by pivot tables and computed columns.

**Active cell.** The cell with focus. Tracked through every keyboard
move + click; exposed via `onActiveCellChange`. At most one cell is
active per grid. Has `tabindex="0"`; every other cell has
`tabindex="-1"` (roving-tabindex pattern).

**Aggregator.** A function that reduces a group's values to a single
cell value (sum, avg, count, min, max, custom). Used by
`columnGroupingFeature` and the pivot engine.

**API (`SvGridApi`).** The imperative interface exposed via
`<SvGrid onApiReady>`. Methods like `setSort`, `setFilter`, `addRow`,
`getDisplayedRows`. See [API reference](./api-reference.md).

## C

**Cell context.** The `ctx` object passed to `cell`, `editable`, and
`formatter` callbacks. Contains `cell`, `row`, `column`, `table`,
`getValue`. Used inside custom cell snippets to access surrounding
state.

**Column definition (`ColumnDef`).** The plain object that describes
one column: how to read its value (`field` / `accessorFn`), how to
render it (`cell`, `header`), and which features apply (`editable`,
`format`, `editorType`). See [Column definitions](./columns/column-definitions.md).

**Column group.** A `ColumnDef` whose `columns` array contains child
column defs. The grid emits one header row per nesting depth with
proper `colSpan`. See [Column groups](./columns/column-groups.md).

**Controlled vs uncontrolled state.** *Controlled*: the consumer owns
the state (a `$state` in your component) and listens to change events.
*Uncontrolled*: the engine owns the state internally. Most grid state
is uncontrollable-by-default; opt in via the `onXxxChange` props.

## D

**Density.** The vertical compaction of rows. Controlled via the
`--sg-row-height` CSS variable + the `rowHeight` prop. Default is
36 px ("comfortable"); 28 px is "compact"; 48 px is "loose".

**Display rows.** The rows the grid is currently showing AFTER the
pipeline runs (filter -> sort -> group -> page). Accessible via
`api.getDisplayedRows()`. NOT the same as the raw `data` prop.

## E

**Editor type.** A string on the `ColumnDef` that picks which built-in
editor the grid uses when a user edits the cell. Values:
`'text'` / `'number'` / `'date'` / `'datetime'` / `'checkbox'` /
`'list'` / `'chips'`. A column without `editorType` is read-only even
when `enableInlineEditing` is true.

**Engine.** Layer 2 in the [architecture](./architecture.md). The
pure-function row-and-column model pipeline. Lives in
`packages/sv-grid-community/src/core.ts` + the `row-models/` folder.

## F

**Feature.** A bundle of row-model + state + behaviour you register
via `tableFeatures({...})`. Examples: `rowSortingFeature`,
`columnFilteringFeature`. Features compose - registering five of them
is normal.

**Field.** The row property a column reads + writes by default. A
shortcut for `accessorFn: (row) => row[field]`. When you can use
`field`, prefer it - the engine has a fast path for property-keyed
columns.

**Filter mode.** A single prop on `<SvGrid>` that picks which filter
UI the grid renders: `'menu'` (icon in each header), `'row'` (input
under each header), `'global'` (one search box), or `'none'`.

**Format / formatter.** `format` is a declarative config (`{ type:
'currency', currency: 'USD' }`) that the grid hands to `Intl`.
`formatter` is a free-form callback that returns a string. Use
`format` for standard types; `formatter` for custom output.

## G

**Group by.** A list of column ids whose unique values become rollup
group rows. Set via `api.setGroupBy([...])` or the column menu's "Group
by this column" entry. Drives `columnGroupingFeature`.

## H

**Header context.** The `ctx` object passed to `header` and `footer`
templates. Contains `header`, `column`, `table`. Used inside custom
header snippets.

**Headless.** Layer 2 without the renderer. `createSvGrid(...)`
returns a headless instance that emits the same row model + state but
doesn't paint anything. See [Why headless?](../why-headless.md).

## I

**Imperative API.** See *API (`SvGridApi`)*.

**Inline editing.** Editing that happens inside the cell itself, vs
in a side form. Toggled via `enableInlineEditing` on `<SvGrid>` +
`editorType` on each column.

## L

**Layer 1, 2, 3.** See [Architecture overview](./architecture.md).
Layer 1 is your data; Layer 2 is the engine; Layer 3 is the
`<SvGrid>` renderer.

**License key.** A string starting with `SVPRO-` set via
`setLicenseKey(...)`. Removes the unlicensed watermark + console
nudge. See [API stability](./api-stability.md) for license-related
errors.

## P

**Pinned column.** A column sticky-positioned to the left or right
edge while the rest scroll. Set via the column menu or
`api.pinColumn(id, 'left' | 'right' | null)`.

**Pipeline.** The chain of row-model transformations: core ->
filtered -> sorted -> grouped -> expanded -> paginated. Runs once per
state change, NOT per scroll frame.

**Pivot.** A reshape of facts into a grid of intersections - row
dimensions cross column dimensions, with measures (aggregated values)
at each intersection. SvGrid doesn't have a `pivot` prop; the pivot
engine in [pivot.md](./pivot.md) builds the pivoted data + nested
ColumnDef tree the renderer needs.

**Placeholder row.** A frozen "stand-in" row used by sparse infinite
scroll. Renders skeleton cells until the real row loads. See
[Server-side data](./server-side-data.md).

**Pro.** The paid `sv-grid-pro` companion package adding export,
import, print, pivot helpers, and the AI assistant. Installed
separately; activated by `installPro(api)`.

## R

**Render template.** A `cell` / `header` / `footer` value that
returns a Svelte snippet via `renderSnippet(SnippetRef, props)`. The
grid mounts the snippet inside the cell.

**Roving tabindex.** The pattern of giving only the active cell
`tabindex="0"` while every other cell has `tabindex="-1"`. Puts the
grid in the tab order exactly once. See
[Accessibility](./accessibility.md).

**Row data.** The `data` prop. Anything assignable to `RowData[]`
(which is `Record<string, unknown>[]`). Plain objects; the grid never
introspects beyond `field` reads.

**Row model.** A pipeline stage that takes rows in and emits rows
out. Examples: `createSortedRowModel`, `createFilteredRowModel`. Pipe
them in via `tableFeatures(...)`. See [Architecture](./architecture.md).

## S

**Selection range.** A rectangular cell selection (anchor + focus
cells), enabled by `enableCellSelection={true}`. Copy + paste (TSV)
and the fill handle both operate on this range.

**Snippet.** A Svelte 5 `{#snippet Foo(props)}` block. Used by the
grid as the render template format for cells, headers, and editors.
`renderSnippet(Foo, props)` is the wrapper the column passes to
`cell`.

**Soft-gate.** The unlicensed Pro behaviour: features still run; a
small watermark + one-time console message appear. Removed by
`setLicenseKey('SVPRO-...')`.

## T

**Table features.** The bag returned by `tableFeatures({...})` -
a typed object identifying which row models + state slices the grid
should enable. Pass to `<SvGrid features={...}>` and use as the first
generic of `ColumnDef<...>`.

**Tree row.** A row with a `depth` field + `childIds` (or
equivalent). Renders with indented chevron + connector lines. The grid
doesn't have a `treeData` prop; you derive `visibleRows` from
`allRows` + `expanded`. See [Tree rows](./rows/tree-rows.md).

## V

**Virtualization.** Rendering only the rows + columns currently in
view + a small overscan buffer. Enabled by default for any grid with
more than a few hundred rows. Bypassed in jsdom (zero layout metrics)
- test against Playwright for virtualization behaviour.

**Visible rows.** Same as *Display rows*.

## W

**Watermark.** The "Unlicensed sv-grid-pro" badge that appears
bottom-right when a Pro feature runs without a valid license. Removed
by `setLicenseKey('SVPRO-...')` or `dismissUnlicensedNudge()` (the
nudge only).

## See also

- [Architecture overview](./architecture.md) - where each piece
  above sits.
- [API reference](./api-reference.md) - every export with its tier
  badge.

<!-- =================================================================
     /help/grouping-aggregation  (community)
     ================================================================== -->

# Grouping & aggregation

Roll rows up by one or more columns and compute aggregates (sum, avg,
count, min, max, custom) at each group level. Powered by
`columnGroupingFeature` plus per-column `aggregator` config.

Try it: drag a column into the group-by lane, then change aggregators
per column:

<div data-docs-demo="07-grouping-aggregation" data-height="500"></div>

## Minimal example

```svelte
<script lang="ts">
  import {
    SvGrid, tableFeatures, rowSortingFeature, columnGroupingFeature,
    type ColumnDef,
  } from 'sv-grid-community'

  type Employee = {
    id: number; name: string; department: string;
    salary: number; performance: number
  }

  const features = tableFeatures({ rowSortingFeature, columnGroupingFeature })

  const columns: ColumnDef<typeof features, Employee>[] = [
    { field: 'department', header: 'Department' },
    { field: 'name',       header: 'Name' },
    { field: 'salary',     header: 'Salary',
      aggregator: 'sum',
      format: { type: 'currency', currency: 'USD' } },
    { field: 'performance', header: 'Performance',
      aggregator: 'avg' },
  ]

  const rows: Employee[] = [
    { id: 1, name: 'Ada',   department: 'Engineering', salary: 180_000, performance: 4.8 },
    { id: 2, name: 'Linus', department: 'Engineering', salary: 195_000, performance: 4.6 },
    { id: 3, name: 'Grace', department: 'Operations',  salary: 165_000, performance: 4.9 },
  ]
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  groupBy={['department']}
/>
```

The grid emits one group row per unique department value, with the
group cell showing the rolled-up salary sum + average performance.
Click the chevron on a group row to expand its children.

## Setting the group-by

Three ways, ranked by ergonomic order:

1. **The column menu.** When the user opens a header's menu, "Group
   by this column" toggles that column in/out of the group-by list.
2. **The `groupBy` prop.** Initial state for the group-by list.
3. **The imperative API.** `api.setGroupBy(['department', 'role'])`
   for toolbars / saved views.

The group order is significant - `['region', 'country']` rolls up
country inside region; reverse the array to flip the hierarchy.

## Built-in aggregators

| Aggregator | Returns                                              | Behaviour on empty groups |
| ---------- | ---------------------------------------------------- | ------------------------- |
| `'sum'`    | Sum of numeric cell values                           | `0`                       |
| `'avg'`    | Arithmetic mean (with safe divide-by-zero)           | `null`                    |
| `'count'`  | Number of leaf rows                                  | `0`                       |
| `'min'`    | Smallest value (numeric or `Intl.Collator`-comparable) | `null`                  |
| `'max'`    | Largest value                                        | `null`                    |

`'sum'` / `'avg'` / `'min'` / `'max'` cast values to `Number`. If the
column has non-numeric values mixed in, those rows are skipped.

## Custom aggregator

Pass a function instead of a string for any group-aware computation:

```ts
{
  field: 'orders',
  header: 'Top customer',
  aggregator: (rows) => {
    const top = rows.reduce<Employee | null>(
      (acc, r) => !acc || r.orders > acc.orders ? r : acc,
      null,
    )
    return top?.name ?? '-'
  },
}
```

The callback gets every leaf row in the group (already filtered).
Return whatever the cell should display - string, number, or a
formatted value.

## Custom group cell rendering

By default the group cell shows `key (n)` - e.g. "Engineering (12)".
Override via the column's `cell` template:

```svelte
{#snippet GroupCell(props: { row: GroupRow<Employee> })}
  <span class="font-semibold">
    {props.row.groupKey}
    <span class="text-sm opacity-60">({props.row.subRows.length} reports)</span>
  </span>
{/snippet}
```

The `row.groupKey` is the unique group value (the department name in
the example). `row.subRows` is the children. `row.depth` is the
nesting level (useful for indentation when you group by multiple
columns).

## Aggregating string columns

Strings work with `'count'`, `'min'`, `'max'`, and any custom
aggregator. For sum / avg you'll get `NaN` because the cast to
`Number` fails - the grid renders this as `-` by default.

A useful custom aggregator for strings:

```ts
{
  field: 'tags',
  aggregator: (rows) => {
    const set = new Set<string>()
    for (const r of rows) for (const t of r.tags) set.add(t)
    return Array.from(set).join(', ')
  },
}
```

## Performance

Aggregation runs once per group-by change, NOT per scroll frame. The
cost is O(n) for `count` / `sum` / `avg`, O(n log n) for `min` / `max`
because the engine sorts to find the extreme.

For a 100k-row dataset grouped by two columns with three aggregators,
the pipeline adds ~36 ms to the initial paint (see
[Performance benchmarks](./benchmarks.md)). After that, scroll is
unaffected - the renderer hands each visible group its precomputed
value.

## Group expansion state

`expanded` is owned by the engine by default; you can hoist it for
saved-views purposes:

```svelte
<SvGrid
  ...
  expanded={controlledExpanded}
  onExpandedChange={(next) => (controlledExpanded = next)}
/>
```

The shape is `Record<groupId, boolean>` where `groupId` is the path
through the hierarchy (`'Engineering > Senior'`).

## Group sort vs leaf sort

The sort UI sorts within the active sort scope:

- When grouping is OFF, sort applies to all rows.
- When grouping is ON, sort applies WITHIN each group - groups stay
  in alphabetical (or group-aggregator) order; only the leaves inside
  each group reorder.

To sort the groups themselves by their rolled-up value, set the sort
on the aggregated column AFTER setting the group-by. The grid
recognises that the column is aggregated and sorts the group rows
instead of the leaves.

## Filtering vs grouping

Filters run BEFORE grouping (see [Architecture](./architecture.md) for
the pipeline order). The aggregator only sees rows that passed the
filter. This is what makes "department salary sum, filtered to active
employees only" work without any extra config.

## Pivot vs group-by

When the question is "group by row dimensions, also group by column
dimensions, also pick aggregators per measure" - that's a pivot. The
[pivot helpers](./pivot.md) build a different data structure
optimised for that shape. Use group-by when you only roll up rows;
use pivot when you also roll up columns.

## See also

- [Architecture overview](./architecture.md) - where grouping sits in
  the pipeline.
- [Pivot tables](./pivot.md) - the column-axis version.
- [Row pagination](./rows/row-pagination.md) - the paging stage runs
  AFTER grouping, so group rows count toward the page size.
- [Demo #07 Grouping + aggregation](https://svgrid.com/#/demos/07-grouping-aggregation)
  - the source for the example above.

## Frequently asked questions

### How do I group rows in SvGrid?

Register `columnGroupingFeature` and group by one or more columns. Each group
renders a collapsible header row, and you attach an `aggregator` per column to
compute sum, avg, count, min, max, or a custom reducer at every group level.

### What aggregation functions does SvGrid support?

Built-in `sum`, `avg`, `count`, `min`, and `max`, plus custom aggregators -
any function that reduces a group's rows to a single value. Aggregates compute
at each group level and at the grand-total footer.

### Is grouping the same as a pivot table?

No. Grouping rolls rows up along the row axis. A pivot table also spreads a
field across the column axis with nested headers - that is the `sv-grid-pro`
pivot model. See [Pivot tables](./pivot.md) for the column-axis version.

<!-- =================================================================
     /help/grouping/aggregators  (community)
     ================================================================== -->

# Group aggregators

When grouping is active, each group row can show a rolled-up value per column -
the sum of revenue, the average score, the count of deals. SvGrid does this
declaratively: set `aggregate` on a column and the group header shows the
result, formatted with that column's own `format`.

```svelte
<script lang="ts">
  import { SvGrid, tableFeatures, columnGroupingFeature, type ColumnDef } from 'sv-grid-community'

  const features = tableFeatures({ columnGroupingFeature })

  const columns: ColumnDef<typeof features, Row>[] = [
    { field: 'region', header: 'Region' },
    { field: 'revenue', header: 'Revenue', aggregate: 'sum', format: { type: 'currency', currency: 'USD' } },
    { field: 'winRate', header: 'Win rate', aggregate: 'avg', format: { type: 'percent' } },
  ]
</script>

<SvGrid {data} {columns} {features} groupable />
```

## Built-in reducers

| `aggregate`       | Result                                              |
| ----------------- | --------------------------------------------------- |
| `'sum'`           | Sum of the finite numeric values.                   |
| `'avg'`           | Mean of the finite numeric values.                  |
| `'min'` / `'max'` | Smallest / largest value.                           |
| `'count'`         | Number of leaf rows in the group.                   |
| `'countDistinct'` | Number of distinct values.                          |
| `'extent'`        | `"min – max"` range string.                         |
| `'first'`         | The first leaf row's value (e.g. a shared label).   |

Non-numeric and empty cells are ignored by the numeric reducers; an all-empty
group yields no value (the header chip is hidden).

## Custom aggregators

Pass a function for anything the built-ins don't cover - weighted average,
median, percentile, distinct-with-rules. It receives the finite numeric values
and the raw leaf rows:

```ts
const median = (vals: number[]) =>
  vals.length ? [...vals].sort((a, b) => a - b)[Math.floor(vals.length / 2)] : 0

const columns = [
  { field: 'score', header: 'Median score', aggregate: median },
  // weighted average using two columns off the raw rows:
  {
    field: 'rate',
    header: 'Blended rate',
    aggregate: (_vals, rows: Row[]) => {
      const w = rows.reduce((s, r) => s + r.weight, 0)
      return w ? rows.reduce((s, r) => s + r.rate * r.weight, 0) / w : 0
    },
  },
]
```

## Notes

- Aggregates roll up **all leaf rows** under a group, at every nesting level.
- The aggregated value is stored on the group row, so
  `api.getDisplayedRows()` and `row.getCellValueByColumnId(id)` return it too -
  handy for exporting group totals.
- The reducer is exported as `applyGroupAggregate(agg, columnId, rows)` for
  reuse outside the grid.

See the live [Group aggregators](https://sv-grid.com/demos/142-group-aggregators)
demo.

<!-- =================================================================
     /help/i18n-rtl  (community)
     ================================================================== -->

# Internationalisation & RTL

The grid is locale-agnostic by design: every text label is yours to
translate, every formatted value goes through `Intl`, and right-to-left
layout flips via standard CSS logical properties.

Try the live RTL + i18n demo - switch between six locales (en, de,
fr-CA, ja, ar, he); the headers, dates, currencies, and the grid's
own scrollbar position all flip:

<div data-docs-demo="38-rtl-i18n" data-height="540"></div>

## What ships translated

**Nothing.** The grid has no built-in strings to translate. Every
visible string in the grid comes from one of three places:

1. Your column `header` strings.
2. Your cell snippet content.
3. The `Intl.NumberFormat` / `Intl.DateTimeFormat` output the grid
   uses for `format: { type: 'number' | 'currency' | 'percent' | 'date' }`.

If you see an English string in the grid that isn't covered by one of
the three, it's a bug - please file it. (The unlicensed Pro
watermark and the console nudge are the only literal strings the
package itself emits, and both are off when a license key is set.)

## Number, currency, date formatting

The built-in `format` config calls `Intl` under the hood. Locale is
inherited from `<html lang="...">` by default; override per-column:

```ts
const columns: ColumnDef<F, Order>[] = [
  // Inherits the document locale (most apps want this).
  { field: 'total', header: 'Total',
    format: { type: 'currency', currency: 'USD' } },

  // Pin to a specific locale - useful for tables of money that should
  // ALWAYS read as USD-grouped regardless of viewer.
  { field: 'usdTotal', header: 'Total (USD)',
    format: { type: 'currency', currency: 'USD', locales: 'en-US' } },

  // Custom Intl options.
  { field: 'createdAt', header: 'Created',
    format: {
      type: 'date',
      pattern: 'long',
      options: { dateStyle: 'medium', timeStyle: 'short' },
    },
  },
]
```

`locales` accepts the same string or array the `Intl` constructors do.
For mixed-locale columns inside a single grid, pass an explicit
`locales`.

## Translating headers and cell content

Use whatever i18n library your app already runs. The grid's only
expectation is "a string, or a render template that returns one":

```svelte
<script lang="ts">
  import { t } from 'svelte-i18n'

  const columns: ColumnDef<F, Order>[] = [
    { field: 'orderId', header: $t('grid.orderId') },
    { field: 'total',   header: $t('grid.total') },
  ]
</script>
```

Because `header` is a string (or a snippet), the column definition
re-evaluates whenever your translation store updates - no extra
re-mount required.

For dynamically-translated cells, use `renderSnippet`:

```svelte
{#snippet StatusCell(props: { row: Order })}
  <span class={`status-${props.row.status}`}>
    {$t(`order.status.${props.row.status}`)}
  </span>
{/snippet}

const columns = [
  { field: 'status', header: $t('grid.status'),
    cell: (ctx) => renderSnippet(StatusCell, { row: ctx.row.original }) },
]
```

## Right-to-left (RTL)

RTL is a single attribute. Set `dir="rtl"` on the `<html>` element (or
on the grid's container) and the layout flips:

```svelte
<html dir={locale.startsWith('ar') || locale.startsWith('he') ? 'rtl' : 'ltr'}>
```

The grid uses logical properties (`inset-inline-start`,
`inset-inline-end`, `padding-inline-start`, etc.) for every position
that depends on direction, including:

- The vertical scrollbar (slides to the left in RTL).
- Column pinning sticky positions.
- The filter row inputs.
- The fill handle on the active cell.
- Sort indicator + filter menu button alignment in headers.

No prop flips; no JS branch. If your layout doesn't flip, look at
your own CSS first - explicit `left` / `right` in your styles will
override the grid's logical-property choices.

### Mixed-direction text

Numbers, currency, and dates inside RTL cells often need an
`<bdi>` wrap so the writing direction doesn't get scrambled by the
surrounding RTL context:

```svelte
{#snippet AmountCell(props: { row: Order })}
  <bdi class="tabular-nums">{fmtMoney(props.row.amount)}</bdi>
{/snippet}
```

The built-in `format` configs already wrap their output - this only
matters for your custom snippets.

## Pluralisation + cardinal rules

`Intl.PluralRules` covers the cases ICU MessageFormat usually
handles. The grid never pluralises on your behalf - your i18n
library should. A common pattern in the gallery demos:

```ts
const status = api.getDisplayedRows().length === 1
  ? '1 result'
  : `${api.getDisplayedRows().length} results`
```

For more languages than "English", use a real plural-rules library:

```ts
const pr = new Intl.PluralRules(locale)
const key = pr.select(count)                    // 'one' | 'other' | ...
const message = i18n[locale][`result_${key}`]
```

## Column ordering by locale

A column called "Cancel" in English might be "Annuler" in French - or
"Stornieren" in German. If users want to find "Cancel" first when
sorting columns alphabetically, sort the column list with
`Intl.Collator`:

```ts
const collator = new Intl.Collator(locale)
const sorted = [...columns].sort((a, b) =>
  collator.compare(String(a.header ?? a.id), String(b.header ?? b.id)),
)
```

The grid never reorders columns on its own (except through
`api.addColumn(..., position)`), so locale-aware sorting is your call.

## CJK column widths

CJK glyphs (Chinese, Japanese, Korean) are roughly double the width
of Latin characters at the same point size. If your default
`columnWidth` was tuned for English, CJK columns will look cramped.

Two options:

1. **Set wider defaults when a CJK locale is active.** A `columnWidth`
   of 180 reads ~10 characters in CJK, vs ~20 in Latin.

   ```ts
   const isCJK = ['ja', 'zh', 'ko'].some((l) => locale.startsWith(l))
   const columns: ColumnDef<F, T>[] = baseColumns.map((c) => ({
     ...c,
     width: c.width ? c.width * (isCJK ? 1.3 : 1) : undefined,
   }))
   ```

2. **Let the user resize.** All grids ship with column resize handles;
   if you let the user save their layout (see [Saved views](./saved-views.md))
   you only need to get the default close, not perfect.

## Date / time picker editors

The `editorType: 'date'` editor uses the browser's native
`<input type="date">`. Locale + first-day-of-week + 24h vs 12h come
from the browser. If you need locked-down behaviour across locales,
swap in a custom editor via [Custom header components](./columns/custom-header-components.md)
+ a custom cell snippet for the editing path.

## A11y interaction with i18n

- Update `<html lang="...">` whenever the locale changes. Screen
  readers pick the right voice from this attribute.
- Update `<html dir="...">` whenever the script flips.
- Keep `aria-label`s in the user's locale; the grid never overrides
  yours.

## See also

- [Tailwind integration](./tailwind.md) - the `--sg-*` tokens and how
  they interact with `dir="rtl"`.
- [Accessibility](./accessibility.md) - all of the above respects
  forced-colors / reduced-motion / screen-reader announcements per
  locale.
- [Demo #38 RTL + i18n](https://svgrid.com/#/demos/38-rtl-i18n)
  - full locale + direction toggle reference.

## Frequently asked questions

### Does SvGrid support right-to-left (RTL) languages?

Yes. Layout flips via standard CSS logical properties, so setting `dir="rtl"` on
a container reverses the grid - columns, scrolling, and pinning included - with
no special configuration.

### How do I localize the grid?

The grid is locale-agnostic: every text label is yours to translate, and every
formatted value (number, currency, percent, date) goes through `Intl` with the
locale you pass. Wire your own i18n strings into headers and custom cells.

### Does SvGrid format numbers and dates per locale?

Yes, through cached `Intl` formatters. Set a column's `format` and the locale,
and values render with the correct separators, currency symbols, and date
patterns automatically.

<!-- =================================================================
     /help/import  (pro)
     ================================================================== -->

# Data import - Pro

The sister to [data export and printing](./export.md). Read an Excel
file, CSV/TSV blob, or JSON array in the browser and produce a typed
preview of every parsed row - including per-cell validation errors -
before any data lands in the grid. Ships in the paid
**[sv-grid-pro](https://www.npmjs.com/package/sv-grid-pro)** add-on.

Click **Preview from text** below to run the bundled sample through
the parser + validator, then **Commit** to push the clean rows into
the grid:

<div data-docs-demo="53-excel-import" data-height="560"></div>


## What it is

`installPro(api)` adds one async method to your `SvGridApi`:

```ts
api.importData(opts): Promise<ImportResult<TData>>
```

The call:

1. Parses the file or text into a typed row set.
2. Maps source columns to your grid's fields via an optional
   `columnMap`.
3. Runs each row through your validator (if you give one).
4. Either **returns the result for you to preview**, or **commits the
   rows into the grid** via `api.addRows(...)` when `commit: true`.

The grid never tries to be a full Excel reader; it handles the shape
Excel, Numbers, Google Sheets, and Apache POI produce by default. For
exotic features (pivot tables embedded in the file, multi-sheet
workbooks, conditional formatting), pre-process server-side and feed
the result through this API.

## When to use it

- **Onboarding flows** where customers upload a spreadsheet to seed
  the app.
- **Bulk edit** workflows where the user downloads a CSV via
  `api.exportData(...)`, edits in Excel, and re-uploads.
- **Pipeline integrations** where another tool dumps an xlsx and your
  app surfaces it for review.

If you control the file format end-to-end and just need server -> grid
data, skip the importer and call `api.addRows(...)` directly with the
parsed rows. The importer's value is in the **review UX** -
column-mapping, validation, error preview - not the parser itself.

## Minimal example

```svelte
<script lang="ts">
  import { SvGrid, tableFeatures, rowSortingFeature, type SvGridApi, type ColumnDef } from 'sv-grid-community'
  import { installPro, setLicenseKey, type ProGridApi } from 'sv-grid-pro'

  setLicenseKey('SVPRO-XXXX-XXXX-XXXX')

  type Order = { orderId: number; customer: string; total: number }
  let rows = $state<Order[]>([])
  let api = $state<ProGridApi<typeof features, Order> | null>(null)

  const features = tableFeatures({ rowSortingFeature })
  const columns: ColumnDef<typeof features, Order>[] = [
    { field: 'orderId',  header: 'Order ID' },
    { field: 'customer', header: 'Customer' },
    { field: 'total',    header: 'Total', format: { type: 'currency', currency: 'USD' } },
  ]

  async function onFile(e: Event) {
    const file = (e.currentTarget as HTMLInputElement).files?.[0]
    if (!file || !api) return
    const result = await api.importData({
      file,
      format: 'auto',
      columnMap: { 'Order #': 'orderId', 'Customer Name': 'customer', 'Total': 'total' },
      validator: (row) => {
        const errs = []
        if (!row.orderId) errs.push({ field: 'orderId', message: 'required' })
        if (row.total < 0) errs.push({ field: 'total', message: 'must be >= 0' })
        return errs
      },
    })
    if (result.errors.length === 0) {
      api.addRows(result.rows, 'bottom')
    } else {
      // Render result.errors in your UI for the user to fix.
      console.warn(result.errors)
    }
  }
</script>

<input type="file" accept=".xlsx,.csv,.tsv,.json" onchange={onFile} />
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  onApiReady={(next) => (api = installPro(next))}
/>
```

## Supported formats

| Format | Source type            | Peer dependency | Notes                                                              |
| ------ | ---------------------- | --------------- | ------------------------------------------------------------------ |
| `xlsx` | `File` / `Blob`        | `jszip`         | First sheet only. Strings, numbers, booleans, dates as ISO strings. |
| `csv`  | `File` / `Blob` / `string` | none        | RFC 4180-ish: quoted fields, embedded newlines, escaped quotes.    |
| `tsv`  | `File` / `Blob` / `string` | none        | Same as CSV with `\t` as separator.                                |
| `json` | `File` / `Blob` / `string` | none        | Top-level array of objects. Column union taken across first ~50 rows. |
| `auto` | any                    | maybe `jszip`   | Format is sniffed from file extension or first character of text. |

The xlsx parser shares the `jszip` peer dependency with xlsx export, so
if you already export to Excel you don't add a second peer for import.

## Column mapping

Pass a `columnMap` from **source header** to **target field**:

```ts
await api.importData({
  file,
  columnMap: {
    'Order #':       'orderId',     // rename
    'Customer Name': 'customer',
    'Customer Email': 'email',
    'Internal Note': null,           // drop this column entirely
  },
})
```

Source headers not listed in `columnMap` fall through to a default
mapping: lowercase + collapse whitespace to underscores + strip
non-alphanumerics. So `"Order ID"` becomes `order_id`. If that's not
what you want, list it explicitly.

Set a column's map entry to `null` to drop it from the parsed rows
entirely - useful for stripping PII you don't want to land in the
client-side grid.

## Type coercion

The parser walks every cell value through a small set of regex-based
heuristics:

| Source value           | Becomes      |
| ---------------------- | ------------ |
| `true` / `false`       | boolean      |
| `123`, `-45.6`, `1e3`  | number       |
| `$1,234.56`            | `1234.56`    |
| `"1,234,567"`          | `1234567`    |
| `2024-03-15`           | string (ISO date) |
| `2024-03-15T12:30:00Z` | string (ISO datetime) |
| empty cell             | `''`         |

The grid columns then apply their own format / parsing on top. If you
want fully strict types, run them through your `validator` and reject
anything that didn't coerce the way you expected.

## Validation

Validators receive each parsed row plus its index. Return an array of
`{ field, message }` errors:

```ts
function validator(row: Order, rowIndex: number) {
  const errs = []
  if (row.total < 0) errs.push({ field: 'total', message: 'must be >= 0' })
  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(row.email))
    errs.push({ field: 'email', message: 'invalid email' })
  return errs
}
```

The errors land in `result.errors` with `rowIndex` (0-based in the
output, *excluding* the header row) and `field` so your preview UX can
highlight the offending cell.

## Preview vs commit

The default is **preview**: you get `{ headers, rows, errors, skipped,
total, format }` back and decide what to do.

Pass `commit: true` to skip the preview and append the rows directly,
with an optional `commitAt` ('top' | 'bottom' | numeric index). If
there are any validator errors, `commit: true` **silently refuses** to
write - your UI should always render `result.errors` regardless.

```ts
const r = await api.importData({ file, commit: true, commitAt: 'top' })
if (r.errors.length > 0) {
  // The commit was skipped. Re-render the import dialog with errors.
}
```

## Result shape

```ts
type ImportResult<TData> = {
  headers: string[]      // source headers verbatim
  rows: TData[]          // parsed, mapped, type-coerced rows
  errors: Array<{ rowIndex: number; field: string; message: string }>
  skipped: number        // rows skipped because they were entirely blank
  total: number          // total source rows (incl. blanks + bad rows)
  format: 'xlsx' | 'csv' | 'tsv' | 'json'
}
```

## Performance

The browser-side parser is O(file size). It walks the bytes once, no
regex backtracking, and pays one `JSON.parse` for JSON imports. For
files up to ~100k rows the parse + validate cycle stays under a few
hundred milliseconds on a typical laptop.

For larger files (>500k rows) we recommend a server-side ingest:
upload the file, stream it through your parser, and emit the result
back via the same `addRows` call. The importer's review UX still works
- just call it on a sample slice first.

## Gotchas

- **First sheet only.** xlsx imports return rows from `sheet1.xml`.
  Pick the right sheet server-side or convert the workbook before
  upload.
- **No formulas.** Cached formula values are read when present, but the
  parser doesn't evaluate uncached formulas.
- **No styles, comments, conditional formatting.** Just values.
- **Blank rows are skipped.** A row whose every cell is empty is
  counted in `skipped`, not `rows`.

## See also

- [Data export and printing](./export.md) - the round-trip partner.
- [Validation while editing](./editing/validation.md) - the same
  validator shape works for inline grid edits.
- [Demo 53 - Excel / CSV import](../../examples/src/demos/53-excel-import.svelte) - the demo this page
  documents.

## Frequently asked questions

### How do I import an Excel or CSV file into the grid?

With `sv-grid-pro`, read an xlsx file, CSV/TSV blob, or JSON array in the browser
and get a typed preview of every parsed row - including per-cell validation
errors - before any data lands in the grid. Nothing is uploaded; parsing happens
client-side.

### Does import validate the data?

Yes. Each parsed row runs through the same validator shape used for inline
editing, so you can surface per-cell errors in the preview and let the user fix
them before committing.

### Is import free?

No. Import ships in `sv-grid-pro`, alongside export and pivot. The free
Community package handles displaying and editing data you already have in
memory.

<!-- =================================================================
     /help/index  (community)
     ================================================================== -->

# SvGrid Help

Topic-oriented documentation for SvGrid. Each page is a focused
explanation of one feature with copy-paste code that runs against the
shipping library - written for SvGrid, not translated from another grid.

Start with [Getting Started](../getting-started.md) if you have not
already.

> **Tier badges.** Pages whose title ends with `- Pro` describe a
> feature that ships in the paid `sv-grid-pro` add-on. Everything else
> is part of the open-source `sv-grid-community` package. The same
> visual convention is used throughout this documentation.

Live reference - the trading-desk demo runs the full feature set at
real-world scale:

<div data-docs-demo="00-trading-desk" data-height="560"></div>

## Background

- [Why headless?](../why-headless.md) - what the headless core gives you and when to reach for it
- [Architecture overview](./architecture.md) - the three-layer model: your data, the engine, the renderer
- [Glossary](./glossary.md) - terminology used across the docs (accessor, snippet, row model, ...)
- [Tailwind integration](./tailwind.md) - re-theming the grid via `--sg-*` tokens, dark-mode wiring, what *not* to do
- [**Pro feature pack**](../pro/README.md) - landing page for the paid add-on; what's in it + how to license it
- [Data export and printing - Pro](./export.md) - Excel, PDF, CSV, TSV, HTML, and Print
- [Data import - Pro](./import.md) - Excel, CSV, TSV, and JSON import with column mapping + validation
- [AI assistant - Pro](./ai.md) - natural-language filter, smart fill, summarise, classify; bring-your-own model adapter
- [Pivot tables - Pro](./pivot.md) - `createPivotModel` + nested column headers; designer UI is a separate demo
- **Migrating to SvGrid** - column / API translation guides from other grids:
  [AG Grid](./migrating-from-ag-grid.md) ·
  [TanStack Table](./migrating-from-tanstack-table.md) ·
  [MUI X DataGrid](./migrating-from-mui-x.md) ·
  [Handsontable](./migrating-from-handsontable.md) ·
  [Glide Data Grid](./migrating-from-glide.md) ·
  [svelte-headless-table](./migrating-from-svelte-headless-table.md) ·
  [SVAR Svelte DataGrid](./migrating-from-svar-svelte-datagrid.md) ·
  [@vincjo/datatables](./migrating-from-vincjo-datatables.md) ·
  [Flowbite / Skeleton / shadcn tables](./migrating-from-ui-kit-tables.md) ·
  [Tabulator](./migrating-from-tabulator.md) ·
  [Grid.js](./migrating-from-gridjs.md) ·
  [React Data Grid](./migrating-from-react-data-grid.md) ·
  [PrimeVue / PrimeNG / PrimeReact](./migrating-from-primevue-datatable.md) ·
  [Kendo UI Grid](./migrating-from-kendo-grid.md) ·
  [DevExtreme](./migrating-from-devextreme.md) ·
  [Syncfusion](./migrating-from-syncfusion.md) ·
  [jqxGrid](./migrating-from-jqxgrid.md) ·
  [Smart.Grid](./migrating-from-smart-grid.md)

## Patterns & playbooks

- [Recipes / Cookbook](./recipes.md) - 20+ copy-paste patterns from sort/filter/paginate to inline edit + cascading totals to streaming, each paired with a live interactive demo
- [AI Smart Paste](./ai-smart-paste.md) - vCard / Markdown / signature-block / CSV parsing with email typo correction, phone normalization, and multi-language headers
- [Spreadsheet formulas](./spreadsheet-formulas.md) - in-cell `=SUM` / `=IF` / `=COUNTIF` with cell refs, ranges, cycle detection
- [Mobile / responsive card view](./mobile-card-view.md) - the same `$state` array driving a desktop grid and a touch-friendly card list
- [Conditional form schema](./conditional-form-schema.md) - declarative `when` rules for per-cell visibility and editability
- [Server-side data](./server-side-data.md) - paginated fetch, server-driven sort + filter, sparse infinite scroll (with velocity-aware chunk loading + abort guards)
- [Real-time / streaming updates](./real-time.md) - poll vs WebSocket, delta merge, pause-while-editing, backpressure
- [Grouping & aggregation](./grouping-aggregation.md) - built-in aggregators, custom group cells, group-vs-leaf sort, performance notes
- [Columns hierarchy + manager](./columns-hierarchy.md) - side-panel column tree with drag-to-reorder, collapsible groups, summary columns
- [State maintenance](./state-maintenance.md) - capture / apply, undo / redo, bookmarks, JSON IO, debounced auto-save
- [Saved views & persistence](./saved-views.md) - localStorage / server-side persistence, view migration, URL sharing
- [Internationalisation & RTL](./i18n-rtl.md) - locale-aware formatting, RTL layout flip, CJK column widths, mixed-direction safety

## Enterprise readiness

- [Security & supply chain](./security.md) - peer-dep table, CSP guidance, SBOM generation, vulnerability handling, data residency
- [Browser & runtime support](./browser-support.md) - tested browsers + versions, SSR runtimes, build tools, DOM-API requirements, mobile
- [Accessibility](./accessibility.md) - WAI-ARIA 1.2 grid pattern, WCAG 2.1 AA mapping, keyboard map, forced-colors + reduced-motion
- [Performance benchmarks](./benchmarks.md) - first paint, sustained scroll FPS, sort / filter / group, memory, bundle size, on a documented machine
- [Testing your grid](./testing.md) - unit tests against the engine, jsdom component tests, Playwright e2e, axe-core for a11y regressions
- [API stability & semver policy](./api-stability.md) - the promise we make to you about breaking changes + deprecation lifecycle
- [**API reference**](../reference/index.md) - exhaustive prop/method/type tables for `<SvGrid>`, `SvGridApi`, `ColumnDef`, features, and the Pro surface
- [API stability badges](./api-reference.md) - flat index of every Stable export with its tier badge
- [Changelog](../changelog.md) - reverse-chronological log of every shipped change
- [Error reference](./errors.md) - every typed error this surface throws, with the trigger and the fix

## Production checklist

A focused walkthrough for the questions enterprise teams ask before
shipping. Each link drops you straight into the relevant topic page.

| Concern                          | Reach for                                                                                          |
| -------------------------------- | -------------------------------------------------------------------------------------------------- |
| Performance with >10k rows       | [Performance benchmarks](./benchmarks.md) + [Row pagination](./rows/row-pagination.md)             |
| Server-side data                 | [Server-side data](./server-side-data.md) - paginated fetch, server-driven sort, sparse infinite scroll |
| Real-time / streaming updates    | [Real-time / streaming](./real-time.md) - delta merge, pause-while-editing, backpressure           |
| Tree / hierarchical data         | [Tree rows](./rows/tree-rows.md) - flat-array + expanded-map pattern, lazy load, keyboard nav      |
| Pivot / multi-level headers      | [Pivot tables](./pivot.md) + [Column groups](./columns/column-groups.md)                           |
| Grouping + aggregation           | [Grouping & aggregation](./grouping-aggregation.md) - built-in aggregators + custom group cells    |
| Inline editing with validation   | [Editing overview](./editing/overview.md) + [Validation while editing](./editing/validation.md)    |
| Theming + dark mode              | [Tailwind integration](./tailwind.md) - the `--sg-*` token list                                    |
| Accessibility / WAI-ARIA         | [Accessibility](./accessibility.md) - WCAG 2.1 AA mapping + keyboard map + forced-colors           |
| Internationalisation / RTL       | [Internationalisation & RTL](./i18n-rtl.md) - locales, formatting, mixed-direction safety          |
| Saved views / layout persistence | [Saved views](./saved-views.md) - localStorage / server-side persistence + migration               |
| Export to Excel / PDF / CSV      | [Data export and printing](./export.md)                                                            |
| Excel / CSV / JSON import        | [Data import](./import.md) - file picker -> column map -> preview -> commit                       |
| Add AI to the grid               | [AI assistant](./ai.md) - one provider adapter, four helpers                                       |
| Multi-app deployment licensing   | [Pricing](https://svgrid.com/#/pricing) - Multiple App License covers an org        |
| Testing the grid                 | [Testing your grid](./testing.md) + [Testing and quality](./testing-and-quality.md)                |

If a question is missing from this table, **press `Ctrl/Cmd + K`** in
the docs sidebar - the search box indexes every page's title, headings,
and body and ranks matches by where they hit.

## Core features

### Columns

- [Column definitions](./columns/column-definitions.md)
- [Updating definitions](./columns/updating-definitions.md)
- [Column state](./columns/column-state.md)
- [Column headers - styling & height](./columns/column-headers.md)
- [Column groups](./columns/column-groups.md)
- [Column sizing](./columns/column-sizing.md)
- [Column moving](./columns/column-moving.md)
- [Column pinning](./columns/column-pinning.md)
- [Column spanning](./columns/column-spanning.md)
- [Custom header components](./columns/custom-header-components.md)

### Rows

- [Row data](./rows/row-data.md)
- [Row sorting](./rows/row-sorting.md)
- [Row spanning](./rows/row-spanning.md)
- [Row pinning](./rows/row-pinning.md)
- [Row height](./rows/row-height.md)
- [Styling rows](./rows/styling-rows.md)
- [Row pagination](./rows/row-pagination.md)
- [Accessing rows](./rows/accessing-rows.md)
- [Row dragging](./rows/row-dragging.md)
- [Full-width rows](./rows/full-width-rows.md)
- [Tree rows (expand / collapse)](./rows/tree-rows.md)

### Cells

- [Getting values](./cells/getting-values.md)
- [Text formatting](./cells/text-formatting.md)
- [Cell components](./cells/cell-components.md)
- [Cell data types](./cells/cell-data-types.md)
- [Styling cells](./cells/styling-cells.md)
- [Highlighting changes](./cells/highlighting-changes.md)
- [Tooltips](./cells/tooltips.md)
- [Expressions](./cells/expressions.md)
- [View refresh](./cells/view-refresh.md)
- [Cell text selection](./cells/cell-text-selection.md)

### Filtering

- [Overview](./filtering/overview.md)
- [Text filter](./filtering/text-filter.md)
- [Number filter](./filtering/number-filter.md)
- [Date filter](./filtering/date-filter.md)
- [Set filter](./filtering/set-filter.md)
- [Filter conditions](./filtering/filter-conditions.md)
- [Applying filters](./filtering/applying-filters.md)
- [Filter API](./filtering/filter-api.md)
- [Custom column filters](./filtering/custom-column-filters.md)
- [Floating filters](./filtering/floating-filters.md)

### Editing

- [Overview](./editing/overview.md)
- [Start / stop editing](./editing/start-stop-editing.md)
- [Parsing values](./editing/parsing-values.md)
- [Saving values](./editing/saving-values.md)
- [Edit components](./editing/edit-components.md)
- [Provided cell editors](./editing/provided-editors.md)
- [Undo / redo](./editing/undo-redo.md)
- [Full-row editing](./editing/full-row.md)
- [Validation](./editing/validation.md)

## Conventions

Each topic page is structured as:

1. **What it is** - a one-sentence definition.
2. **When to use it** - the situation that calls for this feature.
3. **Minimal example** - copy-pasteable code that runs.
4. **Reference** - the relevant exports and prop names.
5. **Gotchas** - known limits, gaps, or things that surprise people.

Pages explicitly note when a feature is **not yet implemented** in the
community build so you know what you can rely on. The current
gap list is at [missing-features.md](./missing-features.md).

<!-- =================================================================
     /help/llm-grounding  (community)
     ================================================================== -->

# Use sv-grid docs as LLM context

This page is the "how do I make ChatGPT / Claude / Cursor write good
sv-grid code?" guide. Three pre-built artefacts ship with the docs
specifically so models can ground themselves in current, accurate
information instead of hallucinating from training data.

## The four files

| File                                     | Format     | Size   | Use for                                                                |
| ---------------------------------------- | ---------- | ------ | ---------------------------------------------------------------------- |
| [`/llms.txt`](/llms.txt)                 | Plain text | ~10 kB | First-pass context: the topic map with one-line summaries              |
| [`/llms-full.txt`](/llms-full.txt)       | Plain text | ~700 kB | Deep grounding: every doc page concatenated                            |
| [`/docs.json`](/docs.json)               | JSON       | ~80 kB | Programmatic crawling: section tree, per-page metadata, demo links     |
| [`/schemas/index.json`](/schemas/index.json) | JSON   | ~30 kB | Validation: machine-checkable shape of `ColumnDef`, `<SvGrid>` props, export options |

All four are regenerated on every commit by `tools/build-docs-index.mjs`
and `tools/build-schemas.mjs`. They live at the docs origin
(`https://svgrid.com/...`) so you can fetch them at runtime.

## Recipe 1: Drop into a custom GPT / Claude project

The simplest way. Both ChatGPT (custom GPTs) and Claude (projects)
let you upload reference files that ride along with every chat.

1. Save [`/llms-full.txt`](/llms-full.txt) locally.
2. In ChatGPT: *Create custom GPT → Configure → Knowledge → Upload files*.
3. In Claude: *Project → Project knowledge → Add document*.
4. Add this system instruction:

```
You are a sv-grid expert. Ground every answer in the attached
llms-full.txt. If a question references an API not in the document,
say so and ask the user to upgrade rather than inventing one. Prefer
the smallest working example. When showing columns, follow the
column-def.json schema exactly.
```

5. (Optional) Upload `column-def.json` and `svgrid-options.json`
   alongside so the model can self-check generated config.

That's it. The next time you ask "how do I export only selected rows
to xlsx?" the model answers from the doc text, not from its
year-old training cutoff.

## Recipe 2: Cursor / Continue / Cody rules file

Most IDE assistants honour a `.cursorrules` / `.continuerules` /
`.aider.conf.yml` file in the repo root. Drop in:

```
# .cursorrules

When generating sv-grid code:
- Read context from https://svgrid.com/llms.txt before answering.
- For column definitions, generate against
  https://svgrid.com/schemas/column-def.json (Draft 2020-12 JSON Schema).
- Use Svelte 5 runes ($state, $derived, $effect) - never legacy stores.
- Use `editorType: 'list'` with `editorOptions` for dropdowns,
  not raw <select> elements.
- Always type the grid as
  `SvGrid<typeof features, RowType>` so column inference works.
- The two npm packages are `sv-grid-community` (MIT) and `sv-grid-pro`
  (commercial). Never import from `@sv-grid/core` or `svelte-grid`,
  which are different projects.
```

## Recipe 3: Programmatic grounding in your own agent

If you're building a custom agent (OpenAI Agents SDK, Anthropic SDK,
LangChain, custom), fetch the docs once at boot:

```ts
const [topicMap, schemas] = await Promise.all([
  fetch('https://svgrid.com/llms.txt').then((r) => r.text()),
  fetch('https://svgrid.com/schemas/index.json').then((r) => r.json()),
])

const systemPrompt = `You write Svelte 5 code that uses sv-grid.

DOCS INDEX (use these URLs to look up specifics):
${topicMap}

SCHEMAS available for validation:
${JSON.stringify(schemas, null, 2)}

For deep API questions, fetch https://svgrid.com/llms-full.txt or
the specific page from the index above.`
```

Now hand the model a tool that can fetch arbitrary `/docs.json` paths
on demand, and it can answer any sv-grid question with current data.

## Recipe 4: MCP server (best for daily-driver chat)

If your workflow centers on Claude Desktop / Cursor / Zed, the
[MCP server](./mcp-server.md) is the single line of config that
exposes all four files PLUS callable tools (`scaffoldColumns`,
`validateColumns`, `previewExport`). Skip Recipes 1-3 and use the
MCP server instead.

## What's IN the grounding files

Every file is exhaustive but tightly scoped to sv-grid surface area:

- **API surface**: every prop on `<SvGrid>`, every method on
  `SvGridApi`, every field on `ColumnDef`
- **Features**: when to use sorting / filtering / grouping / pagination
  feature toggles, and the trade-offs
- **Pro tier**: export, import, pivot, AI helpers - each documented as
  if it were free, with the licensing call-out at the top of the page
- **Recipes**: 25+ copy-paste patterns from the cookbook
- **Migrations**: how to translate AG Grid / TanStack Table / MUI X
  DataGrid / Handsontable / Glide concepts
- **Errors**: every typed error the library throws, with the trigger
  and the fix

## What's NOT in the grounding files

- **Internal implementation**: virtualizer math, headless engine
  pipeline internals - not part of the public surface
- **Future / roadmap**: deliberately excluded so the model never
  confuses ambition with reality
- **CSS class hashes**: Svelte mangles class names. The
  `--sg-*` tokens are stable and documented; the class names are not.

## Keeping the grounding fresh

Re-fetch on every model turn for chat tools; cache for ~24h for
agent loops. The docs are versioned - if you pin to a specific
version, append a `?v=1.6.0` query string when fetching from the
origin (rejected if the major changes; we serve a 410).

## See also

- [MCP server](./mcp-server.md) - the easiest way to wire all this in
- [Agents](./agents.md) - building an agent that DRIVES the grid (not just describes it)
- [API stability](./api-stability.md) - what we promise to keep stable across versions

<!-- =================================================================
     /help/mcp-server  (community)
     ================================================================== -->

# MCP server

The sv-grid MCP server lets AI clients (Claude Desktop, Cursor, Zed,
Continue, custom agents) query the documentation, scaffold column
definitions, and preview exports - all grounded in the same schemas
the library ships with. No API key required; everything runs locally
against your installed copy.

> **What is MCP?** Model Context Protocol is the open standard
> ([modelcontextprotocol.io](https://modelcontextprotocol.io)) for
> exposing tools / resources / prompts to LLM clients. sv-grid ships an
> MCP server out of the box so the model your team already uses can
> "see" the grid without you having to copy-paste docs into prompts.

## Install

```bash
# Inside any project that already depends on sv-grid-community
pnpm add -D @sv-grid/mcp-server
```

The server is a Node binary. Run it on demand from the package's
`bin` field - no daemon to maintain.

## Wire it into your AI client

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "sv-grid": {
      "command": "npx",
      "args": ["-y", "@sv-grid/mcp-server"]
    }
  }
}
```

Restart Claude Desktop. Type `@sv-grid` in any chat to confirm the
tools are exposed.

### Cursor

`Settings → MCP → Add new MCP server`:

```json
{ "command": "npx", "args": ["-y", "@sv-grid/mcp-server"] }
```

### Zed

`~/.config/zed/settings.json`:

```json
{
  "context_servers": {
    "sv-grid": { "command": { "path": "npx", "args": ["-y", "@sv-grid/mcp-server"] } }
  }
}
```

### Custom agents (OpenAI Agents SDK, Anthropic SDK, LangChain)

Point your client's MCP transport at:

```
npx -y @sv-grid/mcp-server
```

Any client that speaks MCP stdio works.

## Tools exposed

The server registers six tools. All return structured JSON; none
require an API key or network access.

### `searchDocs`

Ground the model in the doc set without dumping the whole corpus.

```ts
searchDocs({ query: string, limit?: number }):
  Array<{ path, title, summary, score, snippet }>
```

Backed by the same `docs.json` manifest you can fetch directly.

### `getDocPage`

Pull the full markdown of one page by URL or path.

```ts
getDocPage({ path: '/help/pivot.md' }): { title, source, demoIds }
```

### `scaffoldColumns`

Generate a `ColumnDef[]` from a sample row. Picks reasonable widths,
inferred editor types, sensible header labels, and format options for
numbers / currencies / ISO dates.

```ts
scaffoldColumns({
  sampleRow: { id: 'r1', sellDate: '2026-05-12', price: 1499.99, currency: 'USD' },
  inferFormat?: boolean,    // default true
  language?: 'ts' | 'js',   // default 'ts'
})
// → { code: string, columns: ColumnDef[] }
```

### `validateColumns`

Check a `ColumnDef[]` payload against `column-def.json`. Returns the
list of issues with file / line hints (when the input is a code
string). Useful for agents that generate columns and want a self-check
before showing the result.

```ts
validateColumns({ columns: ColumnDef[] | string }):
  { valid: boolean, issues: Array<{ path, message, severity }> }
```

### `previewExport`

Dry-run an `api.exportData({...})` call. Returns the rows + header
layout the exporter WOULD write, without actually triggering a
download. Useful when an agent is composing a multi-sheet export and
wants to verify column ordering before committing.

```ts
previewExport({ format: 'xlsx', rows: [...], columns: [...] }):
  { sheets: Array<{ label, header, rows }> }
```

### `listDemos`

Returns every demo in `examples/src/demos/` with its title, blurb,
category, source path, and the prompt sidecar (see
[LLM grounding](./llm-grounding.md)).

```ts
listDemos({ category?: string }):
  Array<{ id, title, blurb, category, source, prompt }>
```

## Resources exposed

In addition to tools, the server exposes three MCP **resources** -
read-only documents the client can browse:

| URI                            | Content                                           |
| ------------------------------ | ------------------------------------------------- |
| `svgrid://docs/llms.txt`       | Topic map (see [llms.txt](/llms.txt))             |
| `svgrid://docs/llms-full.txt`  | Concatenated full text of every doc              |
| `svgrid://docs/manifest`       | `docs.json` route manifest                        |
| `svgrid://schemas/column-def`  | JSON Schema for `ColumnDef`                       |
| `svgrid://schemas/svgrid-options` | JSON Schema for `<SvGrid>` props              |
| `svgrid://schemas/export-options` | JSON Schema for `api.exportData({...})`        |

## Prompts exposed

Pre-built MCP prompts you can invoke directly from a chat:

- **`/svgrid:scaffold-grid`** - paste a sample row, get a complete
  `<SvGrid>` + `tableFeatures` + `ColumnDef[]` setup
- **`/svgrid:refactor-to-pivot`** - hand it a flat-grid component, get
  a pivot-grid version
- **`/svgrid:wire-server-side`** - convert client-side data to a
  server-side adapter with sort / filter / paginate round-trips

## Verifying it works

After wiring the server, ask your model: *"What MCP tools do you have
from sv-grid?"* You should see all six tools listed. If not, check
your client's MCP log; the most common issue is `npx` not being on
PATH (use the absolute path to the binary instead).

## Security model

- The server runs **locally**. No telemetry, no outbound network calls.
- File reads are scoped to your project's `node_modules/@sv-grid/*`
  and any `docs/` folder you explicitly pass via the `--docs <dir>` flag.
- `scaffoldColumns` and `previewExport` are pure functions - they
  inspect input and emit text. They never write to disk or fetch from
  the network.
- See [security](./security.md) for the general supply-chain posture.

## Building your own MCP integrations

The same `docs.json` + JSON Schemas + `llms.txt` files the server uses
are also accessible directly from your docs site
([https://svgrid.com](https://svgrid.com)):

```ts
const docs    = await fetch('https://svgrid.com/docs.json').then((r) => r.json())
const schemas = await fetch('https://svgrid.com/schemas/index.json').then((r) => r.json())
const llms    = await fetch('https://svgrid.com/llms-full.txt').then((r) => r.text())
```

If you don't want to run the MCP server, building these into your
agent's system prompt gives ~80% of the same value.

## See also

- [LLM grounding](./llm-grounding.md) - the same files used by the MCP server, but documented for direct LLM consumption
- [Agents](./agents.md) - how to build an AI agent that drives the live grid
- [AI assistant - Pro](./ai.md) - the in-grid AI features (filter / smart-fill / classify / summarise)

## Frequently asked questions

### What is the sv-grid MCP server?

A Model Context Protocol server that lets AI clients (Claude Desktop, Cursor,
Zed, Continue, custom agents) query SvGrid's documentation, scaffold column
definitions, and preview exports - all grounded in the schemas the library
ships with, so the model answers from current facts instead of guessing.

### Do I need an API key to run it?

No. The MCP server runs locally against your installed copy of SvGrid. There is
no key and no external call.

### How does it help AI assistants write better SvGrid code?

It exposes example sources, the docs, and the API reference as MCP tools, so the
assistant retrieves accurate, version-pinned answers rather than hallucinating
an API from training data.

<!-- =================================================================
     /help/migrating-from-ag-grid  (community)
     ================================================================== -->

# Migrating from AG Grid to SvGrid

If you tried AG Grid on a Svelte 5 project - via `ag-grid-svelte`, the
old `ag-grid-community/svelte`, or a hand-rolled wrapper - you probably
hit the same friction everyone hits: the bridge between AG Grid's
React/Angular-first API and Svelte 5 runes is brittle, the bundle is
heavy, and the Enterprise pricing only makes sense at scale.

This page is a 30-minute migration recipe from AG Grid to SvGrid. It
covers what maps 1:1, what's different by design, and what you'll lose.
We tell you when **not** to switch at the bottom.

## TL;DR

| | AG Grid Community | AG Grid Enterprise | SvGrid Community | sv-grid-pro |
| --- | --- | --- | --- | --- |
| **License** | MIT | Commercial (~$999/dev/yr) | **MIT** | $599/dev/yr (single app) or $999/dev/yr (multi app) |
| **Svelte 5 native** | ❌ (wrapper) | ❌ (wrapper) | ✅ | ✅ |
| **Bundle (gzipped)** | ~250 KB | ~400 KB | ~7.5 KB headless / ~42 KB full | lazy-loaded subpaths |
| **Sorting / filtering / grouping** | ✅ | ✅ | ✅ | (in Community) |
| **Master/detail, tree, range select** | ❌ Enterprise only | ✅ | ✅ (free) | (in Community) |
| **Excel export** | ❌ | ✅ Enterprise | ❌ | ✅ |
| **PDF / CSV / TSV / HTML export** | ❌ | Partial | ❌ | ✅ |
| **Print view** | ❌ | ❌ | ❌ | ✅ |
| **Set filter / Excel-style filter menu** | ❌ Enterprise | ✅ | ✅ (free) | (in Community) |

The headline: **SvGrid Community gives you most of AG Grid Enterprise's
features for free**, and `sv-grid-pro` adds the export + print pack for
~40% less than AG Grid Enterprise. The catch is Svelte-only and a much
smaller ecosystem.

## Mental model - what changes

AG Grid is one big object you configure declaratively. SvGrid is a
**headless engine** (`createSvGrid`) with an optional **render
component** (`<SvGrid>`) on top - the same split TanStack Table made
popular. You can use either layer; most projects use the render
component.

```svelte
<!-- AG Grid (via a Svelte wrapper) -->
<AgGridSvelte
  gridOptions={{
    rowData: rows,
    columnDefs: columns,
    onGridReady: (params) => (gridApi = params.api),
  }}
/>

<!-- SvGrid -->
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  onApiReady={(api) => (gridApi = api)}
/>
```

Three things to note:

1. **No giant `gridOptions` blob.** Each capability is a top-level prop.
2. **Features are opt-in.** You pass a `features` object built with
   `tableFeatures({...})` - only the features you list ship JS.
3. **`onApiReady`** gives you a typed `SvGridApi` that is roughly the
   AG Grid `gridApi` equivalent (see the API-mapping table below).

## Column definitions - direct translation

The shapes are similar enough that you can usually translate by hand
without thinking too hard.

```ts
// AG Grid
const columnDefs: ColDef[] = [
  { field: 'name', headerName: 'Name', sortable: true, filter: true, width: 200 },
  { field: 'price', headerName: 'Price', type: 'numericColumn',
    valueFormatter: ({ value }) => `$${value.toFixed(2)}` },
  { field: 'date', headerName: 'Date',
    valueGetter: ({ data }) => new Date(data.date).toISOString().slice(0, 10) },
  { field: 'status', headerName: 'Status',
    cellRenderer: StatusCellRenderer,
    cellRendererParams: { onChange: handleStatusChange } },
]
```

```ts
// SvGrid
import { renderComponent, type ColumnDef } from 'sv-grid-community'
import StatusCell from './StatusCell.svelte'

const columns: ColumnDef<typeof features, Row>[] = [
  { field: 'name', header: 'Name', width: 200 }, // sortable + filterable by default
  { field: 'price', header: 'Price',
    format: { type: 'currency', currency: 'USD' } },
  { field: 'date', header: 'Date',
    format: { type: 'date', pattern: 'y-m-d' } },
  { field: 'status', header: 'Status',
    cell: renderComponent(StatusCell, (ctx) => ({
      value: ctx.getValue(),
      onChange: handleStatusChange,
    })),
  },
]
```

### Property mapping

| AG Grid | SvGrid | Notes |
| --- | --- | --- |
| `field` | `field` | Same. |
| `headerName` | `header` | Accepts a string or a snippet/component. |
| `width` | `width` | Same. |
| `minWidth` / `maxWidth` | `minWidth` / `maxWidth` | Same. |
| `sortable: true` | (default) | Sorting is on when `rowSortingFeature` is registered. |
| `filter: true` | (default) | Filtering is on when `columnFilteringFeature` is registered. |
| `valueFormatter` | `format: { ... }` | Built-in types: `number`, `currency`, `percent`, `date`. For custom, use `cell`. |
| `valueGetter` | `accessorFn` | Returns the value for sorting/filtering. |
| `cellRenderer` + `cellRendererParams` | `cell: renderComponent(C, ctx => props)` | One call, type-checked. |
| `cellEditor: 'agTextCellEditor'` | `editorType: 'text'` | Built-in: `text`, `number`, `checkbox`, `date`. |
| `editable: true` | `enableInlineEditing` prop on `<SvGrid>` | Per-grid, not per-column. (Per-column control on the roadmap.) |
| `pinned: 'left'` / `'right'` | Right-click column menu → Pin | Set programmatically via the api. |
| `rowGroup: true` | Via `setGroupBy([colId])` | See Grouping below. |
| `aggFunc: 'sum'` | `aggregation: 'sum'` | Built-in: `sum`, `avg`, `min`, `max`, `count`. |

## Feature registration - the one new thing

AG Grid auto-enables most features; you turn them off. SvGrid is the
opposite - features are opt-in. The result is a smaller bundle.

```ts
import {
  tableFeatures,
  rowSortingFeature,
  columnFilteringFeature,
  columnGroupingFeature,
  rowExpandingFeature,
  rowPaginationFeature,
  rowSelectionFeature,
} from 'sv-grid-community'

const features = tableFeatures({
  rowSortingFeature,
  columnFilteringFeature,
  rowSelectionFeature,
  // omit any you don't need - their code won't ship
})
```

Pass `features` to `<SvGrid>` once. From then on the grid behaves like
AG Grid's `enableSorting`, `enableFilter`, `rowSelection`, etc. are all
on for the registered features.

## API mapping (`gridApi` → `SvGridApi`)

You get the SvGrid API from `onApiReady` (equivalent to AG Grid's
`onGridReady`).

| AG Grid `gridApi.X()` | SvGrid `api.X()` |
| --- | --- |
| `setRowData(rows)` | (declarative - just update `data` prop) |
| `addRow(row)` / `applyTransaction({ add: [row] })` | `api.addRow(row)` / `api.addRows(rows)` |
| `applyTransaction({ remove: [row] })` | `api.removeRow(rowIndex)` |
| `getValue(colId, rowNode)` | `api.getCellValue(rowIndex, columnId)` |
| `setValue(...)` | `api.setCellValue(rowIndex, columnId, value)` |
| `setColumnVisible(colId, visible)` | `api.setColumnVisible(columnId, visible)` |
| `getSortModel()` / `setSortModel()` | `api.setSort(columnId, 'asc'\|'desc'\|null)` |
| `setFilterModel({...})` | `api.setFilter(columnId, { operator, value })` |
| `getDisplayedRowAtIndex(i)` / `forEachNodeAfterFilterAndSort(...)` | `api.getDisplayedRows()` |
| `getModel()` (raw rows) | `api.getData()` |

## Common patterns

### Sorting + filtering + pagination (the 80% case)

```svelte
<script lang="ts">
  import {
    SvGrid,
    tableFeatures,
    rowSortingFeature,
    columnFilteringFeature,
    rowPaginationFeature,
  } from 'sv-grid-community'

  const features = tableFeatures({
    rowSortingFeature,
    columnFilteringFeature,
    rowPaginationFeature,
  })
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  showPagination
  showColumnFilters
/>
```

AG Grid equivalent: `gridOptions: { defaultColDef: { sortable: true, filter: true }, pagination: true }`.

### Cell editing with persistence

```svelte
<script lang="ts">
  function onCellValueChange(e: { rowIndex: number; columnId: string; value: unknown }) {
    // Persist however you like (fetch to backend, optimistic local update, etc.)
    console.log('cell changed', e)
  }
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  enableInlineEditing
  onCellValueChange={onCellValueChange}
/>
```

AG Grid equivalent: `onCellValueChanged: ({ data, colDef, newValue, oldValue }) => ...`.
SvGrid's event payload is column-id + row-index based rather than node-based; the row data is yours
to mutate (or not) on the `rows` array you passed in.

### Grouping + aggregation

```svelte
<script lang="ts">
  import {
    SvGrid,
    tableFeatures,
    columnGroupingFeature,
    rowSortingFeature,
    rowExpandingFeature,
  } from 'sv-grid-community'

  const features = tableFeatures({
    rowSortingFeature,
    columnGroupingFeature,
    rowExpandingFeature,
  })

  const columns = [
    { field: 'department', header: 'Department' },
    { field: 'team',       header: 'Team' },
    { field: 'salary',     header: 'Salary', aggregation: 'sum',
      format: { type: 'currency', currency: 'USD' } },
  ]

  function setGroup(api) {
    api.setGroupBy(['department', 'team'])
  }
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  showGroupingControls
  onApiReady={setGroup}
/>
```

AG Grid Enterprise's `rowGroupPanelShow: 'always'` + `aggFunc: 'sum'` translates 1:1.

### Master / detail

AG Grid Enterprise feature; **free in SvGrid Community**. See
[demo 08](https://sv-grid.dev/#/demos/08-tree-and-master-detail) for the exact pattern.

### Server-side data

AG Grid uses an `IServerSideDatasource` interface. SvGrid uses
`externalSort` + `externalFilter` props - your code keeps full control
over the query, and the grid records UI state but doesn't re-order rows
locally. See [demo 09](https://sv-grid.dev/#/demos/09-server-side).

### Excel / PDF export

AG Grid: `gridApi.exportDataAsExcel({...})` (Enterprise-only).
SvGrid: install `sv-grid-pro`, call `api.exportData({ format: 'xlsx', ... })`. See [Data export and printing](./export.md).

```ts
import { installPro, setLicenseKey } from 'sv-grid-pro'
setLicenseKey('SVPRO-...')   // your Pro key

// inside onApiReady:
const pro = installPro(api)
await pro.exportData({ format: 'xlsx', filename: 'orders' })
```

## Gotchas - things that don't translate directly

### 1. Per-column `editable: true`
SvGrid v1.0 toggles editing at the grid level (`enableInlineEditing`).
Per-column editability is on the roadmap - until then, you can gate
edits in your `onCellValueChange` handler.

### 2. Column drag-to-reorder
SvGrid v1.0 supports column reorder via the API (`setColumnOrder`), not
header drag. Built-in header drag is on the roadmap. Most teams don't
miss it - it's a power-user feature.

### 3. AG Grid `valueGetter` chains
AG Grid's `valueGetter` can read other column values via the API. In
SvGrid, `accessorFn` only receives the row; if you need cross-column
computed values, do it in the cell renderer with `ctx.row.original` or
compute the derived value upstream and store it in the row.

### 4. `cellClass` / `rowClass` callbacks
On the roadmap. For now, render a wrapper element in your `cell` snippet
with the conditional class.

### 5. The Status Bar / Side Bar / Tool Panels
AG Grid's chrome (status bar with row count, side bar with filters and
columns panels) doesn't exist in SvGrid - build it as plain Svelte
markup around the grid. Most teams build their own anyway because
AG Grid's defaults rarely match a polished design system.

### 6. Set filter (the Excel-style funnel popup)
SvGrid ships an Excel-style filter menu (free in Community). API surface
is similar but not identical - see [Set filter](./filtering/set-filter.md).

## When NOT to migrate

Be honest. Stay on AG Grid if you:

- **Use multiple frameworks** - AG Grid has React, Angular, Vue, Solid, Qwik, vanilla adapters. SvGrid is Svelte-only.
- **Use AG Grid's integrated charts** - those depend on AG Grid's chart engine; SvGrid has no equivalent.
- **Depend on AG Grid pivoting** - not in SvGrid's roadmap.
- **Are mid-project and shipping in <2 weeks** - the migration is a few hours per grid, but only do it when you have buffer.
- **Have a Svelte 4 codebase you can't upgrade** - SvGrid requires Svelte 5 runes. (Consider [htmlelements.com](https://www.htmlelements.com) for vanilla / multi-framework.)

If none of those apply: switching saves you $400-$1000 per dev per year,
cuts your bundle by 200+ KB, and gives you a Svelte-native API that
plays well with runes.

## Step-by-step migration

A typical migration of a single grid takes 1-3 hours:

1. **Install** - `pnpm add sv-grid-community` (and `sv-grid-pro` if you need export).
2. **Translate columnDefs** - use the mapping table above. Most columns are 1:1.
3. **Wrap features** - figure out which AG Grid features you actually use; register only those in `tableFeatures({...})`.
4. **Swap the component** - `<AgGridSvelte gridOptions={...}>` → `<SvGrid data={rows} columns={columns} features={features}>`.
5. **Move event handlers** - AG Grid `onCellValueChanged` → SvGrid `onCellValueChange` (signature differs slightly, see above).
6. **Move API calls** - AG Grid `gridApi.X()` → SvGrid `api.X()` per the API table.
7. **Test interactions** - sort, filter, edit, select. Most "just works."
8. **Remove `ag-grid-*` packages** - `pnpm remove ag-grid-community ag-grid-svelte` etc. Inspect your bundle to confirm the 200+ KB drop.

## Need help migrating?

Pro customers get **migration help included** with the support plan
(architecture review, port one grid for you as a reference). Email
`support@jqwidgets.com` after purchase, or `sales@jqwidgets.com` for
pre-sales questions.

## See also

- [Getting started](../getting-started.md) - full SvGrid walkthrough
- [Why headless?](../why-headless.md) - the headless / render-component split
- [Data export and printing](./export.md) - the `sv-grid-pro` feature pack
- [SvGrid vs AG Grid comparison page](https://sv-grid.dev/#/compare/ag-grid)

## Frequently asked questions

### Is SvGrid a drop-in replacement for AG Grid in Svelte?

Not a literal drop-in - there is no `ag-grid-svelte` shim to swap. But the
concepts map closely: column definitions, row models, sorting, filtering,
grouping, and an imperative API all have direct SvGrid equivalents, so most
teams port a grid in 30 minutes to a day. It is a configuration translation,
not a rewrite.

### What is the SvGrid equivalent of AG Grid Enterprise?

`sv-grid-pro`. It adds Excel/PDF/CSV/TSV/HTML export, a printable view, pivot
tables, data import, and AI helpers. It is licensed per developer
($599 single-app / $999 multi-app), not per deployment, and the Community
package is MIT-licensed and free for commercial use.

### Does SvGrid use Svelte 5 runes, or is it a wrapper?

It is Svelte-5-native. State is `$state` / `$derived` / `$effect` and cells
render through Svelte snippets - there is no React or Angular core underneath
and no framework bridge to keep in sync.

### Will my AG Grid bundle size shrink?

Almost always. SvGrid's full render component is ~42 KB gzipped (or ~7.5 KB
for the headless core) versus a much heavier AG Grid Community bundle, and you
only add `sv-grid-pro` features you actually use - so you ship a fraction of
the JavaScript.

<!-- =================================================================
     /help/migrating-from-devextreme  (community)
     ================================================================== -->

# Migrating from DevExtreme DataGrid (DevExpress)

DevExtreme DataGrid is a deep, commercial multi-framework grid from
DevExpress (jQuery, React, Vue, Angular). Moving to SvGrid trades the
commercial suite for a Svelte-5-native grid with an MIT core and a far
lower-cost paid tier.

> Estimated effort: **3-6 hours** per grid.
>
> DevExtreme's option names vary by framework flavour; map your version's
> columns and events onto the SvGrid equivalents below.

## Concept map

| DevExtreme DataGrid                      | sv-grid                                   |
| ---------------------------------------- | ----------------------------------------- |
| `columns: [{ dataField, caption }]`      | `columns: [{ field, header }]`             |
| `cellTemplate`                           | `cell: (c) => renderSnippet(...)`          |
| `editing: { mode, allowUpdating }`       | `enableInlineEditing` + `editorType`       |
| `sorting` / `filterRow` / `headerFilter` | `rowSortingFeature` / `columnFilteringFeature` |
| `grouping` + `summary`                   | `columnGroupingFeature` + aggregates       |
| `masterDetail`                           | `rowExpandingFeature` / master-detail rows |
| `dataSource` (store / remote)            | `data` array or `externalSort/Filter`      |
| `paging` + `pager`                       | `showPagination`                           |
| `export`                                 | `sv-grid-pro` export pack                  |
| `stateStoring`                           | persist column state yourself (saved views) |

## Shape of the change

```diff
- $('#grid').dxDataGrid({
-   dataSource: rows,
-   paging: { pageSize: 25 },
-   sorting: { mode: 'multiple' }, filterRow: { visible: true },
-   editing: { mode: 'cell', allowUpdating: true },
-   columns: [
-     { dataField: 'name',   caption: 'Name' },
-     { dataField: 'amount', caption: 'Amount', format: 'currency' },
-   ],
- })

+ <SvGrid
+   data={rows}
+   columns={[
+     { field: 'name',   header: 'Name' },
+     { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },
+   ]}
+   features={tableFeatures({ rowSortingFeature, columnFilteringFeature })}
+   showPagination enableInlineEditing />
```

## Why teams switch

- **Svelte 5 native** instead of a multi-framework commercial library.
- **MIT community core** plus an optional Pro pack for export / import /
  pivot / AI.
- **Much lower-cost paid tier.**

## What to weigh

- DevExtreme has a **larger built-in feature surface** (state storing,
  broad export, a full suite). If you depend on those, factor them in -
  `stateStoring` in particular becomes a saved-views pattern you wire up.

## See also

- [SvGrid vs DevExtreme DataGrid](https://svgrid.com/compare/devextreme-datagrid) - the side-by-side comparison
- [Saved views](./saved-views.md) - the state-persistence pattern
- [Data export and printing - Pro](./export.md) - the Pro export pack

## Frequently asked questions

### How do DevExtreme columns map to SvGrid?

`dataField` becomes `field`, `caption` becomes `header`, and `cellTemplate`
becomes a `renderSnippet` cell. Sorting / filtering / grouping move from grid
options to registered features.

### Is SvGrid cheaper than DevExtreme?

For a Svelte stack, yes - the core is MIT and the paid tier is far below
commercial-suite pricing. You give up DevExtreme's multi-framework reach and
some built-in features like `stateStoring`.

### Does SvGrid export like DevExtreme?

Yes, via the `sv-grid-pro` pack: Excel, PDF, CSV, TSV, and HTML export plus a
printable view.

<!-- =================================================================
     /help/migrating-from-glide  (community)
     ================================================================== -->

# Migrating from Glide Data Grid

Glide Data Grid is the canvas-rendered, ultra-high-performance choice
for very wide datasets (100k+ rows, 100+ columns). Sv-grid renders to
DOM with virtualization, which trades the absolute peak FPS for
accessibility + standards-compliant HTML.

> Estimated effort: **3-6 hours** per grid. Glide's getCellContent /
> onCellEdited cell-data model is the opposite of sv-grid's
> data-array model; the mental flip takes the most time.

## Mental-model flip

Glide gives you a **canvas + a `getCellContent` callback**: the grid
asks you for each visible cell on demand. Sv-grid wants the
**whole data array up front** (`<SvGrid data={rows}>`); the engine
slices for virtualization.

```diff
- function getCellContent([col, row]) {
-   const r = rows[row]
-   if (col === 0) return { kind: 'text', data: r.name,    displayData: r.name,    allowOverlay: true }
-   if (col === 1) return { kind: 'number', data: r.amount, displayData: fmt(r.amount), allowOverlay: true }
- }
- <DataEditor columns={[...]} getCellContent={getCellContent} rows={rows.length} />

+ const columns: ColumnDef<typeof features, Row>[] = [
+   { field: 'name',   header: 'Name',   editorType: 'text' },
+   { field: 'amount', header: 'Amount', editorType: 'number',
+     format: { type: 'currency', currency: 'USD' } },
+ ]
+ <SvGrid data={rows} columns={columns} features={features} />
```

This change is **good** for 99% of apps: it's less code, less risk
of typos in cell coordinates, full TypeScript type checking on the
row shape. For the 1% of apps with rows that don't fit in memory,
see "Out-of-memory data" below.

## Cell editing

```diff
- function onCellEdited([col, row], newValue) {
-   rows[row] = { ...rows[row], [colToField(col)]: newValue.data }
- }
- <DataEditor onCellEdited={onCellEdited} />

+ <SvGrid
+   data={rows} columns={columns} features={features}
+   onCellValueChange={(e) => {
+     rows[e.rowIndex] = { ...rows[e.rowIndex], [e.columnId]: e.newValue }
+   }}
+ />
```

You can also rely on sv-grid's built-in write-back if `data` is a
Svelte 5 `$state` array - mutations propagate automatically.

## Sorting + filtering

Glide doesn't ship sort / filter UI; you wrap your own. Sv-grid
ships them:

```diff
- // Build your own sort buttons in the toolbar; sort rows yourself.

+ const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
+ <SvGrid data={rows} columns={columns} features={features} filterMode="menu" />
```

## Frozen columns / row markers

| Glide                                  | sv-grid                                       |
| -------------------------------------- | --------------------------------------------- |
| `freezeColumns={1}`                    | `api.setColumnPinning({ left: ['firstColId'] })` |
| `rowMarkers="number"`                  | `showRowNumbers={true}` prop                  |
| `rowMarkers="checkbox"`                | `selectionMode="row"` prop                    |

## Custom drawing → custom snippets

Glide's `drawCustomCell` lets you render anything via canvas. The
sv-grid equivalent is a Svelte snippet (DOM):

```diff
- drawCustomCell(args) {
-   const ctx = args.ctx
-   ctx.fillStyle = args.cell.data.color
-   ctx.fillRect(args.rect.x, args.rect.y, args.rect.width, args.rect.height)
-   return true
- }

+ {
+   field: 'color',
+   cell: (ctx) => renderSnippet(ColorChip, { color: ctx.row.original.color }),
+ }
```

```svelte
{#snippet ColorChip(props)}
  <span style="display: inline-block; width: 18px; height: 18px; background: {props.color};"></span>
{/snippet}
```

## Out-of-memory data

For "10M rows, fetched on scroll" workloads (the only case Glide
genuinely beats sv-grid on), use sv-grid's
[server-side / infinite-scroll pattern](./server-side-data.md):

```svelte
<SvGrid
  data={loadedSlice}
  columns={columns} features={features}
  externalSort={true}
  externalFilter={true}
  onSortingChange={async (s) => { loadedSlice = await fetchPage({ sort: s, offset: 0, limit: 200 }) }}
/>
```

You'll cap practical perf at ~100k rendered rows; for true 10M+
datasets Glide's canvas approach has a perf edge sv-grid won't
match. Most apps don't need 10M rows on screen at once - they need
fast server-side filtering, which both libraries support equally.

## Theming

Glide: huge `theme` prop object. Sv-grid: CSS custom properties (`--sg-*`).

```diff
- <DataEditor theme={{
-   accentColor: '#4F5DFF',
-   accentLight: 'rgba(62, 116, 253, 0.2)',
-   bgCell: '#1c1c20',
-   /* …40 more properties… */
- }} />

+ <div style="--sg-accent: #4F5DFF; --sg-bg: #1c1c20;">
+   <SvGrid {data} {columns} features={features} />
+ </div>
```

See [design tokens](./tokens.md) for the full list (≤ 30 tokens
covers everything; Glide's theme has ~40).

## What you get for free vs Glide

- **Accessibility.** Glide's canvas is invisible to screen readers
  unless you build an off-screen ARIA buffer. Sv-grid is WAI-ARIA
  1.2 grid pattern out of the box; demo 17 covers axe-core CI.
- **Standard HTML.** SEO crawlers, browser Find-in-Page, browser
  zoom, OS-level text scaling - all work because the grid emits
  actual `<table><tr><td>`.
- **Familiar editing.** Browser-native `<input>` / `<select>` for
  cells, with autofill / clipboard / autocorrect intact.
- **Built-in sort / filter / pagination UI.**

## What you give up

- **Peak FPS on >200k visible rows.** Canvas wins here. For most
  apps the gap is invisible; if you've actually measured it on real
  hardware and need the FPS, Glide remains the right call.
- **Per-pixel cell drawing.** DOM cells are sub-pixel-uniform but
  not arbitrarily drawn.

## See also

- [SvGrid vs Glide Data Grid](https://svgrid.com/compare/glide-data-grid) - the side-by-side comparison
- [Performance benchmarks](./benchmarks.md) - measured numbers
- [Server-side data](./server-side-data.md) - the >100k-row pattern
- [Accessibility](./accessibility.md) - the standards compliance Glide doesn't ship

## Frequently asked questions

### Should I move from Glide Data Grid to SvGrid?

Move if you need accessibility, standards-compliant HTML, SEO-friendly markup,
or DOM-based custom cells. Stay on Glide only if you have measured a need for
peak canvas FPS on 200k+ simultaneously visible rows. For most apps the
performance gap is invisible, and SvGrid virtualizes comfortably to 100k+ rows.

### How long does a Glide migration take?

About 3-6 hours per grid. The biggest shift is conceptual: Glide's
`getCellContent` / `onCellEdited` cell-data model is the inverse of SvGrid's
plain data-array model, so the mental flip takes the most time, not the code.

### Does SvGrid render to canvas or DOM?

DOM, with row and column virtualization. That is what gives you WAI-ARIA roles,
keyboard navigation, screen-reader support, and selectable/indexable text -
things a canvas grid like Glide cannot offer.

<!-- =================================================================
     /help/migrating-from-gridjs  (community)
     ================================================================== -->

# Migrating from Grid.js

Grid.js is a small vanilla-JS table for search, sort, and pagination
that you render into a DOM element. SvGrid does the same in a
Svelte-5-native component and keeps going - virtualization, Excel-style
filters, editing, grouping - when you outgrow the basics.

> Estimated effort: **30 min - 1 hour** per table.

## Vocabulary cheat sheet

| Grid.js                                   | sv-grid                                   |
| ----------------------------------------- | ----------------------------------------- |
| `new Grid({ ... }).render(el)`            | `<SvGrid ... />`                           |
| `columns: ['Name', 'Amount']`             | `columns: [{ field, header }]`             |
| `columns: [{ name, formatter }]`          | `{ header, cell: (c) => renderSnippet(...) }` |
| `sort: true`                              | `rowSortingFeature`                        |
| `search: true`                            | `api.setGlobalFilter(query)` / filter feature |
| `pagination: { limit: 25 }`               | `showPagination` (+ page size)             |
| `server: { url, then }`                   | `externalSort` / `externalFilter` + refetch |

## Before / after

```diff
- import { Grid } from 'gridjs'
- import 'gridjs/dist/theme/mermaid.css'
-
- new Grid({
-   data: rows,
-   columns: ['Name', 'Amount'],
-   sort: true, search: true,
-   pagination: { limit: 25 },
- }).render(document.getElementById('grid'))

+ <script lang="ts">
+   import {
+     SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
+     type ColumnDef,
+   } from 'sv-grid-community'
+   const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
+   const columns: ColumnDef<typeof features, Row>[] = [
+     { field: 'name',   header: 'Name' },
+     { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },
+   ]
+ </script>
+
+ <SvGrid data={rows} columns={columns} features={features} showPagination />
```

## What you gain

- **Virtualization** for large datasets (Grid.js renders the page).
- **Excel-style filter menu**, **inline editing**, **grouping**, and
  **tree / master-detail** when you need them.
- **Reactive data** - no `.render(el)` re-instantiation.
- A **headless engine** and an **imperative API** plus `sv-grid-mcp`.

## See also

- [SvGrid vs Grid.js](https://svgrid.com/compare/gridjs) - the side-by-side comparison
- [Getting started](../getting-started.md) - a working grid in ~15 lines
- [Server-side data](./server-side-data.md) - the external-data pattern

## Frequently asked questions

### When should I move from Grid.js to SvGrid?

When you need more than search / sort / paginate - virtualization for big
datasets, inline editing, Excel-style filters, grouping, or tree data. For a
small table, Grid.js stays lighter.

### Is SvGrid MIT-licensed like Grid.js?

Yes. `sv-grid-community` is MIT. Only the optional `sv-grid-pro` add-on is paid.

### Does SvGrid support server-side data like Grid.js?

Yes. Set `externalSort` / `externalFilter` and refetch on the
`onSortingChange` / `onFiltersChange` events.

<!-- =================================================================
     /help/migrating-from-handsontable  (community)
     ================================================================== -->

# Migrating from Handsontable

Handsontable's mental model is "spreadsheet-in-a-page": every cell
editable, formulas, copy/paste with the OS clipboard, frozen rows
and columns. Sv-grid covers ~90% of the same surface; the port is
mostly a configuration translation, except for HyperFormula (see
the Formulas section below).

> Estimated effort: **2-4 hours** per grid for typical spreadsheet
> workflows. **Add 1-2 days** if you depend heavily on
> HyperFormula features sv-grid doesn't ship.

## Imports

```diff
- import Handsontable from 'handsontable'
- import 'handsontable/dist/handsontable.full.min.css'

+ import {
+   SvGrid, tableFeatures,
+   rowSortingFeature, columnFilteringFeature, rowSelectionFeature,
+   type ColumnDef,
+ } from 'sv-grid-community'
```

## Schema → columns

Handsontable accepts a 2D array OR an array of objects. Sv-grid
expects the array-of-objects form:

```diff
- const hot = new Handsontable(container, {
-   data: [
-     ['Tesla',     2017, 'black', false],
-     ['Nissan',    2018, 'blue',  true ],
-   ],
-   colHeaders: ['Make', 'Year', 'Color', 'In stock'],
-   columns: [
-     {},
-     { type: 'numeric' },
-     {},
-     { type: 'checkbox' },
-   ],
- })

+ type Car = { make: string; year: number; color: string; inStock: boolean }
+ const rows: Car[] = [
+   { make: 'Tesla',  year: 2017, color: 'black', inStock: false },
+   { make: 'Nissan', year: 2018, color: 'blue',  inStock: true  },
+ ]
+ const columns: ColumnDef<typeof features, Car>[] = [
+   { field: 'make',    header: 'Make' },
+   { field: 'year',    header: 'Year',     editorType: 'number' },
+   { field: 'color',   header: 'Color' },
+   { field: 'inStock', header: 'In stock', editorType: 'checkbox' },
+ ]
+ <SvGrid data={rows} columns={columns} features={features} />
```

If your existing data is a 2D array, transform once at boot:

```ts
const headerRow = raw[0]
const rows = raw.slice(1).map((cells) =>
  Object.fromEntries(cells.map((v, i) => [headerRow[i], v])),
)
```

## Editor types

| Handsontable                                   | sv-grid                                          |
| ---------------------------------------------- | ------------------------------------------------ |
| `type: 'text'`                                 | `editorType: 'text'`                              |
| `type: 'numeric'`                              | `editorType: 'number'`                            |
| `type: 'date'`                                 | `editorType: 'date'`                              |
| `type: 'checkbox'`                             | `editorType: 'checkbox'`                          |
| `type: 'dropdown', source: [...]`              | `editorType: 'list', editorOptions: [...]`        |
| `type: 'autocomplete'`                         | `editorType: 'list'` (combobox UI ships)          |
| `type: 'time'`                                 | Use `editorType: 'text'` + your own format        |
| `type: 'password'`                             | Use `editorType: 'text'` + a custom snippet       |

## Selection + clipboard

| Handsontable                            | sv-grid                                                 |
| --------------------------------------- | ------------------------------------------------------- |
| `selectCells([[0,0,2,5]])`              | `selectionMode='cell'`; programmatic range API is in v2 |
| `getSelected()`                         | Combine `onActiveCellChange` + `onRowSelectionChange`    |
| `copyPaste: true` (default)             | Ships built-in; `enableCellSelection={true}`             |
| `fillHandle: true`                      | Ships built-in (drag-to-fill on selected range)          |

## Frozen rows / columns

| Handsontable                       | sv-grid                                                |
| ---------------------------------- | ------------------------------------------------------ |
| `fixedColumnsStart: 2`             | `api.setColumnPinning({ left: ['firstColId', 'secondColId'] })` |
| `fixedRowsTop: 1`                  | n/a - use header row + grouped header for sticky labels |
| `manualColumnFreeze: true`         | Ships via the column-header right-click menu             |

## Hooks → callbacks

| Handsontable hook                      | sv-grid                                                 |
| -------------------------------------- | ------------------------------------------------------- |
| `afterChange((changes, src) => {})`    | `onCellValueChange((e) => {...})`                       |
| `afterSelection(...)`                  | `onActiveCellChange((cell) => {...})`                   |
| `afterFilter(...)`                     | `onFiltersChange((f) => {...})`                         |
| `afterColumnSort(...)`                 | `onSortingChange((s) => {...})`                          |
| `beforeChange((changes) => false)`     | Throw / return `false` from your inline validator; see [validation](./editing/validation.md) |
| `afterCreateRow / afterRemoveRow`      | Wrap `api.addRow / removeRow` in your own emitter        |

## Formulas (HyperFormula)

Sv-grid ships a focused subset under
[`spreadsheet-formulas`](./spreadsheet-formulas.md) (SUM, IF, COUNTIF
+ cell refs + ranges + cycle detection). It does NOT ship the full
HyperFormula library.

If you need HyperFormula's full surface (~400 functions, complex
date math, R1C1 refs), the integration pattern is:

```ts
import { HyperFormula } from 'hyperformula'

const hf = HyperFormula.buildFromArray(rowsAsMatrix, { licenseKey: 'gpl-v3' })

// On every cell edit, push to HF + read back the computed value:
function onCellValueChange(e) {
  hf.setCellContents({ sheet: 0, row: e.rowIndex, col: columnIndex }, e.newValue)
  // ...read computed cells you depend on + push back via api.setCellValue
}
```

This is the only piece where the swap isn't 1:1. Most teams find
sv-grid's shipped subset covers 80% of real-world formula usage; if
yours is in the 20%, HyperFormula plugs in cleanly.

## Trial → license

Handsontable's commercial trial expires after 45 days. Sv-grid's
[Pro tier](../pro/licensing.md) is soft-gated (works forever, with
a watermark for unlicensed builds) - no hard cutoff to plan around.

## What you get for free vs Handsontable

- **No GPLv3 licensing fork.** sv-grid-community is MIT.
- **Modern Svelte 5 ergonomics.** `$state` arrays beat
  `loadData(...)`.
- **CSP-clean.** Handsontable's HyperFormula path needs CSP `eval`
  exceptions in some configurations.

## What you give up

- **Full HyperFormula surface.** Sv-grid ships a subset; see above.
- **Comments + named ranges.** Not in sv-grid today.
- **Merge cells UI.** Sv-grid supports column groups + row spanning
  but no drag-to-merge UI yet.

## See also

- [SvGrid vs Handsontable](https://svgrid.com/compare/handsontable) - the side-by-side comparison
- [Spreadsheet formulas](./spreadsheet-formulas.md) - sv-grid's
  built-in formula engine
- [Demo 27 (Spreadsheet + Ribbon)](https://svgrid.com/#/demos/27-spreadsheet-ribbon) - live
- [Migrating from AG Grid](./migrating-from-ag-grid.md)

## Frequently asked questions

### Can SvGrid replace Handsontable's spreadsheet features?

It covers roughly 90% of the surface - inline editing on every cell, copy/paste
as TSV, range selection, column groups, and a built-in formula engine. Budget
2-4 hours per grid for typical spreadsheet workflows, plus 1-2 days if you lean
heavily on the full HyperFormula function set.

### Does SvGrid support formulas like Handsontable?

Yes, a built-in formula engine with cell references, ranges, and common
functions (see the spreadsheet-formulas guide and demo 27). It is a practical
subset rather than the complete HyperFormula library, so verify your specific
functions before porting.

### Is SvGrid licensed like Handsontable?

The `sv-grid-community` core is MIT and free for commercial use - no per-seat
license key. The optional `sv-grid-pro` pack (export, pivot, import) is priced
per developer.

<!-- =================================================================
     /help/migrating-from-jqxgrid  (community)
     ================================================================== -->

# Migrating from jqxGrid (jQWidgets)

jqxGrid and SvGrid come from the **same team**. jqxGrid is the mature,
multi-framework grid (jQuery core with Angular, React, and Vue
integrations); SvGrid is the Svelte-5-native member of the family. If
your team is consolidating on Svelte 5, this guide maps a jqxGrid setup
onto SvGrid - and the concepts will feel familiar because the
engineering lineage is shared.

> Estimated effort: **2-4 hours** per grid. Most of the work is moving
> from the imperative jQuery source / API to reactive `$state`.

## Vocabulary cheat sheet

| jqxGrid                                  | sv-grid                                   |
| ---------------------------------------- | ----------------------------------------- |
| `$('#grid').jqxGrid({ ... })`            | `<SvGrid ... />`                           |
| `source` / `jqxDataAdapter`              | `data` array (or `externalSort/Filter`)    |
| `{ text: 'Name', datafield: 'name' }`    | `{ header: 'Name', field: 'name' }`        |
| `cellsrenderer`                          | `cell: (c) => renderSnippet(...)`          |
| `columntype` / cell editor              | `editorType`                               |
| `cellsformat: 'c2'`                      | `format: { type: 'currency', currency: 'USD' }` |
| `sortable` / `filterable`                | `rowSortingFeature` / `columnFilteringFeature` |
| `groupable` + `groups`                   | `columnGroupingFeature` + `api.setGroupBy()` |
| `pageable`                               | `showPagination`                           |
| `jqxGrid('updatebounddata')`             | reassign the `$state` data array           |
| `editable` + `cellendedit` event         | `enableInlineEditing` + `onCellValueChange` |

## Before / after

```diff
- const source = { localdata: rows, datatype: 'array' }
- const adapter = new $.jqx.dataAdapter(source)
- $('#grid').jqxGrid({
-   source: adapter, sortable: true, filterable: true, pageable: true, editable: true,
-   columns: [
-     { text: 'Name',   datafield: 'name' },
-     { text: 'Amount', datafield: 'amount', cellsformat: 'c2' },
-   ],
- })

+ <script lang="ts">
+   import {
+     SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
+     type ColumnDef,
+   } from 'sv-grid-community'
+   const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
+   const columns: ColumnDef<typeof features, Row>[] = [
+     { field: 'name',   header: 'Name' },
+     { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },
+   ]
+ </script>
+
+ <SvGrid data={rows} columns={columns} features={features} showPagination enableInlineEditing />
```

## What changes

- **jQuery source / dataAdapter → reactive `$state`.** No
  `updatebounddata()`; reassign the array.
- **`cellsrenderer` → snippet cells** via `renderSnippet`.
- **jQWidgets theme → `--sg-*` tokens** (or your Tailwind theme).

## A note on family

This is not "switching vendors" - it is moving to the team's Svelte-5
grid. The Pro tier and support come from the same people behind jqxGrid.
If your app is still on jQuery / Angular / React / Vue, jqxGrid remains
the right tool; reach for SvGrid when the codebase is Svelte 5.

## See also

- [SvGrid vs jqxGrid](https://svgrid.com/compare/jqxgrid) - the side-by-side comparison
- [About SvGrid](https://svgrid.com/about) - built by jQWidgets
- [Getting started](../getting-started.md) - a working grid in ~15 lines

## Frequently asked questions

### Is SvGrid made by the same team as jqxGrid?

Yes. SvGrid is built by jQWidgets - the same team behind jqxGrid - specifically
for Svelte 5, rebuilt around runes and snippets with an MIT community core.

### How do jqxGrid columns map to SvGrid?

`text` becomes `header`, `datafield` becomes `field`, `cellsrenderer` becomes a
`renderSnippet` cell, and `cellsformat` maps onto the `format` config. Sorting /
filtering / grouping move to registered features.

### Should I migrate my jQuery jqxGrid app to SvGrid?

Only if you are moving that app to Svelte 5. If it stays on jQuery / Angular /
React / Vue, jqxGrid is the better fit. SvGrid is the native choice once the
stack is Svelte.

<!-- =================================================================
     /help/migrating-from-kendo-grid  (community)
     ================================================================== -->

# Migrating from Kendo UI Grid (Telerik)

Kendo UI Grid is the polished, commercial enterprise grid from Telerik /
Progress, available for jQuery, React, Vue, and Angular. Moving to SvGrid
trades the multi-framework commercial suite for a Svelte-5-native grid
with an MIT core - and a much cheaper paid tier.

> Estimated effort: **3-6 hours** per grid - column / event translation
> plus re-theming.
>
> Kendo's exact API differs across its jQuery / React / Vue / Angular
> flavours; map your version's column and event names onto the SvGrid
> equivalents below.

## Concept map

| Kendo UI Grid                            | sv-grid                                   |
| ---------------------------------------- | ----------------------------------------- |
| `columns: [{ field, title }]`            | `columns: [{ field, header }]`             |
| `template` / cell render                 | `cell: (c) => renderSnippet(...)`          |
| `editable` + editor                      | `enableInlineEditing` + `editorType`       |
| `sortable` / `filterable`                | `rowSortingFeature` / `columnFilteringFeature` |
| `group` / aggregates                     | `columnGroupingFeature` + `api.setGroupBy()` |
| `dataSource` (local / remote)            | `data` array or `externalSort/Filter`      |
| `pageable`                               | `showPagination`                           |
| Kendo themes (Default / Bootstrap)       | `--sg-*` tokens / Tailwind                 |
| Grid events (`change`, `dataBound`)      | `onCellValueChange`, `onApiReady`, ...      |

## Shape of the change

```diff
- $('#grid').kendoGrid({
-   dataSource: { data: rows, pageSize: 25 },
-   sortable: true, filterable: true, pageable: true, editable: true,
-   columns: [
-     { field: 'name',   title: 'Name' },
-     { field: 'amount', title: 'Amount', format: '{0:c}' },
-   ],
- })

+ <SvGrid
+   data={rows}
+   columns={[
+     { field: 'name',   header: 'Name' },
+     { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },
+   ]}
+   features={tableFeatures({ rowSortingFeature, columnFilteringFeature })}
+   showPagination enableInlineEditing />
```

## Why teams switch

- **Svelte 5 native** instead of a jQuery / multi-framework suite.
- **MIT community core** - no per-developer license for the grid itself.
- **Paid support at a fraction of enterprise-suite pricing.**
- **No design-system lock-in** - theme via `--sg-*` tokens.

## What to weigh

- Kendo bundles a **huge component suite** (charts, scheduler, editor)
  and decades of vendor support. If you need the whole suite across
  several frameworks, that has real value.

## See also

- [SvGrid vs Kendo UI Grid](https://svgrid.com/compare/kendo-ui-grid) - the side-by-side comparison
- [Pricing](https://svgrid.com/pricing) - the SvGrid Pro tiers
- [Architecture](./architecture.md) - engine + render-component split

## Frequently asked questions

### Is SvGrid a cheaper alternative to Kendo UI Grid?

For a Svelte stack, yes: the `sv-grid-community` core is MIT (free, including
commercial use), and the paid `sv-grid-pro` tier is a fraction of enterprise
component-suite pricing.

### How long does a Kendo Grid migration take?

About 3-6 hours per grid. It is a column / event rename pass plus re-theming;
the columns and editing concepts map closely.

### Does SvGrid match Kendo's feature set?

For the grid itself it covers the common enterprise surface - sorting,
Excel-style filters, grouping, virtualization, editing, master/detail, tree.
Kendo's value beyond that is the wider suite and multi-framework parity.

<!-- =================================================================
     /help/migrating-from-mui-x  (community)
     ================================================================== -->

# Migrating from MUI X DataGrid

MUI X DataGrid is the most common starting point for teams already
on Material UI. It's a closed-source-Pro / open-source-Community
split very similar to sv-grid's. The port is mostly mechanical.

> Estimated effort: **1-3 hours** per grid, depending on how heavily
> you've leant on `apiRef.current.*` calls.

## Package map

| MUI X                                | sv-grid                                  |
| ------------------------------------ | ---------------------------------------- |
| `@mui/x-data-grid`                   | `sv-grid-community`                      |
| `@mui/x-data-grid-pro`               | `sv-grid-pro` (export, import, pivot, AI) |
| `@mui/x-data-grid-premium`           | All of `sv-grid-pro` ships in one tier   |

## Imports

```diff
- import { DataGrid, GridColDef, GridRowsProp } from '@mui/x-data-grid'

+ import { SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
+          type ColumnDef } from 'sv-grid-community'
```

## Column defs

```diff
- const columns: GridColDef[] = [
-   { field: 'id',       headerName: 'ID',       width: 90 },
-   { field: 'lastName', headerName: 'Last',     width: 150, editable: true },
-   { field: 'age',      headerName: 'Age',      type: 'number', width: 110, editable: true },
- ]

+ const columns: ColumnDef<typeof features, Row>[] = [
+   { field: 'id',       header: 'ID',   width: 90  },
+   { field: 'lastName', header: 'Last', width: 150 },
+   { field: 'age',      header: 'Age',  width: 110, editorType: 'number' },
+ ]
```

- `headerName` → `header`
- `type: 'number'` → `editorType: 'number'`
- `editable: true` → omit (every column is editable by default; set
  `editable: false` to OPT OUT)

## Mounting

```diff
- <DataGrid rows={rows} columns={columns} pageSize={25} checkboxSelection />

+ <SvGrid
+   data={rows} columns={columns} features={features}
+   showPagination={true} pageSize={25}
+   selectionMode="row" />
```

`tableFeatures({ rowSortingFeature, columnFilteringFeature,
rowSelectionFeature })` registers what you'd implicitly get from
MUI X.

## `apiRef` translation

| MUI X (`apiRef.current.*`)                   | sv-grid (`api.*`)                          |
| -------------------------------------------- | ------------------------------------------ |
| `setRows(rows)`                              | mutate the `$state` array you bound to `data` |
| `updateRows([{id, ...patch}])`               | `api.setCellValue(rowIndex, field, value)` |
| `setSortModel([{field, sort}])`              | `api.setSort(field, sort)`                  |
| `setFilterModel({items: [...]})`             | `api.setFilter(field, {operator, value})`   |
| `setPage(0)` / `setPageSize(50)`             | Use the built-in pager; for headless control register `pageSize` prop |
| `selectRow(id)`                              | Toggle the row checkbox via the wrapper's UI; programmatic select is `api.setRowSelection({id: true})` |
| `getSelectedRows()`                          | `api.getDisplayedRows().filter((r) => ...)` |
| `exportDataAsExcel()`                        | `api.exportData({ format: 'xlsx' })` (Pro)  |
| `setColumnVisibilityModel({field: false})`   | `api.setColumnVisible('field', false)`     |

## Custom cells

```diff
- {
-   field: 'status',
-   renderCell: ({ row }) => <Chip label={row.status} color={row.status === 'active' ? 'success' : 'default'} />,
- }

+ {
+   field: 'status',
+   cell: (ctx) => renderSnippet(StatusChip, { status: ctx.row.original.status }),
+ }
```

## Selection

```diff
- <DataGrid checkboxSelection
-   onRowSelectionModelChange={(ids) => setSelected(ids)} />

+ <SvGrid
+   {data} {columns} features={features}
+   selectionMode="row"
+   onRowSelectionChange={(selection, rows) => setSelected(rows)} />
```

`selectionMode` values: `'row'` (the MUI X equivalent), `'cell'`
(spreadsheet-style range), `'both'`, `'none'`.

## Inline editing

MUI X had `processRowUpdate(newRow, oldRow)` returning the new row.
Sv-grid's equivalent is `onCellValueChange`:

```diff
- <DataGrid processRowUpdate={async (newRow) => {
-   await api.savePatch(newRow)
-   return newRow
- }} />

+ <SvGrid
+   onCellValueChange={async (e) => {
+     await api.savePatch({ id: e.row.id, [e.columnId]: e.newValue })
+   }}
+ />
```

For full-row editing (one Save button per row), see
[Full-row editing](./editing/full-row.md).

## Server-side data

MUI X's `pagination + serverSideMode + filterMode='server'` maps to
sv-grid's `externalSort + externalFilter`:

```svelte
<SvGrid
  data={rows} columns={columns} features={features}
  externalSort={true}
  externalFilter={true}
  onSortingChange={async (s) => { rows = await fetchPage({ sort: s }) }}
  onFiltersChange={async (f) => { rows = await fetchPage({ filters: f.columns }) }}
/>
```

## Slots / customisation

MUI X exposes a `slots` object. Sv-grid doesn't - instead, every
visual piece is a CSS custom property (`--sg-*`); see
[design tokens](./tokens.md). Override at any DOM level:

```css
.grid-host { --sg-accent: #db2777; --sg-row-height: 40px; }
```

For full theme presets (Ant, MUI, Fluent, Base Web, shadcn) see
[demo 74](https://svgrid.com/#/demos/74-theme-integrations).

## What you get for free vs MUI X

- **No Emotion / no Material theme dependency.** ~50 kB gzip total
  vs MUI X DataGrid Community's ~270 kB.
- **All Pro features in one tier.** No DataGrid Pro vs Premium split.
- **CSP-clean.** No `eval`.

## What you give up

- **The Material Design look out of the box.** Sv-grid ships
  unstyled-by-token; the [MUI preset in demo 74](https://svgrid.com/#/demos/74-theme-integrations)
  is one drop-in.
- **MUI form-field integration.** Bind directly to your own MUI
  inputs in custom cell components if you want them.

## See also

- [SvGrid vs MUI X DataGrid](https://svgrid.com/compare/mui-x-datagrid) - the side-by-side comparison
- [Migrating from AG Grid](./migrating-from-ag-grid.md)
- [Migrating from TanStack Table](./migrating-from-tanstack-table.md)
- [Design tokens](./tokens.md)

## Frequently asked questions

### How hard is it to migrate from MUI X DataGrid to SvGrid?

Mostly mechanical - typically 1-3 hours per grid, depending on how heavily you
relied on `apiRef.current.*`. The Community/Pro split mirrors MUI X's, so the
licensing mental model carries over directly.

### Can SvGrid keep the Material Design look?

Yes. SvGrid ships unstyled-by-token and re-themes through `--sg-*` CSS
variables; the MUI preset in demo 74 is a drop-in starting point. You can also
bind your own MUI inputs inside custom cell components.

### Is SvGrid cheaper than MUI X Pro/Premium?

SvGrid's Community tier is MIT and free for commercial use, and `sv-grid-pro`
is priced per developer ($599 single-app / $999 multi-app) rather than
per seat with Premium add-ons. Compare your team size and feature needs against
the [pricing page](https://sv-grid.dev/#/pricing).

<!-- =================================================================
     /help/migrating-from-primevue-datatable  (community)
     ================================================================== -->

# Migrating from PrimeVue / PrimeNG / PrimeReact DataTable

The Prime DataTable is the grid in the Prime UI suites for Vue, Angular,
and React. Its columns are declared as `<Column>` children with `field`
/ `header` props - a shape that maps cleanly onto SvGrid's `ColumnDef`
array. The port is mostly translating columns and events into a Svelte 5
component.

> Estimated effort: **2-4 hours** per grid.

## Vocabulary cheat sheet

| Prime DataTable                          | sv-grid                                   |
| ---------------------------------------- | ----------------------------------------- |
| `<DataTable :value="rows">`              | `<SvGrid data={rows}>`                     |
| `<Column field="name" header="Name" />`  | `{ field: 'name', header: 'Name' }`        |
| `sortable`                               | `rowSortingFeature`                        |
| `:filters` / filter display             | `columnFilteringFeature`                   |
| `<template #body>` cell slot             | `cell: (c) => renderSnippet(...)`          |
| `editMode` + cell editor template       | `editorType` (+ custom `cellEditor`)       |
| `:expandedRows` / row expansion          | `rowExpandingFeature`                      |
| `lazy` + `@page` / `@sort` / `@filter`  | `externalSort` / `externalFilter` + events |
| `paginator` + `:rows`                    | `showPagination` (+ page size)             |

## Before / after

```diff
- <DataTable :value="rows" paginator :rows="25" sortMode="multiple">
-   <Column field="name"   header="Name" sortable />
-   <Column field="amount" header="Amount" sortable>
-     <template #body="{ data }">{{ fmt(data.amount) }}</template>
-   </Column>
- </DataTable>

+ <script lang="ts">
+   import {
+     SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
+     type ColumnDef,
+   } from 'sv-grid-community'
+   const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
+   const columns: ColumnDef<typeof features, Row>[] = [
+     { field: 'name',   header: 'Name' },
+     { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },
+   ]
+ </script>
+
+ <SvGrid data={rows} columns={columns} features={features} showPagination />
```

## What changes

- **`<Column>` children → a `ColumnDef[]` array.**
- **`#body` slots → `cell` snippets** via `renderSnippet`.
- **Prime theming → `--sg-*` tokens / Tailwind** - no Prime theme
  dependency.
- **`lazy` → `externalSort` / `externalFilter`** with refetch on events.

## See also

- [SvGrid vs Prime DataTable](https://svgrid.com/compare/primevue-datatable) - the side-by-side comparison
- [Tailwind integration](./tailwind.md) - match your design system
- [Cell components](./cells/cell-components.md) - snippet cells + editors

## Frequently asked questions

### How do Prime `<Column>` definitions map to SvGrid?

Each `<Column field header />` becomes a `{ field, header }` object in SvGrid's
`columns` array, and `#body` templates become `renderSnippet` cells. Sorting and
filtering move from per-column props to the `rowSortingFeature` /
`columnFilteringFeature` registration.

### Is SvGrid open-source like the Prime grid core?

Yes. `sv-grid-community` is MIT, like the Prime component cores. The difference
is framework: SvGrid is Svelte 5, not Vue / Angular / React.

### Do I lose Prime theming?

You re-create the look with `--sg-*` tokens (optionally driven by your Tailwind
theme), so the grid matches your design system without a Prime theme dependency.

<!-- =================================================================
     /help/migrating-from-react-data-grid  (community)
     ================================================================== -->

# Migrating from React Data Grid (adazzle)

`react-data-grid` is a fast, Excel-like React grid with a clean column
API. SvGrid mirrors its shape - virtualized DOM, typed columns, inline
editing, custom cells - on Svelte 5 runes instead of React, so the port
is mostly a column rename pass.

> Estimated effort: **2-4 hours** per grid, more if you lean on custom
> editors.

## Vocabulary cheat sheet

| react-data-grid                          | sv-grid                                   |
| ---------------------------------------- | ----------------------------------------- |
| `<DataGrid columns rows />`              | `<SvGrid columns data />`                  |
| `{ key: 'name', name: 'Name' }`          | `{ field: 'name', header: 'Name' }`        |
| `renderCell: (p) => <Badge .../>`        | `cell: (c) => renderSnippet(Badge, {...})` |
| `renderEditCell` / `editor`              | `editorType` (+ custom `cellEditor`)       |
| `rowKeyGetter={(r) => r.id}`             | `getRowId={(r) => r.id}`                   |
| `onRowsChange={setRows}`                 | `onCellValueChange` (+ your state)         |
| `sortColumns` / `onSortColumnsChange`    | `rowSortingFeature` + `onSortingChange`    |
| `<DataGrid className=...>` theming       | `--sg-*` tokens / Tailwind                 |

## Before / after

```diff
- import DataGrid, { textEditor } from 'react-data-grid'
- const columns = [
-   { key: 'name',   name: 'Name' },
-   { key: 'amount', name: 'Amount', renderEditCell: textEditor },
- ]
- <DataGrid columns={columns} rows={rows} rowKeyGetter={(r) => r.id} onRowsChange={setRows} />

+ <script lang="ts">
+   import {
+     SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
+     type ColumnDef,
+   } from 'sv-grid-community'
+   const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
+   const columns: ColumnDef<typeof features, Row>[] = [
+     { field: 'name',   header: 'Name' },
+     { field: 'amount', header: 'Amount', editorType: 'text' },
+   ]
+ </script>
+
+ <SvGrid data={rows} columns={columns} features={features}
+   getRowId={(r) => r.id} enableInlineEditing
+   onCellValueChange={(e) => save(e)} />
```

## What changes

- **React → Svelte 5.** `renderCell` / `renderEditCell` become
  `renderSnippet` snippets and `editorType`.
- **`onRowsChange` → `onCellValueChange`.** SvGrid writes to its own
  working copy; subscribe to commits and persist where you like.
- **Filtering UI is built in.** react-data-grid leaves the filter row to
  you; SvGrid ships the Excel-style menu.

## See also

- [SvGrid vs React Data Grid](https://svgrid.com/compare/react-data-grid) - the side-by-side comparison
- [Migrating from TanStack Table](./migrating-from-tanstack-table.md) - sibling React-to-Svelte guide
- [Cell components](./cells/cell-components.md) - custom cells + editors

## Frequently asked questions

### How do react-data-grid columns map to SvGrid?

`key` becomes `field`, `name` becomes `header`, `renderCell` becomes a
`renderSnippet` cell, and editors map to `editorType` (or a custom `cellEditor`
snippet). `rowKeyGetter` becomes `getRowId`.

### Is SvGrid free like react-data-grid?

Yes - `sv-grid-community` is MIT-licensed, like react-data-grid. SvGrid adds an
optional paid Pro pack for export, import, pivot, and AI.

### Does SvGrid have built-in filtering?

Yes. react-data-grid asks you to build the filter UI; SvGrid ships an
Excel-style column filter menu and a global filter out of the box.

<!-- =================================================================
     /help/migrating-from-smart-grid  (community)
     ================================================================== -->

# Migrating from Smart.Grid (Smart Web Components)

Smart.Grid (htmlelements.com) and SvGrid come from the **same team**.
Smart.Grid is a framework-agnostic custom element - it even works inside
Svelte today - while SvGrid is the reactive, Svelte-5-native option. If
you are standardising a Svelte app on idiomatic components, this guide
maps a Smart.Grid setup onto SvGrid.

> Estimated effort: **2-4 hours** per grid. The main shift is from a
> custom element bound through properties / attributes to a reactive
> Svelte component.

## Vocabulary cheat sheet

| Smart.Grid (web component)               | sv-grid                                   |
| ---------------------------------------- | ----------------------------------------- |
| `<smart-grid>` element                   | `<SvGrid ... />`                           |
| `grid.dataSource = new Smart.DataAdapter`| `data` array (or `externalSort/Filter`)    |
| `{ label: 'Name', dataField: 'name' }`   | `{ header: 'Name', field: 'name' }`        |
| `template` / cell template               | `cell: (c) => renderSnippet(...)`          |
| `editing` + editor                       | `enableInlineEditing` + `editorType`       |
| `sorting` / `filtering`                  | `rowSortingFeature` / `columnFilteringFeature` |
| `grouping`                               | `columnGroupingFeature` + `api.setGroupBy()` |
| `paging` + `pager`                       | `showPagination`                           |
| element events (`change`, ...)           | `onCellValueChange`, `onApiReady`          |
| `theme` attribute                        | `--sg-*` tokens / Tailwind                 |

## Before / after

```diff
- <smart-grid id="grid" sorting filtering paging></smart-grid>
- <script>
-   const grid = document.querySelector('#grid')
-   grid.dataSource = new Smart.DataAdapter({ dataSource: rows, dataFields: [...] })
-   grid.columns = [
-     { label: 'Name',   dataField: 'name' },
-     { label: 'Amount', dataField: 'amount' },
-   ]
- </script>

+ <script lang="ts">
+   import {
+     SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
+     type ColumnDef,
+   } from 'sv-grid-community'
+   const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
+   const columns: ColumnDef<typeof features, Row>[] = [
+     { field: 'name',   header: 'Name' },
+     { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },
+   ]
+ </script>
+
+ <SvGrid data={rows} columns={columns} features={features} showPagination />
```

## What changes

- **Custom element + DataAdapter → reactive `$state`.** Data binding is a
  prop, not an assigned `dataSource`.
- **Element templates → Svelte snippets** via `renderSnippet`.
- **`theme` attribute → `--sg-*` tokens.**

## A note on family

Smart.Grid is a genuinely good framework-agnostic grid from the same
team, and it runs in Svelte as a web component. The reason to pick SvGrid
is *idiomatic* Svelte: runes, snippets, and an MIT core. If you need one
grid across Angular, React, Vue, Svelte, and vanilla, Smart.Grid is the
right call.

## See also

- [SvGrid vs Smart.Grid](https://svgrid.com/compare/smart-grid) - the side-by-side comparison
- [About SvGrid](https://svgrid.com/about) - built by jQWidgets / htmlelements.com
- [Cell components](./cells/cell-components.md) - snippet-based custom cells

## Frequently asked questions

### Is SvGrid from the same team as Smart.Grid?

Yes. Smart Web Components (htmlelements.com) and SvGrid are built by the same
team. SvGrid is the Svelte-5-native option with an MIT community core.

### Can I keep using Smart.Grid in Svelte instead?

Yes - Smart.Grid is a web component and works inside Svelte. Choose SvGrid when
you want an idiomatic Svelte component (runes + snippets) rather than a custom
element bound through properties.

### How do Smart.Grid columns map to SvGrid?

`label` becomes `header`, `dataField` becomes `field`, and element templates
become `renderSnippet` cells. Sorting / filtering / grouping move to registered
features.

<!-- =================================================================
     /help/migrating-from-svar-svelte-datagrid  (community)
     ================================================================== -->

# Migrating from SVAR Svelte DataGrid

SVAR Svelte DataGrid (`wx-svelte-grid`) is, like SvGrid, an actual
Svelte-native grid rather than a wrapper, and both are MIT-licensed and
free for commercial use. Because both are component-first with
array-of-object column definitions, a port is mostly a configuration
translation. The reasons people switch are **capability** (SvGrid adds
row grouping with aggregation, master-detail, Excel-style cell-range
selection, integrated charts, and pivot) and **architecture** (SvGrid
also exposes a headless engine and an MCP server).

> Estimated effort: **2-4 hours** per grid - a prop and event rename
> pass, plus re-theming.
>
> SVAR's exact prop and event names evolve across releases; check the
> current SVAR docs and map them onto the SvGrid equivalents below.

## Concept map

| SVAR DataGrid (wx-svelte-grid)            | sv-grid                                   |
| ----------------------------------------- | ----------------------------------------- |
| `<Grid {data} {columns} />`               | `<SvGrid data={...} columns={...} />`      |
| `columns: [{ id, header, width, ... }]`   | `columns: [{ field, header, width, ... }]` |
| Per-column `editor` / `template`          | `editorType` + `cell` snippet              |
| Tree / hierarchical data                  | `rowExpandingFeature` + tree row shape     |
| Built-in sort / filter config             | `rowSortingFeature` / `columnFilteringFeature` |
| Edit / change events                      | `onCellValueChange`                        |
| Theme / skin classes                      | `--sg-*` CSS custom properties / Tailwind  |
| Imperative grid API                       | `SvGridApi` via `onApiReady`               |

## Before / after (shape, not exact prop names)

```diff
- <script>
-   import { Grid } from 'wx-svelte-grid'
-   const columns = [
-     { id: 'name',   header: 'Name',   width: 200 },
-     { id: 'amount', header: 'Amount', width: 120, editor: 'text' },
-   ]
- </script>
-
- <Grid {data} {columns} />

+ <script lang="ts">
+   import {
+     SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
+     type ColumnDef,
+   } from 'sv-grid-community'
+
+   const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
+   const columns: ColumnDef<typeof features, Row>[] = [
+     { field: 'name',   header: 'Name',   width: 200 },
+     { field: 'amount', header: 'Amount', width: 120, editorType: 'text' },
+   ]
+ </script>
+
+ <SvGrid data={data} columns={columns} features={features} enableInlineEditing />
```

## Licensing note

Both grids are MIT and free for commercial use, so licensing is not the
deciding factor. The difference is monetization: SVAR keeps the whole
grid free (including CSV export and print) and sells its Gantt instead,
whereas SvGrid's `sv-grid-community` core is MIT and the optional
`sv-grid-pro` pack (advanced XLSX/PDF export, pivot, import, AI, support)
is the paid piece. If all you need is CSV export, SVAR gives it free; if
you need pivot, advanced export, or a support SLA, that is Pro on SvGrid.

## What you get with SvGrid

- **Row grouping with aggregation**, **master-detail**, **pinned rows**,
  and left/right column freezing - beyond SVAR's documented surface.
- A **headless engine** (`createSvGrid` + row models) in addition to the
  component, if you want to compose your own layer.
- **Excel-style filter menu**, **cell-range selection + TSV copy**, a
  **fill handle**, **integrated charts**, and a documented **imperative API**.
- **sv-grid-mcp** so AI assistants answer accurately about your grid.

## What to check on the SVAR side

- The **wider SVAR suite** (Gantt, Scheduler) - if you use several SVAR
  components together, staying on SVAR may be simpler.
- Any **SVAR-specific column features** you rely on; map each to a SvGrid
  `cell` snippet, `editorType`, or feature before porting.

## See also

- [SvGrid vs SVAR Svelte DataGrid](https://svgrid.com/compare/svar-svelte-datagrid) - the side-by-side comparison
- [Architecture](./architecture.md) - the engine + render-component split
- [Cell components](./cells/cell-components.md) - custom cells and editors

## Frequently asked questions

### Why move from SVAR Svelte DataGrid to SvGrid?

Capability and architecture, not licensing (both are MIT). SvGrid adds row
grouping with aggregation, master-detail, Excel-style cell-range selection,
integrated charts, and pivot, and it ships a headless engine plus an MCP server
alongside the component. Both are genuinely Svelte-native, so the core grid
behaviour is comparable; SvGrid simply reaches further.

### Is the migration a rewrite?

No. Both are component-first with array-of-object columns, so it is mostly a
prop / event rename pass (`id` → `field`, edit events → `onCellValueChange`)
plus re-theming through `--sg-*` tokens.

### Are SvGrid and SVAR both free and MIT?

Yes. `sv-grid-community` and the SVAR DataGrid are both MIT and free for
commercial, closed-source use. SVAR keeps the whole grid free and monetizes its
Gantt; on SvGrid, only the optional `sv-grid-pro` add-on (advanced export,
pivot, import, AI, support) is paid.

<!-- =================================================================
     /help/migrating-from-svelte-headless-table  (community)
     ================================================================== -->

# Migrating from svelte-headless-table

svelte-headless-table popularised the headless-table pattern in the
Svelte ecosystem. It is built on Svelte 4 stores and plugins
(`addSortBy`, `addColumnFilters`, `addPagination`, ...), and it leaves
the markup to you. SvGrid keeps the same headless idea but runs on
Svelte 5 runes and ships a render component, so the port mostly
*removes* the table you used to hand-author.

> Estimated effort: **1-3 hours** per grid. Most of the time is deleting
> the `<table>` markup and `Subscribe` blocks you no longer need.

## Vocabulary cheat sheet

| svelte-headless-table                     | sv-grid                                   |
| ----------------------------------------- | ----------------------------------------- |
| `createTable(data, plugins)`              | `createSvGrid({...})` or `<SvGrid>`        |
| `table.createColumns((t) => [...])`       | `columns: ColumnDef[]`                     |
| `t.column({ accessor: 'x', header })`     | `{ field: 'x', header }`                   |
| `t.column({ accessor: (r) => ... })`      | `{ id, accessorFn: (r) => ... }`           |
| `t.group({ header, columns })`            | `{ header, columns: [...] }` (column group) |
| `addSortBy()`                             | `rowSortingFeature`                        |
| `addColumnFilters()` / `addTableFilter()` | `columnFilteringFeature`                   |
| `addPagination()`                         | Built in; toggle `showPagination`          |
| `addExpandedRows()` / `addSubRows()`      | `rowExpandingFeature`                      |
| `addGroupBy()`                            | `columnGroupingFeature` + `api.setGroupBy()` |
| `addSelectedRows()`                       | `rowSelectionFeature`                      |
| `addDataExport()`                         | `sv-grid-pro` export pack                  |
| `createViewModel(columns)` + `Subscribe`  | `<SvGrid>` (no view model to wire)         |
| `pluginStates.sort.sortKeys`              | `api.setSort(id, dir)` / `onSortingChange` |

## Before / after

```diff
- <script>
-   import { createTable } from 'svelte-headless-table'
-   import { addSortBy, addColumnFilters, addPagination } from 'svelte-headless-table/plugins'
-   import { readable } from 'svelte/store'
-
-   const table = createTable(readable(data), {
-     sort: addSortBy(), filter: addColumnFilters(), page: addPagination(),
-   })
-   const columns = table.createColumns((t) => [
-     t.column({ accessor: 'name',   header: 'Name' }),
-     t.column({ accessor: 'amount', header: 'Amount' }),
-   ])
-   const { headerRows, rows, tableAttrs, tableBodyAttrs } = table.createViewModel(columns)
- </script>
-
- <table {...$tableAttrs}>
-   <thead> ...Subscribe over headerRows... </thead>
-   <tbody {...$tableBodyAttrs}> ...Subscribe over rows... </tbody>
- </table>

+ <script lang="ts">
+   import {
+     SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
+     type ColumnDef,
+   } from 'sv-grid-community'
+
+   const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
+   const columns: ColumnDef<typeof features, Row>[] = [
+     { field: 'name',   header: 'Name' },
+     { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },
+   ]
+ </script>
+
+ <SvGrid data={rows} columns={columns} features={features} showPagination />
```

## What you get for free

- **The renderer.** No `createViewModel`, no `Subscribe`, no hand-built
  `<table>`. SvGrid ships virtualization, sticky headers, column
  resize, keyboard nav, and ARIA.
- **Excel-style filter menu** and **cell-range selection + TSV copy**,
  which are BYO in svelte-headless-table.
- **Inline editing** with typed editors and validation hooks.
- **Pro features** - export, import, pivot, AI - in one paid add-on.

## What changes

- **Stores → runes.** Reactive data is `$state` / a plain array, not a
  Svelte store you pass to `createTable`.
- **Plugins → features.** Register `rowSortingFeature` etc. in
  `tableFeatures({...})` instead of `addSortBy()` in the plugin bag.
- **View model → component.** You stop owning the markup; style through
  `--sg-*` tokens (and Tailwind) instead of `tableAttrs`.

## See also

- [SvGrid vs svelte-headless-table](https://svgrid.com/compare/svelte-headless-table) - the side-by-side comparison
- [Migrating from TanStack Table](./migrating-from-tanstack-table.md) - sibling headless guide
- [Why headless?](../why-headless.md) - the design rationale
- [Architecture](./architecture.md) - the engine + render-component split

## Frequently asked questions

### How hard is it to move from svelte-headless-table to SvGrid?

Usually 1-3 hours per grid. The plugin-to-feature mapping is almost one-to-one;
most of the work is deleting the `createViewModel` + `Subscribe` + `<table>`
markup, because SvGrid renders that for you.

### Does SvGrid use Svelte 5 runes instead of stores?

Yes. svelte-headless-table is built on Svelte 4 stores; SvGrid is Svelte-5
native (`$state` / `$derived` / `$effect`) with snippets for custom cells.

### Is SvGrid still headless like svelte-headless-table?

Yes - `createSvGrid` plus the row-model factories is a headless engine you can
drive with your own markup. The difference is that SvGrid *also* ships a
batteries-included `<SvGrid>` component so you usually do not have to.

<!-- =================================================================
     /help/migrating-from-syncfusion  (community)
     ================================================================== -->

# Migrating from Syncfusion Grid

Syncfusion Grid is a comprehensive commercial grid across JavaScript,
React, Vue, Angular, and Blazor, with a free community license for
qualifying small teams. Moving to SvGrid trades the multi-framework suite
for a Svelte-5-native grid with an unconditional MIT core.

> Estimated effort: **3-6 hours** per grid.
>
> Syncfusion's option names vary across its framework flavours; map your
> version's columns and events onto the SvGrid equivalents below.

## Concept map

| Syncfusion Grid                          | sv-grid                                   |
| ---------------------------------------- | ----------------------------------------- |
| `columns: [{ field, headerText }]`       | `columns: [{ field, header }]`             |
| `template` / cell template               | `cell: (c) => renderSnippet(...)`          |
| `editSettings` + `editType`              | `enableInlineEditing` + `editorType`       |
| `allowSorting` / `allowFiltering`        | `rowSortingFeature` / `columnFilteringFeature` |
| `allowGrouping` + `aggregates`           | `columnGroupingFeature` + aggregates       |
| `detailTemplate`                         | `rowExpandingFeature` / master-detail rows |
| `dataSource` (local / `DataManager`)     | `data` array or `externalSort/Filter`      |
| `allowPaging` + `pageSettings`           | `showPagination`                           |
| `toolbar` export                         | `sv-grid-pro` export pack                  |

## Shape of the change

```diff
- <ejs-grid [dataSource]="rows" [allowSorting]="true" [allowFiltering]="true"
-           [allowPaging]="true" [editSettings]="{ allowEditing: true }">
-   <e-columns>
-     <e-column field="name"   headerText="Name"></e-column>
-     <e-column field="amount" headerText="Amount" format="C2"></e-column>
-   </e-columns>
- </ejs-grid>

+ <SvGrid
+   data={rows}
+   columns={[
+     { field: 'name',   header: 'Name' },
+     { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },
+   ]}
+   features={tableFeatures({ rowSortingFeature, columnFilteringFeature })}
+   showPagination enableInlineEditing />
```

## Why teams switch

- **Svelte 5 native** instead of a multi-framework commercial suite.
- **Unconditional MIT core** - no revenue / headcount threshold like the
  Syncfusion community license.
- **Optional Pro pack** for export / import / pivot / AI.

## What to weigh

- Syncfusion ships **one of the largest feature sets and suites**
  available, plus Blazor support. If you need that breadth or Blazor,
  weigh it against the Svelte-native fit.

## See also

- [SvGrid vs Syncfusion Grid](https://svgrid.com/compare/syncfusion-grid) - the side-by-side comparison
- [Data export and printing - Pro](./export.md) - the Pro export pack
- [Getting started](../getting-started.md) - a working grid in ~15 lines

## Frequently asked questions

### Is SvGrid free, unlike the Syncfusion commercial license?

`sv-grid-community` is MIT - free for everyone, with no revenue or team-size
conditions. Syncfusion's community license is free only for qualifying small
teams; otherwise it is commercial.

### How do Syncfusion columns map to SvGrid?

`field` stays `field`, `headerText` becomes `header`, and `template` becomes a
`renderSnippet` cell. Sorting / filtering / grouping move to registered
features.

### Does SvGrid support Blazor?

No - SvGrid is Svelte 5 only. If you need Blazor, that is a genuine reason to
stay on Syncfusion. For a Svelte stack, SvGrid is the native fit.

<!-- =================================================================
     /help/migrating-from-tabulator  (community)
     ================================================================== -->

# Migrating from Tabulator

Tabulator is a feature-rich vanilla-JS table you instantiate against a
DOM element and drive imperatively (`table.setData(...)`,
`table.on('cellEdited', ...)`). SvGrid covers a similar feature surface
but as a Svelte 5 component: data is a reactive `$state` array, custom
cells are snippets, and there is no manual mount / teardown.

> Estimated effort: **2-4 hours** per grid - column translation plus
> swapping imperative `setData` for reactive state.

## Vocabulary cheat sheet

| Tabulator                              | sv-grid                                   |
| -------------------------------------- | ----------------------------------------- |
| `new Tabulator(el, { data, columns })` | `<SvGrid data={...} columns={...} />`      |
| `{ title: 'Name', field: 'name' }`     | `{ header: 'Name', field: 'name' }`        |
| `formatter: fn` / `formatter: 'money'` | `cell: (c) => renderSnippet(...)` or `format` |
| `editor: 'input' / 'number' / ...`     | `editorType: 'text' / 'number' / ...`      |
| `headerFilter: true`                   | `columnFilteringFeature`                   |
| `dataTree: true`                       | `rowExpandingFeature` + tree row shape     |
| `table.setData(rows)`                  | reassign the `$state` data array           |
| `table.on('cellEdited', ...)`          | `onCellValueChange`                        |
| `table.setSort(field, dir)`            | `api.setSort(field, dir)`                  |
| `layout: 'fitColumns'`                 | `fitColumns` prop                          |

## Before / after

```diff
- import { TabulatorFull as Tabulator } from 'tabulator-tables'
-
- const table = new Tabulator('#grid', {
-   data: rows,
-   layout: 'fitColumns',
-   columns: [
-     { title: 'Name',   field: 'name' },
-     { title: 'Amount', field: 'amount', formatter: 'money', editor: 'number' },
-   ],
- })
- table.on('cellEdited', (cell) => save(cell.getData()))

+ <script lang="ts">
+   import {
+     SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
+     type ColumnDef,
+   } from 'sv-grid-community'
+   const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
+   const columns: ColumnDef<typeof features, Row>[] = [
+     { field: 'name',   header: 'Name' },
+     { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' }, editorType: 'number' },
+   ]
+ </script>
+
+ <SvGrid data={rows} columns={columns} features={features} fitColumns enableInlineEditing
+   onCellValueChange={(e) => save(e)} />
```

## What changes

- **Imperative → reactive.** No `setData()` - reassign the `$state`
  array and the grid updates.
- **String formatters → snippets.** Custom cells are Svelte snippets /
  components, not HTML-string formatters.
- **Mount / teardown disappears.** No `new Tabulator(el)` and no manual
  destroy on unmount.

## See also

- [SvGrid vs Tabulator](https://svgrid.com/compare/tabulator) - the side-by-side comparison
- [Cell components](./cells/cell-components.md) - snippet-based custom cells
- [Architecture](./architecture.md) - engine + render-component split

## Frequently asked questions

### Is migrating from Tabulator to SvGrid hard?

It is a configuration translation plus one mindset shift: you stop calling
`setData()` and instead let a reactive `$state` array drive the grid. Budget
2-4 hours per grid.

### Is SvGrid free like Tabulator?

Yes. `sv-grid-community` is MIT-licensed like Tabulator. The optional
`sv-grid-pro` pack (export, import, pivot, AI) is the only paid piece.

### Can I keep Tabulator's custom formatters?

You re-create them as Svelte snippets via `renderSnippet`, which is more
powerful than HTML-string formatters - any component or markup works.

<!-- =================================================================
     /help/migrating-from-tanstack-table  (community)
     ================================================================== -->

# Migrating from TanStack Table

TanStack Table (formerly React Table v8) is the closest conceptual
sibling to sv-grid - both are "headless data grid" libraries with
explicit row-model pipelines. If you already think in
`createTable()` + `getCoreRowModel()`, this is a half-day port.

> Estimated effort: **30 min** per grid for read-only views, **2-4
> hours** for editing-heavy grids.

## Vocabulary cheat sheet

| TanStack Table                  | sv-grid                                  |
| ------------------------------- | ---------------------------------------- |
| `useReactTable({...})`          | `createSvGrid({...})` or `<SvGrid>`       |
| `getCoreRowModel()`             | `createCoreRowModel()`                    |
| `getSortedRowModel()`           | Auto-registered by `rowSortingFeature`    |
| `getFilteredRowModel()`         | Auto-registered by `columnFilteringFeature` |
| `getPaginationRowModel()`       | Built in; toggle with `showPagination`    |
| `getGroupedRowModel()`          | `columnGroupingFeature` + `api.setGroupBy()` |
| `getExpandedRowModel()`         | `rowExpandingFeature`                     |
| `flexRender(col.cell, ctx)`     | `renderSnippet(MyCell, props)` OR string field |
| `columnHelper.accessor('field')` | `{ field: 'field' }` directly             |
| `table.getRowModel().rows`      | `api.getDisplayedRows()`                   |
| `table.setColumnFilters(...)`   | `api.setFilter(id, {...})` per column      |
| `meta` (column / table)         | n/a - use column `cellClass` / `cell` instead |

## Imports

```diff
- import {
-   useReactTable, getCoreRowModel, getSortedRowModel, getFilteredRowModel,
-   flexRender, createColumnHelper,
- } from '@tanstack/react-table'

+ import {
+   SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
+   renderSnippet, type ColumnDef,
+ } from 'sv-grid-community'
```

## Column definitions

```diff
- const columnHelper = createColumnHelper<Order>()
- const columns = [
-   columnHelper.accessor('orderId',  { header: 'Order ID' }),
-   columnHelper.accessor('amount',   { header: 'Amount', cell: ({ getValue }) => fmt(getValue<number>()) }),
- ]

+ const columns: ColumnDef<typeof features, Order>[] = [
+   { field: 'orderId', header: 'Order ID' },
+   { field: 'amount',  header: 'Amount', format: { type: 'currency', currency: 'USD' } },
+ ]
```

The `accessorFn` form is the same:

```diff
- columnHelper.accessor((row) => row.profile.name, { id: 'name', header: 'Name' })

+ { id: 'name', accessorFn: (row) => row.profile.name, header: 'Name' }
```

## Mounting

```diff
- const table = useReactTable({
-   data, columns,
-   getCoreRowModel:       getCoreRowModel(),
-   getSortedRowModel:     getSortedRowModel(),
-   getFilteredRowModel:   getFilteredRowModel(),
- })
- return (
-   <table>
-     <thead>{table.getHeaderGroups().map(/* ... */)}</thead>
-     <tbody>{table.getRowModel().rows.map(/* ... */)}</tbody>
-   </table>
- )

+ const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
+
+ <SvGrid data={rows} columns={columns} features={features} />
```

Sv-grid bundles the render + virtualization. No `<table>` you have
to author yourself.

## Imperative state

| TanStack Table                              | sv-grid                                  |
| ------------------------------------------- | ---------------------------------------- |
| `table.setColumnFilters([{id, value}])`     | `api.setFilter(id, { operator: 'contains', value })` |
| `table.getColumn('id')?.setFilterValue(v)`  | `api.setFilter(id, { operator: 'contains', value: v })` |
| `table.setSorting([{id, desc}])`            | `api.setSort(id, desc ? 'desc' : 'asc')`  |
| `table.setRowSelection(state)`              | n/a - use `api.clearRowSelection()` + UI events |
| `table.toggleAllRowsExpanded()`             | `api.expandAllGroups()`                   |
| `table.getColumn('x').toggleVisibility()`   | `api.setColumnVisible('x', false)`        |
| `table.options.meta?.foo`                   | Pass through component props / `$state`   |

## Custom cells

```diff
- {
-   header: 'Status',
-   cell: ({ row }) => <Badge tone={row.original.status} />,
- }

+ {
+   field: 'status', header: 'Status',
+   cell: (ctx) => renderSnippet(StatusCell, { tone: ctx.row.original.status }),
+ }
```

`renderSnippet` accepts any Svelte 5 snippet; `renderComponent`
accepts a regular component if you prefer SFCs.

## Server-side data

```diff
- const [pagination, setPagination] = useState({pageIndex: 0, pageSize: 25})
- const [sorting, setSorting]       = useState([])
- const table = useReactTable({
-   data, columns, manualPagination: true, manualSorting: true,
-   state: { pagination, sorting },
-   onPaginationChange: setPagination,
-   onSortingChange:    setSorting,
- })

+ <SvGrid
+   data={rows} columns={columns} features={features}
+   externalSort={true}
+   externalFilter={true}
+   onSortingChange={(clauses) => refetch({ sort: clauses })}
+   onFiltersChange={(f)       => refetch({ filters: f.columns })}
+ />
```

## What you get for free vs TanStack Table

- **Renderer**. TanStack is headless-only; you draw the `<table>`.
  Sv-grid ships an opinionated, fast renderer with virtualization,
  scroll, sticky headers, column resize, keyboard nav, ARIA.
- **Inline editing**. `editorType: 'text' | 'number' | 'date' |
  'list' | ...` - built-in editors with parsing + validation hooks.
- **CSP-clean**. No `eval`. The shipped tests confirm.
- **Pro features**. Export, import, pivot, AI - in one paid add-on.

## What you give up

- **React-first ecosystem.** Sv-grid is Svelte 5-native. There's no
  React wrapper.
- **`meta` for arbitrary side-channel state.** Pass props directly.
- **`@tanstack/match-sorter-utils` integration**. The grid's filter
  has a `contains` operator; if you need fuzzy match, plug your
  matcher in via the column's `cell` snippet or use
  `externalFilter={true}` and run the matcher yourself.

## See also

- [Architecture](./architecture.md) - the headless engine + render
  component split
- [Migrating from AG Grid](./migrating-from-ag-grid.md) - sibling guide
- [Why headless?](../why-headless.md) - the design rationale

## Frequently asked questions

### How long does it take to migrate from TanStack Table to SvGrid?

About 30 minutes per read-only grid and 2-4 hours for editing-heavy grids.
Both libraries use explicit row-model pipelines, so `createTable()` +
`getCoreRowModel()` maps almost directly onto `createSvGrid()` +
`createCoreRowModel()`.

### Why switch from TanStack Table to SvGrid on Svelte 5?

TanStack Table is headless-only and multi-framework, so you build the entire
DOM, virtualization, filter UI, and editing layer yourself. SvGrid keeps the
headless core but ships a batteries-included `<SvGrid>` render component -
virtualization, Excel-style filters, cell selection, and inline editing work
in one prop pass.

### Is SvGrid free like TanStack Table?

Yes - `sv-grid-community` is MIT-licensed, like TanStack Table. SvGrid
additionally offers an optional paid `sv-grid-pro` pack for export, pivot, and
import, which TanStack Table does not provide at all.

<!-- =================================================================
     /help/migrating-from-ui-kit-tables  (community)
     ================================================================== -->

# Migrating from a UI-kit table (Flowbite / Skeleton / shadcn-svelte)

Flowbite-Svelte, Skeleton, and shadcn-svelte all ship a styled `<Table>`
component. They are presentation components: they render the rows you
pass and match your design tokens, but sorting, filtering,
virtualization, and editing are yours to write by hand. Moving to SvGrid
replaces that hand-rolled logic with built-in features - while still
letting you match the design system.

> Estimated effort: **30 min - 1 hour** per table. You are mostly
> deleting `{#each}` markup and the sort / filter state you wrote
> yourself.

## When this guide applies

You have a table that started simple and has grown:

- You added a click-to-sort handler and a sort-state variable.
- You added a search box and an array `.filter(...)`.
- The list got long and now you want virtualization or pagination.
- You started editing cells inline and it got messy.

That is the moment a styled `<Table>` stops paying for itself.

## Before / after

```diff
- <script>
-   import { Table, TableHead, TableHeadCell, TableBody, TableBodyRow, TableBodyCell } from 'flowbite-svelte'
-   let sortKey = 'name', asc = true
-   $: sorted = [...rows].sort((a, b) => (a[sortKey] > b[sortKey] ? 1 : -1) * (asc ? 1 : -1))
- </script>
-
- <Table>
-   <TableHead>
-     <TableHeadCell on:click={() => (sortKey = 'name')}>Name</TableHeadCell>
-     <TableHeadCell on:click={() => (sortKey = 'amount')}>Amount</TableHeadCell>
-   </TableHead>
-   <TableBody>
-     {#each sorted as row}
-       <TableBodyRow>
-         <TableBodyCell>{row.name}</TableBodyCell>
-         <TableBodyCell>{row.amount}</TableBodyCell>
-       </TableBodyRow>
-     {/each}
-   </TableBody>
- </Table>

+ <script lang="ts">
+   import {
+     SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
+     type ColumnDef,
+   } from 'sv-grid-community'
+
+   const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
+   const columns: ColumnDef<typeof features, Row>[] = [
+     { field: 'name',   header: 'Name' },
+     { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },
+   ]
+ </script>
+
+ <SvGrid data={rows} columns={columns} features={features} showPagination />
```

The sort handler, the `sorted` derivation, and the `{#each}` all go
away. Sorting is a click on the header; filtering is the column menu.

## Keep your design system

SvGrid is unstyled-by-token, so it can match Flowbite / Skeleton /
shadcn:

- Re-theme through the `--sg-*` CSS custom properties (borders, header
  background, zebra rows, hover, selection, density).
- Or drive those tokens from your Tailwind theme - see the
  [Tailwind integration](./tailwind.md) guide.

## What you get for free

- **Sorting, filtering, and pagination** without writing handlers.
- **Row + column virtualization** so thousands of rows stay smooth.
- **Inline editing**, **cell-range selection + copy**, grouping, tree,
  and master/detail when you need them.
- **Accessibility** - WAI-ARIA grid roles and keyboard navigation built
  in, instead of a plain `<table>`.

## What you give up

- The **tiny footprint** of a styled `<table>` for a truly static list.
- A **pixel-perfect**, zero-config match with the rest of the kit - you
  re-create the look with tokens instead (a one-time setup).

## See also

- [SvGrid vs UI-kit tables](https://svgrid.com/compare/svelte-ui-kit-tables) - the side-by-side comparison
- [Tailwind integration](./tailwind.md) - match your design system
- [Getting started](../getting-started.md) - a working grid in ~15 lines

## Frequently asked questions

### When should I replace a Flowbite / Skeleton / shadcn table with a data grid?

When the table needs sorting, filtering, virtualization, inline editing, or
large datasets. UI-kit tables are presentation components; once you are
hand-writing table behaviour, a data grid like SvGrid removes that code.

### Can SvGrid match my existing UI-kit styling?

Yes. SvGrid themes through `--sg-*` CSS variables, which you can wire to your
Tailwind / design-system tokens so it matches Flowbite, Skeleton, or
shadcn-svelte.

### Is it overkill for a small static table?

For a small, static table that never sorts or filters, a styled `<table>` is
lighter and fine. Switch when the behaviour - not just the styling - becomes the
work.

<!-- =================================================================
     /help/migrating-from-vincjo-datatables  (community)
     ================================================================== -->

# Migrating from @vincjo/datatables

`@vincjo/datatables` is a small, ergonomic Svelte datatable helper: you
wrap your data in a handler and it gives you reactive sorting,
filtering, and pagination while you keep your own table markup. SvGrid
covers the same job and then keeps going - virtualization, an
Excel-style filter menu, inline editing, and a render component - so the
port is mostly about deciding how much markup you want to keep.

> Estimated effort: **30 min - 2 hours** per table. A simple list is a
> 30-minute swap; a feature-heavy one trends toward two hours.

## Vocabulary cheat sheet

| @vincjo/datatables                         | sv-grid                                   |
| ------------------------------------------ | ----------------------------------------- |
| `new TableHandler(data, { rowsPerPage })`  | `createSvGrid({...})` or `<SvGrid>`        |
| `<ThSort {table} field="name">`            | `rowSortingFeature` (header sort built in) |
| `<ThFilter {table} field="name">`          | `columnFilteringFeature`                   |
| `table.global.set(query)` (search)         | `api.setGlobalFilter(query)`               |
| `<Pagination {table} />` / `<RowCount>`    | Built in; toggle `showPagination`          |
| `table.rows` (current page rows)           | `api.getDisplayedRows()`                   |
| Server mode (`table.load(...)`)            | `externalSort` / `externalFilter` + refetch |
| Your own `<table>` + `{#each table.rows}`  | `<SvGrid>` render component                 |

## Before / after

```diff
- <script>
-   import { TableHandler, ThSort, ThFilter, Pagination } from '@vincjo/datatables'
-   const table = new TableHandler(rows, { rowsPerPage: 25 })
- </script>
-
- <table>
-   <thead><tr>
-     <ThSort {table} field="name">Name</ThSort>
-     <ThSort {table} field="amount">Amount</ThSort>
-   </tr></thead>
-   <tbody>
-     {#each table.rows as row}
-       <tr><td>{row.name}</td><td>{row.amount}</td></tr>
-     {/each}
-   </tbody>
- </table>
- <Pagination {table} />

+ <script lang="ts">
+   import {
+     SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
+     type ColumnDef,
+   } from 'sv-grid-community'
+
+   const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
+   const columns: ColumnDef<typeof features, Row>[] = [
+     { field: 'name',   header: 'Name' },
+     { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },
+   ]
+ </script>
+
+ <SvGrid data={rows} columns={columns} features={features} showPagination />
```

## Server-side data

```diff
- // @vincjo/datatables: drive a server with the handler's load hook
- const table = new TableHandler(rows, { rowsPerPage: 25 })
- table.load((state) => fetchRows(state)) // sort/filter/page sent to your API

+ <SvGrid
+   data={rows} columns={columns} features={features}
+   externalSort={true} externalFilter={true}
+   onSortingChange={(clauses) => refetch({ sort: clauses })}
+   onFiltersChange={(f)       => refetch({ filters: f.columns })}
+ />
```

## What you get for free

- **A render component** with virtualization - you stop authoring the
  `<table>` and the `{#each}`.
- **Excel-style filter menu**, **cell-range selection + copy**, and
  **inline editing** with typed editors.
- **Grouping, tree data, and master/detail** when the table grows up.
- **Pro features** - export, import, pivot, AI.

## What you give up

- **The tiny footprint.** If all you ever need is sort / filter /
  paginate over a small list, `@vincjo/datatables` stays smaller.
- **Total markup control.** SvGrid renders the table; you theme it with
  `--sg-*` tokens and Tailwind rather than writing every `<td>`.

## See also

- [SvGrid vs @vincjo/datatables](https://svgrid.com/compare/vincjo-datatables) - the side-by-side comparison
- [Migrating from svelte-headless-table](./migrating-from-svelte-headless-table.md) - sibling Svelte guide
- [Why headless?](../why-headless.md) - keep your own markup if you want to

## Frequently asked questions

### Should I move from @vincjo/datatables to SvGrid?

Move when a hand-rolled table stops being enough - when you need virtualization
for large datasets, an Excel-style filter menu, inline editing, grouping, or
tree data. For a small sort/filter/paginate list, `@vincjo/datatables` is a fine,
lighter choice.

### Is SvGrid also MIT-licensed like @vincjo/datatables?

Yes. `sv-grid-community` is MIT, like `@vincjo/datatables`. SvGrid adds an
optional paid `sv-grid-pro` pack (export, import, pivot, AI).

### Can I keep my own table markup after switching?

Yes. SvGrid has a headless core (`createSvGrid` + row-model factories) you can
drive with your own markup, the same way `@vincjo/datatables` lets you. Most
teams use the `<SvGrid>` component instead because it removes the boilerplate.

<!-- =================================================================
     /help/missing-features  (community)
     ================================================================== -->

# Missing features

This is the honest accounting of capabilities the help topics flagged as
**not yet implemented** in the community build. Each entry has:

- a short description of the gap,
- the topic page(s) that link here, and
- a rough effort estimate (S - small, M - medium, L - large).

Use this list to decide which to PR yourself, which to file an issue
about, and which to work around in the meantime.

## Columns

| Gap | Where | Effort |
| --- | ----- | ------ |
| ~~`getRowId` prop on `<SvGrid>` wrapper~~ - **shipped** | [Row data](./rows/row-data.md) | ✓ |
| ~~`cellClass(ctx)` / `rowClass(ctx)` callbacks~~ - **shipped** | [Styling rows](./rows/styling-rows.md), [Styling cells](./cells/styling-cells.md) | ✓ |
| ~~`getColumnWidths()` / `setColumnWidth()` on `SvGridApi`~~ - **shipped** | [Column sizing](./columns/column-sizing.md) | ✓ |
| ~~`setColumnPinning()` / `getColumnPinning()` on `SvGridApi`~~ - **shipped** | [Column pinning](./columns/column-pinning.md) | ✓ |
| Header drag-to-reorder, built-in | [Column moving](./columns/column-moving.md) | M |
| Per-column `enableSorting: false` / `enableFilter: false` flags | [Row sorting](./rows/row-sorting.md), [Filter API](./filtering/filter-api.md) | S |
| Column spanning (`colSpan` on cell context) | [Column spanning](./columns/column-spanning.md) | L |

## Rows

| Gap | Where | Effort |
| --- | ----- | ------ |
| Row pinning (top / bottom) | [Row pinning](./rows/row-pinning.md) | M |
| Row spanning (merged cells across rows) | [Row spanning](./rows/row-spanning.md) | L |
| Full-width / detail row API | [Full-width rows](./rows/full-width-rows.md) | M |
| Built-in row dragging - managed + unmanaged + drop zones + grid-to-grid | [Row dragging](./rows/row-dragging.md) | L |
| ~~`api.getDisplayedRows()` (post-pipeline)~~ - **shipped in v1.0** | [Accessing rows](./rows/accessing-rows.md) | ✓ |
| Variable row height with `<SvGrid>` (only available via the headless virtualizer today) | [Row height](./rows/row-height.md) | M |

## Cells

| Gap | Where | Effort |
| --- | ----- | ------ |
| Built-in tooltip API on `ColumnDef` | [Tooltips](./cells/tooltips.md) | S |
| Built-in cell flash / animated change highlight on `ColumnDef` (demos roll their own via `renderSnippet`, e.g. `11-stock-market`, `18-cascade-editing`) | [Highlighting changes](./cells/highlighting-changes.md) | S |
| Formula language / formula editor (enterprise-grade parity) | [Expressions](./cells/expressions.md) | L |
| Find-in-grid feature | (enterprise gap) | M |
| Notes feature | (enterprise gap) | M |

## Export / Print

| Gap | Where | Effort |
| --- | ----- | ------ |
| ~~Excel / xlsx export~~ - **shipped in `sv-grid-pro` v1.0** | [Export](./export.md) | ✓ |
| ~~PDF export~~ - **shipped in `sv-grid-pro` v1.0** | [Export](./export.md) | ✓ |
| ~~CSV / TSV / HTML export~~ - **shipped in `sv-grid-pro` v1.0** | [Export](./export.md) | ✓ |
| ~~Print (printable view + browser print dialog)~~ - **shipped in `sv-grid-pro` v1.0** | [Export](./export.md) | ✓ |

## Filtering

| Gap | Where | Effort |
| --- | ----- | ------ |
| Floating filters with per-operator parity (inline filter row exists; per-operator UI under the funnel) | [Floating filters](./filtering/floating-filters.md) | M |
| ~~`between` operator exposed in the column menu~~ - **shipped** (Number + Date columns get a "Between" entry with two value inputs) | [Number filter](./filtering/number-filter.md), [Date filter](./filtering/date-filter.md) | ✓ |
| Set filter - tree-list, async values, Excel-mode | [Set filter](./filtering/set-filter.md) | L |
| `multi`-filter on a single column (AND / OR within column) | [Filter conditions](./filtering/filter-conditions.md) | M |
| ~~`clearAllFilters()` on `SvGridApi`~~ - **shipped in v1.0** | [Filter API](./filtering/filter-api.md) | ✓ |
| ~~`api.getFilters()` reader on `SvGridApi`~~ - **shipped in v1.0** | [Filter API](./filtering/filter-api.md) | ✓ |
| Locale-aware text filtering (accent-insensitive, ICU-style collation) | [Text filter](./filtering/text-filter.md) | M |

## Editing

| Gap | Where | Effort |
| --- | ----- | ------ |
| `cellEditor` slot for custom inline editors | [Edit components](./editing/edit-components.md) | M |
| Built-in select & rich-select editors | [Provided editors](./editing/provided-editors.md) | M |
| Built-in large-text (textarea) editor | [Provided editors](./editing/provided-editors.md) | S |
| Per-column `valueParser` | [Parsing values](./editing/parsing-values.md) | S |
| Per-column `validate()` returning `string | true` | [Validation](./editing/validation.md) | S |
| Programmatic `api.startEditing(rowIndex, columnId)` / `stopEditing()` | [Start / stop editing](./editing/start-stop-editing.md) | S |
| Full-row editing mode | [Full-row](./editing/full-row.md) | M |
| Built-in undo / redo stack (now feasible since `onCellValueChange` ships) | [Undo / redo](./editing/undo-redo.md) | M |
| Batch / staged editing mode (commit a set, not individual cells) | (enterprise gap) | M |

## What's already there

For balance - the things that **are** built in and stable:

- Sorting (single + multi, click + shift-click) with `onSortingChange` callback
- Per-column filtering (menu + filter row + global) with operators `contains` / `equals` / `startsWith` / `greaterThan` / `lessThan` / **`between`** (two-input range) / `isBlank`, and an `onFiltersChange` callback that emits the consolidated `{ global, columns: [{ id, operator, value, valueTo? }] }` payload
- **External-data mode**: `externalSort` / `externalFilter` props let the consumer own row ordering and filtering for server-side / tree data; the grid records UI state but does not re-order rows (see demo `09-server-side`, `08-tree-and-master-detail`)
- Pagination, programmatic page controls
- Grouping (one or more columns) + grouped/aggregated footer summaries
- Row expansion (`rowExpandingFeature`)
- Row selection (single, multi, checkbox column) with `onRowSelectionChange` callback
- Cell range selection + copy/paste as TSV
- Inline editing with five built-in editor types and `onCellValueChange(event)` callback (used by demo `18-cascade-editing`)
- Row + column virtualization, with overscan controls; column virtualizer detects per-column size changes (so resize / fit-to-width re-render correctly)
- Column resize via the header handle, plus `api.setColumnWidth(id, px)` / `api.getColumnWidths()` for programmatic / persisted layouts
- Fit columns to viewport (`fitColumns` prop) - residue-absorbing, with modest shrink-to-fit
- Column pinning (left / right) via the column menu **and** via `api.setColumnPinning({left, right})` / `api.getColumnPinning()`
- **Stable row identity**: `getRowId(row, index)` prop on `<SvGrid>` (and `SvGridOptions` for the headless core) - drives selection / expansion / edit state across re-orders and filters
- **Conditional class hooks**: `cellClass` on `ColumnDef` and `rowClass` on `<SvGrid>` accept string / array / `Record<string, boolean>` or a callback - no more wrapping every cell in a render snippet just to tint it
- Optional leading row-number column (`showRowNumbers`) and selection checkbox column
- "Source" button in the gallery shell shows each demo's raw `.svelte` source for copy-paste
- Imperative API for data + columns + filters + sort + grouping + visibility (`onApiReady`)
- WAI-ARIA grid pattern with helpers in [`a11y.ts`](../../packages/sv-grid-community/src/a11y.ts) (see demo `17-accessibility`)
- Locale-aware number / currency / percent / date / datetime formatters with `Intl` caching (see demo `15-localization`)
- Built-in CSS custom-property theming surface (`--sg-*`); per-instance theme via `style="--sg-bg: ..."` (see demo `10-custom-cells-and-themes`)
- CSP-clean runtime: no `eval`, no `new Function`, no inline scripts (see demo `16-csp-compliant`)
- SSR-friendly: the grid renders meaningful HTML before hydration (see demo `19-ssr`)

## How to contribute

1. Pick an entry from above.
2. Open an issue describing the API you'd want - names, types, the
   minimal change.
3. If you can write the patch, do so. Keep tests with the change.

PRs that close items here are the fastest way to move SvGrid towards
real enterprise-quality parity in the community build.

<!-- =================================================================
     /help/mobile-card-view  (community)
     ================================================================== -->

# Mobile card view

On wide screens the grid is the grid. Under a viewport breakpoint
(by convention 720 px), the same `$state` array re-renders as
touch-friendly cards. Tap a card to expand it into an edit panel; the
write flows through `api.setCellValue` so dirty tracking, filtering,
and external observers see every edit identically, whether it came
from the desktop grid or from the mobile card.

The headless engine is the single source of truth - filter, sort,
and selection state live on `api`, so swapping between viewport sizes
preserves the user's working set.

<div data-docs-demo="81-mobile-card-view" data-height="640"></div>

## The pivot

Three pieces wire the responsive pivot together:

1. **A viewport observer** that flips a `$state` boolean under the
   breakpoint.
2. **A single `data` array** shared between the grid and the card list.
3. **A single mutation function** that writes through `api.setCellValue`
   when the grid is mounted, or mutates the array directly when only
   the card list is mounted.

```ts
const MOBILE_MAX = 720
let isMobile = $state(false)

$effect(() => {
  isMobile = window.innerWidth <= MOBILE_MAX
  const onResize = () => (isMobile = window.innerWidth <= MOBILE_MAX)
  window.addEventListener('resize', onResize)
  return () => window.removeEventListener('resize', onResize)
})
```

## Complete drop-in example

A ticket board that renders as a SvGrid on desktop and as a card list
on mobile. Both views write through the same `setCell` helper so the
data layer doesn't care which one is active.

```svelte
<script lang="ts">
  import {
    SvGrid,
    tableFeatures,
    rowSortingFeature,
    columnFilteringFeature,
    type ColumnDef,
    type SvGridApi,
  } from 'sv-grid-community'

  type Status   = 'open' | 'in_progress' | 'blocked' | 'done'
  type Priority = 'low' | 'med' | 'high' | 'urgent'
  type Ticket = {
    id: string
    title: string
    assignee: string
    status: Status
    priority: Priority
    dueDate: string
    estimateHours: number
  }

  let rows = $state<Ticket[]>([
    { id: 't01', title: 'Onboarding wizard',     assignee: 'Ada Lovelace',   status: 'in_progress', priority: 'high',   dueDate: '2026-06-15', estimateHours: 12 },
    { id: 't02', title: 'Stripe webhook retry',  assignee: 'Linus Torvalds', status: 'open',        priority: 'urgent', dueDate: '2026-06-10', estimateHours: 6  },
    { id: 't03', title: 'Search index migration',assignee: 'Grace Hopper',   status: 'blocked',     priority: 'med',    dueDate: '2026-06-22', estimateHours: 16 },
  ])

  const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
  let api = $state<SvGridApi<typeof features, Ticket> | null>(null)

  // ---- Viewport ----------------------------------------------------------
  const MOBILE_MAX = 720
  let isMobile = $state(false)
  $effect(() => {
    isMobile = window.innerWidth <= MOBILE_MAX
    const onResize = () => (isMobile = window.innerWidth <= MOBILE_MAX)
    window.addEventListener('resize', onResize)
    return () => window.removeEventListener('resize', onResize)
  })

  // ---- The one mutation path ---------------------------------------------
  function setCell<K extends keyof Ticket>(rowId: string, field: K, value: Ticket[K]) {
    const ix = rows.findIndex((r) => r.id === rowId)
    if (ix === -1) return
    if (api) api.setCellValue(ix, field as string, value)
    else (rows[ix] as Ticket)[field] = value
  }

  // ---- Card expand state -------------------------------------------------
  let expandedId = $state<string | null>(null)

  const STATUS_OPTS: Status[]   = ['open', 'in_progress', 'blocked', 'done']
  const PRIO_OPTS:   Priority[] = ['low', 'med', 'high', 'urgent']

  const columns: ColumnDef<typeof features, Ticket>[] = [
    { field: 'id',            header: 'ID',       editorType: 'text',   width: 80,  editable: false },
    { field: 'title',         header: 'Title',    editorType: 'text',   width: 220 },
    { field: 'assignee',      header: 'Assignee', editorType: 'text',   width: 180 },
    { field: 'status',        header: 'Status',
      editorType: 'list', editorOptions: STATUS_OPTS as unknown as ReadonlyArray<string>, width: 140 },
    { field: 'priority',      header: 'Priority',
      editorType: 'list', editorOptions: PRIO_OPTS as unknown as ReadonlyArray<string>, width: 120 },
    { field: 'dueDate',       header: 'Due',      editorType: 'date',   width: 130 },
    { field: 'estimateHours', header: 'Est. h',   editorType: 'number', width: 100 },
  ]
</script>

<div style="height: 100%;">
  {#if isMobile}
    <!-- ─────────── CARD LIST (mobile) ─────────── -->
    <div style="height: 100%; overflow-y: auto; display: flex; flex-direction: column; gap: 8px;">
      {#each rows as r (r.id)}
        {@const open = expandedId === r.id}
        <article style="border: 1px solid #e2e8f0; border-radius: 12px; background: #fff;">
          <button
            type="button"
            onclick={() => (expandedId = open ? null : r.id)}
            style="width: 100%; text-align: left; border: 0; background: transparent; padding: 12px 14px; cursor: pointer;"
          >
            <div style="display: flex; gap: 8px; align-items: center; margin-bottom: 6px;">
              <code style="font-size: 11px; color: #64748b;">{r.id}</code>
              <span style="font-size: 10px; font-weight: 700; text-transform: uppercase; padding: 2px 8px; border-radius: 999px; background: #fee2e2; color: #991b1b;">
                {r.priority}
              </span>
            </div>
            <div style="font-weight: 600; font-size: 15px; color: #0f172a;">{r.title}</div>
            <div style="display: flex; gap: 12px; margin-top: 6px; font-size: 12px; color: #64748b;">
              <span>👤 {r.assignee}</span>
              <span>📅 {r.dueDate}</span>
              <span>⏱ {r.estimateHours}h</span>
            </div>
          </button>

          {#if open}
            <div style="border-top: 1px solid #e2e8f0; padding: 14px; background: #f8fafc; display: grid; grid-template-columns: repeat(2, 1fr); gap: 10px;">
              <label style="grid-column: 1 / -1;">
                Title
                <input type="text" value={r.title}
                  oninput={(e) => setCell(r.id, 'title', (e.currentTarget as HTMLInputElement).value)} />
              </label>
              <label>
                Status
                <select value={r.status}
                  onchange={(e) => setCell(r.id, 'status', (e.currentTarget as HTMLSelectElement).value as Status)}>
                  {#each STATUS_OPTS as s (s)}<option value={s}>{s}</option>{/each}
                </select>
              </label>
              <label>
                Priority
                <select value={r.priority}
                  onchange={(e) => setCell(r.id, 'priority', (e.currentTarget as HTMLSelectElement).value as Priority)}>
                  {#each PRIO_OPTS as p (p)}<option value={p}>{p}</option>{/each}
                </select>
              </label>
            </div>
          {/if}
        </article>
      {/each}
    </div>
  {:else}
    <!-- ─────────── GRID (desktop) ─────────── -->
    <SvGrid
      data={rows}
      columns={columns}
      features={features}
      enableInlineEditing={true}
      enableCellSelection={true}
      rowHeight={40}
      containerHeight="100%"
      fitColumns={true}
      onApiReady={(next) => (api = next)}
    />
  {/if}
</div>
```

## Why the two-path mutation matters

The card view mounts only when the grid is *un*mounted. When the user
edits a field in card mode, `api` is `null` because the grid component
is not in the DOM. The `setCell` helper handles both cases:

```ts
function setCell<K extends keyof Ticket>(rowId: string, field: K, value: Ticket[K]) {
  const ix = rows.findIndex((r) => r.id === rowId)
  if (ix === -1) return
  if (api) api.setCellValue(ix, field as string, value)
  else (rows[ix] as Ticket)[field] = value
}
```

Why bother with both? Two reasons:

- When the grid is mounted, `api.setCellValue` emits `onCellValueChange`,
  triggers validators, and updates dirty tracking. Direct mutation
  skips all of that.
- When the grid is unmounted, `api` is `null`. Direct mutation is the
  only path that still updates the underlying `$state` array.

If you want **identical observer behavior in both modes**, register
your `onCellValueChange` callbacks against the `$state` array via a
`$effect` instead of via the grid prop. Then either path triggers it.

## A force-toggle for testing

Users on tablets sit awkwardly across the breakpoint; QA wants to
verify both views without resizing. Add a manual override:

```svelte
<script lang="ts">
  let forceView = $state<'auto' | 'grid' | 'cards'>('auto')
  const showCards = $derived(forceView === 'cards' || (forceView === 'auto' && isMobile))
</script>

<div role="group" aria-label="View mode">
  <button onclick={() => (forceView = 'auto')}  class:on={forceView === 'auto'}>Auto</button>
  <button onclick={() => (forceView = 'grid')}  class:on={forceView === 'grid'}>Grid</button>
  <button onclick={() => (forceView = 'cards')} class:on={forceView === 'cards'}>Cards</button>
</div>
```

Then drive the conditional render off `showCards` instead of `isMobile`.

## Density parity

When the user toggles between views, density should not jolt. Match
`rowHeight` (grid) with the card height (cards):

```svelte
<SvGrid rowHeight={96} ... />

<style>
  .card-head { height: 96px; }
</style>
```

A 96 px row is large for a desktop grid but matches a typical mobile
card. If your grid is denser, pick a card height closer to your row
height (e.g. 56 px for compact grids), and put the title + meta in
one line.

## See also

- [Demo 81 - Mobile card view](../../examples/src/demos/81-mobile-card-view.svelte) - full source with KPI strip, view-mode toggle, and per-priority colour bars
- [Demo 76 - Kanban board](../../examples/src/demos/76-kanban-board.svelte) - same headless-engine-driven-multiple-views pattern, four columns instead of one card list
- [Conditional form schema](./conditional-form-schema.md) - if your card form needs declarative field-visibility rules

## Frequently asked questions

### Is SvGrid responsive / mobile-friendly?

Yes. Above a breakpoint (720 px by convention) it renders as a normal grid;
below it, the same `$state` data re-renders as touch-friendly cards. Both views
are driven by one headless engine, so edits and state stay in sync.

### How do edits on mobile cards stay consistent with the grid?

Card edits flow through `api.setCellValue`, the same path desktop grid edits use.
Dirty tracking, filtering, and external observers see every change identically
regardless of which view produced it.

### Can I reuse the same data for a Kanban or card layout?

Yes. The headless engine can drive multiple views from one data source - the
mobile card view and the Kanban demo are the same pattern with different
rendering.

<!-- =================================================================
     /help/observability  (community)
     ================================================================== -->

# Observability

Production-grade visibility into a live grid: which rows users see,
which cells they edit, what they filter for, how often the imperative
API is invoked. Everything you need to wire into Sentry, Datadog,
OpenTelemetry, Honeycomb, your own pipeline.

The library is **callback-driven**: every observable event surfaces
as a prop you can subscribe to. No metrics SDK is bundled - you wire
to whatever your org already runs.

## What you can observe

| Signal              | Callback                                  | Fires when                                                       |
| ------------------- | ----------------------------------------- | ---------------------------------------------------------------- |
| Active cell move    | `onActiveCellChange`                      | User clicks / tabs / arrow-keys into a new cell                  |
| Cell edit committed | `onCellValueChange`                       | An edit lands (Enter / Tab / blur)                               |
| Row selection      | `onRowSelectionChange`                    | User toggles a row checkbox / clicks a row in `selectionMode='row'` |
| Filter change      | `onFiltersChange`                         | Any filter (menu / row / facet / global) changes                 |
| Sort change        | `onSortingChange`                         | Sort clauses change                                              |
| Grouping change    | `onGroupingChange`                        | The `groupBy` clauses change                                     |
| API ready          | `onApiReady`                              | Once, when the imperative `SvGridApi` is wired                   |

For server-side adapters (`externalSort` / `externalFilter`) the same
callbacks fire BEFORE the network call, giving you a natural place to
measure server latency.

## Recipe 1: Datadog Browser RUM

```svelte
<script lang="ts">
  import { datadogRum } from '@datadog/browser-rum'

  function track(name: string, payload: Record<string, unknown>) {
    datadogRum.addAction(name, payload)
  }
</script>

<SvGrid
  {data} {columns} features={features}
  onActiveCellChange={(cell) => track('grid.cell.focus',  cell)}
  onCellValueChange={(e)    => track('grid.cell.edit',   { columnId: e.columnId, rowId: e.row.id })}
  onFiltersChange={(f)      => track('grid.filter',      { columns: f.columns.length, hasGlobal: !!f.global })}
  onSortingChange={(s)      => track('grid.sort',        { columns: s.length })}
/>
```

PII discipline: send IDs and counts, never values. The third callback
above sends `columns: 3` (the count of active filter columns), not
the actual filter text the user typed.

## Recipe 2: Sentry breadcrumbs

```ts
import * as Sentry from '@sentry/svelte'

function crumb(category: string, message: string, data?: unknown) {
  Sentry.addBreadcrumb({ category, message, data, level: 'info' })
}
```

Then in the grid:

```svelte
<SvGrid
  ...
  onCellValueChange={(e) => crumb('grid', `edit ${e.columnId}`, { id: e.row.id })}
  onFiltersChange={(f)   => crumb('grid', 'filter change',       { n: f.columns.length })}
/>
```

When an exception fires elsewhere in the app, the Sentry event ships
with the last ~30 grid actions as breadcrumbs - massive debug time
saver.

## Recipe 3: OpenTelemetry browser SDK

```ts
import { trace } from '@opentelemetry/api'

const tracer = trace.getTracer('sv-grid')

function span<T>(name: string, fn: () => T): T {
  return tracer.startActiveSpan(name, (s) => {
    try { return fn() } finally { s.end() }
  })
}
```

Wrap the server-adapter callback so each filter change becomes one
span:

```svelte
<SvGrid
  ...
  externalFilter={true}
  onFiltersChange={(f) => span('grid.filter', async () => {
    await refetchFromServer(f)
  })}
/>
```

Now you get a flame graph that shows filter → fetch → render times
end-to-end.

## Recipe 4: Roll-your-own event bus

If your org already publishes a JS event bus / analytics layer,
adapt the same shape:

```ts
import { track } from '@your-org/analytics'

const handlers = {
  onActiveCellChange:    (c)   => track('grid_cell_focus',  { rowId: c.rowId, columnId: c.columnId }),
  onCellValueChange:     (e)   => track('grid_cell_edit',   { rowId: e.row.id, columnId: e.columnId }),
  onRowSelectionChange:  (_, rows) => track('grid_row_select', { n: rows.length }),
  onFiltersChange:       (f)   => track('grid_filter',      { n: f.columns.length }),
  onSortingChange:       (s)   => track('grid_sort',        { columns: s.map((x) => x.id) }),
}
```

Then spread:

```svelte
<SvGrid {data} {columns} features={features} {...handlers} />
```

## What good metrics look like

After a week of production traffic, the dashboards we recommend
building:

| Metric                              | Why                                                                |
| ----------------------------------- | ------------------------------------------------------------------ |
| `grid.cell.edit` count per user/day | Adoption of the inline-editing feature                              |
| `grid.filter` heatmap by column     | Which columns users filter most → priority for fast-filter UX       |
| `grid.cell.focus` columnId distribution | Are users reading every column or only 3? Inform default visibility |
| `grid.sort` columnId distribution   | Which columns deserve to be the default sort                        |
| `grid.row.count` (sampled)          | How big are the visible result sets in practice                     |
| Time between `onApiReady` and first `onActiveCellChange` | Time-to-first-interaction (proxy for perf)         |

## PII guidance

The default callbacks pass references to your row objects. If your
rows contain PII (emails, names, salaries) and your analytics
pipeline must stay PII-free:

1. **Send IDs, not row references.** `crumb({ rowId: e.row.id })` not
   `crumb({ row: e.row })`.
2. **Never send `e.newValue` / `e.oldValue`.** Send `columnId` and a
   PII-safe label only.
3. **Clip strings.** Even when sending labels, cap at ~40 chars so a
   wild paste can't leak a SSN.

See [security](./security.md) for the broader posture.

## What's NOT observable today

- **Render frame timing.** The grid uses requestAnimationFrame-driven
  virtualization; if you need per-frame metrics, wrap the page in
  Datadog's RUM long-task observer (it'll catch any frame > 50ms,
  which is the spec for "slow frame").
- **Bytes-on-the-wire.** Sv-grid never makes a network call - your
  adapter does. Measure at the adapter.
- **Memory.** Use Chrome DevTools Performance Monitor for live RSS;
  there's no in-library hook.

## See also

- [Production checklist](./production.md)
- [Server-side data](./server-side-data.md) - the natural place to add
  latency spans
- [Security](./security.md) - PII boundaries, data residency
- [API stability](./api-stability.md) - which callbacks are guaranteed
  not to be renamed

<!-- =================================================================
     /help/pivot  (pro)
     ================================================================== -->

# Pivot tables - Pro

A built-in pivot model that turns a flat data set into a row-axis tree,
a nested column-axis header, and one aggregated cell per
`(row-path × col-path × measure)` triple. Ships in **`sv-grid-pro`**.

The output is plain SvGrid data + columns, so the rendering pipeline is
the same one you already understand - the grid never knows it is
displaying a pivot.

<div data-docs-demo="52-pivot-table" data-height="600"></div>

## Minimal example

```ts
import { createPivotModel } from 'sv-grid-pro'
import {
  SvGrid, tableFeatures, rowSortingFeature, rowExpandingFeature,
} from 'sv-grid-community'

const features = tableFeatures({ rowSortingFeature, rowExpandingFeature })

const pivot = createPivotModel(orders, {
  rows:   ['region', 'salesPerson'],
  cols:   ['quarter'],
  values: [
    { field: 'amount', agg: 'sum', label: 'Total', format: { type: 'currency', currency: 'USD' } },
    { field: 'amount', agg: 'avg', label: 'Avg' },
  ],
})
```

```svelte
<SvGrid
  data={pivot.rows}
  columns={pivot.columns}
  features={features}
  rowHeight={32}
/>
```

The result:

| region / salesPerson | 2024 Q1 Total | 2024 Q1 Avg | 2024 Q2 Total | ... | Grand total |
| -------------------- | ------------- | ----------- | ------------- | --- | ----------- |
| (group) North        | $48,210       | $1,203      | ...           | ... | $211,090    |
| Ada                  | $12,400       | $1,033      | ...           | ... | $58,200     |
| Linus                | $35,810       | $1,348      | ...           | ... | $152,890    |
| (group) South        | ...           | ...         | ...           | ... | ...         |
| **Grand total**      | $182,300      | $1,287      | ...           | ... | $812,440    |

## Via the imperative API

When you've called `installPro(api)`, the same builder hangs off the
api object so the designer UI can rebuild on every config change
without re-importing:

```ts
import { installPro } from 'sv-grid-pro'

const pro = installPro(api)

function applyPivot(config: PivotConfig<Order>) {
  const result = pro.pivot.build(config)
  pivotRows    = result.rows
  pivotColumns = result.columns
}
```

`pro.pivot.buildFrom(data, config)` accepts an arbitrary array - useful
for previewing a designer's config against a small sample before
committing.

## The `PivotConfig` shape

```ts
type PivotConfig<TData> = {
  /** Outer-most first. Each entry becomes one level of row grouping. */
  rows: ReadonlyArray<keyof TData & string>
  /** Outer-most first. Each entry becomes one level of column grouping. */
  cols: ReadonlyArray<keyof TData & string>
  /** One or more measures aggregated under each column-axis leaf. */
  values: ReadonlyArray<PivotValueConfig<TData>>
  /** Grand-total row at the bottom. Default `true`. */
  grandTotalRow?: boolean
  /** Grand-total column on the right. Default `true`. */
  grandTotalCol?: boolean
  /** Subtotal rows between row groups. Default `true`. */
  rowSubtotals?: boolean
  /** Sort axis values per dim level. Defaults to numeric/alpha. */
  colSort?: (a: unknown, b: unknown, level: number) => number
  rowSort?: (a: unknown, b: unknown, level: number) => number
}

type PivotValueConfig<TData> = {
  field: keyof TData & string
  agg: PivotAggregatorId | PivotAggregator
  label?: string
  format?: CellFormatConfig
}

type PivotAggregatorId =
  | 'sum' | 'avg' | 'min' | 'max'
  | 'count' | 'countDistinct'
  | 'first' | 'last'
```

For anything beyond the built-ins, pass a function: `agg: (values) =>
weightedAvg(values, weights)`.

## The `PivotRow` shape

Every entry in `result.rows` is a plain object:

```ts
type PivotRow = {
  __pivotId: string
  __pivotKind: 'group' | 'subtotal' | 'leaf' | 'grandTotal'
  __pivotDepth: number          // 0 for top-level groups / grand total
  __pivotLabel: string           // first-column label
  __pivotParentId: string | null // for filterCollapsedPivotRows; null = always visible
  __pivotExpandable: boolean     // true for group rows with descendants
  [columnId: string]: unknown    // value cells, keyed by leaf column id
}
```

## Expandable rows

Each `group` row carries `__pivotExpandable: true` and each descendant
carries `__pivotParentId` pointing at its containing group. To make the
pivot collapsible: track an "expanded" `Set<string>` of group ids and
run the rows through `filterCollapsedPivotRows`:

```svelte
<script lang="ts">
  import { createPivotModel, filterCollapsedPivotRows } from 'sv-grid-pro'

  const pivot = createPivotModel(orders, config)
  let expanded = $state<Set<string>>(new Set())   // empty = all collapsed
  const visible = $derived(filterCollapsedPivotRows(pivot.rows, expanded))

  function toggle(id: string) {
    const next = new Set(expanded)
    if (next.has(id)) next.delete(id); else next.add(id)
    expanded = next
  }
</script>

<SvGrid
  data={visible}
  columns={pivot.columns}
  features={features}
/>
```

The first column's cell renderer is the natural place to draw the
expand/collapse chevron - check `__pivotExpandable` and `__pivotKind`
on the row:

```svelte
{#snippet labelCell(ctx)}
  {@const row = ctx.row.original}
  <span style="padding-left: {row.__pivotDepth * 16}px">
    {#if row.__pivotExpandable}
      <button onclick={() => toggle(row.__pivotId)}>
        {expanded.has(row.__pivotId) ? '▾' : '▸'}
      </button>
    {/if}
    {row.__pivotLabel}
  </span>
{/snippet}
```

Pass `true` to `filterCollapsedPivotRows` to bypass filtering (all rows
visible); pass an empty `Set` to collapse everything to subtotals only.

Use `__pivotKind` to style subtotal / grand-total rows differently:

```svelte
<SvGrid
  data={pivot.rows}
  columns={pivot.columns}
  features={features}
  rowClass={(row) => ({
    'pv-group':    row.__pivotKind === 'group',
    'pv-subtotal': row.__pivotKind === 'subtotal',
    'pv-grand':    row.__pivotKind === 'grandTotal',
  })}
/>
```

(The `rowClass` callback itself is on the
[Missing features](./missing-features.md) list; until it ships, target
rows via `data-pivot-kind` on a custom row snippet.)

## Pivot designer UI

The pivot model is pure - drop a new config in, get a new
`{ rows, columns }` back. Wrapping this in a drag-and-drop designer is
the demo's job, not the engine's:

- Four drop zones: Filters / Rows / Columns / Values.
- Each zone is a plain `ondragover` / `ondrop` target.
- When the user drops a measure into Values, prompt for the aggregator
  or default to `sum`.
- Persist the `PivotConfig` to `localStorage` for cheap "saved views".

See demo [52 - Pivot table + Designer](../../examples/src/demos/52-pivot-table.svelte)
for a full ~400-line example.

## Performance notes

The engine is a single pass over the input rows: it builds a row-axis
tree and a column-axis tree, then for each (row-path × col-path)
combination runs each measure aggregator over the matched source rows.

For an N-row dataset with R row-axis combos and C col-axis combos, the
cost is roughly `O(N + R * C * V)` where V is the number of measure
configs. In practice that means a 100k-row source pivots in under
~100 ms when the row+col cardinality is under a few hundred. For
million-row sources, run the pivot on the server and pass the result
straight into `data` / `columns`.

## See also

- [Column groups](./columns/column-groups.md) - multi-level column
  headers; pivot uses these for the column-axis tree.
- [Demo 52 - Pivot table + Designer](../../examples/src/demos/52-pivot-table.svelte)
- [Data export and printing - Pro](./export.md) - the result of
  `createPivotModel` exports like any other grid view.

## Frequently asked questions

### Does SvGrid support pivot tables?

Yes, in the paid `sv-grid-pro` add-on. `createPivotModel` turns a flat data set
into a row-axis tree with a nested column-axis header and one aggregated cell
per (row-path × col-path × measure). The Community package does not include
pivoting.

### How is pivot different from grouping?

Grouping (in Community) rolls rows up along the row axis only. Pivot also spreads
a field across the column axis with nested headers and computes a measure for
each row/column intersection.

### Can I export a pivot table?

Yes. A pivot view exports to Excel/PDF/CSV like any other grid view through the
same `sv-grid-pro` export helpers.

<!-- =================================================================
     /help/production  (community)
     ================================================================== -->

# Production deployment

The checklist that turns "it works on my laptop" into "it ships". One
page per concern; each concern is one paragraph + the code that
matters.
<div data-docs-demo="22-admin-template" data-height="540"></div>

## 1. Pin your versions

```json
{
  "dependencies": {
    "sv-grid-community": "1.0.0",
    "sv-grid-pro":       "1.0.0"
  }
}
```

Pre-1.0, prefer exact pins (no `^`, no `~`). The
[changelog](../changelog.md) annotates breaking changes; the
[API stability page](./api-stability.md) names which exports are
under the semver promise.

## 2. Bundle size: what actually ships

Measured gzipped, with Svelte excluded as a peer dependency:

| What you import                                       | Gzipped | Minified |
| ----------------------------------------------------- | ------- | -------- |
| Headless core (`createSvGrid` + `createCoreRowModel`) | ~7.5 KB | ~35 KB   |
| Full `<SvGrid>` render component (everything)         | ~42 KB  | ~189 KB  |

The `<SvGrid>` component is batteries-included: virtualization, Excel-style
filters, inline editing, grouping, tree, master/detail, and accessibility are
all in that one import. For a smaller footprint, use the headless core and
render your own markup, registering only the features you need.

Pro adds per feature you import:

| Pro module          | Approx KB | Peer deps                       |
| ------------------- | --------- | ------------------------------- |
| `exportGrid` (csv/tsv/html) | ~6 KB    | -                          |
| + xlsx               | ~6 KB    | `jszip` (loaded on first xlsx call) |
| + pdf                | ~9 KB    | `pdfmake` (loaded on first pdf call) |
| `importData`         | ~7 KB    | `jszip` (xlsx only)             |
| AI helpers           | ~3 KB    | -. You bring your provider.     |
| `createPivotModel`   | ~4 KB    | -                               |

Use the **subpath imports** to avoid pulling features you don't use:

```ts
import { exportGrid }      from 'sv-grid-pro/export'    // export only
import { createPivotModel } from 'sv-grid-pro/pivot'    // pivot only
```

## 3. Peer dependencies

| Peer dep   | When you need it                                                   | Install                             |
| ---------- | ------------------------------------------------------------------ | ----------------------------------- |
| `svelte`   | Always. SvGrid renders against Svelte 5.                           | `pnpm add svelte`                   |
| `jszip`    | xlsx export OR xlsx import.                                        | `pnpm add jszip`                    |
| `pdfmake`  | PDF export.                                                        | `pnpm add pdfmake`                  |

Both `jszip` and `pdfmake` are dynamic imports - the bundle splits and
loads them on the first call. Nothing ships in your initial chunk until
the user actually clicks "Export to xlsx".

## 4. Lazy-load Pro at route boundaries

If only one route in your app needs export, gate `installPro` behind a
dynamic import so the rest of the app doesn't ship the Pro bundle:

```svelte
<script lang="ts">
  import type { SvGridApi } from 'sv-grid-community'
  import type { ProGridApi } from 'sv-grid-pro'

  let api = $state<SvGridApi<typeof features, Order> | null>(null)
  let pro = $state<ProGridApi<typeof features, Order> | null>(null)

  async function enablePro() {
    if (!api) return
    const { installPro, setLicenseKey } = await import('sv-grid-pro')
    setLicenseKey(import.meta.env.VITE_SVPRO_KEY)
    pro = installPro(api)
  }
</script>

<SvGrid {...} onApiReady={(next) => (api = next)} />

<button onclick={enablePro}>Enable export</button>
{#if pro}
  <button onclick={() => pro?.exportData({ format: 'xlsx' })}>⬇ XLSX</button>
{/if}
```

## 5. License the Pro pack

```ts
// main.ts (or +layout.svelte for SvelteKit)
import { setLicenseKey } from 'sv-grid-pro'

if (import.meta.env.VITE_SVPRO_KEY) {
  setLicenseKey(import.meta.env.VITE_SVPRO_KEY)
}
```

Pro is **soft-gated** - it works unlicensed, but renders a small
watermark + a one-time console nudge. Set the key once at app
startup; both disappear.

Don't commit the key to source control. Inject via env (Vite reads
`VITE_*` variables at build time; SvelteKit reads `$env/static/public`).

For per-tenant deployments where each tenant has their own key, set
the key inside the consumer's bootstrap, never inside the library
package.

## 6. CSP-safe deployment

The recommended `Content-Security-Policy` header:

```
Content-Security-Policy:
  default-src 'self';
  script-src 'self';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data:;
  font-src 'self' data:;
  connect-src 'self';
  frame-ancestors 'none';
  base-uri 'self';
  form-action 'self';
```

No `'unsafe-eval'`, no `'unsafe-inline'` on `script-src`. SvGrid
Community + Pro run clean under this policy. [Demo 16](../../examples/src/demos/16-csp-compliant.svelte)
includes a runtime self-check.

If you ship in an iframe (embedded analytics, dashboards), add
`frame-ancestors` to the host's CSP to allow the embed.

## 7. SSR

For SvelteKit:

```ts
// +page.server.ts
export async function load() {
  const rows = await db.query('select * from people limit 100')
  return { rows }
}
```

```svelte
<!-- +page.svelte -->
<script lang="ts">
  import { SvGrid, tableFeatures, rowSortingFeature } from 'sv-grid-community'
  let { data } = $props()
  const features = tableFeatures({ rowSortingFeature })
</script>

<SvGrid data={data.rows} columns={columns} features={features} />
```

The first paint contains the data in a real `<table>` (good for SEO +
LCP). Hydration only attaches event listeners. See
[demo 19](../../examples/src/demos/19-ssr.svelte) for a sandboxed
JS-disabled iframe that proves the markup is meaningful pre-hydration.

## 8. Performance budgets

Targets that have held up in production:

| Surface                            | Target               | What you do if you miss it                                       |
| ---------------------------------- | -------------------- | ---------------------------------------------------------------- |
| Time to first row visible          | < 200 ms             | Lazy-load Pro. Defer non-critical columns. Smaller initial page. |
| Scroll FPS (10k rows, virtualized) | 60 FPS               | Cap `overscan`. Avoid `cell` render functions that allocate per render. |
| Sort over 100k rows                | < 60 ms              | Set `editorType` on numeric / date columns so `sortFns.number` / `sortFns.date` get used instead of `sortFns.auto`. |
| Filter input → re-render           | < 30 ms              | Debounce server-side filters; the local filter UI is already ≤ 16 ms for 10k rows. |
| Export 10k rows to xlsx            | < 1 s                | Don't include columns you're going to hide. Use `columns: [...]` to project. |

The [benchmarks page](./benchmarks.md) has the reproducible numbers.

## 9. Error boundaries

The render component throws on truly broken state (e.g. a `field` that
doesn't exist on any row). Wrap in a Svelte error boundary or guard
with `if (rows.length === 0)` for empty data. The grid's `emptyMessage`
prop covers the empty case without crashing.

```svelte
<svelte:boundary>
  <SvGrid {data} {columns} {features} />

  {#snippet failed(error, reset)}
    <div class="error">Grid failed: {error.message}</div>
    <button onclick={reset}>Retry</button>
  {/snippet}
</svelte:boundary>
```

## 10. Monitoring + observability

The grid emits everything you'd want to observe via callbacks:
`onSortingChange`, `onFiltersChange`, `onRowSelectionChange`,
`onCellValueChange`. Wire them into your analytics / logging:

```ts
function track(event: string, payload: object) {
  // sentry, posthog, your own beacon - pick one
}

<SvGrid
  ...
  onSortingChange={(s)     => track('grid.sort',   { clauses: s })}
  onFiltersChange={(f)     => track('grid.filter', { columns: f.columns.length })}
  onCellValueChange={(e)   => track('grid.edit',   { column: e.columnId })}
/>
```

## See also

- [Why headless?](../why-headless.md) - the architectural decision
  behind Community + Pro.
- [API stability](./api-stability.md) - the semver promise and what
  it covers.
- [Security](./security.md) - peer-dep table, SBOM, vulnerability
  handling, data residency.
- [Browser support](./browser-support.md) - tested matrix, mobile,
  build tools.

<!-- =================================================================
     /help/real-time  (community)
     ================================================================== -->

# Real-time / streaming updates

How to drive the grid from a WebSocket / SSE / poll. Three patterns
ranked by the rate of change:

1. **Periodic full refresh** - poll for the latest rows, swap the array.
2. **Cell flash on change** - the same swap, but the renderer
   highlights cells whose values just changed.
3. **Delta merge with backlog** - WebSocket pushes individual row
   patches; you merge them into the in-memory state, optionally
   batching while the user has the page paused.

Try a streaming order desk - cell flashes on every change, pause / resume,
disconnect / reconnect, configurable throughput slider:

<div data-docs-demo="34-realtime-orders" data-height="520"></div>

## Pattern 1: periodic full refresh

The simplest reactive pattern. Poll every N seconds, hand the new
array down.

```svelte
<script lang="ts">
  let rows = $state<Order[]>([])

  $effect(() => {
    const id = setInterval(async () => {
      rows = await fetch('/api/orders').then((r) => r.json())
    }, 5_000)
    return () => clearInterval(id)
  })
</script>

<SvGrid data={rows} columns={columns} features={features} />
```

The grid re-renders the visible rows; virtualization keeps the cost
proportional to the viewport, not the dataset.

**Use when:** dataset is small (< 1000 rows), update rate is low (≥ 5 s),
"freshness" is the only requirement.

**Avoid when:** the user is mid-edit on a cell. A full swap mid-edit
will close the editor. Pause your refresh while
`onActiveCellChange` reports a non-null active cell.

## Pattern 2: cell flash on change

Same swap, but each cell snippet tracks its previous value and renders
a brief highlight when it differs.

```svelte
<script lang="ts">
  // Track per-row, per-field last-seen values.
  let lastSeen = new Map<string, Record<string, unknown>>()
  function diff(rowId: string, current: Record<string, unknown>): Record<string, boolean> {
    const prev = lastSeen.get(rowId)
    const changed: Record<string, boolean> = {}
    if (prev) for (const k of Object.keys(current)) if (prev[k] !== current[k]) changed[k] = true
    lastSeen.set(rowId, { ...current })
    return changed
  }
</script>

{#snippet PriceCell(props: { row: Order })}
  {@const changes = diff(props.row.id, props.row)}
  <span class={`tabular-nums ${changes.price ? 'flash' : ''}`}>
    {fmtMoney(props.row.price)}
  </span>
{/snippet}
```

```css
.flash {
  animation: flash-bg 800ms ease-out;
}
@keyframes flash-bg {
  from { background: rgba(250, 204, 21, 0.4); }
  to   { background: transparent; }
}
```

**Use when:** user wants to spot changes. The stock-ticker pattern.

**Avoid when:** the flash interferes with selection or accessibility -
add `prefers-reduced-motion` guards if the flash is purely
decorative.

## Pattern 3: delta merge with backlog

The grown-up pattern for higher-rate updates. The server pushes
individual row patches; you maintain an in-memory map and reassign the
array when needed.

```svelte
<script lang="ts">
  type OrderId = string
  let rowsMap = $state(new Map<OrderId, Order>())
  let paused = $state(false)
  let backlog = $state<Order[]>([])
  const flushDebounce = 200  // ms

  const rows = $derived(Array.from(rowsMap.values()))

  $effect(() => {
    const ws = new WebSocket('/api/orders/stream')
    ws.onmessage = (e) => {
      const patch: Order = JSON.parse(e.data)
      if (paused) {
        backlog = [...backlog, patch]
        return
      }
      applyPatch(patch)
    }
    return () => ws.close()
  })

  function applyPatch(patch: Order) {
    const next = new Map(rowsMap)
    next.set(patch.id, patch)
    rowsMap = next
  }

  function resume() {
    paused = false
    for (const p of backlog) applyPatch(p)
    backlog = []
  }
</script>

<button onclick={() => (paused = !paused)}>
  {paused ? `Resume (${backlog.length} pending)` : 'Pause'}
</button>

<SvGrid data={rows} columns={columns} features={features} />
```

A few production knobs:

- **Debounce the resignment.** A WebSocket spitting out 20 patches per
  second creates 20 array allocations per second. Batch into the next
  `requestAnimationFrame`:

  ```ts
  let pendingPatches: Order[] = []
  let scheduled = false
  function applyPatch(patch: Order) {
    pendingPatches.push(patch)
    if (scheduled) return
    scheduled = true
    requestAnimationFrame(() => {
      const next = new Map(rowsMap)
      for (const p of pendingPatches) next.set(p.id, p)
      rowsMap = next
      pendingPatches = []
      scheduled = false
    })
  }
  ```

- **Out-of-order safety.** Each patch carries a server-side sequence
  number; drop patches older than the latest you've applied for that
  row. The streaming demo (#34) shows this with `lastSeq` per row.

- **Disconnect handling.** On `ws.onclose`, set a status flag the user
  sees ("reconnecting…") and reconnect with exponential backoff. The
  demo shows the recovery flow.

## Pause during edit / selection

A common mistake: updates fly in while the user is mid-paste or
mid-edit. The fix is two flags:

```ts
let isEditing = $state(false)
let hasSelection = $state(false)
const isInteracting = $derived(isEditing || hasSelection)

$effect(() => {
  if (isInteracting) {
    paused = true
  } else if (paused) {
    resume()
  }
})
```

Wire to the grid:

```svelte
<SvGrid
  ...
  onEditingChange={(state) => (isEditing = state.cell != null)}
  onRowSelectionChange={({ selectedRows }) => (hasSelection = selectedRows.length > 0)}
/>
```

## Backpressure (when the server is too fast)

If your producer can outrun the UI's frame budget, sample down at the
client. Drop intermediate patches for the same row; only the newest
one survives:

```ts
function applyPatch(patch: Order) {
  // pendingPatches is keyed by row id so a fast-moving row only
  // commits its NEWEST value per frame.
  pendingPatches.set(patch.id, patch)
  /* ...schedule rAF... */
}
```

For 1000 rows updating at 5 Hz, this caps the work at 1000
assignments per frame regardless of the actual message rate. The
streaming demo's "throughput slider" stresses this exact path.

## Combining with sort + filter

The grid's sort + filter run AFTER your patches land in `rows`. Two
implications:

- **A row that no longer matches the filter disappears.** Expected.
- **The active row may move.** When `onActiveCellChange` fires with a
  new index because the row above shifted, your toolbar / detail panel
  should follow.

If you're using a side detail panel keyed on row id (not index),
this is a non-issue - the detail stays bound to the order even as
the row moves.

## See also

- [Server-side data](./server-side-data.md) - the pull side of
  remote data.
- [Saved views](./saved-views.md) - persist a "live mode on / off"
  toggle alongside the rest of the view config.
- [Performance benchmarks](./benchmarks.md) - measured per-frame cost
  of the patterns above.

## Frequently asked questions

### How do I show real-time data in SvGrid?

Drive the grid's `data` from a WebSocket, SSE, or poll. This page covers three
patterns ranked by update rate: periodic full refresh, targeted row patches via
`getRowId`, and high-frequency cell updates with change-flash highlighting.

### Will the grid keep my scroll and selection on live updates?

Yes, if you give rows a stable identity with `getRowId`. Then selection,
expansion, edit state, and scroll position survive incoming updates instead of
resetting on every refresh.

### How fast can SvGrid update?

Fast enough for tick-by-tick feeds - the stock-market demo updates 25 symbols
every 250 ms with green/red cell flashes while sorting and selection stay live.
For very high rates, patch only changed rows rather than swapping the whole
array.

<!-- =================================================================
     /help/recipes  (community)
     ================================================================== -->

# Recipes / Cookbook

Quick patterns for the questions that come up over and over. Each
recipe is paired with a live demo or a minimal snippet that runs
against the shipping library.

## Sort, filter, paginate at the same time

Three of the most-asked features wired together against a 5k-row
dataset. Click any header to sort, open the filter icon to filter,
use the pager at the bottom to walk pages:

<div data-docs-demo="02-sort-filter-paginate" data-height="440"></div>

The implementation: register all three features in one
`tableFeatures(...)` call and enable the matching props on `<SvGrid>`.
See [Filtering overview](./filtering/overview.md) and
[Row sorting](./rows/row-sorting.md).

## Select rows + copy / paste a range

Click + drag selects a rectangular cell range; Ctrl/Cmd+C copies as
TSV; pasting back from Excel writes through the same cell-write
pipeline as inline edit:

<div data-docs-demo="04-selection-copy-paste" data-height="440"></div>

The pattern: enable `enableCellSelection={true}` and let the grid
handle the keyboard + paste plumbing. Cell writes go through
`onCellValueChange` so your validator runs on every pasted value.

## Bulk actions toolbar

The Gmail / Linear pattern: tick row checkboxes, a sticky toolbar
reveals "Mark / Delete / Copy as TSV":

<div data-docs-demo="23-bulk-actions" data-height="440"></div>

The trick: subscribe to `onRowSelectionChange` and render your
toolbar whenever the count is > 0. The grid doesn't ship a bulk-action
component on purpose - your design system's button + toast UI is
better than anything we could embed.

## Cascade editing (formula-like dependencies)

Editing qty / price cascades into line totals + a summary card:

<div data-docs-demo="18-cascade-editing" data-height="440"></div>

In `onCellValueChange`, after writing the cell, recompute the dependent
cells in the same row (or in the summary state) and let Svelte 5's
reactivity carry the update through. The pattern is essentially
"editable cells + a `$derived` summary".

## Validation while editing

Per-column rules: invalid commits get rolled back via `setCellValue`,
and a sidebar logs the rejection so users can audit what was tried:

<div data-docs-demo="24-validation" data-height="440"></div>

Use `onCellValueChange`: validate, and if invalid, call
`api.setCellValue(rowIndex, columnId, oldValue)` to undo. The grid
emits a fresh `onCellValueChange` for the undo write that your
validator can recognise and skip.

## Column pinning + freezing

Wide 13-column grid: pin Company on the left and Price on the right;
the middle scrolls under sticky edges:

<div data-docs-demo="25-column-pinning" data-height="440"></div>

The user pins via the column menu - no extra wiring needed if
`columnFilteringFeature` is registered (the menu lives on the same
header button). Or call `api.pinColumn(columnId, 'left' | 'right' | null)`
programmatically.

## List + chips editors

The two built-in multi-select editors:

<div data-docs-demo="26-list-chips-editors" data-height="440"></div>

Add `editorType: 'list'` for a single `<select>` or `editorType: 'chips'`
with `editorMultiple={true}` for removable tokens. Pass static
`editorOptions` or a `(row) => options` callback for cascading lists
(e.g. City options depend on Country).

## Spreadsheet ribbon

An Excel-style Ribbon UI driving the grid via `SvGridApi`: bold + colour
+ number format + insert/delete row + sort, plus a live SUM/AVG/COUNT
status bar:

<div data-docs-demo="27-spreadsheet-ribbon" data-height="500"></div>

The ribbon is a regular Svelte component; every button calls
`api.setCellValue`, `api.addRow`, `api.setSort`, etc. Status bar
reads `getDisplayedRows()` for the live aggregate.

## Master / detail

A hierarchical row that expands to reveal a child grid:

<div data-docs-demo="08-tree-and-master-detail" data-height="440"></div>

Same flatten pattern as [tree rows](./rows/tree-rows.md): a flat
`visibleRows` derivation, plus a custom cell snippet that renders the
detail grid inline when the row is expanded.

## Forms-in-grid (master grid + side form)

Click a row to load it into a tabbed detail form on the right; edits
flow back to the grid live:

<div data-docs-demo="40-forms-master-detail" data-height="500"></div>

Pattern: `onActiveCellChange` -> set `activeRowId` -> `draft = $state.snapshot(activeRow)` -> form
binds against `draft`. On save, write `draft` back into the rows array.
**Use `$state.snapshot()`, not `structuredClone()`**, on Svelte 5 state
proxies - the latter throws `DataCloneError`.

## Saved views / persistence

Pivot-lite with chips + saved views stored in localStorage:

<div data-docs-demo="36-reporting-workspace" data-height="500"></div>

The pattern: a `view: { groupBy, sortBy, filters, columns }` object
that you serialise into localStorage under a versioned key
(`'my-app:view:v1'`). On load, hydrate the state from the saved view
and call the matching `api.set*` methods.

## Theming studio

Live token playground: brand color, density, radius, font, dark/light,
zebra. The CSS snippet at the bottom is copy-ready:

<div data-docs-demo="37-theming-studio" data-height="540"></div>

Theming is `--sg-*` custom properties - see [Tailwind integration](./tailwind.md)
for the full token list.

## Localisation + RTL switching

Six locales (en, de, fr-CA, ja, ar, he); headers, currencies, dates,
and the grid's own scrollbar flip:

<div data-docs-demo="38-rtl-i18n" data-height="500"></div>

Set `<html dir="...">` and `<html lang="...">` based on the locale.
Per-column `format: { type: 'currency', locales }` overrides the
document locale for specific columns.

## Print + boardroom export

Quarterly P&L print pack: cover page, repeat-on-page headers, page-
size + orientation, CSV / HTML download, browser-native PDF:

<div data-docs-demo="39-print-board-export" data-height="500"></div>

`api.print({ title, columns, rows, orientation, pageSize })` opens a
sandbox window with an isolated HTML document and calls `.print()` on
it. The popup pattern is what isolates your print stylesheet from your
app's CSS.

## Healthcare EMR (role-based editing)

Inpatient board with vitals sparklines, risk score, code status, allergy
chips, role-based editing (viewer / nurse / physician / admin):

<div data-docs-demo="41-healthcare-emr" data-height="500"></div>

The role gate uses `editable: (ctx) => roleCanEdit(currentRole, ctx.column.id)`.
That lambda runs per-cell, so you get column + role granularity
without a separate config table.

## Live shipment / fleet board

Streaming-style live update at 2-3 Hz with cell-level flash on change,
ETA delta colors, alert chips:

<div data-docs-demo="42-logistics-fleet" data-height="500"></div>

The pattern: a `$state` rows array that you mutate from a
WebSocket/SSE handler. The render component diffs at the data-array
level, so reassigning the array (`rows = updated`) is what triggers
the visible repaint.

## Compliance / approval queue

L1 / L2 / L3 approval chain with live SLA timer, role-gated approve /
return / reject buttons, immutable case-history audit panel:

<div data-docs-demo="43-compliance-queue" data-height="500"></div>

This is the pattern for any "this row needs a decision; some users can
make it, some can't" workflow. Status changes go through a state
machine you own; the grid only renders the current state.

## Field service dispatch

Dispatcher board: priority + status + tech editable inline, SLA tone
gauge, today-timeline cell, tech capacity panel, live status stream:

<div data-docs-demo="44-field-service" data-height="500"></div>

Same `editable: (ctx) => ...` per-cell pattern for tech/status. The
today-timeline cell is a positioned-bar in a single wide cell - see
the [pivot doc](./pivot.md) for that pattern.

## Gantt chart in a grid

Project plan with a wide custom Schedule cell: bars positioned by
start/end %, phase coloring, progress fill, today line, overdue glow:

<div data-docs-demo="45-gantt-chart" data-height="540"></div>

No special Gantt mode - it's a single wide cell per row whose snippet
positions absolute bars by `(start - projectStart) / projectSpan * 100`.
Axis above the grid uses the same math.

## Scheduler (single-day appointments)

Providers as rows, an hour axis, click any appointment to edit it in
the side panel. Now-line ticks live:

<div data-docs-demo="46-scheduler" data-height="540"></div>

Same single-wide-cell pattern as the Gantt. The axis-wrap inside the
grid wrapper uses `ResizeObserver` so the axis width matches the
schedule column - that's what keeps the now-line aligned between the
header and the cells.

## Trash truck timeline (animated)

Public-works dispatcher: each truck glides along its day-long route
with spinning wheels, stops, and live fill levels:

<div data-docs-demo="47-trash-truck-timeline" data-height="540"></div>

The mover uses `transition: left 220ms linear` so the new position
animates in. The bounce + wheel spin are CSS keyframes; no JS animation
loop required.

## CRM - sales pipeline

Deal board with stage chips, weighted forecast bar, inline stage +
probability editing, deal detail aside with activity feed:

<div data-docs-demo="48-crm-sales-pipeline" data-height="540"></div>

This is the canonical example of mixing inline edit + a side panel
that mirrors the active row.

## Enterprise admin dashboard

CRUD-heavy users board: inline role / status / MFA edit, bulk
activate / deactivate / delete, invite dialog, permissions matrix,
live audit log:

<div data-docs-demo="49-admin-dashboard" data-height="540"></div>

The audit log is the recurring pattern: every mutation appends an
entry to a `$state` array; the right-side panel renders the array.
Delete + Invite use simple `<dialog>`-style modals.

## E-commerce seller panel

Tabbed Amazon-seller view: catalog with SVG thumbnails, inventory bars
vs reorder threshold, live orders pipeline, pricing rules:

<div data-docs-demo="50-seller-panel" data-height="540"></div>

The tab strip is just chip buttons that swap which dataset / columns
the grid receives. One grid component, four tabs - share styling and
behavior without four separate mounts.

## Long-form recipes

The recipes above pair a paragraph + a demo. These deeper write-ups
have their own pages:

- [Persist column layout to URL](../recipes/persist-column-layout-to-url.md) - sort + filter + page in the URL, with debounced replaceState and restore-on-mount.
- [Two-grid master / detail](../recipes/two-grid-master-detail.md) - one master grid drives a second detail grid; remount semantics and multi-select union.
- [Bulk-edit selected rows](../recipes/bulk-edit-selected-rows.md) - the standard back-office workflow: pick a field, pick a value, apply to N selected rows. Includes optimistic + rollback patterns.
- [Server-side filter with TanStack Query](../recipes/server-side-filter-with-tanstack-query.md) - caching, deduplication, cancellation, retries, optimistic edits via mutations.

## See also

- [Architecture overview](./architecture.md) - the layered model that
  makes these recipes composable.
- [API reference](../reference/index.md) - every method called in the
  recipes above.

<!-- =================================================================
     /help/rows/accessing-rows  (community)
     ================================================================== -->

# Accessing rows

You can read the grid's current rows in three ways.
<div data-docs-demo="04-selection-copy-paste" data-height="540"></div>

## 1. From the imperative API

`api.getData()` returns the **underlying data array** - pre-sort, pre-filter,
pre-paginate. Use this when you want to know what the grid is showing
*before* its row model has been applied.

```svelte
<script lang="ts">
  let api: SvGridApi<{}, Person> | null = $state(null)
</script>

<SvGrid {data} {columns} features={{}} onApiReady={(next) => (api = next)} />

<button onclick={() => console.log(api?.getData().length)}>
  How many?
</button>
```

The reverse direction - write a cell - is also on `SvGridApi`:

```ts
api.setCellValue(rowIndex, columnId, value)
const v = api.getCellValue(rowIndex, columnId)
```

## 2. From the row model (post-pipeline)

For the rows the grid is **rendering** (after sort + filter + grouping +
pagination), you need the headless grid instance. The wrapper does not
expose it as a prop today; if you need post-pipeline access, instantiate
the headless engine yourself with `createSvGrid` and pass its computed
output into your own renderer. See
[`packages/sv-grid-community/src/createGrid.svelte.ts`](../../../packages/sv-grid-community/src/createGrid.svelte.ts).

A dedicated `api.getDisplayedRows()` is on the
[gap list](../missing-features.md).

## 3. From the source data directly

In most apps the cleanest path is "the parent owns the data array, the
grid reflects it". When you need to know what's in the grid, look at your
own state - not the grid.

```svelte
<script lang="ts">
  let rows = $state<Person[]>([])
</script>

<SvGrid data={rows} {columns} features={{}} />

<p>{rows.length} rows total.</p>
```

This works because data passed to `<SvGrid>` is treated as the authoritative
source - the grid never silently mutates it.

## Iterating

```ts
const data = api?.getData() ?? []
for (const row of data) {
  // ...
}
```

For thousands of rows in a hot loop, prefer indexed iteration:

```ts
const data = api!.getData()
for (let i = 0; i < data.length; i++) {
  const row = data[i]!
  // ...
}
```

## See also

- [Row data](./row-data.md)
- [Filter API](../filtering/filter-api.md)

<!-- =================================================================
     /help/rows/full-width-rows  (community)
     ================================================================== -->

# Full-width rows

"Full-width rows" are rows whose content takes the entire grid width
instead of being cell-by-cell - useful for inline editors, banner ads,
section dividers, and detail-row expansions.
<div data-docs-demo="08-tree-and-master-detail" data-height="540"></div>

## Status

Built-in support - through `enableRowSummaries={true}` for a single
sticky footer row - exists; arbitrary mid-table full-width rows are
**not** built in.

For inline master/detail (where expanding a row reveals a child) see
[demos/08-tree-and-master-detail.svelte](../../../examples/src/demos/08-tree-and-master-detail.svelte):
the demo expands a row to mount a second `<SvGrid>` underneath, with the
detail keyed to the parent.

## Workaround - render a divider between groups

When you only need a visual band (no editing, no nested grid), render a
plain DOM band above the grid for sticky banners, or use
[grouping](./row-data.md) to get a "group label" row that visually spans
the row width through the indented label column.

## Tracked at

[Missing features](../missing-features.md) - first-class full-width rows
and detail-row API.

## See also

- [Master / detail demo](../../../examples/src/demos/08-tree-and-master-detail.svelte)
- [Grouping](./row-data.md)

<!-- =================================================================
     /help/rows/row-data  (community)
     ================================================================== -->

# Row data

Row data is whatever you pass to `<SvGrid data={...}>`. It is a
`ReadonlyArray<TData>` where `TData` is your row type. Any shape works;
the grid does not require a base class or interface.
<div data-docs-demo="01-quick-start" data-height="540"></div>

## Static

```svelte
<script lang="ts">
  const rows = [
    { id: '1', name: 'Ada',   age: 36 },
    { id: '2', name: 'Linus', age: 54 },
  ]
</script>
<SvGrid data={rows} {columns} features={{}} />
```

## Reactive

Use a Svelte 5 `$state` array. The grid re-derives its row model whenever
the array reference changes:

```svelte
<script lang="ts">
  let rows = $state<Person[]>([])
  $effect(() => { fetchPeople().then((next) => (rows = next)) })
</script>
<SvGrid data={rows} {columns} features={{}} />
```

In-place mutation works too - `rows.push(x)` or `rows[i] = y` - because
`$state` arrays are deep-reactive.

## Row identity (`getRowId`)

Without `getRowId`, the grid uses each row's array index as its id.
That's fine for static data, but selection / expansion / edit state
won't survive sorts, filters, or insertions.

For anything beyond a read-only grid, pass `getRowId`:

```svelte
<SvGrid
  data={rows}
  {columns}
  features={features}
  getRowId={(row, index) => row.id}
/>
```

The function fires per row at row-model build time. Return any stable
string - a database PK, a UUID, a slug. The same `id` then flows into
`onRowSelectionChange`, `onCellValueChange`, `api.getCellValue(...)`,
and every other API surface that takes a row id.

Available on both the `<SvGrid>` wrapper and the headless
`createSvGrid({ getRowId })` core.

## Empty state

The grid renders the `emptyMessage` prop when `data.length === 0`:

```svelte
<SvGrid data={[]} {columns} features={{}} emptyMessage="No people found." />
```

## Loading state

Pass `loading` to overlay a spinner / skeleton (the wrapper has a built-in
overlay layer):

```svelte
<SvGrid {data} {columns} features={{}} loading={isFetching} />
```

For controlled skeleton-row UX in virtualized server-side grids, see
[demos/09-server-side.svelte](../../../examples/src/demos/09-server-side.svelte).

## See also

- [Accessing rows](./accessing-rows.md)
- [Row pagination](./row-pagination.md)
- [Server-side guide](../../getting-started.md#11-server-side-data)

<!-- =================================================================
     /help/rows/row-dragging  (community)
     ================================================================== -->

# Row dragging

Drag-to-reorder for rows is a common interaction (kanban-like reordering,
moving items between two grids, dragging rows out to an external drop
zone).
<div data-docs-demo="23-bulk-actions" data-height="540"></div>

## Status

Row dragging is **not yet built in**. There is no managed-drag prop and no
unmanaged-drag hook. There is no row drop zone support, and no
grid-to-grid drag.

## Workaround - HTML5 DnD on a leading "handle" column

Add a leading column whose cell renders a draggable handle. Use a row id
in the dataTransfer payload and reorder the data array on drop. A working
sketch - drop into your column array:

```ts
import { renderSnippet } from 'sv-grid-community'

{#snippet Handle(p: { id: string })}
  <span
    draggable="true"
    ondragstart={(e) => e.dataTransfer?.setData('text/plain', p.id)}
    aria-label="Drag row"
  >⋮⋮</span>
{/snippet}

const columns = [
  {
    id: 'drag',
    header: '',
    width: 24,
    cell: (ctx) => renderSnippet(Handle, { id: ctx.row.original.id }),
  },
  // ... rest of your columns
]
```

The receiving row needs `ondragover` / `ondrop` handlers - register them
via a custom `cell` renderer on a column the user can drop onto, or via a
row-level event listener on the grid container (only the leftmost cell of
each row is enough to act as the drop target if the grid stretches to the
viewport width).

## Tracked at

[Missing features](../missing-features.md) - first-class row dragging,
external drop zones, grid-to-grid moves.

## See also

- [Custom cells](../cells/cell-components.md)
- [Updating data](./row-data.md)

<!-- =================================================================
     /help/rows/row-height  (community)
     ================================================================== -->

# Row height

Row height is a single integer in pixels.
<div data-docs-demo="10-custom-cells-and-themes" data-height="540"></div>

```svelte
<SvGrid {data} {columns} features={{}} rowHeight={36} />
```

The default is 36 px. The virtualizer reads `rowHeight` once and uses it to
compute the visible window and total scroll height.

## Density

For a density toggle, change `rowHeight` and a matching CSS custom property:

```svelte
<script lang="ts">
  let density = $state<'compact' | 'normal' | 'comfortable'>('normal')
  const px = $derived(density === 'compact' ? 28 : density === 'comfortable' ? 48 : 36)
</script>

<div style:--sg-row-height="{px}px">
  <SvGrid {data} {columns} features={{}} rowHeight={px} />
</div>
```

The example gallery's
[demos/10-custom-cells-and-themes.svelte](../../../examples/src/demos/10-custom-cells-and-themes.svelte)
shows the density toggle in full.

## Variable row height

The built-in virtualizer assumes uniform row height. **Variable height is not
supported by `<SvGrid>` directly**.

If you absolutely need it, use the lower-level headless virtualizer and roll
your own row layout:

```ts
import { createSvelteVirtualizer } from 'sv-grid-community'

const virtualizer = createSvelteVirtualizer({
  count: () => rows.length,
  getScrollElement: () => scrollEl,
  estimateSize: (index) => rows[index]!.tall ? 80 : 36,
  overscan: 6,
})
```

See [`packages/sv-grid-community/src/virtualization/`](../../../packages/sv-grid-community/src/virtualization/).

## Header height

Header height is independent of row height. See
[Column headers](../columns/column-headers.md) for how to size it.

## Row-number column width

When `showRowNumbers={true}`, the leading row-number column defaults
to **56 px**, which fits up to `99,999`. For larger datasets, bump
the width via `rowNumberWidth`:

```svelte
<!-- One million rows: "1,000,000" needs ~ 92 px to stay fully visible -->
<SvGrid
  {data}
  {columns}
  features={{}}
  showRowNumbers={true}
  rowNumberWidth={92}
  rowHeight={18}
  virtualization={true}
  containerHeight="100%"
/>
```

Rule of thumb: budget ~ 8 px per digit plus 14 px of padding. So:

| Row count    | Largest number | Suggested `rowNumberWidth` |
|--------------|----------------|----------------------------|
| < 1 000      | "999"          | `40`                       |
| < 100 000    | "99,999"       | `56` (default)             |
| < 10 000 000 | "9,999,999"    | `92`                       |

Demo 78 ("1 million rows") uses 92 px so the millionth row's index
stays legible at the bottom of the scroll.

## See also

- [Row pinning](./row-pinning.md)
- [Styling rows](./styling-rows.md)
- [Demo 78 - 1 million rows](../../../examples/src/demos/78-million-rows.svelte)

<!-- =================================================================
     /help/rows/row-pagination  (community)
     ================================================================== -->

# Row pagination

Pagination is opt-in. Register the feature, register the row model, then
either turn it on with `showPagination` or drive its state from outside.
<div data-docs-demo="02-sort-filter-paginate" data-height="540"></div>

```svelte
<script lang="ts">
  import {
    SvGrid, tableFeatures,
    rowPaginationFeature, createPaginatedRowModel,
    type ColumnDef,
  } from 'sv-grid-community'

  const features = tableFeatures({ rowPaginationFeature })
</script>

<SvGrid {data} {columns} features={features} showPagination={true} />
```

The wrapper renders a footer with page nav and a page-size selector.

## Set the initial page size

```svelte
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  showPagination={true}
  pageSize={25}
/>
```

The wrapper's footer renders 10 / 25 / 50 / 100 in the size selector
and lets the user change it at runtime. Jumping to a page from outside
or driving a server-side fetcher is best done by hiding the built-in
footer (`showPagination={false}`) and rendering your own controls -
see the [`09-server-side` demo](../../../examples/src/demos/09-server-side.svelte)
for the canonical pattern.

## Page size

The default is 10 unless you pass `pageSize`. The footer's size
selector picks 10 / 25 / 50 / 100; pass a different `pageSize` to seed
a different initial value.

## Pagination + virtualization

These two **work together** but they solve different problems. Use
virtualization when the page itself is large (>200 rows); use pagination
when you want explicit pages, when the user prints/exports, or when
server-side fetch returns pages.

For 100k-row + virtualized examples, pagination is off and the whole
filtered set is scrollable - see
[demos/06-large-dataset.svelte](../../../examples/src/demos/06-large-dataset.svelte).

## See also

- [Server-side guide](../../getting-started.md#11-server-side-data)
- [Accessing rows](./accessing-rows.md)

<!-- =================================================================
     /help/rows/row-pinning  (community)
     ================================================================== -->

# Row pinning (top / bottom)

Pin specific rows to the **top** or **bottom** of the grid so they stay visible while the rest of the data scrolls. Typical use cases:

- A **totals** or **aggregate** row anchored at the top of a long ledger.
- An **industry benchmark** or **target** row for at-a-glance comparison.
- A **page totals** row at the bottom that recomputes as filters narrow the visible set.
- A **headline metric** (e.g. "Closing balance") that should never scroll out of view.

<div data-docs-demo="108-pinned-rows-engine" data-height="540"></div>

## Props

`<SvGrid>` accepts two props:

```ts
pinnedTopRows?:    ReadonlyArray<TData>
pinnedBottomRows?: ReadonlyArray<TData>
```

Each is an array of your own row objects (same `TData` type as `data`). The grid renders them inside the same table as the regular rows, with `position: sticky` so they track the scroll. They share the column schema (widths, pinning, `format`, `cellClass`) - you do not redefine columns.

## Quick start

```ts
<script lang="ts">
  import { SvGrid, tableFeatures, rowSortingFeature, type ColumnDef } from 'sv-grid-community'

  type Row = { id: string; account: string; arr: number; seats: number }

  let rows = $state<Row[]>([ /* ...200 accounts... */ ])

  // Pinned-top: a single "totals" row computed from `rows`.
  const totals = $derived<Row[]>([
    {
      id: '⌃ TOTALS',
      account: `All ${rows.length} accounts`,
      arr:   rows.reduce((s, r) => s + r.arr, 0),
      seats: rows.reduce((s, r) => s + r.seats, 0),
    },
  ])

  const features = tableFeatures({ rowSortingFeature })
  const columns: ColumnDef<typeof features, Row>[] = [
    { field: 'id',      header: 'Account', width: 130, editable: false },
    { field: 'account', header: 'Name',    width: 240, editable: false },
    { field: 'arr',     header: 'ARR',     width: 140, align: 'right',
      format: { type: 'number', options: { style: 'currency', currency: 'USD' } } },
    { field: 'seats',   header: 'Seats',   width: 100, align: 'right' },
  ]
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  pinnedTopRows={totals}
/>
```

The totals row sticks under the header and stays in view while the user scrolls.

## Filter-aware "page totals" at the bottom

The grid exposes `api.getDisplayedRows()` - the post-filter / post-sort / post-pagination row set. Combine it with `pinnedBottomRows` for a "page total" that updates as filters narrow the data.

```ts
<script lang="ts">
  let api = $state<SvGridApi<typeof features, Row> | null>(null)
  let snapshot = $state<readonly Row[]>([])

  // Resync the snapshot whenever filters / sorts likely changed. A
  // 400 ms poll keeps the demo simple; production code can hook the
  // `onFiltersChange` / `onSortingChange` events instead.
  $effect(() => {
    const id = setInterval(() => { snapshot = api?.getDisplayedRows() ?? rows }, 400)
    return () => clearInterval(id)
  })

  const pageTotals = $derived<Row[]>([{
    id: '⌄ PAGE',
    account: `Visible page (n = ${snapshot.length})`,
    arr:   snapshot.reduce((s, r) => s + r.arr, 0),
    seats: snapshot.reduce((s, r) => s + r.seats, 0),
  }])
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  pinnedBottomRows={pageTotals}
  onApiReady={(next) => (api = next)}
/>
```

## Multiple pinned rows

Pass more than one row in either array; the grid stacks them. The first row sticks closest to the header (top) or to the bottom edge (bottom).

```svelte
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  pinnedTopRows={[totals, benchmark, target]}
  pinnedBottomRows={[pageTotals, runningBalance]}
/>
```

The built-in CSS supports stacking up to 4 rows per side. For larger stacks, override the CSS variables yourself:

```css
.sv-grid-pinned-row-top[data-pinned-index="4"] td {
  top: calc(var(--sg-thead-h, 36px) + var(--sg-pinned-row-h, 32px) * 4);
}
```

## How pinned rows behave

| Behavior | Regular rows | Pinned rows |
| --- | --- | --- |
| Inline editing | Yes (when `enableInlineEditing`) | No |
| Selection checkbox | Yes (when enabled) | No (cell rendered empty) |
| Cell selection rectangle | Yes | No (cells skipped) |
| Sorting | Yes | No (pinned rows are in a separate `<tbody>`) |
| Filtering | Yes | No (pinned rows are not filtered) |
| Fill handle | Yes | No |
| `cellClass` | Yes | Yes |
| `format` | Yes | Yes |
| Column pinning (left/right) | Yes | Yes |

Pinned rows are **read-only by design** - they represent aggregates or annotations, not transactional data. If you need an editable row at the top, render it OUTSIDE the grid as a separate toolbar, or use a regular row with `data` and filter it to always sort first.

## Styling

Pinned rows expose two CSS variables on the grid shell that you can override:

```css
.sv-grid-shell {
  --sg-pinned-bg:     color-mix(in oklab, #6366f1 4%, #ffffff);
  --sg-pinned-border: color-mix(in oklab, #6366f1 24%, transparent);
}
```

For per-row styling, target the row's class directly:

```css
.sv-grid-pinned-row-top    { font-weight: 700; }
.sv-grid-pinned-row-bottom { background: #ecfdf5; }
```

Each row also carries `data-pinned-row="top" | "bottom"` and `data-pinned-index="0..N"` so you can paint distinct ranks differently.

## See also

- Demo 108: Pinned rows (engine prop)
- Demo 107: Pinned rows (stacked-grids user-land pattern)
- `api.getDisplayedRows()` - drives filter-aware page totals.

<!-- =================================================================
     /help/rows/row-sorting  (community)
     ================================================================== -->

# Row sorting

Sorting is a feature you opt into. Try it live - click any column
header to cycle `none → asc → desc → none`; shift-click adds the
column to the sort key list (multi-sort):

<div data-docs-demo="02-sort-filter-paginate" data-height="440"></div>



```svelte
<script lang="ts">
  import {
    SvGrid, tableFeatures, rowSortingFeature, type ColumnDef,
  } from 'sv-grid-community'

  const features = tableFeatures({ rowSortingFeature })

  const columns: ColumnDef<typeof features, Person>[] = [
    { field: 'firstName', header: 'First name', editorType: 'text' },
    { field: 'age',       header: 'Age',        editorType: 'number' },
    { field: 'joinedAt',  header: 'Joined',     editorType: 'date' },
  ]
</script>

<SvGrid {data} {columns} features={features} />
```

Clicking a sortable header toggles `none → asc → desc → none`. Shift-click
adds the column to the sort key list (multi-sort).

## Sort functions

`sortFns` exposes the built-in comparators:

```ts
import { sortFns } from 'sv-grid-community'
// sortFns.auto    - lexical (default for unknown types)
// sortFns.number  - numeric, NaN-safe
// sortFns.date    - Date-parsed
```

The grid picks the comparator based on the column's `editorType`:

| editorType | comparator |
| ---------- | ---------- |
| `'number'` | `sortFns.number` |
| `'date'` \| `'datetime'` | `sortFns.date` |
| anything else | `sortFns.auto` |

If your column has a non-trivial type, set `editorType` even if you do not
want inline editing - it is what tells sort and filter how to behave.

## Programmatic sort

```ts
api.setSort('age', 'desc')   // sort by age descending
api.setSort('age', null)     // clear sort on this column
api.clearSort()              // clear all sort
```

`setSort` replaces any existing sort with a single clause. For
multi-column sort, the user clicks the second column header with
**Shift** held (the in-grid affordance). A multi-sort setter on the API
is tracked in [Missing features](../missing-features.md).

To observe sort changes from outside the grid:

```svelte
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  onSortingChange={(next) => (sorting = next)}
/>
```

## Disable sort per column

Not yet first-class - there is no `enableSorting: false` field. To
prevent a column from being sortable, omit `rowSortingFeature` from
`tableFeatures(...)`, or render a custom header via `header: () =>
renderSnippet(...)` that doesn't bind to the sort button.

## Sorting + server-side data

When sort happens on the backend, pair `externalSort={true}` with
`onSortingChange` and round-trip the sort clauses through your
fetcher. See the [`09-server-side` demo](../../../examples/src/demos/09-server-side.svelte).

## See also

- [Filter API](../filtering/filter-api.md)
- [Server-side guide](../../getting-started.md#11-server-side-data)

<!-- =================================================================
     /help/rows/row-spanning  (community)
     ================================================================== -->

# Row spanning

"Row spanning" lets one cell's content cover **multiple rows**, the way a
merged cell does in a spreadsheet.

## Status

Row spanning is **not yet built in**. The grid renders a strict 1-cell-per-
row-column grid; there is no `rowSpan` field on `ColumnDef` or
`CellContext`.

## Workarounds

### 1. Group-by

If the spanning intent is "show 'Engineering' once for every engineer", use
grouping ([Row data](./row-data.md), [demos/07](../../../examples/src/demos/07-grouping-aggregation.svelte)) - the grid renders a single group row
in place of repeated values.

### 2. Cell renderer that suppresses repeats

If you simply want the *display* of repeated values to be blanked, render
the value only when it differs from the row above:

```ts
const columns: ColumnDef<{}, Person>[] = [
  {
    field: 'department',
    header: 'Department',
    cell: (ctx) => {
      const data = ctx.table.getRowModel().rows
      const prev = data[ctx.row.index - 1]?.getCellValueByColumnId('department')
      return prev === ctx.getValue() ? '' : ctx.getValue() as string
    },
  },
]
```

This *looks* like a span but does not actually merge cells - keyboard
navigation still moves through every row.

## Tracked at

[Missing features](../missing-features.md) → "row spanning / merged cells".

## See also

- [Column spanning](../columns/column-spanning.md)
- [Grouping](./row-data.md)

<!-- =================================================================
     /help/rows/styling-rows  (community)
     ================================================================== -->

# Styling rows

Rows are `<tr role="row">` elements inside the grid table. Style them with
plain CSS.
<div data-docs-demo="62-conditional-styling" data-height="540"></div>

## Zebra striping

```css
table[role='grid'] tbody tr:nth-child(even) {
  background: var(--sg-row-alt-bg);
}
```

## Hover

```css
table[role='grid'] tbody tr:hover {
  background: var(--sg-row-hover-bg);
}
```

## Selection

A selected row carries `aria-selected="true"`:

```css
table[role='grid'] tbody tr[aria-selected='true'] {
  background: var(--sg-selection-bg);
}
```

## Conditional row styling

`<SvGrid>` accepts a `rowClass` callback. Return a string, an array
of strings, or a `Record<string, boolean>`, and the classes are
added to the `<tr>`:

```svelte
<SvGrid
  data={rows}
  {columns}
  features={features}
  rowClass={({ row }) => ({
    'is-overdue':   row.dueDate < new Date().toISOString().slice(0, 10),
    'is-cancelled': row.status === 'cancelled',
  })}
/>

<style>
  :global(tr.is-overdue   .sv-grid-cell) { background: rgba(220, 38, 38, 0.06); }
  :global(tr.is-cancelled .sv-grid-cell) { color: var(--sg-muted); text-decoration: line-through; }
</style>
```

The callback receives `{ row, rowIndex }` - the un-mutated source
row + its data-array index. Runs per visible row on every render, so
keep the body cheap (string lookups, equality checks - no `.find()`
over the whole dataset).

For one-cell tints, use `cellClass` on the column def - same shape,
called per cell with the standard `CellContext`. See
[Styling cells](../cells/styling-cells.md).

## CSS custom properties

The gallery defines these tokens - override at `:root` or on the grid host:

```
--sg-bg                 grid background
--sg-fg                 grid foreground
--sg-border             cell borders
--sg-header-bg          header background
--sg-header-fg          header foreground
--sg-row-alt-bg         even-row background
--sg-row-hover-bg       hover background
--sg-selection-bg       selected-row background
--sg-row-height         row height (also pass `rowHeight` prop)
--sg-focus-ring         focus outline (box-shadow)
--sg-accent             primary accent (sort arrow, etc)
```

## See also

- [Row height](./row-height.md)
- [Custom cells](../cells/cell-components.md)

<!-- =================================================================
     /help/rows/transactions  (community)
     ================================================================== -->

# Transactions

`api.applyTransaction({ add, update, remove })` applies a batch of row
mutations in a **single** data update - one re-render for the whole batch,
not one per row. It's the path to use for high-frequency / streaming feeds
(WebSocket deltas, tick data) where calling `addRow` / `setCellValue` per row
would thrash.

```ts
const result = api.applyTransaction({
  add:    [newOrder],                          // appended
  update: [{ ...order, price: nextPrice }],    // matched by id
  remove: ['ORD-1001', staleRowRef],           // by id OR row reference
})
// result -> { added: 1, updated: 1, removed: 2 }
```

## Matching

- **`add`** - rows are appended to the data.
- **`update`** - each row is matched to an existing row by **id**, then
  replaced. Set `getRowId` so the grid can compute ids; without it, updates
  can't be matched.
- **`remove`** - accepts row **ids** (needs `getRowId`) and/or row **object
  references** (always works). Unknown ids are silently ignored.

The call returns the counts actually applied, so you can log or reconcile.

## Why batch

Each `applyTransaction` produces exactly one new data array and therefore one
reactive update, regardless of how many rows changed. On a live feed that
emits dozens of deltas per second, batching them per animation frame (or per
WebSocket message) keeps the grid smooth where per-row calls would not.

```ts
// buffer deltas, flush once per frame
let buffer: Delta[] = []
socket.onmessage = (e) => { buffer.push(JSON.parse(e.data)); schedule() }

function schedule() {
  requestAnimationFrame(() => {
    api.applyTransaction({
      add:    buffer.filter((d) => d.type === 'add').map((d) => d.row),
      update: buffer.filter((d) => d.type === 'update').map((d) => d.row),
      remove: buffer.filter((d) => d.type === 'remove').map((d) => d.id),
    })
    buffer = []
  })
}
```

## Notes

- The grid owns its data after mount; read the current rows back with
  `api.getData()` (which reflects applied transactions).
- Selection, expansion, and edit state keyed by `getRowId` survive a
  transaction - that's the point of a stable row id.

See the live [Transaction API](https://sv-grid.com/demos/145-transaction-api)
demo.

<!-- =================================================================
     /help/rows/tree-rows  (community)
     ================================================================== -->

# Tree rows (expand / collapse)

SvGrid does not have a `treeData` prop. Tree-shaped data renders through
the same data + columns pipeline as any other grid, with the tree
behaviour living in *your* derived-state code. This is on purpose: a
tree is just "a flat list with a depth field and a collapsible
subtree", and the headless engine doesn't need to know which.

Try the org-chart pattern - click any chevron to expand a branch,
or focus a name cell and press Right / Left / Enter:

<div data-docs-demo="28-org-chart-tree" data-height="520"></div>


## What it is

A "tree row" is any row with a `depth: number`, a `childIds: string[]`
(or equivalent), and a parent reference. Whether a row is currently
visible depends on its ancestors' expanded state.

## The pattern

Three pieces of state, the third one derived:

```ts
let allRows = $state<Node[]>(/* every node, flat */)
let expanded = $state<Record<string, boolean>>({ root: true })

const visibleRows = $derived.by(() => {
  const out: Node[] = []
  const byId = new Map(allRows.map((n) => [n.id, n]))
  function walk(id: string) {
    const node = byId.get(id)
    if (!node) return
    out.push(node)
    if (expanded[id]) for (const cid of node.childIds) walk(cid)
  }
  for (const root of allRows.filter((n) => n.parentId === null)) walk(root.id)
  return out
})
```

Hand `visibleRows` to `<SvGrid data={visibleRows} ...>` like any
other dataset. The grid stays unaware that the data is hierarchical.

## The expand-chevron cell

Render the chevron + indentation as part of a custom cell snippet on
the leftmost (or "name") column:

```svelte
{#snippet NameCell(props: { node: Node })}
  {@const canExpand = props.node.childIds.length > 0}
  {@const isOpen = !!expanded[props.node.id]}
  <span class="tree-name" style="padding-left: {props.node.depth * 22}px">
    {#if canExpand}
      <button
        type="button"
        class={`tree-chev ${isOpen ? 'tree-chev-open' : ''}`}
        onclick={() => (expanded = { ...expanded, [props.node.id]: !isOpen })}
        aria-expanded={isOpen}
        aria-label={isOpen ? 'Collapse' : 'Expand'}
      >
        <svg viewBox="0 0 16 16" width="10" height="10"
             fill="none" stroke="currentColor" stroke-width="2.4"
             stroke-linecap="round" stroke-linejoin="round">
          <polyline points="5 3 11 8 5 13" />
        </svg>
      </button>
    {/if}
    <span>{props.node.name}</span>
  </span>
{/snippet}
```

The corresponding CSS rotates the SVG instead of swapping a character,
which animates smoothly:

```css
.tree-chev {
  transition: transform 160ms ease;
}
.tree-chev-open { transform: rotate(90deg); }
```

## Tree connector lines

For visual continuity between parents and children, draw guide lines
in absolute position inside the name cell. One vertical guide per
ancestor depth, plus a short horizontal "elbow" into the current row:

```svelte
<span class="tree-name" style="position: relative; padding-left: {4 + node.depth * 22}px">
  {#each Array(node.depth) as _, i (i)}
    <span class="tree-guide" style="left: {4 + i * 22 + 11}px"></span>
  {/each}
  {#if node.depth > 0}
    <span class="tree-elbow" style="left: {4 + (node.depth - 1) * 22 + 11}px"></span>
  {/if}
  ...
</span>
```

```css
.tree-guide {
  position: absolute;
  top: 0; bottom: 0;
  border-left: 1px dashed rgba(148, 163, 184, 0.35);
}
.tree-elbow {
  position: absolute;
  top: 50%;
  width: 14px;
  border-top: 1px dashed rgba(148, 163, 184, 0.45);
}
```

## Keyboard navigation

The grid's built-in arrow-key handling moves the active cell between
columns. To get standard tree-grid keys (Right expands, Left collapses,
Enter toggles), intercept at the window level **with a capture
listener** so your handler runs before the grid's:

```ts
let activeCol = $state<string>('')
let activeRowIndex = $state<number>(0)

$effect(() => {
  function onKey(e: KeyboardEvent) {
    if (activeCol !== 'name') return                      // not on the tree column
    const node = visibleRows[activeRowIndex]
    if (!node || node.childIds.length === 0) return       // leaves don't toggle
    const isOpen = !!expanded[node.id]
    if (e.key === 'ArrowRight' && !isOpen) {
      e.preventDefault()
      expanded = { ...expanded, [node.id]: true }
    } else if (e.key === 'ArrowLeft' && isOpen) {
      e.preventDefault()
      expanded = { ...expanded, [node.id]: false }
    } else if (e.key === 'Enter' || e.key === ' ') {
      e.preventDefault()
      expanded = { ...expanded, [node.id]: !isOpen }
    }
  }
  window.addEventListener('keydown', onKey, true)
  return () => window.removeEventListener('keydown', onKey, true)
})
```

Wire SvGrid to track the active cell:

```svelte
<SvGrid
  data={visibleRows}
  columns={columns}
  onActiveCellChange={(args) => {
    activeCol = args.columnId
    activeRowIndex = args.rowIndex
  }}
  ...
/>
```

This pattern is non-invasive: regular arrow keys still move the active
cell between non-name columns; tree keys only fire when the user is
focused on the tree column.

## Roll-ups (computed values at non-leaf rows)

When a parent's value is a roll-up of its children (headcount,
percent-complete, cost), put the computation in a separate function
that runs after every leaf edit and writes the result back onto the
parent rows:

```ts
function recompute(rows: Node[]): Node[] {
  const byId = new Map(rows.map((r) => [r.id, { ...r }]))
  // post-order DFS: deepest first so each parent already has updated children
  const ordered = [...byId.values()].sort((a, b) => b.depth - a.depth)
  for (const r of ordered) {
    if (r.childIds.length === 0) continue
    let sum = 0
    for (const cid of r.childIds) sum += byId.get(cid)!.subtotal
    r.subtotal = sum
  }
  return rows.map((r) => byId.get(r.id)!)
}
```

Hook it from `onCellValueChange`:

```svelte
<SvGrid
  ...
  onCellValueChange={(e) => {
    const next = allRows.slice()
    const ix = next.findIndex((r) => r.id === e.row.id)
    next[ix] = { ...next[ix], [e.columnId]: e.newValue }
    allRows = recompute(next)
  }}
/>
```

## Lazy load on first expand

For trees that are too large to seed up front, fetch children only when
the user expands a node:

```ts
async function toggle(id: string) {
  const isOpen = !!expanded[id]
  expanded = { ...expanded, [id]: !isOpen }
  if (isOpen) return  // collapsing - no fetch needed

  const node = allNodes.find((n) => n.id === id)
  if (!node || !node.expandable || node.loadState === 'loaded') return

  allNodes = allNodes.map((n) => (n.id === id ? { ...n, loadState: 'loading' } : n))
  const children = await fetchChildren(id)
  allNodes = allNodes
    .map((n) => n.id === id ? { ...n, loadState: 'loaded', childIds: children.map((c) => c.id) } : n)
    .concat(children)
}
```

Render a placeholder spinner row in `visibleRows` while `loadState === 'loading'`.

## See also

- [Row data](./row-data.md) - the underlying `data` prop and accessors.
- [Row sorting](./row-sorting.md) - applies to tree rows too, but you
  control the order via the `visibleRows` derivation.
- [Cell components](../cells/cell-components.md) - the custom-cell
  pattern used for the expand chevron.

<!-- =================================================================
     /help/saved-views  (community)
     ================================================================== -->

# Saved views & layout persistence

The pattern for "user changes sort + filters + columns; reopens the
page next week; everything is where they left it." Powered entirely
by your own state - the grid never writes to storage on its own.

Live reference: a reporting workspace with named saved views in
localStorage:

<div data-docs-demo="36-reporting-workspace" data-height="540"></div>

## The shape

A "view" is everything the user can change about the grid that's not
the data itself:

```ts
type GridView = {
  /** Stable id for storage. */
  id: string
  /** Display name in the picker. */
  name: string
  /** Schema version - bump when you change the shape. */
  v: 1
  /** Column visibility, in their preferred order. */
  columns: Array<{ id: string; visible: boolean; width?: number; pinned?: 'left' | 'right' | null }>
  /** Sort spec. */
  sorting: Array<{ id: string; desc: boolean }>
  /** Column filters keyed by column id. */
  filters: Record<string, { operator: string; value: string }>
  /** Group-by columns in order. */
  groupBy: string[]
  /** Active page + page size. */
  pagination?: { page: number; pageSize: number }
  /** Density preset. */
  density?: 'compact' | 'comfortable' | 'spacious'
}
```

Two ground rules:

1. **Always carry a `v` field.** The schema WILL change. Reading an
   older view requires a migration; reading a newer view should fall
   back to defaults.
2. **Store column references by `id`, not array index.** Reordering
   the source columns shouldn't scramble saved views.

## Reading + writing

```ts
const STORAGE_KEY = 'my-app:grid:orders:v1'

function loadView(): GridView | null {
  if (typeof localStorage === 'undefined') return null
  try {
    const raw = localStorage.getItem(STORAGE_KEY)
    if (!raw) return null
    const parsed = JSON.parse(raw) as GridView
    if (parsed.v !== 1) return migrate(parsed)
    return parsed
  } catch {
    return null
  }
}

function saveView(view: GridView): void {
  if (typeof localStorage === 'undefined') return
  try {
    localStorage.setItem(STORAGE_KEY, JSON.stringify(view))
  } catch {
    // Quota / private mode - swallow.
  }
}
```

Both are no-ops on the server (SSR safe).

## Wiring into the grid

The wrapper exposes change callbacks for the slices users actually
mutate (sort, filter, selection, cell edits). Sort + filter cover the
view-state most apps care about; re-apply on mount through the
imperative API.

```svelte
<script lang="ts">
  import type { SvGridApi } from 'sv-grid-community'

  let view = $state<GridView>(loadView() ?? defaultView())
  let api  = $state<SvGridApi<typeof features, Row> | null>(null)

  // Debounce writes so a flurry of input events doesn't hit localStorage 60x/s.
  let saveTimer: ReturnType<typeof setTimeout> | null = null
  function persist() {
    if (saveTimer) clearTimeout(saveTimer)
    saveTimer = setTimeout(() => saveView(view), 200)
  }
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  filterMode="menu"
  onApiReady={(next) => {
    api = next
    // Replay saved state into the fresh grid.
    if (view.groupBy?.length) api.setGroupBy(view.groupBy)
    for (const s of view.sorting ?? []) api.setSort(s.id, s.desc ? 'desc' : 'asc')
    for (const f of view.filters ?? []) api.setFilter(f.id, { operator: f.operator, value: f.value })
  }}
  onSortingChange={(s) => { view = { ...view, sorting: s }; persist() }}
  onFiltersChange={(next) => { view = { ...view, filters: next.columns }; persist() }}
/>
```

The debounced `persist()` keeps storage writes bounded; the in-memory
`view` updates immediately so the UI is responsive.

> Column width / pinning / visibility change events on the wrapper
> aren't shipped yet. Until they are, persist them only when the user
> hits an explicit "Save view" button (read the current widths from
> `getColumnWidths` once it lands - tracked in
> [Missing features](./missing-features.md)).

## Multiple named views

A view picker is just an array of `GridView`s with one marked active:

```ts
type SavedViews = {
  v: 1
  active: string                       // id of the current view
  views: GridView[]
}
```

UI:

```svelte
<select bind:value={saved.active} onchange={() => applyView(saved.views.find((v) => v.id === saved.active)!)}>
  {#each saved.views as v (v.id)}
    <option value={v.id}>{v.name}</option>
  {/each}
</select>
<button onclick={saveCurrentAsNew}>Save as new view</button>
<button onclick={deleteCurrent} disabled={saved.views.length <= 1}>Delete</button>
```

`applyView` calls the imperative API to push the saved values into
the grid:

```ts
function applyView(view: GridView) {
  if (!api) return
  api.clearAllFilters()
  api.clearSort()
  api.setGroupBy(view.groupBy)
  for (const s of view.sorting) api.setSort(s.id, s.desc ? 'desc' : 'asc')
  for (const [id, f] of Object.entries(view.filters)) api.setFilter(id, f)
  for (const c of view.columns) {
    api.setColumnVisible(c.id, c.visible)
    if (c.width) api.setColumnWidth?.(c.id, c.width)
  }
}
```

## Migrations

A `v: 1` → `v: 2` example: you renamed a field from
`'placedAt'` to `'placed_at'` and want the saved sort + filters to
follow.

```ts
function migrate(input: { v: number } & Record<string, unknown>): GridView {
  if (input.v === 1) {
    const v1 = input as GridView
    return {
      ...v1,
      v: 2,
      sorting: v1.sorting.map((s) => s.id === 'placedAt' ? { ...s, id: 'placed_at' } : s),
      filters: Object.fromEntries(
        Object.entries(v1.filters).map(([id, f]) =>
          id === 'placedAt' ? ['placed_at', f] : [id, f],
        ),
      ),
    } as unknown as GridView
  }
  // Unknown version → start fresh. Better than crashing on someone
  // who downgraded.
  return defaultView()
}
```

## Storage locations

| Storage          | Capacity   | When to use                                                                       |
| ---------------- | ---------- | --------------------------------------------------------------------------------- |
| `localStorage`   | ~5 MB / origin | Default. Per-browser; survives reloads + restarts; no expiry.                |
| `sessionStorage` | ~5 MB / tab | Per-tab views: when the user opens the same screen in two tabs and wants them independent. |
| Cookies          | ~4 KB      | Don't. Saved views grow.                                                          |
| Server / IndexedDB | unbounded | When the view should follow the user across machines (logged-in app).            |

For server-side persistence, replace the `saveView` body with a
`fetch('/api/views', { method: 'PUT', body: JSON.stringify(view) })`.
The pattern is otherwise unchanged.

## Sharing a view via URL

For "send me this view" sharing, encode the view in the URL hash:

```ts
function viewToHash(view: GridView): string {
  // btoa is fine for small payloads; for >2 KB views, use lz-string.
  return btoa(unescape(encodeURIComponent(JSON.stringify(view))))
}
function viewFromHash(hash: string): GridView | null {
  try {
    return JSON.parse(decodeURIComponent(escape(atob(hash)))) as GridView
  } catch {
    return null
  }
}
```

A "Share" button copies `window.location.origin + '/orders#' +
viewToHash(view)`. The page hydrates from the hash on load and falls
back to the user's saved view if there isn't one.

## What NOT to save

- **Active cell / focus.** Restoring focus on load is jarring; users
  expect to land at the top.
- **Selection.** Same reason.
- **Live data filter state if the underlying rows change between
  visits.** A filter for "Region = EMEA" still works; a filter for
  `customerId = 12345` is broken if 12345 no longer exists.

## SSR + hydration

`localStorage` is undefined on the server. Guard the read in
`loadView()` (the snippet above already does). Defer the
`applyView()` call to `$effect` (or `onMount`) so the server-rendered
output isn't influenced by client-only state.

## See also

- [Architecture overview](./architecture.md) - which state lives
  where.
- [Recipes / Cookbook](./recipes.md) - the saved-views recipe uses
  this page's pattern.
- [Demo #36 Reporting workspace](https://svgrid.com/#/demos/36-reporting-workspace)
  - end-to-end implementation.

<!-- =================================================================
     /help/security  (community)
     ================================================================== -->

# Security & supply chain

SvGrid is built for shipping into regulated environments where every
dependency, every runtime call, and every network egress has to be
justified before procurement signs. This page is the answer to "what
does this package do, what does it depend on, and what would I tell
our InfoSec team?".
<div data-docs-demo="16-csp-compliant" data-height="540"></div>

## TL;DR

| Property                          | Status                                                                 |
| --------------------------------- | ---------------------------------------------------------------------- |
| Network egress at runtime         | **None.** Zero analytics, zero phone-home, no automatic update checks. |
| Telemetry                         | **Zero.** No `fetch`, no `navigator.sendBeacon`, no console identifiers. |
| `eval` / `new Function` / dynamic code | **None in `sv-grid-community`.** See [CSP-compliant grid](https://svgrid.com/#/demos/16-csp-compliant) demo + runtime self-check. |
| Cookies / localStorage            | None set by the library itself. (Your app's saved-views helpers may opt in.) |
| Outbound dependencies             | **Community:** zero runtime deps. **Pro:** two optional peer deps (`jszip`, `pdfmake`), see below. |
| AI calls                          | The user's own `AIProvider` adapter calls whichever endpoint *they* configured. The package never embeds a model client. |
| License                           | Community: MIT. Pro: commercial (see [LICENSE](../../packages/sv-grid-pro/LICENSE)). |
| npm provenance + signing          | Published with `npm publish --provenance` from GitHub Actions; integrity hashes in the npm registry. |
| Source                            | 100% open source. `pnpm patch` works; everything in this monorepo is the same code that ships to npm. |

## Runtime dependencies

`sv-grid-community` has **zero runtime dependencies**. It is a single
package with no transitive supply chain - the only thing the user's
build pulls in is `svelte` itself (peer).

`sv-grid-pro` adds two **optional** peer dependencies, both lazy-loaded
on first use:

| Peer            | When loaded                                  | License        | Why optional                                                     |
| --------------- | -------------------------------------------- | -------------- | ---------------------------------------------------------------- |
| `jszip` ^3.10   | `api.exportData({ format: 'xlsx' })` *or* `api.importData({ format: 'xlsx' })` | MIT            | If you don't export/import Excel, you don't install this peer. |
| `pdfmake` ^0.2  | `api.exportData({ format: 'pdf' })`          | MIT            | If you don't export to PDF, you don't install this peer.         |

Neither is bundled. Both are dynamically `import()`-ed at first call. If
the consumer hasn't installed the peer, the call throws a typed error
naming the missing module and the install command - the rest of the
library keeps working.

CSV, TSV, HTML, JSON import/export, print, the AI assistant, and the
pivot helpers have **no extra peer dependencies** at all.

## What the package does at runtime

Every observable side effect, mapped:

| Surface                              | Side effect                                                                |
| ------------------------------------ | -------------------------------------------------------------------------- |
| `<SvGrid>` mount                     | Sets up `requestAnimationFrame`, `ResizeObserver`, and DOM event listeners on the grid container. |
| Inline editing                       | Reads + writes `document` selection; commits via your `onCellValueChange`. |
| Export to xlsx / pdf / csv / tsv / html | Creates a `Blob` and triggers a download via a synthetic `<a download>`. No network. |
| Import from xlsx / csv / tsv / json  | Reads the user-provided `File` via `arrayBuffer()` / `text()`. No network. |
| Print                                | Opens a sandbox popup window with an isolated HTML document and calls its `print()`. |
| AI helpers                           | Build a prompt locally and call the consumer-registered `AIProvider`. The grid itself never opens a connection. |
| License key check                    | A 4-line string-prefix check against an in-memory revoked-key set. No network. |
| Unlicensed watermark                 | Renders a small DOM badge linking to the pricing page. No network. |
| Unlicensed upgrade prompt            | On first unlicensed Pro feature call, appends a one-time DOM card linking to a trial. No network, no storage; one in-memory flag. |

## CSP guidance

The community grid is CSP-friendly. A strict policy that works:

```
default-src 'self';
script-src 'self';
style-src 'self' 'unsafe-inline';
img-src 'self' data:;
connect-src 'self';
```

Notes:

- `'unsafe-inline'` on `style-src` is needed because Svelte 5 emits
  scoped style attributes inline. You can drop it if you switch to
  `unsafe-hashes` with a CSP nonce-aware build of Svelte.
- `connect-src 'self'` is enough - the grid never opens a connection to
  a third-party origin.
- `script-src` does NOT need `'unsafe-eval'` for community. (Pro pulls
  in `pdfmake` which historically used `eval`; check the pdfmake version
  if your CSP is strict.)
- Demo [16. CSP-compliant grid](https://svgrid.com/#/demos/16-csp-compliant) runs the grid under a CSP header and surfaces any violation in real time.

## Source provenance

- Source repository: `github.com/sv-grid/sv-grid` - all releases tagged.
- Build pipeline: GitHub Actions. The release workflow signs and
  publishes to npm with `--provenance`. You can verify the signature
  via `npm audit signatures` (npm 9+) or by inspecting the
  package metadata on the registry.
- No private patches. The code on npm is the code in the public
  monorepo at the tagged commit.

## Vulnerability handling

- Reports: open a draft security advisory on the GitHub repository, or
  email `support@jqwidgets.com`. PGP key on the repository's SECURITY.md.
- Response SLA (paid customers): acknowledgement within one business
  day, advisory + patch within five business days for severity High +
  Critical.
- Community: best-effort but every report is triaged.
- Public advisories for Pro customers go out via the support Slack +
  email **before** the GitHub advisory page goes public.

## SBOM

Every release ships an `npm pack` tarball. You can generate a CycloneDX
or SPDX SBOM directly:

```bash
npx @cyclonedx/cdxgen -t npm -o sbom.json sv-grid-community
# or
npx @cyclonedx/cdxgen -t npm -o sbom.json sv-grid-pro
```

For Pro, the SBOM lists `jszip` and `pdfmake` as optional peers - flag
to your scanner if you don't use those formats.

## Data residency

The library processes data **in the browser**. Nothing leaves the user's
machine via the package itself.

If you wire `setAIProvider(fn)` to a remote endpoint, the prompt + row
sample the helpers build (a column schema + at most ~25 sampled rows)
is what goes through your adapter. The package gives you the prompt
verbatim before sending - you decide whether to redact, route to an
on-prem model, or hash sensitive fields.

## Audit-friendly defaults

- **No global state** beyond a few module-scoped variables for the
  license + AI provider registration. No singletons that survive HMR.
- **Pure-function helpers** for filtering / sorting / aggregation -
  every callable you import is testable in isolation (vitest suite
  proves this for 1000+ assertions).
- **No prototype pollution surface.** Every helper uses
  `Object.create(null)` or own-property maps; no untyped object
  merging.
- **No reflection-driven config.** Column definitions are plain
  objects; the grid never reads metadata via `eval` or `with`.

## See also

- [Browser support](./browser-support.md) - tested target matrix.
- [Testing and quality](./testing-and-quality.md) - the test suite that
  underwrites this page's claims.
- [API stability](./api-stability.md) - semver policy, deprecation
  lifecycle.

## Frequently asked questions

### Is SvGrid safe to use in a regulated or enterprise environment?

Yes. SvGrid is a client-side library: it makes no network calls of its own,
sends no telemetry, and runs CSP-clean (no `eval`, no `new Function`, no inline
scripts). All data stays in the browser, so it does not change your app's data
egress posture.

### Does SvGrid send any telemetry or phone home?

No. There is zero outbound traffic from the library. Any network calls in your
app are ones you write.

### What is SvGrid's supply-chain footprint?

The Community core has a minimal dependency surface; Pro export/import features
lazy-load their dependencies only when used. See this page for the full
dependency and runtime-call accounting procurement asks for.

<!-- =================================================================
     /help/server-side-data  (community)
     ================================================================== -->

# Server-side data

The patterns for moving sort, filter, group, and pagination off the
client and onto your API. Three flavours, ranked by complexity:

1. **Plain paginated server fetch** - you fetch each page on demand
   and replace the rows.
2. **Server-driven filter / sort** - the grid hands you the spec; you
   round-trip and return matching rows + a total.
3. **Sparse infinite scroll** - the grid renders placeholder rows for
   slots you haven't loaded yet; you fetch chunks as the user scrolls
   through them, with debounce + cancellation.

> Live demos: **#33 Server-side infinite scroll** is the production
> reference for option 3. It's embedded below so you can scroll, sort,
> filter, and watch the network panel light up.

<div data-docs-demo="33-server-infinite" data-height="560"></div>

## Why move work to the server?

Two reasons - one is correctness, one is cost:

- **Correctness.** When your dataset has 5 million rows, you can't
  ship them all to the browser. Server-side filtering + pagination is
  the only way to keep the page responsive.
- **Cost.** Even for moderate datasets (10k-100k rows), pushing the
  work down lets you cache aggregates at the DB layer (materialised
  views, indexed sort orders, denormalised pre-joined tables) and pay
  for that once per query rather than once per client.

If your dataset is < 50k rows and the user is the only one interacting
with it, **stay client-side**. The pipeline in
[Architecture](./architecture.md) is fast enough that you don't gain
much from a round-trip, and you lose offline-while-scrolling.

## Option 1: paginated server fetch

The simplest pattern. You own the rows; the grid only renders the
page you give it. Sort + filter UIs are off because the grid would
sort/filter only the visible page, which is wrong.

```svelte
<script lang="ts">
  import { SvGrid, tableFeatures, type ColumnDef } from 'sv-grid-community'

  let rows = $state<Order[]>([])
  let page = $state(0)
  let pageSize = $state(50)
  let total = $state(0)
  let busy = $state(false)

  // No row models registered: the grid takes the rows as-is.
  const features = tableFeatures({})

  $effect(() => {
    busy = true
    void fetchPage(page, pageSize).then((r) => {
      rows = r.rows
      total = r.total
      busy = false
    })
  })

  const columns: ColumnDef<typeof features, Order>[] = [/* ... */]
</script>

<div class="flex items-center gap-2">
  <button disabled={page === 0} onclick={() => (page -= 1)}>Prev</button>
  <span>Page {page + 1} of {Math.ceil(total / pageSize)}</span>
  <button disabled={(page + 1) * pageSize >= total} onclick={() => (page += 1)}>Next</button>
</div>

<SvGrid {rows} {columns} {features} loading={busy} showPagination={false} />
```

Performance: O(pageSize) work in the browser; the server does the
rest. This is what you want for "give me a CRUD admin view of a
million-row table".

## Option 2: server-driven sort + filter

The grid still owns the UI. Each interaction emits a state change you
hand to the server.

```svelte
<script lang="ts">
  import { SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
           type ColumnDef, type SvGridApi } from 'sv-grid-community'

  let rows = $state<Order[]>([])
  let total = $state(0)
  let busy = $state(false)

  const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })

  let api = $state<SvGridApi<typeof features, Order> | null>(null)
  let sortState = $state<Array<{ id: string; desc: boolean }>>([])
  let filterState = $state<Record<string, { operator: string; value: string }>>({})
  let page = $state(0)

  // Debounce so a flurry of header clicks coalesces into one fetch.
  let abort: AbortController | null = null
  $effect(() => {
    void sortState
    void filterState
    void page
    abort?.abort()
    abort = new AbortController()
    const signal = abort.signal
    busy = true
    void fetchPage({ sort: sortState, filters: filterState, page, pageSize: 50 }, signal)
      .then((r) => { if (!signal.aborted) { rows = r.rows; total = r.total } })
      .finally(() => { if (!signal.aborted) busy = false })
  })

  function onApiReady(next: SvGridApi<typeof features, Order>) {
    api = next
  }
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  loading={busy}
  filterMode="menu"
  externalSort={true}
  externalFilter={true}
  onApiReady={onApiReady}
  onSortingChange={(s) => { sortState = s; page = 0 }}
  onFiltersChange={(next) => { filterState = next.columns; page = 0 }}
/>
```

Notes:

- **Reset to page 0 on filter / sort change** - a "page 5 of new
  results" is almost never what the user wants.
- **`AbortController`** is mandatory in production. Without it a fast
  user can land out-of-order results.
- **Don't register `createSortedRowModel` / `createFilteredRowModel`** -
  they'd sort/filter the page you got back, which scrambles your
  server's careful work.

## Option 3: sparse infinite scroll

The most polished pattern - the user scrolls a "1,000,000 rows" grid
that pulls slices on demand. Demo #33 above is the canonical
implementation; the engine of it boils down to:

```ts
// Sparse rows: one placeholder per unloaded slot, real Transaction per loaded.
const PLACEHOLDER: Transaction = Object.freeze({ id: '', /* zero values */ })
let rows = $state.raw<Transaction[]>(new Array(TOTAL_ROWS).fill(PLACEHOLDER))

// Bookkeeping
let loadedChunks = $state.raw(new Set<number>())
let pendingChunks = $state.raw(new Set<number>())
let abortedChunks = new Set<number>()
let cacheGeneration = 0  // bumped on filter/sort change

const CHUNK_SIZE = 200
const SCROLL_DEBOUNCE_MS = 90        // coalesce scroll bursts
const FAST_SCROLL_PX_PER_MS = 3      // velocity threshold

function chunkOf(rowIndex: number) { return Math.floor(rowIndex / CHUNK_SIZE) }
```

On scroll, you:

1. Read `scrollContainer.scrollTop` + `clientHeight` to compute the
   visible row range.
2. Compute `firstChunk` and `lastChunk` from that range.
3. Track velocity (px/ms between scroll events). If above ~3 px/ms,
   fetch only the chunks currently in view and skip prefetch - the
   user is flying through, you'd queue work for chunks they're about
   to leave.
4. Mark any in-flight chunks that just dropped out of view as
   "aborted" - their results will be discarded on arrival.
5. Issue a chunk request for any chunk in `[firstChunk - lookBehind,
   lastChunk + lookAhead]` not already in `loadedChunks` or
   `pendingChunks`.
6. Debounce step 5 by ~90 ms so a wheel-flick that traverses 50
   chunks lands as one final fetch pass, not 50.

When a chunk lands:

```ts
if (generation !== cacheGeneration) return  // filter/sort changed under us
if (abortedChunks.has(chunkIndex)) return    // user scrolled away
// Splice into rows
const next = rows.slice()
for (let i = 0; i < result.rows.length; i += 1) next[result.rangeStart + i] = result.rows[i]
rows = next
loadedChunks.add(chunkIndex)
```

When the user changes sort or filter, **bump `cacheGeneration`** and
wipe `rows`/`loadedChunks`/`pendingChunks`. Any chunks still in flight
see the generation mismatch on arrival and discard themselves -
cheaper than tracking individual fetch promises.

### Cell snippet shape

Each cell needs to render a skeleton when the row is still
placeholder, real content otherwise. Cheap pattern: the placeholder
has an empty `id`; the snippet checks that.

```svelte
{#snippet AmountCell(props: { row: Transaction })}
  {#if props.row.id === ''}
    <span class="sk-cell"></span>
  {:else}
    <span class="tabular-nums">{fmtMoney(props.row.amount)}</span>
  {/if}
{/snippet}
```

## Pushing other operations to the server

| Operation         | Push-down pattern                                                              |
| ----------------- | ------------------------------------------------------------------------------ |
| Sort              | Send `Array<{ id, desc }>` to your query builder; map to `ORDER BY`.            |
| Filter            | Send `Record<columnId, { operator, value }>`; map each operator to a SQL fragment. |
| Group + aggregate | Send `{ groupBy: string[], aggregators: Record<col, 'sum'|'avg'|'count'|...> }`. Build a `GROUP BY` per dimension and a `SELECT SUM(col)` per aggregator. |
| Search            | Concatenate the searchable fields server-side: `WHERE field1 || ' ' || field2 ILIKE '%' || $1 || '%'`. |

Pivot is intentionally NOT on this list - the pivot engine in
[pivot.md](./pivot.md) is designed for in-memory facts. For server-side
pivots, compute the pivoted result server-side and feed `PivotedRow[]`
straight into the demo's render pipeline.

## Error handling

A few patterns that pay off in production:

- **Show the previous rows during a refetch**, not a spinner over an
  empty grid. The `loading` prop is for empty-initial-load; once you
  have rows, keep them visible while a new fetch is in flight.
- **Toast the error, don't clear the rows.** A network glitch on
  `fetchPage` shouldn't wipe what the user is looking at.
- **Idempotent retries.** Send a client-generated request id with each
  fetch; the server can return cached results if it sees the same id
  twice in a row.

## See also

- [Architecture](./architecture.md) - where the engine sits in the
  pipeline.
- [Row pagination](./rows/row-pagination.md) - controlled vs
  uncontrolled pagination state.
- [Real-time streaming](./real-time.md) - the live-update pattern (a
  different beast: pushes from the server, not polls).
- [Performance benchmarks](./benchmarks.md) - the chunk-loader's
  measured behaviour in demo #33.

## Frequently asked questions

### How does SvGrid handle server-side data?

Set `externalSort` / `externalFilter` so the grid records UI state but lets
your API own ordering, filtering, and pagination. You fetch each page (or chunk)
on demand and feed rows back into `data`. Three patterns are covered above,
ranked by complexity, from plain paginated fetch to cursor-based infinite
scroll.

### Can SvGrid handle millions of rows?

Yes, with server-side or chunked loading plus row/column virtualization - only
the visible window is ever in the DOM. For purely client-side data the grid
scrolls smoothly through 100k+ rows; beyond that, move sort/filter/page to the
server using the patterns on this page.

### Does server-side mode work with TanStack Query or GraphQL?

Yes. The grid is transport-agnostic: it emits sort/filter/page state and
consumes rows, so you can back it with REST, GraphQL, or TanStack Query. See the
related recipes for worked examples.

<!-- =================================================================
     /help/server/server-row-model  (community)
     ================================================================== -->

# Server-Side Row Model (SSRM)

When the data lives on the server - millions of rows in a database - the grid
should hold only the page on screen and push sorting, filtering, and paging to
the backend. SvGrid packages this as **one datasource contract**: you implement
a single async `getRows`, and `createServerDataSource` owns the rest.

```ts
import { createServerDataSource, type ServerDataSource } from 'sv-grid-community'

const source: ServerDataSource<Row> = {
  async getRows({ startRow, endRow, sortModel, filterModel }) {
    const res = await fetch('/api/rows', {
      method: 'POST',
      body: JSON.stringify({ startRow, endRow, sortModel, filterModel }),
    })
    const { rows, total } = await res.json()
    return { rows, rowCount: total }
  },
}

let s = $state(/* initial ServerState */)
const ctl = createServerDataSource(source, { pageSize: 50, onChange: (next) => (s = next) })
ctl.refresh()
```

## Wiring to the grid

Run the grid in **controlled** mode - it records sort/filter UI state but
doesn't reorder/slice the data itself (the server already did) - and feed it
the controller's current page:

```svelte
<SvGrid
  data={s.rows}
  {columns} {features}
  sortable filterable
  externalSort externalFilter
  loading={s.loading}
  pageable={false}
  onSortingChange={(sorting) => ctl.setSort(sorting)}
  onFiltersChange={(f) => ctl.setFilter({ global: f.global, columns: toColumnModel(f.columns) })}
/>
<!-- your pager drives ctl.setPage(...) from s.pageIndex / s.pageCount -->
```

## The controller

`createServerDataSource(source, { pageSize, onChange })` returns:

| Method            | Does                                            |
| ----------------- | ----------------------------------------------- |
| `refresh()`       | Re-fetch the current page (after a mutation).   |
| `setSort(model)`  | New sort, jump to page 0, fetch.                |
| `setFilter(model)`| New filter, jump to page 0, fetch.             |
| `setPage(i)`      | Fetch page `i`.                                 |
| `setPageSize(n)`  | New page size, page 0, fetch.                   |
| `getState()`      | Current `{ rows, total, loading, pageIndex, pageCount, ... }`. |
| `dispose()`       | Stop accepting responses (call on unmount).     |

`onChange` fires on every state transition (including `loading: true` before a
fetch and `loading: false` after) so the UI tracks in-flight requests.

## Race safety

Each fetch carries a monotonic id; only the **latest** request is allowed to
land. A slow response for an old sort/filter can't clobber a newer one - the
classic SSRM bug, handled for you. `dispose()` drops everything in flight.

## Notes

- The `ServerRequest` carries `startRow` / `endRow` (block bounds),
  `pageIndex` / `pageSize`, plus `sortModel` and `filterModel` - map these to
  your `ORDER BY` / `WHERE` / `LIMIT`.
- This is the **controlled** building block; pair it with optimistic updates
  (demo 115) or `applyTransaction` for writes.

See the live [Server-Side Row Model](https://sv-grid.com/demos/148-server-row-model)
demo.

<!-- =================================================================
     /help/spreadsheet-formulas  (community)
     ================================================================== -->

# Spreadsheet formulas

A minimal Excel-style formula engine that runs in the browser, with no
dependencies. Cells can hold either a literal value (number, string,
boolean) or a formula starting with `=`. When the formula resolves
against the sheet, the cell shows the computed value; when you click
the cell, the formula bar shows the source.

Useful for budgets, scorecards, cascading totals, conditional reports,
lightweight planning - anything that needs in-cell calc without
bundling a full spreadsheet engine like HyperFormula.

<div data-docs-demo="83-spreadsheet-formulas" data-height="640"></div>

## What's supported

| Category       | Examples                                                           |
|----------------|--------------------------------------------------------------------|
| Cell refs      | `A1`, `B2`, `AA10`, `$C$3` (absolute = relative here)              |
| Ranges         | `A1:A10`, `B2:D5`                                                  |
| Arithmetic     | `+ - * / ^ %`  (unary `-`)                                         |
| Comparison     | `=` `<>` `<` `>` `<=` `>=`                                         |
| String concat  | `&`                                                                |
| Functions      | `SUM`, `AVG`/`AVERAGE`, `MIN`, `MAX`, `COUNT`, `COUNTA`, `COUNTIF` |
|                | `IF`, `AND`, `OR`, `NOT`                                           |
|                | `ROUND`, `ABS`                                                     |
|                | `LEN`, `LEFT`, `RIGHT`, `UPPER`, `LOWER`, `CONCAT`                 |
|                | `TODAY`                                                            |
| Literals       | numbers (`1.5`, `-3`), strings (`"hello"`), booleans (`TRUE`/`FALSE`) |

## Error codes

The engine produces the same error vocabulary as Excel:

| Code        | When                                          |
|-------------|-----------------------------------------------|
| `#REF!`     | Cell reference points outside the sheet       |
| `#CYCLE!`   | Circular dependency                           |
| `#DIV/0!`   | Division by zero                              |
| `#VALUE!`   | Type mismatch (e.g. `="abc"+1`)               |
| `#NAME?`    | Unknown function name                         |
| `#PARSE!`   | Syntax error                                  |

## Complete drop-in example

A self-contained budget sheet. The engine code (≈ 280 lines) is the
same one the demo ships - copy it verbatim, or read the full source
in [demo 83](../../examples/src/demos/83-spreadsheet-formulas.svelte).

The grid shows the *computed* values; a formula bar above lets the
user inspect or edit the raw formula behind the active cell.

```svelte
<script lang="ts">
  import {
    SvGrid,
    tableFeatures,
    rowSortingFeature,
    renderSnippet,
    type ColumnDef,
  } from 'sv-grid-community'

  // ─────────────────── ENGINE ───────────────────
  type CellVal = string | number | boolean | { error: string }
  type Sheet = string[][]

  function isError(v: CellVal): v is { error: string } {
    return typeof v === 'object' && v !== null && 'error' in v
  }

  function colToLetters(c: number): string {
    let n = c, s = ''
    while (n >= 0) { s = String.fromCharCode(65 + (n % 26)) + s; n = Math.floor(n / 26) - 1 }
    return s
  }
  function lettersToCol(l: string): number {
    let c = 0
    for (const ch of l.toUpperCase()) c = c * 26 + (ch.charCodeAt(0) - 64)
    return c - 1
  }
  function parseRef(ref: string): { row: number; col: number } | null {
    const m = ref.replace(/\$/g, '').match(/^([A-Z]+)(\d+)$/i)
    return m ? { row: parseInt(m[2]!, 10) - 1, col: lettersToCol(m[1]!) } : null
  }

  // (tokenize / parse / evaluate omitted for brevity - copy from demo 83)
  // Below is the public surface you actually call.

  declare function tokenize(formula: string): unknown[]
  declare function parse(tokens: unknown[]): unknown
  declare function evaluate(ast: unknown, resolve: (r: number, c: number) => CellVal): CellVal

  function computeSheet(sheet: Sheet): CellVal[][] {
    const rowsN = sheet.length
    const colsN = sheet[0]?.length ?? 0
    const computed: (CellVal | undefined)[][] =
      Array.from({ length: rowsN }, () => new Array(colsN))
    const visiting: boolean[][] =
      Array.from({ length: rowsN }, () => new Array(colsN).fill(false))

    function resolve(r: number, c: number): CellVal {
      if (r < 0 || r >= rowsN || c < 0 || c >= colsN) return { error: '#REF!' }
      if (computed[r]![c] !== undefined) return computed[r]![c]!
      if (visiting[r]![c]) return { error: '#CYCLE!' }
      visiting[r]![c] = true
      const raw = (sheet[r]![c] ?? '').trim()
      let value: CellVal
      if (raw === '') value = ''
      else if (raw.startsWith('=')) {
        try { value = evaluate(parse(tokenize(raw.slice(1))), resolve) }
        catch (e) {
          const msg = e instanceof Error ? e.message : '#ERR!'
          value = { error: msg.startsWith('#') ? msg : '#PARSE!' }
        }
      } else {
        const n = Number(raw)
        value = Number.isFinite(n) ? n : raw
      }
      visiting[r]![c] = false
      computed[r]![c] = value
      return value
    }
    for (let r = 0; r < rowsN; r++) for (let c = 0; c < colsN; c++) resolve(r, c)
    return computed.map((row) => row.map((v) => v ?? '')) as CellVal[][]
  }

  // ─────────────────── DEMO ───────────────────
  // raw[row][col] = the text the user typed (formula or literal).
  let raw = $state<Sheet>([
    ['Item',     'Cost', 'Qty', 'Subtotal',         'Total'],
    ['Domain',   '12.99','3',   '=B2*C2',           '=ROUND(D2*1.08,2)'],
    ['Hosting',  '49',   '12',  '=B3*C3',           '=ROUND(D3*1.08,2)'],
    ['SSL',      '85',   '1',   '=B4*C4',           '=ROUND(D4*1.08,2)'],
    ['TOTALS',   '',     '',    '=SUM(D2:D4)',      '=SUM(E2:E4)'],
    ['Status',   '',     '',    '',                 '=IF(E5>500,"REVIEW","OK")'],
  ])
  const computed = $derived(computeSheet(raw))

  let activeRow = $state<number | null>(null)
  let activeCol = $state<number | null>(null)
  const activeRaw = $derived(
    activeRow != null && activeCol != null ? raw[activeRow]?.[activeCol] ?? '' : '',
  )
  let formulaInput = $state('')
  $effect(() => { formulaInput = activeRaw })

  function commit() {
    if (activeRow == null || activeCol == null) return
    const next = raw.map((row) => row.slice())
    next[activeRow]![activeCol] = formulaInput
    raw = next
  }

  function formatValue(v: CellVal): string {
    if (isError(v)) return v.error
    if (typeof v === 'number') return Number.isInteger(v) ? String(v) : v.toFixed(2)
    if (typeof v === 'boolean') return v ? 'TRUE' : 'FALSE'
    return String(v)
  }

  // SvGrid columns - one per spreadsheet column. Each row is a SheetRow.
  type SheetRow = { rowIndex: number; cells: CellVal[] }
  const gridRows = $derived<SheetRow[]>(
    computed.slice(1).map((cells, i) => ({ rowIndex: i + 1, cells })),
  )
  const headerCells = $derived(computed[0] ?? [])

  const features = tableFeatures({ rowSortingFeature })
  const columns = $derived<ColumnDef<typeof features, SheetRow>[]>(
    Array.from({ length: 5 }, (_, c) => ({
      id: colToLetters(c),
      header: `${colToLetters(c)} · ${formatValue(headerCells[c] ?? '')}`,
      width: c === 0 ? 160 : 130,
      editable: false,
      cell: (ctx) => renderSnippet(SheetCell, { row: ctx.row.original, col: c }),
    })),
  )
</script>

{#snippet SheetCell(props: { row: SheetRow; col: number })}
  {@const r = props.row.rowIndex}
  {@const c = props.col}
  {@const v = props.row.cells[c] ?? ''}
  {@const active = activeRow === r && activeCol === c}
  <span
    onclick={() => { activeRow = r; activeCol = c }}
    style="display: inline-block; width: 100%; cursor: pointer;
           {active ? 'background: rgba(99,102,241,0.10); box-shadow: inset 0 0 0 2px #6366f1;' : ''}
           {isError(v) ? 'color: #dc2626; font-family: ui-monospace, Menlo, monospace;' : ''}"
    title={raw[r]?.[c] ?? ''}
  >{formatValue(v)}</span>
{/snippet}

<section style="display: flex; flex-direction: column; gap: 10px; height: 100%;">
  <!-- Formula bar -->
  <div style="display: flex; align-items: center; gap: 8px; border: 1px solid #cbd5e1; border-radius: 8px;">
    <span style="background: #f1f5f9; padding: 8px 12px; font-family: ui-monospace, Menlo, monospace; font-weight: 700; min-width: 64px; text-align: center;">
      {activeRow != null && activeCol != null ? `${colToLetters(activeCol)}${activeRow + 1}` : '-'}
    </span>
    <input
      type="text"
      bind:value={formulaInput}
      placeholder="Click a cell, then type =SUM(D2:D4) here…"
      onkeydown={(e) => { if (e.key === 'Enter') { e.preventDefault(); commit() } }}
      onblur={commit}
      style="flex: 1; border: 0; outline: none; font-family: ui-monospace, Menlo, monospace; padding: 7px 8px;"
    />
  </div>

  <div style="flex: 1; min-height: 0;">
    <SvGrid
      data={gridRows}
      columns={columns}
      features={features}
      enableInlineEditing={false}
      enableCellSelection={false}
      showRowNumbers={true}
      rowNumberWidth={48}
      rowHeight={32}
      containerHeight="100%"
    />
  </div>
</section>
```

> The `tokenize` / `parse` / `evaluate` functions are declared but not
> defined inline above - they are ~ 200 lines of TypeScript. Copy
> them from the
> [demo source](../../examples/src/demos/83-spreadsheet-formulas.svelte)
> which is fully self-contained.

## How the recompute works

`computeSheet(raw)` runs every time the raw sheet changes. It walks
every cell once, lazily resolving references:

1. **Literal** - try `Number(raw)`, fall back to the string.
2. **Formula** - tokenize, parse to an AST, evaluate against the
   resolver.
3. **Memoize** - once a cell is computed, its value is cached so
   downstream cells don't re-parse the same formula.
4. **Cycle detection** - a `visiting` flag per cell. If a resolver
   tries to read a cell that's currently being computed, it returns
   `#CYCLE!` instead of looping forever.

The `$derived` wrapper (`computed = $derived(computeSheet(raw))`)
re-runs the whole sheet whenever any cell changes. For sheets under
~ 10 000 cells this is fast - the demo's 16 × 8 sheet recomputes in
under a millisecond.

For very large sheets, switch to incremental recompute by tracking
which cells depend on which (build a forward edges graph during the
first pass) and recomputing only the affected sub-DAG. The shape of
the resolver doesn't change.

## Try these formulas

In the formula bar of the demo, click a cell and type:

```text
=SUM(D2:D4)               // sum a range
=AVG(E2:E4)               // average
=IF(E5>500,"REVIEW","OK") // conditional text
=COUNTIF(F2:F4,"REVIEW")  // count matches
=B2*C2&" units"           // arithmetic + string concat
=ROUND(E2/E$5*100,1)      // percentage with rounding
=TODAY()                  // today's date as YYYY-MM-DD
```

Each commits immediately on `Enter` and recomputes the whole sheet.

## Bridging to xlsx export

The engine stores raw formulas as text. When you export to xlsx via
`sv-grid-pro`, you have two choices:

1. **Export computed values** - default. The xlsx receives numbers
   and strings, Excel sees them as values.
2. **Export formulas** - mark formula cells with a leading `=` in the
   exported value. Excel parses them and recomputes on open. Useful
   when the recipient wants to drill into the math.

Both modes preserve cell formatting (currency, dates) you set on the
columns.

## Limitations & when to reach for HyperFormula

The bundled engine intentionally covers ~80% of common spreadsheet
formulas. It does NOT support:

- VLOOKUP / INDEX / MATCH (planned)
- Volatile functions beyond `TODAY()` (`NOW`, `RAND`, `RANDBETWEEN`)
- Array formulas
- Named ranges
- 3-D references across multiple sheets

If you need full Excel parity, integrate
[HyperFormula](https://hyperformula.handsontable.com) - it's a 600 KB
add-on that drops in alongside SvGrid. Reach for it only when you
actually need it; the bundled engine is < 5 KB minified.

## See also

- [Demo 83 - Spreadsheet + formulas](../../examples/src/demos/83-spreadsheet-formulas.svelte) - the full engine source
- [Demo 27 - Spreadsheet + Ribbon bar](../../examples/src/demos/27-spreadsheet-ribbon.svelte) - bold / colour / format ribbon
- [Demo 18 - Cascade editing](../../examples/src/demos/18-cascade-editing.svelte) - the alternative when you want JS-driven recompute instead of formulas
- [Export and print](./export.md) - xlsx export for the computed sheet

<!-- =================================================================
     /help/state-maintenance  (community)
     ================================================================== -->

# State maintenance

The pattern for snapshotting every dimension the user can change about
the grid - sort, filters, group-by, column visibility + widths,
pagination, expansion, selection, active cell - into a single JSON
bag, and rehydrating the grid from one. Builds on
[Saved views](./saved-views.md) but adds undo / redo, named
bookmarks, JSON import / export, and debounced auto-save.

Live reference - the demo wires all five surfaces:

<div data-docs-demo="55-state-maintenance" data-height="560"></div>

## Why a "snapshot" instead of saved views

The two patterns differ in intent:

- [Saved views](./saved-views.md) is the **end-user** flow: "save the
  layout I'm looking at; load it again next week."
- This page's **snapshot** is the **mechanism**: capture / apply, with
  undo / redo as a first-class concern.

You'd build saved views on top of snapshots: a saved view is just a
snapshot with a `label`, persisted server-side.

## The snapshot shape

```ts
export type GridStateSnapshot = {
  v: 1                                                 // schema version
  capturedAt: number                                   // Date.now() at capture
  label?: string                                       // free-form

  sorting: Array<{ columnId: string; desc: boolean }>
  filters: Record<string, { operator: string; value: string }>
  columnVisibility: Record<string, boolean>            // missing key = visible
  columnWidths: Record<string, number>                 // missing key = default

  extras: Record<string, unknown>                      // demo-defined slices
}
```

The `extras` bucket is the escape hatch: the engine doesn't track
page index, row selection, expansion, etc. internally, so the demo
passes them in via `extras` at capture time and reads them back at
apply time.

## Capture

```ts
import { captureGridState } from './state-snapshot'

function snapshotNow(label?: string): GridStateSnapshot {
  return captureGridState(api, {
    label,
    extras: {
      // These live in your $state, not on the grid - mirror them in.
      sorting,
      columnVisibility,
      columnWidths,
      // Anything else the demo cares about:
      page,
      rowSelection,
      expanded,
    },
  })
}
```

Calling `snapshotNow()` is cheap (microseconds); call it whenever a
meaningful change happens.

## Apply

```ts
import { applyGridState } from './state-snapshot'

function applySnapshot(snap: GridStateSnapshot) {
  applyGridState(api, snap, {
    onReset: () => {
      // Wipe any consumer-owned state that doesn't appear in the
      // snapshot - prevents stale entries from surviving the apply.
    },
    onSlots: (s) => {
      // The wrapper-owned slots come back through this callback.
      sorting = s.sorting
      columnVisibility = s.columnVisibility
      columnWidths = s.columnWidths
    },
    onExtras: (extras) => {
      // Demo-specific slices.
      page = (extras.page as number) ?? 0
      rowSelection = (extras.rowSelection as RowSelectionState) ?? {}
      expanded = (extras.expanded as ExpandedState) ?? {}
    },
  })
}
```

The helper itself calls `api.clearAllFilters()`, `api.clearSort()`,
the relevant `api.setFilter` / `api.setSort` / `api.setColumnVisible`
methods, and your `onSlots` / `onExtras` callbacks for everything that
lives in component state.

## Undo / redo

A bounded ring of snapshots plus a cursor:

```ts
const HISTORY_CAP = 30
let history = $state<GridStateSnapshot[]>([])
let historyIndex = $state<number>(-1)

function pushHistory(snap: GridStateSnapshot) {
  // Trim the redo tail when a new action happens after an undo.
  const trimmed = history.slice(0, historyIndex + 1)
  const next = [...trimmed, snap]
  history = next.slice(Math.max(0, next.length - HISTORY_CAP))
  historyIndex = history.length - 1
}

function undo() { if (historyIndex > 0) { historyIndex -= 1; applySnapshot(history[historyIndex]!) } }
function redo() { if (historyIndex < history.length - 1) { historyIndex += 1; applySnapshot(history[historyIndex]!) } }
```

Trigger `pushHistory(snapshotNow(label))` from each grid event that
should be undoable - `onSortingChange`, `onFiltersChange`,
`onRowSelectionChange`, `onCellValueChange`. Column-visibility,
width, and pinning callbacks aren't shipped yet (see
[Missing features](./missing-features.md)); for those, push history
manually when the user clicks "Save view" or similar.

## Named bookmarks

Bookmarks are snapshots that don't get pruned by the ring. Store them
separately:

```ts
let bookmarks = $state<GridStateSnapshot[]>([])

function captureBookmark() {
  const label = prompt('Bookmark name:', `View ${bookmarks.length + 1}`)
  if (!label) return
  bookmarks = [...bookmarks, snapshotNow(label)]
}

function restoreBookmark(bm: GridStateSnapshot) {
  applySnapshot(bm)
}
```

Persisting bookmarks - localStorage for per-browser, your server for
cross-device:

```ts
function saveBookmarks() {
  localStorage.setItem('myapp:bookmarks:v1', JSON.stringify(bookmarks))
}
```

## Auto-save

For "reload the page and come back to where you were", debounce a
localStorage write on every state change:

```ts
import { autoSaveSnapshot, loadAutoSavedSnapshot } from './state-snapshot'

const STORAGE_KEY = 'myapp:grid:state:v1'
let autoSaveOn = $state(false)

// Wire to every grid event:
function onAnyChange() {
  if (autoSaveOn) autoSaveSnapshot(STORAGE_KEY, snapshotNow('auto'))
}

// On mount, rehydrate:
$effect(() => {
  if (!api) return
  const saved = loadAutoSavedSnapshot(STORAGE_KEY)
  if (saved) applySnapshot(saved)
})
```

The helper debounces writes at 250 ms so a flurry of resize events
doesn't hit storage 60×/s.

## JSON import / export

A snapshot is plain JSON - serialise to share, restore from paste:

```ts
import { snapshotToJson, snapshotFromJson } from './state-snapshot'

function copyState() {
  const text = snapshotToJson(snapshotNow('export'))
  navigator.clipboard.writeText(text)
}

function applyFromText(text: string) {
  try {
    const snap = snapshotFromJson(text)
    applySnapshot(snap)
  } catch (e) {
    // Show the error in your UI.
  }
}
```

This is the easiest "send a teammate the exact view I'm looking at"
flow - paste into Slack, click the link in a ticket, etc.

## Forward-compatible migrations

When the snapshot shape changes (new field, renamed field), bump `v`
and add a migration arm. The `migrateStateSnapshot` helper is the
single switch:

```ts
export function migrateStateSnapshot(input: Partial<GridStateSnapshot>): GridStateSnapshot {
  if (!input || typeof input !== 'object') return emptySnapshot()
  if (input.v === 1) return { ...emptySnapshot(), ...input } as GridStateSnapshot
  if (input.v === 2) {
    // New "extras.groupBy" -> top-level "groupBy".
    return { ...emptySnapshot(), ...input, groupBy: input.extras?.groupBy ?? [] }
  }
  // Unknown version - start fresh rather than crash.
  return emptySnapshot()
}
```

Old saved snapshots keep working; new fields are filled with defaults.

## Composing with shared-config

A common production setup: snapshots stay per-user in localStorage,
**named bookmarks** live server-side under the user's account, and
**team views** live on a shared endpoint. The shape doesn't care
where each kind lives - the helper produces a `GridStateSnapshot`
that any storage backend accepts.

## What NOT to capture

- **Cell content (`rows`).** The snapshot describes the grid's *view*
  of your data, not the data itself. Storing rows in a snapshot bloats
  it and races with your real data source.
- **Volatile UI state.** Active cell + focus restoration on load is
  jarring. Capture them by all means, but consider not applying them.
- **Editor session state.** "I was mid-edit on a cell" doesn't
  survive a reload cleanly.

## See also

- [Saved views](./saved-views.md) - the end-user flow built on
  snapshots.
- [Columns hierarchy](./columns-hierarchy.md) - the tree state is
  another slice to capture in `extras`.
- [Architecture](./architecture.md) - which slices live where.
- [Demo #55 State maintenance](https://svgrid.com/#/demos/55-state-maintenance)
  - the reference implementation.

<!-- =================================================================
     /help/state/named-views  (community)
     ================================================================== -->

# Named views

A "view" is a saved snapshot of the grid's state - sort, filters, column
order/width/visibility, page, grouping. Named views let a user save the layout
they like and switch between them. SvGrid ships this as a small manager over
the grid's `getState()` / `setState()`, with pluggable storage.

```svelte
<script lang="ts">
  import { SvGrid, createNamedViews, localStorageViews, type SvGridApi } from 'sv-grid-community'

  let views: ReturnType<typeof createNamedViews> | null = null

  function onApiReady(api: SvGridApi<F, Row>) {
    views = createNamedViews(api, { storage: localStorageViews('my-grid-views') })
  }
</script>

<SvGrid {data} {columns} {features} onApiReady={onApiReady} />

<button onclick={() => views?.save('Top earners')}>Save</button>
<button onclick={() => views?.load('Top earners')}>Restore</button>
```

## The manager API

`createNamedViews(api, { storage })` returns:

| Method            | Does                                                       |
| ----------------- | ---------------------------------------------------------- |
| `list()`          | All saved views, oldest first.                             |
| `save(name)`      | Capture the current state under `name` (overwrites a dup). |
| `load(name)`      | Apply a saved view. Returns `false` if unknown.            |
| `remove(name)`    | Delete a view. Returns `false` if unknown.                 |
| `rename(a, b)`    | Rename, unless `b` already exists.                         |
| `has(name)`       | Whether a view exists.                                     |

It's pure and synchronous - all persistence goes through the storage adapter.

## Storage adapters

- **`localStorageViews(key)`** - persists per browser. SSR-safe (no-ops when
  `localStorage` is unavailable).
- **`memoryViews()`** - in-memory only (the default if you pass no storage).
- **Custom** - implement `ViewStorage` (`read()` / `write(views)`) to sync
  views to a server or a per-user account:

```ts
const serverStorage: ViewStorage = {
  read: () => cachedViews,
  write: (views) => { cachedViews = views; fetch('/api/views', { method: 'PUT', body: JSON.stringify(views) }) },
}
createNamedViews(api, { storage: serverStorage })
```

## Notes

- A view stores whatever `api.getState()` returns; restoring calls
  `api.setState(view.state)`, which applies only the keys present.
- This is the building block; the demo wires a simple save-box + chips UI on
  top, but the manager is headless so you can render views however you like.

See the live [Named views](https://sv-grid.com/demos/143-named-views) demo.

<!-- =================================================================
     /help/status-bar  (community)
     ================================================================== -->

# Status bar

The status bar is the strip under the grid that shows live aggregates of the
**selected cell range** - count, sum, average, min, max - the way Excel does at
the bottom-right when you select a block of numbers.

```svelte
<SvGrid {data} {columns} {features} enableCellSelection statusBar />
```

It needs `enableCellSelection` (the bar aggregates the selected rectangle).
Drag a range across numeric cells and the bar updates instantly.

## Choosing aggregates

`statusBar={true}` shows the default set (`count`, `sum`, `avg`, `min`, `max`).
Pass an object to pick which:

```svelte
<SvGrid enableCellSelection statusBar={{ aggregates: ['count', 'sum', 'avg'] }} />
```

| Aggregate      | Meaning                                              |
| -------------- | ---------------------------------------------------- |
| `count`        | Cells in the selection (non-group).                  |
| `numericCount` | How many of those hold a finite number.              |
| `sum`          | Sum of the numeric cells.                            |
| `avg`          | Mean of the numeric cells.                           |
| `min` / `max`  | Smallest / largest numeric value.                    |

## Behavior

- The numeric aggregates (`sum`, `avg`, `min`, `max`) only appear when the
  selection actually contains numbers - selecting text cells shows just the
  count.
- A single-cell selection shows nothing; the bar appears once a range of two
  or more cells is selected.
- Edited values are respected: the aggregates read the displayed value, so an
  in-progress edit is reflected.
- Group rows are skipped.

See the live [Status bar](https://sv-grid.com/demos/144-status-bar) demo.

<!-- =================================================================
     /help/tailwind  (community)
     ================================================================== -->

# Tailwind integration

SvGrid was built alongside Tailwind v4 (the gallery is the proof). The
two compose cleanly because they have **non-overlapping concerns**:
<div data-docs-demo="10-custom-cells-and-themes" data-height="540"></div>

- Tailwind styles your *page* - controls, buttons, sidebar, modal,
  spacing, typography.
- SvGrid ships its own scoped class names (`.sv-grid-*`) and reads
  every visual value from a small set of CSS custom properties
  (`--sg-*`) - so you re-theme it with **CSS variables**, not Tailwind
  utilities.

You don't put `class="bg-slate-50"` on grid internals. You set
`--sg-bg: theme(colors.slate.50)` once and the grid inherits.

## Install

```bash
pnpm add -D tailwindcss @tailwindcss/postcss autoprefixer postcss
```

`postcss.config.cjs`:

```js
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
    autoprefixer: {},
  },
}
```

`tailwind.config.cjs`:

```js
module.exports = {
  content: ['./index.html', './src/**/*.{ts,svelte}'],
  theme: { extend: {} },
  plugins: [],
}
```

Your global stylesheet (`src/index.css`):

```css
@import 'tailwindcss';

/* See "Dark mode" below - Tailwind's `dark:` follows whatever attribute
 * your app uses for theme. The gallery uses html[data-theme='dark']. */
@custom-variant dark (&:where(html[data-theme='dark'], html[data-theme='dark'] *));
```

That's it - the grid's class names ship as part of the component; you
don't need a Tailwind plugin or a `safelist` entry.

## The theming surface: `--sg-*` custom properties

SvGrid's stylesheet uses CSS custom properties everywhere a colour, a
size, or a hover effect appears. The defaults live in the published
CSS; you override by declaring the variables at any level **above** the
grid (`:root` for the whole app, or on a wrapper `<div>` for one grid
instance).

The full surface (see the gallery's
[`src/index.css`](../../examples/src/index.css) for live values):

| Token | What it paints |
| ----- | -------------- |
| `--sg-bg` | Cell background |
| `--sg-fg` | Cell text |
| `--sg-muted` | Secondary text (footers, subtitles) |
| `--sg-border` | Cell + header borders, scrollbar separators |
| `--sg-header-bg` / `--sg-header-fg` | Header row |
| `--sg-row-alt-bg` | Zebra rows |
| `--sg-row-hover-bg` | Row + cell hover |
| `--sg-row-height` | Row height (read by the wrapper's `rowHeight` prop) |
| `--sg-selection-bg` | Selected cell / row tint |
| `--sg-accent` | Sort indicator, focus ring, primary buttons |
| `--sg-focus-ring` | Keyboard focus outline |
| `--sg-input-bg` / `--sg-input-border` | Inline editor + filter inputs |
| `--sg-pill-active`, `--sg-pill-pending`, `--sg-pill-inactive` (+ `-fg` variants) | Status pills |
| `--sg-scrollbar-*` | The custom-painted scrollbars (10+ tokens for arrow / thumb / hover) |

Tailwind's `theme(...)` works inside these declarations, so you can
keep your design tokens in the Tailwind config and reference them once:

```css
:root {
  --sg-bg:          theme(colors.white);
  --sg-fg:          theme(colors.slate.900);
  --sg-border:      theme(colors.slate.200);
  --sg-header-bg:   theme(colors.slate.100);
  --sg-row-alt-bg:  theme(colors.slate.50);
  --sg-row-hover-bg: theme(colors.indigo.50);
  --sg-accent:      theme(colors.blue.600);
}
```

## Dark mode

The grid is dark-mode-aware by re-declaring the same tokens under a
selector for "dark":

```css
html[data-theme='dark'] {
  --sg-bg:          theme(colors.slate.900);
  --sg-fg:          theme(colors.slate.100);
  --sg-border:      theme(colors.slate.700);
  --sg-header-bg:   theme(colors.slate.800);
  --sg-row-alt-bg:  theme(colors.slate.800);
  --sg-row-hover-bg: theme(colors.slate.700);
  --sg-accent:      theme(colors.blue.400);
  color-scheme: dark;
}
```

The gallery's `App.svelte` writes the active theme into
`document.documentElement.dataset.theme`, and the `@custom-variant`
declaration above makes Tailwind's `dark:` modifier follow the same
attribute. Result: Tailwind utilities and SvGrid tokens flip together.

```svelte
<button class="bg-white dark:bg-slate-900">  <!-- Tailwind -->
  switch theme
</button>
<SvGrid {...props} />  <!-- inherits --sg-* from html[data-theme] -->
```

## Per-instance theming

Because the tokens are CSS custom properties they cascade. To restyle
a single grid, wrap it in a `<div>` that sets its own values:

```svelte
<div style="--sg-bg: #ffffff; --sg-accent: #db2777;">
  <SvGrid {data} {columns} features={features} />
</div>
```

The [`10-custom-cells-and-themes` demo](../../examples/src/demos/10-custom-cells-and-themes.svelte)
shows this pattern with three full palettes (light / dark / high-contrast)
applied via a `style="..."` per the user's pick.

## When you *do* need to override a class

Some things aren't tokens - column-resize handle width, the funnel
button hover opacity, pill paddings. The grid's class names are
deliberately stable so you can target them from your global CSS
(NOT through `@apply` - the grid lives outside the Tailwind
purge pass):

```css
.sv-grid-resize-handle {
  width: 8px;            /* default is 5px */
}

.sv-grid-col-filter-btn {
  opacity: 0;            /* hide funnels unless hovered */
}
.sv-grid-column:hover .sv-grid-col-filter-btn,
.sv-grid-col-filter-btn.is-active {
  opacity: 1;
}

.sv-grid-cell[data-align='right'] {
  font-variant-numeric: tabular-nums;
}
```

Add these rules to your global stylesheet, *after* `@import 'tailwindcss';`,
so Tailwind's preflight + utilities load first and your overrides win
on equal-specificity ties.

## Anti-patterns

**Don't put Tailwind utility classes on the grid's children.** The
default renderer owns those nodes; your classes will get clobbered on
re-render or row-virtualisation recycle. Use the `--sg-*` tokens or
target the stable `.sv-grid-*` class names.

**Don't `@apply` inside grid selectors.** `@apply` reads Tailwind's
preflight scope. Mixed with the grid's component-scoped CSS the
specificity gets weird. Plain property declarations (`background:
theme(colors.slate.50)`) are more predictable.

**Don't fight the column widths in CSS.** Set them in your
`ColumnDef`s. The wrapper uses `style="width: Npx; min-width: Npx;
max-width: Npx;"` and the layout will not respond to a Tailwind utility
on the `<th>`.

## See also

- [Why headless?](../why-headless.md) - the architectural reason the
  theming surface looks like this
- [Getting started](../getting-started.md) - end-to-end gallery setup
- [Styling cells](./cells/styling-cells.md) - cell-level overrides
- [Styling rows](./rows/styling-rows.md) - row-level overrides
- Demo [`10-custom-cells-and-themes`](../../examples/src/demos/10-custom-cells-and-themes.svelte) -
  three palettes applied via `style="--sg-*: ..."`

## Frequently asked questions

### Does SvGrid work with Tailwind CSS?

Yes - it was built alongside Tailwind v4. They compose cleanly because they have
non-overlapping concerns: Tailwind styles your layout and custom cell content,
while the grid's internals are themed through `--sg-*` CSS variables.

### How do I theme or re-skin the grid?

Set the `--sg-*` custom properties - per instance via `style="--sg-bg: ..."` or
globally in your CSS. They control borders, header background, zebra rows, hover,
selection, and density, including dark mode.

### Do I need Tailwind to use SvGrid?

No. The grid ships a default theme and depends only on its own CSS variables.
Tailwind is one convenient way to style around it, not a requirement.

<!-- =================================================================
     /help/testing-and-quality  (community)
     ================================================================== -->

# Testing & Quality

SvGrid ships with a comprehensive automated test suite. This page is the
honest accounting of what we test, what we don't, and where coverage
stands today.

## Headline numbers (v1.0)

> **92.2% line coverage** on the testable surface
> (`pnpm --filter sv-grid-community test:lib`)

| Metric | Coverage | Threshold |
| ------ | -------- | --------- |
| Lines | 92.20% | ≥ 90% |
| Statements | 90.94% | ≥ 90% |
| Branches | 82.21% | ≥ 75% |
| Functions | 82.87% | ≥ 80% |

Run the suite locally:

```bash
pnpm test            # alias for: pnpm --filter sv-grid-community test:lib
pnpm test:types      # svelte-check on every package
```

The full coverage report lands in
`packages/sv-grid-community/coverage/index.html`.

## What's measured

The **testable surface** is the headless engine, helpers, and pure logic
functions:

- `core.ts` (createSvGrid, row models, sortFns, filterFns) - ≥ 89% lines
- `a11y.ts` (ARIA prop builders) - 100% lines
- `keyboard.ts` (intent + next-cell math) - 100% lines
- `cell-formatting.ts` (locale / currency / percent / date helpers) - 100% lines
- `editors/cell-editors.ts` (parseEditorValue for every editor type) - 100% lines
- `filtering/excel-filters.ts` (every Excel-style operator + edge cases) - 100% lines
- `render-component.ts` (renderSnippet / renderComponent factories) - 100% lines
- `subscribe.ts` (store subscription + shallow-compare) - 100% lines
- `virtualization/*` - ≥ 86% lines

## What's measured separately

Two files are tested via **behavioral mount tests** rather than line coverage
because their branches depend on real browser layout (offsetWidth, scroll
dimensions, ResizeObserver fires) that jsdom returns as zero:

- **`SvGrid.svelte`** - the 4000-line render component. Covered by **60+
  behavioral mount tests** across
  [`svgrid.behavior.test.ts`](https://github.com/sv-grid/sv-grid/blob/main/packages/sv-grid-community/src/svgrid.behavior.test.ts),
  [`svgrid.interaction.test.ts`](https://github.com/sv-grid/sv-grid/blob/main/packages/sv-grid-community/src/svgrid.interaction.test.ts),
  and
  [`svgrid.api.test.ts`](https://github.com/sv-grid/sv-grid/blob/main/packages/sv-grid-community/src/svgrid.api.test.ts).
  Each test mounts the real `<SvGrid />` in jsdom and exercises a specific
  feature: sort, filter, pagination, inline editing, cell selection,
  grouping, row selection, column add/remove, keyboard navigation, etc.
- **`sv-grid-scrollbar.ts`** - a custom element that paints scrollbar
  glyphs from layout measurements. Its paint loop runs in a real browser;
  jsdom can't exercise it.

## What's excluded

The coverage report excludes:

- `SvGrid.svelte` (covered behaviorally - see above)
- `FlexRender.svelte` (covered by `flex-render.test.ts` + every SvGrid mount)
- `sv-grid-scrollbar.ts` (custom element)
- `static-functions.ts` (pure re-exports)
- `createGridState.svelte.ts` (downstream-adapter thin layer)
- `test-fixtures/**`, `test-setup.ts`, `**/*.test.ts`, `**/*.d.ts`

The exclusion list is part of `packages/sv-grid-community/vite.config.ts`
and is documented inline with the reasoning for each entry.

## Test files

| File | Surface | Tests |
| ---- | ------- | ----- |
| `createGrid.test.ts` | Headless `createSvGrid` instance | Unit |
| `svgrid.features.test.ts` | Row-model composition (core → filter → sort → group → expand → paginate) | Integration |
| `svgrid.api.test.ts` | The imperative `SvGridApi` exposed via `onApiReady` | Mounted |
| `svgrid.behavior.test.ts` | Wide behavior coverage: 30+ scenarios mounting the real component | Mounted |
| `svgrid.interaction.test.ts` | Keyboard / pointer / scroll / edit events | Mounted |
| `svgrid.wrapper.test.ts` | Source-string safety net | Static |
| `svgrid.features.test.ts` | Feature composition + state hydration | Headless |
| `core.coverage.test.ts` | Row / cell lazy getters, sortFns, filterFns, grouping | Unit |
| `cell-formatting.test.ts` | Locale / currency / percent / date helpers | Unit |
| `subscribe.test.ts` | Store subscription + shallowCompare | Unit |
| `render-component.test.ts` | renderSnippet / renderComponent factories | Unit |
| `flex-render.test.ts` | `<FlexRender />` discriminator (string / fn / config) | Mounted |
| `editors/cell-editors.test.ts` | `parseEditorValue` per editor type | Unit |
| `filtering/excel-filters.test.ts` | Every operator + every edge case | Unit |
| `keyboard.test.ts` | `getKeyboardIntent` / `getNextActiveCell` | Pure unit |
| `a11y.test.ts`, `a11y.contract.test.ts` | ARIA prop builders + contract | Pure unit |
| `core.performance.test.ts` | Engine performance under large row counts | Benchmark |

Total: **168 tests** across **14 test files**.

## Quality controls beyond unit tests

- **TypeScript strict mode** across both packages. `pnpm test:types`
  must pass on every PR (currently 0 errors / 0 warnings).
- **ESLint** at `pnpm lint`, with the Svelte plugin.
- **Publint** at `pnpm --filter sv-grid-community test:build` checks the
  published `exports` map.
- **CSP-strict runtime**: no `eval`, no `new Function`, no inline scripts.
  Demo `16-csp-compliant` includes a runtime self-check.
- **SSR snapshot**: demo `19-ssr` proves the grid renders meaningful HTML
  before hydration.
- **Accessibility contracts**: `a11y.contract.test.ts` asserts that root,
  row, header, and cell prop builders produce a consistent ARIA tree.
- **Mount-based behavioral tests** mount the real `<SvGrid />` in jsdom
  with polyfilled `ResizeObserver` / `IntersectionObserver` / `scrollIntoView`
  and exercise the imperative API end-to-end.

## How to contribute a test

1. Pick a behavior you want to lock down. Bias toward
   *"user does X, grid does Y"* over *"function Z returns W"*.
2. If the behavior involves the rendered DOM, mount the component using
   the pattern in `svgrid.api.test.ts`:
   ```ts
   import { mount, unmount } from 'svelte'
   import SvGrid from './SvGrid.svelte'

   const target = document.createElement('div')
   document.body.appendChild(target)
   const app = mount(SvGrid, {
     target,
     props: { data, columns, features, onApiReady: (a) => { api = a } },
   })
   // exercise + assert
   unmount(app)
   ```
3. If the behavior is pure (a row model, a sort comparator, an a11y prop
   builder), add to one of the existing unit-test files.
4. Run `pnpm --filter sv-grid-community exec vitest run <file>` to iterate
   fast.
5. Open the PR; include the before/after coverage delta in the description.

## CI

The deploy workflow (`.github/workflows/deploy-website.yml`) currently
builds the library and the website. The next step is to add a
**Test workflow** that runs `pnpm test` + `pnpm test:types` on every PR
and posts the coverage delta as a comment.

<!-- =================================================================
     /help/testing  (community)
     ================================================================== -->

# Testing your grid

How to write tests that catch regressions before they ship. SvGrid is
designed for both **fast unit tests** (Layer 2, the headless engine,
runs in pure node) and **slow but accurate browser tests** (Layer 3,
the `<SvGrid>` component, needs a real DOM or jsdom).

## Test pyramid for a grid app

```
                /─────────────\
               /  Playwright   \   slow,   ~5-15 / page
              /    end-to-end   \  accurate
             /───────────────────\
            /  jsdom + svelte-    \
           /   testing-library     \ ~15-60 / file
          /    component tests      \
         /───────────────────────────\
        /     vitest engine tests     \   fast,   ~50-200 / file
       /     (Layer 2, no DOM, pure)   \  pure JS
      /─────────────────────────────────\
```

You want a wide base of fast tests (the engine surface), a narrower
middle layer of component tests (mount + interact with the renderer),
and a small top layer of e2e tests for the journeys that actually
matter to your users.

## Engine tests (Layer 2, vitest)

Every helper in `sv-grid-community` is a pure function. Test them
without a DOM.

```ts
import { describe, it, expect } from 'vitest'
import { createSvGrid, tableFeatures, rowSortingFeature } from 'sv-grid-community'

describe('sort behaviour', () => {
  it('sorts by a single column ascending', () => {
    type Row = { id: number; name: string }
    const features = tableFeatures({ rowSortingFeature })
    const grid = createSvGrid<typeof features, Row>({
      data: [
        { id: 1, name: 'Charlie' },
        { id: 2, name: 'Alice' },
        { id: 3, name: 'Bob' },
      ],
      columns: [
        { field: 'id', header: 'ID' },
        { field: 'name', header: 'Name' },
      ],
      _features: features,
    })
    grid.setSort([{ id: 'name', desc: false }])
    const visible = grid.getRowModel().rows.map((r) => r.original.name)
    expect(visible).toEqual(['Alice', 'Bob', 'Charlie'])
  })
})
```

Engine tests run at ~10k assertions/second on a modern laptop. The
`sv-grid-community` package itself ships [hundreds of these](https://github.com/sv-grid/sv-grid/tree/main/packages/sv-grid-community/src) -
you can model yours after them.

## Pro feature tests (vitest + jsdom)

The Pro helpers need `jsdom` because `importData` calls `Blob.text()`
and `exportData` builds an `<a download>`. Set vitest's `environment`
to `'jsdom'` for these files.

```ts
import { describe, it, expect, beforeEach } from 'vitest'
import { importData, setLicenseKey } from 'sv-grid-pro'

beforeEach(() => setLicenseKey('SVPRO-DEV-TEST'))

describe('CSV import', () => {
  it('parses, coerces types, and rejects negative prices', async () => {
    const csv = 'id,price\n1,-5\n2,10\n'
    const fakeApi = makeFakeApi()       // see below
    const result = await importData(fakeApi, {
      file: csv,
      format: 'csv',
      validator: (row) => row.price < 0
        ? [{ field: 'price', message: 'must be >= 0' }]
        : [],
    })
    expect(result.rows).toHaveLength(2)
    expect(result.errors).toHaveLength(1)
    expect(result.errors[0].rowIndex).toBe(0)
  })
})
```

The 48-test suite in `packages/sv-grid-pro/src/*.test.ts` shows the
full pattern, including a `fakeApi` stub you can copy.

## Component tests (svelte-testing-library + jsdom)

For "does the grid actually render the rows", mount the `<SvGrid>`
component in jsdom:

```ts
import { render } from '@testing-library/svelte'
import { describe, it, expect } from 'vitest'
import { SvGrid, tableFeatures, rowSortingFeature, type ColumnDef } from 'sv-grid-community'

type Row = { id: number; name: string }

const features = tableFeatures({ rowSortingFeature })
const columns: ColumnDef<typeof features, Row>[] = [
  { field: 'id',   header: 'ID' },
  { field: 'name', header: 'Name' },
]

describe('<SvGrid>', () => {
  it('renders one row per data entry', () => {
    const { container } = render(SvGrid, {
      props: {
        data: [{ id: 1, name: 'Ada' }, { id: 2, name: 'Linus' }],
        columns,
        features,
      },
    })
    const bodyRows = container.querySelectorAll('tbody tr')
    expect(bodyRows.length).toBe(2)
  })
})
```

A few caveats:

- **Vitest config:** `environment: 'jsdom'` plus
  `resolve.conditions: ['browser']` so vitest picks Svelte's client
  build. The `sv-grid-community` repo's `vite.config.ts` shows the
  exact knobs.
- **No virtualization in jsdom.** jsdom returns `0` for every layout
  metric, so the row virtualizer never advances. Test on small
  datasets (< 50 rows) at this layer; push virtualization tests to
  Playwright.
- **No clipboard.** `document.execCommand('copy')` is a no-op in
  jsdom; if you're testing copy/paste, mock the clipboard or skip
  to Playwright.

## End-to-end (Playwright)

For real-DOM behaviours: virtualization, scroll-driven chunk loading,
focus traps, clipboard, the `<SvGrid>`'s `ResizeObserver`-driven
layout.

```ts
import { test, expect } from '@playwright/test'

test('Sort + filter + paginate together', async ({ page }) => {
  await page.goto('http://localhost:5180/#/demos/02-sort-filter-paginate')
  // Sort by Customer
  await page.locator('thead th', { hasText: 'Customer' }).click()
  // First row should now be alphabetically first.
  const first = await page.locator('tbody tr').first().textContent()
  expect(first?.startsWith('A')).toBe(true)
  // Apply a filter
  await page.locator('thead th', { hasText: 'Region' }).locator('button[aria-label*=Filter]').click()
  await page.locator('.sv-grid-menu-option', { hasText: 'EMEA' }).click()
  // Row count drops
  const visible = await page.locator('tbody tr').count()
  expect(visible).toBeLessThan(50)
})
```

The 53-demo gallery is the easiest target for e2e: every demo is a
URL you can navigate, every behaviour is reachable from the keyboard.
Mirror your in-app test flows against a paired demo first; it surfaces
bugs at the API layer before they hit your app's code.

## Accessibility regression tests

Wrap [axe-core](https://github.com/dequelabs/axe-core) into your
Playwright suite to catch contrast / role / label regressions on every
commit:

```ts
import { test, expect } from '@playwright/test'
import { injectAxe, checkA11y } from 'axe-playwright'

test('a11y: quick-start grid', async ({ page }) => {
  await page.goto('http://localhost:5180/#/demos/01-quick-start')
  await injectAxe(page)
  await checkA11y(page, '.sv-grid-shell', {
    detailedReport: false,
    axeOptions: {
      runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa'] },
    },
  })
})
```

The grid passes axe's WCAG 2.1 AA rules at the default theme; if your
custom theme breaks contrast, this test fails immediately.

## Visual regression

For the small set of pixels that matter (header bar height, focus ring
width, the "selected row" highlight), Playwright's `toHaveScreenshot()`
is a good fit:

```ts
test('focused cell matches the design system ring', async ({ page }) => {
  await page.goto('http://localhost:5180/#/demos/01-quick-start')
  await page.locator('tbody tr').first().locator('td').first().click()
  await expect(page.locator('.sv-grid-cell-active')).toHaveScreenshot('active-cell.png')
})
```

Pin the screenshot to a tight selector and a 1x device-pixel-ratio so
your team's various GPUs don't churn the baseline.

## Performance regression

The benchmark script (`pnpm bench`) is meant to be run on every release.
For your own app, capture two numbers in CI:

1. **Time to first paint** on your largest grid - run a Playwright
   trace, look at the timing of the first `tbody tr` appearing.
2. **Sustained scroll p95 frame time** - use Playwright's
   `page.evaluate(() => performance.timing)` or the Chrome DevTools
   protocol's `Performance.getMetrics`.

Both can fail your CI with a 10% deviation threshold. See
[Performance benchmarks](./benchmarks.md) for the documented numbers
on the published package.

## Test data fixtures

A common pitfall: ad-hoc test rows that drift across tests until
nothing reuses them.

```ts
// tests/fixtures/orders.ts
export function makeOrder(overrides: Partial<Order> = {}): Order {
  return {
    id: 1,
    customer: 'Acme',
    total: 100,
    placedAt: '2024-01-01',
    status: 'pending',
    ...overrides,
  }
}
```

Every test uses `makeOrder()` with the diffs it cares about. When the
domain shape changes, ONE fixture changes, not 200 tests.

## What NOT to do

- **Don't grep DOM classes.** `.sv-grid-cell-active` is implementation
  detail (see [API stability](./api-stability.md)). Tests against it
  break on minor releases. Prefer `aria-selected="true"` or a custom
  `data-testid`.
- **Don't snapshot the entire rendered HTML.** Internal markup changes
  per release; snapshots become churn. Snapshot small specific
  fragments instead.
- **Don't test the framework.** SvGrid is well-tested at the package
  level; you don't need to verify that "click on a sort header sorts".
  Test YOUR business rules - "rejected orders never appear in the
  active queue".

## See also

- [API stability](./api-stability.md) - what's safe to assert against.
- [Architecture overview](./architecture.md) - which layer to test at.
- [Performance benchmarks](./benchmarks.md) - reference numbers you
  can use as CI thresholds.
- [Accessibility](./accessibility.md) - the a11y contract these tests
  enforce.

<!-- =================================================================
     /help/tokens  (community)
     ================================================================== -->

# Design tokens

Every visual property the grid exposes for theming is a CSS custom
property (`--sg-*`). Tokens cascade like any other CSS variable -
override at `:root`, on a wrapper element, or per-grid; the closest
declaration wins.
<div data-docs-demo="74-theme-integrations" data-height="540"></div>

> No build step. No theme provider. No design-system lock-in. Set a
> few `--sg-*` tokens and the grid re-skins immediately.

Live in [demo 74 (Theme integrations)](https://svgrid.com/#/demos/74-theme-integrations)
- shows the same grid rendered through Ant Design, MUI, Fluent, Base
Web, and shadcn token sets.

## Core surface tokens

These are the tokens 95% of integrations override. Stable; safe to
ship in a corporate design system.

| Token                  | Default (light)        | Default (dark)         | What it paints                                                       |
| ---------------------- | ---------------------- | ---------------------- | -------------------------------------------------------------------- |
| `--sg-bg`              | `#ffffff`              | `#0f172a`              | Grid background / cell fill                                          |
| `--sg-fg`              | `#0f172a`              | `#f1f5f9`              | Primary text colour                                                  |
| `--sg-muted`           | `#64748b`              | `#94a3b8`              | Secondary text (header subtitles, placeholders, "no data" message)   |
| `--sg-border`          | `#e2e8f0`              | `#1e293b`              | Cell borders, separators                                             |
| `--sg-header-bg`       | `#f8fafc`              | `#1e293b`              | Column-header row background                                         |
| `--sg-header-fg`       | inherits `--sg-fg`     | inherits `--sg-fg`     | Column-header text                                                   |
| `--sg-row-alt-bg`      | inherits `--sg-bg`     | inherits `--sg-bg`     | Zebra-stripe background for even-indexed rows                        |
| `--sg-row-hover-bg`    | `rgba(148,163,184,.10)`| `rgba(148,163,184,.14)`| Hover row background                                                 |
| `--sg-selection-bg`    | `rgba(99,102,241,.10)` | `rgba(99,102,241,.18)` | Selected row / selected cell-range fill                              |
| `--sg-accent`          | `#6366f1`              | `#818cf8`              | Active-cell ring, primary buttons, sort indicator                    |
| `--sg-focus-ring`      | `0 0 0 2px rgba(99,102,241,.40)` | same | Box-shadow used for the focus outline                                |

## Layout tokens

| Token                  | Default     | What it controls                                                       |
| ---------------------- | ----------- | ---------------------------------------------------------------------- |
| `--sg-row-height`      | `32px`      | Default row height. Per-grid override via the `rowHeight` prop wins.    |
| `--sg-radius`          | `6px`       | Border radius on rounded UI inside the grid (chips, badges, menus)      |
| `--sg-font`            | inherits    | Font family used inside the grid                                        |

## Pinned-column tokens

| Token                  | Default     | What it paints                                                         |
| ---------------------- | ----------- | ---------------------------------------------------------------------- |
| `--sg-pinned-bg`       | inherits `--sg-bg` | Pinned-column cell background (must be opaque to cover scroll under) |
| `--sg-pinned-header-bg`| inherits `--sg-header-bg` | Pinned-column header background                              |
| `--sg-pinned-divider`  | `#cbd5e1`   | 2px separator between pinned and scrolling region                      |

## Input + form tokens

| Token                  | Default                | What it paints                                                       |
| ---------------------- | ---------------------- | -------------------------------------------------------------------- |
| `--sg-input-bg`        | inherits `--sg-bg`     | Cell-editor `<input>` background                                     |
| `--sg-input-border`    | inherits `--sg-border` | Cell-editor border                                                   |
| `--sg-rating-on`       | `#f59e0b`              | Filled star colour in the rating editor                              |
| `--sg-rating-empty`    | `#cbd5e1`              | Empty star colour                                                    |
| `--sg-rating-hover`    | `#fbbf24`              | Star hover-state colour                                              |

## Scrollbar tokens

The grid uses a custom scrollbar so it looks consistent across OSes.

| Token                            | Default     |
| -------------------------------- | ----------- |
| `--sg-scrollbar-bg`              | `transparent` |
| `--sg-scrollbar-border`          | inherits `--sg-border` |
| `--sg-scrollbar-thumb`           | `rgba(148,163,184,.45)` |
| `--sg-scrollbar-thumb-hover`     | `rgba(148,163,184,.65)` |
| `--sg-scrollbar-thumb-active`    | `rgba(148,163,184,.85)` |
| `--sg-scrollbar-arrow`           | inherits `--sg-muted` |
| `--sg-scrollbar-arrow-hover`     | inherits `--sg-fg` |
| `--sg-scrollbar-arrow-hover-bg`  | inherits `--sg-row-hover-bg` |
| `--sg-scrollbar-arrow-active`    | inherits `--sg-accent` |
| `--sg-scrollbar-arrow-active-bg` | inherits `--sg-row-hover-bg` |
| `--sg-scrollbar-arrow-disabled`  | `rgba(148,163,184,.35)` |

## Pill / status tokens (gallery-defined)

These are used by several demos but live in the gallery, not the
library. Copy if you want the same convention; rename freely otherwise.

| Token                       | Used for                                |
| --------------------------- | --------------------------------------- |
| `--sg-pill-active`          | "Active" status chip background         |
| `--sg-pill-active-fg`       | "Active" status chip text               |
| `--sg-pill-pending`         | "Pending" status chip background        |
| `--sg-pill-pending-fg`      | "Pending" status chip text              |
| `--sg-pill-inactive`        | "Inactive" status chip background       |
| `--sg-pill-inactive-fg`     | "Inactive" status chip text             |

## How to override

### Globally (your app's stylesheet)

```css
:root {
  --sg-accent: #db2777;          /* hot pink everywhere */
  --sg-row-height: 36px;
  --sg-font: 'Inter', sans-serif;
}
```

### Per-grid (Tailwind / inline style)

```svelte
<div class="my-grid" style="--sg-accent: #16a34a">
  <SvGrid {data} {columns} features={features} />
</div>
```

### Dark mode

The library doesn't ship a built-in dark theme - it reads whatever
your app provides. Most apps gate via `[data-theme="dark"]` on
`<html>`; sv-grid's only requirement is that you override the same
token set under that selector:

```css
[data-theme="dark"] {
  --sg-bg:           #0f172a;
  --sg-fg:           #f1f5f9;
  --sg-border:       #1e293b;
  --sg-header-bg:    #1e293b;
  --sg-row-hover-bg: rgba(148, 163, 184, 0.14);
  --sg-selection-bg: rgba(99, 102, 241, 0.18);
}
```

Theme presets ship in
[demo 74](https://svgrid.com/#/demos/74-theme-integrations) for Ant
Design, MUI, Fluent, Base Web, and shadcn - each with a light AND a
dark token bundle ready to copy.

## Stability promise

Core surface tokens (the first table) are **stable**: they will not
be renamed or removed in a minor version. New tokens may be added.
See [API stability](./api-stability.md) for the full policy.

Layout / pinned / scrollbar / input tokens follow the same promise.

Pill tokens are gallery-defined - the LIBRARY makes no promise about
them.

## See also

- [Tailwind integration](./tailwind.md) - how to wire tokens through
  Tailwind's theming layer
- [Custom cells + themes](https://svgrid.com/#/demos/10-custom-cells-and-themes) demo - the canonical token-override example
- [Theme integrations](https://svgrid.com/#/demos/74-theme-integrations) demo - five design-system presets side by side

<!-- =================================================================
     /help/versioning  (community)
     ================================================================== -->

# Doc versioning

How sv-grid documentation tracks multiple shipping major versions.

## Today (single-version mode)

While v1 is the only major in support, the docs at
[svgrid.com](https://svgrid.com) describe v1. The
[`versions.json`](/versions.json) manifest at the docs root says so
explicitly so external tools (LLM crawlers, custom search indexes,
the [MCP server](./mcp-server.md)) can ground themselves on which
version they're reading.

```json
{
  "versions": [
    { "id": "latest", "label": "v1 (current)", "tag": "1.x", "default": true, "docsPath": "/" }
  ]
}
```

## When v2 ships

The day v2.0.0 publishes:

1. **Snapshot v1.** Copy `docs/` → `docs/v1/` in the same PR that
   publishes v2.
2. **Update the manifest.**
   ```json
   {
     "versions": [
       { "id": "latest", "label": "v2 (current)", "tag": "2.x", "default": true, "docsPath": "/" },
       { "id": "v1",     "label": "v1 (LTS)",    "tag": "1.x", "supportUntil": "2027-06-01", "docsPath": "/v1/" }
     ]
   }
   ```
3. **Add a version switcher** to the docs sidebar. Reads
   `/versions.json`; renders a dropdown that swaps the URL prefix.
4. **Add a banner** to every page under `/v1/` linking to the
   matching `/` page in v2 (when one exists) + the migration guide.
5. **Update `llms.txt` + `docs.json`** to default to v2 but list v1
   under a separate section so models grounded against v1 can still
   resolve URLs.

## Long-term support window

Per [api-stability](./api-stability.md):

- The **current major** is fully supported (features + fixes +
  security patches)
- The **previous major** receives **security patches for 12 months**
  after the next-major ships
- Older majors are unsupported

Enterprise Pro customers may extend LTS - see
[Pro support](../pro/support.md).

## Why we don't ship every version separately

Most teams pin to a specific minor and read the docs that match. A
URL like `/v1.6.3/help/pivot.md` would just be extra surface to
maintain - and old text we can't easily fix.

The promise: every shipping major has its own URL prefix and stays
reachable for the LTS window. We don't archive per-minor.

## See also

- [API stability](./api-stability.md) - the semver + deprecation policy
- [Changelog](../changelog.md) - Keep-a-Changelog format with one section per release
- [`versions.json`](/versions.json) - the machine-readable manifest agents and crawlers consume

<!-- =================================================================
     /help/web-components  (community)
     ================================================================== -->

# Web Components & Custom Elements

Ship SvGrid as a framework-agnostic web component (custom element) and use
the Svelte 5 data grid in React, Vue, Angular, or plain HTML - no Svelte
required in the host app.

SvGrid is authored in Svelte 5, but Svelte compiles to standards-based
[custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components).
That means you can wrap `<SvGrid>` once, build it to a single `.js` file, and
drop `<sv-grid>` into any page or framework - the same way you'd use a native
HTML element. If you searched for a "web component data grid" or a
"framework-agnostic Svelte table," this is the integration path.

## Why a custom element

- **Use it anywhere.** React, Vue, Angular, Solid, Astro, Rails/Laravel
  server-rendered pages, or a plain `<script>` tag. The browser treats
  `<sv-grid>` like any built-in element.
- **One bundle, no framework lock-in.** Ship a single file to a CDN; consumers
  add one `<script type="module">` and a tag.
- **Same engine.** The custom element wraps the real grid - virtualization,
  Excel-style filters, inline editing, grouping, sorting, pagination all come
  along.

If your team *is* on Svelte 5, use the component directly
([First grid](../getting-started/2-first-grid.md)) - the custom element only
exists to reach non-Svelte hosts.

## Quick start (no build)

We publish a prebuilt, self-contained element as
[`sv-grid-wc`](https://www.npmjs.com/package/sv-grid-wc). Drop it in from a CDN
and you're done - no bundler, no Svelte in your app:

```html
<script type="module" src="https://unpkg.com/sv-grid-wc"></script>

<sv-grid id="grid" sortable filterable style="display:block;height:420px"></sv-grid>

<script type="module">
  const grid = document.getElementById('grid')
  grid.columns = [{ field: 'name', header: 'Name' }, { field: 'role', header: 'Role' }]
  grid.data = [{ name: 'Ada', role: 'Engineering' }, { name: 'Alan', role: 'Research' }]
</script>
```

Or via npm:

```bash
npm install sv-grid-wc
```

```js
import 'sv-grid-wc' // registers <sv-grid> globally
```

The rest of this page shows how that package is built, so you can fork it,
trim it, or extend the attribute surface for your own element.

## 1. The wrapper component

Create one Svelte file that declares the custom element and maps its
properties onto `<SvGrid>`. Complex inputs (`data`, `columns`) are passed as
JavaScript **properties**; simple toggles are exposed as **attributes**.

```svelte
<!-- src/sv-grid-element.svelte -->
<svelte:options
  customElement={{
    tag: 'sv-grid',
    shadow: 'none',
    props: {
      data: { type: 'Array' },
      columns: { type: 'Array' },
      sortable: { type: 'Boolean', attribute: 'sortable' },
      filterable: { type: 'Boolean', attribute: 'filterable' },
      selectable: { type: 'Boolean', attribute: 'selectable' },
      editable: { type: 'Boolean', attribute: 'editable' },
      rowHeight: { type: 'Number', attribute: 'row-height' },
    },
  }}
/>

<script lang="ts">
  import {
    SvGrid,
    tableFeatures,
    rowSortingFeature,
    columnFilteringFeature,
    rowSelectionFeature,
  } from 'sv-grid-community'

  let {
    data = [],
    columns = [],
    sortable = true,
    filterable = true,
    selectable = false,
    editable = false,
    rowHeight = 36,
  } = $props()

  // Build the feature set from the boolean attributes.
  const features = $derived(
    tableFeatures({
      ...(sortable ? { rowSortingFeature } : {}),
      ...(filterable ? { columnFilteringFeature } : {}),
      ...(selectable ? { rowSelectionFeature } : {}),
    }),
  )

  // Re-emit grid callbacks as DOM CustomEvents so non-Svelte hosts can listen
  // with addEventListener('rowclick', ...). $host() is the custom element.
  function emit(name: string, detail: unknown) {
    $host().dispatchEvent(new CustomEvent(name, { detail, bubbles: true, composed: true }))
  }
</script>

<div style="height: 100%; min-height: 320px;">
  <SvGrid
    {data}
    {columns}
    features={features}
    filterMode="menu"
    selectionMode="row"
    showRowSelection={selectable}
    enableInlineEditing={editable}
    {rowHeight}
    containerHeight="100%"
    fitColumns={true}
    onRowClick={(e) => emit('rowclick', e.row)}
    onRowSelectionChange={(_e, sel) => emit('selectionchange', sel)}
  />
</div>
```

`shadow: 'none'` keeps the grid in the light DOM so your page's CSS custom
properties (`--sg-*`) theme it normally. See
[Styling](#styling-and-shadow-dom) for the trade-offs.

## 2. Build it to a single file

Enable custom-element compilation **only** for the wrapper (compiling every
component as a custom element would break the internal grid). With
`@sveltejs/vite-plugin-svelte`:

```js
// vite.config.js
import { defineConfig } from 'vite'
import { svelte } from '@sveltejs/vite-plugin-svelte'

export default defineConfig({
  plugins: [
    svelte({
      // Compile ONLY the wrapper as a custom element.
      dynamicCompileOptions({ filename }) {
        if (filename.endsWith('sv-grid-element.svelte')) {
          return { customElement: true }
        }
      },
    }),
  ],
  build: {
    lib: {
      entry: 'src/sv-grid-element.svelte',
      formats: ['es'],
      fileName: 'sv-grid-element',
    },
  },
})
```

```bash
npm run build   # -> dist/sv-grid-element.js
```

Host the resulting `dist/sv-grid-element.js` on your own server or a CDN.

## 3. Use it in plain HTML

```html
<script type="module" src="/sv-grid-element.js"></script>

<sv-grid id="grid" sortable filterable style="display:block;height:420px"></sv-grid>

<script type="module">
  const grid = document.getElementById('grid')
  // Arrays/objects are set as properties, not attributes:
  grid.columns = [
    { field: 'name', header: 'Name', editorType: 'text', width: 200 },
    { field: 'role', header: 'Role', width: 160 },
    { field: 'salary', header: 'Salary', align: 'right',
      format: { type: 'currency', currency: 'USD' } },
  ]
  grid.data = [
    { name: 'Ada Lovelace', role: 'Engineering', salary: 145000 },
    { name: 'Alan Turing', role: 'Research', salary: 160000 },
  ]
  grid.addEventListener('rowclick', (e) => console.log('clicked row', e.detail))
</script>
```

## 4. Use it in React, Vue, Angular

The element is registered globally once you import the bundle. Each framework
passes object props slightly differently:

**React 19+** passes objects/arrays to custom elements directly:

```jsx
import '/sv-grid-element.js'

export function Grid({ rows, columns }) {
  return <sv-grid sortable filterable .data={rows} .columns={columns} />
}
```

On React 18 and earlier, set the properties via a `ref` instead
(`ref.current.data = rows`), since older React serializes props to attributes.

**Vue 3** - bind as a property with `.prop`, and tell Vue it's a custom
element (`compilerOptions.isCustomElement` / `app.config` for `sv-`):

```vue
<sv-grid sortable filterable :data.prop="rows" :columns.prop="columns" />
```

**Angular** - add `CUSTOM_ELEMENTS_SCHEMA` to the module/component, then bind
properties:

```html
<sv-grid [data]="rows" [columns]="columns" sortable filterable></sv-grid>
```

## Styling and shadow DOM

| Mode | What happens | When to use |
| --- | --- | --- |
| `shadow: 'none'` (recommended) | Grid renders in the light DOM. Page CSS and `--sg-*` theme tokens apply normally. | Almost always - a data grid wants to inherit your app theme. |
| `shadow: 'open'` (Svelte default) | Grid is encapsulated in a shadow root. Set `--sg-*` tokens on the `sv-grid` host; outside CSS won't leak in. | Strict style isolation / embedding in third-party pages. |

Theme either mode with the same custom properties:

```css
sv-grid {
  --sg-bg: #fff;
  --sg-header-bg: #f8fafc;
  --sg-border: #e2e8f0;
}
```

See [Tailwind integration](./tailwind.md) for the full `--sg-*` token list.

## Events

The wrapper above re-emits grid callbacks as DOM `CustomEvent`s, so any host
listens the standard way:

```js
grid.addEventListener('rowclick', (e) => { /* e.detail = the row */ })
grid.addEventListener('selectionchange', (e) => { /* e.detail = selected rows */ })
```

Add more by calling `emit('yourevent', detail)` from any SvGrid callback.

## Caveats

- **Objects go through properties, not attributes.** `data` and `columns` are
  arrays - set `el.data = [...]`, not `data="..."`. Only primitive toggles
  (`sortable`, `row-height`) work as HTML attributes.
- **Custom cell snippets** (`renderSnippet`) are a Svelte authoring feature.
  Across the custom-element boundary, prefer column `format` options and
  `accessorFn` for display, or build the snippet logic inside the wrapper.
- **Bundle size.** The custom element ships the grid plus the Svelte runtime in
  one file. That's expected for a self-contained drop-in element; native Svelte
  consumers share the runtime and ship less.
- **Pro features.** `installPro` works the same inside the wrapper - import it
  and augment the api in `onApiReady`. The license check is unchanged.

## Frequently asked questions

### Can I use SvGrid without Svelte?

Yes. Compile it to a custom element (web component) and use `<sv-grid>` in
React, Vue, Angular, or plain HTML. The host app does not need Svelte
installed - the element ships the runtime inside its own bundle.

### Does SvGrid work as a web component / custom element?

Yes. Svelte 5 compiles components to standards-based custom elements. Wrap
`<SvGrid>` in a file with `<svelte:options customElement="sv-grid">`, build it
to a single `.js`, and register `<sv-grid>` globally.

### How do I use SvGrid in React, Vue, or Angular?

Build the custom element, import the bundle once, then render `<sv-grid>` and
set `data` / `columns` as properties. React 19, Vue (`:data.prop`), and Angular
(`CUSTOM_ELEMENTS_SCHEMA`) all support binding object properties to custom
elements.

### Should I use shadow DOM?

For a data grid, usually no - build with `shadow: 'none'` so your app's CSS and
`--sg-*` theme tokens apply. Use shadow DOM only when you need strict style
isolation.

### How do I pass columns and data to the `<sv-grid>` element?

As JavaScript properties: `el.columns = [...]; el.data = [...]`. HTML
attributes only carry strings, so arrays and objects must be set on the element
instance.

## See also

- [First grid](../getting-started/2-first-grid.md) - using SvGrid directly in Svelte
- [Starters & scaffolding](../getting-started/starters.md) - `npm create sv-grid`
- [Tailwind integration](./tailwind.md) - the `--sg-*` theme tokens
- [Architecture](./architecture.md) - headless core vs. render component

<!-- =================================================================
     /pro/evaluation  (pro)
     ================================================================== -->

# Pro evaluation

The `sv-grid-pro` package is soft-gated; you can evaluate every
feature in production-equivalent code paths without contacting
sales. This page is the playbook.

## Step 1: Install

```bash
pnpm add sv-grid-pro
# Add the peers for the features you want to evaluate:
pnpm add jszip          # xlsx export/import
pnpm add pdfmake        # pdf export
```

`jszip` and `pdfmake` are lazy-loaded by sv-grid-pro - they're only
required if you actually invoke the matching feature.

## Step 2: Install the evaluation key

```ts
import { setLicenseKey } from 'sv-grid-pro'
setLicenseKey('SVPRO-DEV-DEMO')
```

This suppresses the watermark in local dev. **For staging /
production evaluation, request an evaluation key** at
[svgrid.com/evaluate](https://svgrid.com/evaluate) - it's a one-form
request, no sales call, key arrives in ~10 minutes.

The evaluation key is a real key with a 30-day expiry. Behaves
identically to a paid license; lets you ship internal staging /
demo deployments to evaluators without the watermark.

### What unlicensed looks like

With no key set, Pro stays fully functional but nudges you:

- A small **"www.svgrid.com" watermark** in the corner of each grid
  (fades after 5 seconds).
- The first time you actually invoke a Pro feature (export, import,
  print, AI), a one-time **upgrade card** appears in the bottom-right
  naming that feature, with a one-click link to start a free trial. It
  shows at most once per session.

Both are pure DOM - **no network calls, no cookies, no web storage**
(see [security](../help/security.md)). `setLicenseKey()` with any
valid key suppresses them before they appear. To remove the upgrade
card programmatically (e.g. you render your own upgrade UI), call:

```ts
import { dismissUpgradePrompt } from 'sv-grid-pro'
dismissUpgradePrompt()
```

## Step 3: Wire up

```svelte
<script lang="ts">
  import { SvGrid, type SvGridApi } from 'sv-grid-community'
  import { installPro, type ProGridApi } from 'sv-grid-pro'

  let api = $state<ProGridApi<typeof features, Order> | null>(null)
</script>

<SvGrid
  data={rows} columns={columns} features={features}
  onApiReady={(next: SvGridApi<typeof features, Order>) => {
    api = installPro(next)
  }}
/>

<button onclick={() => api?.exportData({ format: 'xlsx' })}>Export</button>
```

That's the integration. The Community grid is unchanged; Pro
augments the api object.

## Step 4: Try the features (30-min tour)

| Feature | One-line evaluation                                                  |
| ------- | -------------------------------------------------------------------- |
| Export  | `api.exportData({ format: 'xlsx', filename: 'data' })`                |
| Pivot   | `const pivot = createPivotModel(rows, { rows: ['region'], cols: ['quarter'], values: [{ field: 'amount', agg: 'sum' }] })` |
| Import  | `<input type="file" onchange={(e) => api.importData({ file: e.target.files[0] }).then(r => api.addRows(r.rows))}>` |
| AI      | `setAIProvider(yourAdapter); const plan = await api.ai.filter('show last quarter > $10k')` |

Each Pro feature has a fully-working demo in the gallery
([56-60 + 51 + 52 + 53](https://svgrid.com/#/demos)) that you can
read end-to-end.

## Step 5: Performance + budget check

Bundle sizes (gzip):

| Surface         | Size  | Notes                              |
| --------------- | ----- | ---------------------------------- |
| Community only  | 49 kB | Renderer + engine                  |
| + Pro export    | +12 kB| + `jszip` peer when xlsx is used   |
| + Pro pdf       | +90 kB| + `pdfmake` peer when pdf is used  |
| + Pro pivot     | +6 kB | Pure TS, no peers                  |
| + Pro AI        | +4 kB | You bring the model client         |
| + Pro import    | +5 kB | + `jszip` for xlsx import          |

Subpath imports (`sv-grid-pro/export`, `sv-grid-pro/pivot`, etc.)
ensure you only pay for what you use.

## Step 6: Decide

- Shipping one production app? **Single Application Developer License**
  ($599 per developer).
- Shipping multiple apps across your org? **Multiple Application
  Developer License** ($999 per developer).
- Large team (5+), multi-year, NDA, or PO? **Enterprise / volume**
  (contact sales).

Each is a perpetual license + 1 year of updates and support that renews
automatically; cancel anytime.

[Full pricing](https://svgrid.com/pricing).

## Migrating from another grid mid-evaluation

If you're swapping out AG Grid / TanStack Table / MUI X / Handsontable
/ Glide, see the [migration guides](../help/migrating-from-ag-grid.md)
- typically a half-day port for a 5-grid app.

## See also

- [Pro licensing](./licensing.md) - what each tier covers
- [Pro support](./support.md) - what you get with each tier
- [Missing features](../help/missing-features.md) - the honest gap list

<!-- =================================================================
     /pro/licensing  (pro)
     ================================================================== -->

# Pro licensing

The `sv-grid-pro` package is **soft-gated**: every feature runs
without a key, with a small unlicensed-build watermark in the
bottom-right corner of the grid + a one-time console nudge. Set a
key once at app startup and both disappear.

## Setting the key

```ts
import { setLicenseKey } from 'sv-grid-pro'

setLicenseKey(import.meta.env.VITE_SVPRO_KEY)
```

Call this before the first `<SvGrid>` mounts. In Vite/SvelteKit,
expose the key as `VITE_SVPRO_KEY=SVPRO-...` in your `.env` (NOT
checked in) - or read it from your config service.

## License tiers

Every Pro license is a **perpetual license** that includes **1 year of
updates and support**. The price shown **renews automatically each year**
to keep updates and support active; **cancel anytime** and you keep every
version released during your paid term.

| License                                    | Apps covered                        | Price (per developer) | Support                                   |
| ------------------------------------------ | ----------------------------------- | --------------------- | ----------------------------------------- |
| **Single Application Developer License**   | One deployed production app         | **$599**              | Email (next business day) + private Slack |
| **Multiple Application Developer License** | Unlimited apps in your organisation | **$999**              | Email (next business day) + private Slack |
| **Enterprise / volume**                    | Unlimited                           | Custom quote          | Priority + named contact, NDA / PO        |

> Priced **per developer** - engineers who write or modify code that imports
> `sv-grid-pro`. Production seats / end users are unlimited. One license key
> activates every grid in scope - no per-page or per-component accounting.
> Teams of 5+ and multi-year terms get volume discounts; email
> `sales@jqwidgets.com`.

## License key format

```
SVPRO-IXIX-XXXX-XXXX-XXXX-XXXX
       │
       └── single hex-encoded payload, verified locally
```

The check is purely client-side, signed against our public key.
**No network call** is ever made to validate. Air-gapped deployments
work out of the box.

## Per-environment keys

Different keys for different deployment stages so revoking is surgical:

```ts
const KEY = {
  development: import.meta.env.VITE_SVPRO_DEV_KEY,
  staging:     import.meta.env.VITE_SVPRO_STAGING_KEY,
  production:  import.meta.env.VITE_SVPRO_PROD_KEY,
}[import.meta.env.MODE] ?? ''

setLicenseKey(KEY)
```

## Dev / demo key

For demos + integration tests, use the published sentinel:

```ts
setLicenseKey('SVPRO-DEV-DEMO')
```

This suppresses the watermark for local development. **Do not ship
this key to production** - it's a dev-only convenience and will be
revoked in any production-domain validation pipeline.

## What happens without a key

| Surface                     | Behaviour                                                  |
| --------------------------- | ---------------------------------------------------------- |
| Grid render                 | Works.                                                     |
| Editing, sort, filter       | Works.                                                     |
| `pro.exportData(...)`       | Works.                                                     |
| `pro.importData(...)`       | Works.                                                     |
| `pro.ai.*`                  | Works.                                                     |
| `createPivotModel(...)`     | Works.                                                     |
| Unlicensed watermark        | Visible on every grid instance.                            |
| Console nudge               | Logged once per page load.                                  |

Nothing is "trial mode" - the soft-gate is meant for evaluation. Once
you're sold, drop in a key.

## License renewal

The license itself is perpetual; what renews each year is your
**updates-and-support term**. It renews automatically until you cancel
(cancel anytime). The key keeps validating every version released during
a paid term, and if you cancel or let the term lapse, your installed
version keeps working - you just stop receiving new releases and support.

- 60 days before the term ends: yellow nudge on the watermark
- 30 days: orange
- 7 days: red
- After the term ends (if you cancelled): features keep working; only
  versions released after your paid term need a renewed term

We never disable working features on a paying customer.

## Audit trail

Each license key has a stable ID embedded. The same key activates as
many builds as you want; the ID is what we cross-reference against
your subscription in support tickets. **No telemetry is sent** -
support uses the ID you give us, not anything we phoned home for.

## See also

- [Pro evaluation](./evaluation.md) - 30-day evaluation flow
- [Pro support](./support.md) - SLAs, escalation, contact channels
- [Pricing](https://svgrid.com/pricing) - canonical pricing source

<!-- =================================================================
     /pro/README  (pro)
     ================================================================== -->

# Pro feature pack

`sv-grid-pro` is a paid add-on for `sv-grid-community`. It bolts onto
the same `<SvGrid>` you already have and adds four feature areas: data
export, data import, an AI assistant, and pivot tables.

```bash
pnpm add sv-grid-pro
```

```ts
import { installPro, setLicenseKey } from 'sv-grid-pro'

setLicenseKey('SVPRO-…')   // once, at app startup
const pro = installPro(api) // wraps a SvGridApi with Pro methods
```

That's the whole integration. Every Pro helper hangs off the api object
you already have; the grid component stays Community.

## What ships in Pro

### [Data export](../help/export.md)

`pro.exportData(opts)` writes the current view to Excel (xlsx), PDF,
CSV, TSV, or HTML. The xlsx writer honours:

- **Cell + row styles** via `opts.styles` - read the same `--sg-*`
  tokens the grid renders with so the file matches the theme.
- **Page header + footer** lines with text or embedded images
  (`opts.header`, `opts.footer`).
- **Embedded images** from cell values when columns are listed in
  `opts.imageFields`.
- **Multiple sheets** in one workbook via `opts.sheets`.
- **Printable view** via `pro.print(opts)` - opens a new window with
  repeat-on-page headers, cover page, page-size + orientation.

Demos: [56 theme-matched](../../examples/src/demos/56-export-theme-matched.svelte),
[57 header + footer + logo](../../examples/src/demos/57-export-header-footer-logo.svelte),
[58 images](../../examples/src/demos/58-export-with-images.svelte),
[59 multi-sheet](../../examples/src/demos/59-export-multi-sheet.svelte).

### [Data import](../help/import.md)

`pro.importData(opts)` reads an Excel / CSV / TSV / JSON file (or
inline text), maps columns to your row shape, validates each row, and
returns a typed `ImportResult` with `rows`, `errors`, and a `summary`.
You decide whether to commit the rows into the grid or preview first.

Demo: [53 Excel import](../../examples/src/demos/53-excel-import.svelte).

### [AI assistant](../help/ai.md)

Four model-agnostic helpers on `pro.ai`:

- `filter(query)` - natural-language filter + sort plan ("show me last
  quarter's churn over $10k, sorted by date").
- `smartFill(opts)` - propose values for empty cells from a few worked
  examples.
- `summarize(opts)` - one-paragraph + bullets summary of a row,
  selection, group, or the whole view.
- `classify(opts)` - classify free-text cells into one of a known set
  of labels.

You register a provider via `setAIProvider(yourAdapter)`. No model
client is bundled - you bring OpenAI / Anthropic / Ollama / local.

Demo: [51 AI assistant](../../examples/src/demos/51-ai-assistant.svelte).

### [Pivot tables](../help/pivot.md)

`createPivotModel(data, config)` (or `pro.pivot.build(config)` against
the live api) returns `{ rows, columns }` you feed to a separate
`<SvGrid>` instance. Supports row + column axes, eight built-in
aggregators (sum/avg/min/max/count/countDistinct/first/last) or
custom, grand-total row + column, subtotals, custom axis sort.

Demo: [52 pivot table + designer](../../examples/src/demos/52-pivot-table.svelte).

## Licensing

The pack is **soft-gated**. Until a valid license key is set,
everything still functions but the grid shows a small "unlicensed"
watermark + a one-time console nudge. Set a key once at app startup
and the watermark disappears:

```ts
import { setLicenseKey } from 'sv-grid-pro'
setLicenseKey('SVPRO-XXXX-XXXX-XXXX')
```

For dev builds, the demos use `setLicenseKey('SVPRO-DEV-DEMO')` to
suppress the watermark in screenshots.

Pricing + multi-app licensing: <https://sv-grid.dev/pricing>.

## How Pro integrates

```ts
import { SvGrid, type SvGridApi } from 'sv-grid-community'
import { installPro, setLicenseKey, type ProGridApi } from 'sv-grid-pro'

setLicenseKey(import.meta.env.VITE_SVPRO_KEY)

let api = $state<ProGridApi<typeof features, Order> | null>(null)
```

```svelte
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  onApiReady={(next: SvGridApi<typeof features, Order>) => {
    api = installPro(next)
  }}
/>

<button onclick={() => api?.exportData({ format: 'xlsx', filename: 'orders' })}>
  Export to Excel
</button>
```

`installPro` mutates and returns the same api object - existing
references keep working. The `ProGridApi` type extends `SvGridApi` so
the grid's existing methods are still there alongside the new ones.

## Tree-shaking

Each Pro module is a separate subpath export:

```ts
import { exportGrid }     from 'sv-grid-pro/export'    // export only
import { importData }     from 'sv-grid-pro/import'    // import only
import { aiFilter }       from 'sv-grid-pro/ai'        // AI only
import { createPivotModel } from 'sv-grid-pro/pivot'   // pivot only
```

If you only need export, the AI provider plumbing, pivot engine, and
import parser don't ship. The `sv-grid-pro` barrel import is
convenient; the subpaths are smaller.

## Peer dependencies

| Feature | Peer dep             | Optional?                                  |
| ------- | -------------------- | ------------------------------------------ |
| xlsx    | `jszip`              | Yes - only loaded when xlsx is exported.   |
| pdf     | `pdfmake`            | Yes - only loaded when pdf is exported.    |
| import  | `jszip` (xlsx only)  | Yes - only for xlsx import.                |
| AI      | -                    | -. You bring your own provider client.     |
| pivot   | -                    | -. Pure TypeScript, no runtime deps.       |

Install only what you need:

```bash
pnpm add sv-grid-pro jszip            # community + Pro + xlsx
pnpm add sv-grid-pro jszip pdfmake    # also pdf
```

## See also

- [Getting started](../getting-started.md) - if you haven't seen the
  Community walkthrough yet.
- [Help index](../help/index.md) - all topic pages including the four
  Pro pages.
- [Missing features](../help/missing-features.md) - the honest gap list.

<!-- =================================================================
     /pro/support  (pro)
     ================================================================== -->

# Pro support

What you get on each tier, what response time to expect, how to
escalate.

## SLAs

| Tier                  | Channel                  | First response | Resolution target | Hours of cover   |
| --------------------- | ------------------------ | -------------- | ----------------- | ---------------- |
| Community (free)      | GitHub issues            | best-effort    | best-effort       | community-driven |
| Single Application    | Email + private Slack    | next business day | 5 business days | 9-5 ET, M-F      |
| Multiple Application  | Email + private Slack    | next business day | 5 business days | 9-5 ET, M-F      |
| Enterprise            | Named contact + Slack    | 4h business hours, **1h for sev-1** | per contract | 9-7 ET, M-F (+ on-call sev-1) |

"Sev-1" = production outage caused by sv-grid; "sev-2" = major
feature broken; "sev-3" = bug; "sev-4" = question.

## What's in scope

| In scope                                  | Out of scope                                           |
| ----------------------------------------- | ------------------------------------------------------ |
| sv-grid bugs                              | Bugs in your application code                          |
| Type-error questions in sv-grid surface   | Generic TypeScript / Svelte questions                  |
| Migration help (from AG Grid / etc.)      | Full app port (we can recommend partners)              |
| Performance triage on supported browsers  | Performance on EOL browsers                            |
| Feature-request triage                    | We promise to evaluate; we don't promise to build      |
| Production-down incident triage           | Re-architecture of your data layer                     |

## How to open a ticket

1. **Reproduce in a minimal repo** - StackBlitz / CodeSandbox / `pnpm
   create svelte` + the smallest grid that shows the issue. We
   support the official `sv-grid-community` and `sv-grid-pro`
   packages.
2. **Include**:
   - sv-grid version (`pnpm ls sv-grid-community sv-grid-pro`)
   - Svelte version, Vite version, OS
   - Browser + version (we test on the latest 2 majors of Chrome, Firefox, Safari, Edge - see [browser support](../help/browser-support.md))
   - The exact error message + stack trace
   - A 30-second screen recording for visual issues
3. **Send to** `support@jqwidgets.com` with subject `[sev-N] <one-line summary>`.

## Escalation

For Team and above, replying to the ticket with `[escalate]` in the
subject moves it to the on-call engineer regardless of business hours.
Use for production outages only.

Enterprise customers get a Slack Connect channel; ping `@oncall` for
sev-1.

## Security disclosures

For security issues, **do not file a public issue**. Email
`support@jqwidgets.com` (PGP fingerprint at
[svgrid.com/.well-known/security.txt](https://svgrid.com/.well-known/security.txt)).
Response within 24h; patch within 7 days for high-severity.

See [security & supply chain](../help/security.md) for the full
disclosure policy.

## Roadmap visibility

- Community: public roadmap at [svgrid.com/roadmap](https://svgrid.com/roadmap)
- Single / Multiple Application: quarterly roadmap email + invite to monthly office hours
- Enterprise: named PM, monthly roadmap call, ability to sponsor features

## Documentation feedback

Found a doc bug, unclear page, or missing topic? Open an issue at
[github.com/sv-grid/sv-grid/issues](https://github.com/sv-grid/sv-grid/issues)
with the `docs` label, or hit the "Edit on GitHub" link on any page.

## See also

- [Pro licensing](./licensing.md)
- [Pro evaluation](./evaluation.md)
- [Security & supply chain](../help/security.md)
- [API stability](../help/api-stability.md) - the deprecation policy that drives support windows

<!-- =================================================================
     /recipes/autosave-with-debounce  (community)
     ================================================================== -->

# Auto-save edits with debounce

Persist every cell edit to the server, debounced so a fast typer
generates one save, not twenty.

```svelte
<script lang="ts">
  import { SvGrid } from 'sv-grid-community'

  type Patch = { rowId: string; columnId: string; value: unknown }
  let pending = new Map<string, Patch>()  // dedupe per (rowId, columnId)
  let flushTimer: number | null = null

  function queue(rowId: string, columnId: string, value: unknown) {
    pending.set(`${rowId}::${columnId}`, { rowId, columnId, value })
    if (flushTimer !== null) clearTimeout(flushTimer)
    flushTimer = window.setTimeout(flush, 600)
  }

  async function flush() {
    flushTimer = null
    if (pending.size === 0) return
    const batch = [...pending.values()]
    pending.clear()
    try {
      await fetch('/api/patch', {
        method: 'POST',
        body: JSON.stringify({ patches: batch }),
      })
    } catch {
      // Re-enqueue on failure for next flush.
      for (const p of batch) pending.set(`${p.rowId}::${p.columnId}`, p)
    }
  }
</script>

<svelte:window onbeforeunload={flush} />

<SvGrid
  {data} {columns} features={features}
  onCellValueChange={(e) => queue(e.row.id, e.columnId, e.newValue)}
/>
```

Three details that make this production-grade:

- **Dedupe**. The map key collapses repeated edits to the same cell - only the latest value ships.
- **`beforeunload` flush**. Tab close before debounce fires? Still flushes.
- **Re-enqueue on failure**. Network blip is harmless; retries next tick.

For a more elaborate version with undo / redo, see
[demo 55 (State maintenance)](https://svgrid.com/#/demos/55-state-maintenance).

## See also

- [Observability](../help/observability.md) - same callback, different sink
- [Demo 24 (Validation while editing)](https://svgrid.com/#/demos/24-validation) - reject-and-rollback on validation failure

<!-- =================================================================
     /recipes/barcode-cells  (community)
     ================================================================== -->

# Barcode cells in a Svelte data grid (EAN-13)

Render a real, scannable EAN-13 barcode in every row of your Svelte data grid -
drawn as crisp SVG with no canvas, no `eval`, and no third-party dependency.
This is the retail, warehouse, and inventory pattern: a product table where each
row carries its own barcode label, sharp at any zoom and ready to print.

<div data-docs-demo="112-barcode-cells" data-height="640"></div>

## When to use it

- Product catalogs, inventory, and stock-keeping grids (UPC / EAN).
- Warehouse pick lists, shelf labels, and asset tags.
- Any grid where a row maps to a physical item that needs a barcode.

## How it works

A barcode is a pure function from a code to a set of bars. Encode the 13-digit
value once, then render the bars as SVG through `renderSnippet` - the same way
you would render any custom cell. Because it is SVG (not a canvas bitmap) it
stays crisp when zoomed, themes with the grid, prints perfectly, and keeps your
CSP-clean runtime intact.

```svelte
<script lang="ts">
  import { SvGrid, renderSnippet, type ColumnDef } from 'sv-grid-community'

  // --- EAN-13 encoder (the actual GS1 spec - the output scans) ----------
  const L = ['0001101','0011001','0010011','0111101','0100011','0110001','0101111','0111011','0110111','0001011']
  const G = ['0100111','0110011','0011011','0100001','0011101','0111001','0000101','0010001','0001001','0010111']
  const R = ['1110010','1100110','1101100','1000010','1011100','1001110','1010000','1000100','1001000','1110100']
  const PARITY = ['LLLLLL','LLGLGG','LLGGLG','LLGGGL','LGLLGG','LGGLLG','LGGGLL','LGLGLG','LGLGGL','LGGLGL']

  /** Mod-10 check digit for the first 12 digits. */
  function ean13Check(d12: string): number {
    let odd = 0, even = 0
    for (let i = 0; i < 12; i++) (i % 2 === 0 ? (odd += +d12[i]!) : (even += +d12[i]!))
    return (10 - ((odd + 3 * even) % 10)) % 10
  }
  /** 12-digit prefix -> full, valid 13-digit EAN-13. */
  const ean13 = (prefix12: string) => prefix12 + ean13Check(prefix12)

  const QUIET = 9, H_BAR = 24, H_GUARD = 30, VB_H = 38
  const isGuard = (m: number) => m <= 2 || (m >= 45 && m <= 49) || m >= 92

  /** Encode a 13-digit code into 1-module-wide bar rects. */
  function encode(code: string) {
    const first = +code[0]!, left = code.slice(1, 7), right = code.slice(7, 13)
    let mods = '101'
    for (let i = 0; i < 6; i++) mods += PARITY[first]![i] === 'L' ? L[+left[i]!]! : G[+left[i]!]!
    mods += '01010'
    for (let i = 0; i < 6; i++) mods += R[+right[i]!]!
    mods += '101'
    const bars: { x: number; h: number }[] = []
    for (let m = 0; m < mods.length; m++) if (mods[m] === '1') bars.push({ x: QUIET + m, h: isGuard(m) ? H_GUARD : H_BAR })
    return { bars, width: QUIET + 95 + QUIET }
  }

  type Product = { sku: string; name: string; ean12: string }
  const rows: Product[] = [
    { sku: 'TOTE-RED-M', name: 'Canvas tote bag - red', ean12: '500100000017' },
    { sku: 'MUG-LOGO-12OZ', name: 'Logo mug 12 oz', ean12: '500100000062' },
  ]

  const columns: ColumnDef<{}, Product>[] = [
    { field: 'sku', header: 'SKU', width: 150 },
    { field: 'name', header: 'Product', width: 230 },
    {
      field: 'ean12', header: 'Barcode', width: 220,
      cell: (c) => renderSnippet(BarcodeCell, { code: ean13(c.row.original.ean12) }),
    },
  ]
</script>

{#snippet BarcodeCell(props: { code: string })}
  {@const bc = encode(props.code)}
  <svg viewBox={`0 0 ${bc.width} ${VB_H}`} width={bc.width * 1.6} height={VB_H * 1.6}
       role="img" aria-label={`EAN-13 ${props.code}`}>
    <rect x="0" y="0" width={bc.width} height={VB_H} fill="#fff" />
    {#each bc.bars as bar}
      <rect x={bar.x} y="0" width="1" height={bar.h} fill="#000" shape-rendering="crispEdges" />
    {/each}
  </svg>
{/snippet}

<SvGrid data={rows} columns={columns} rowHeight={62} />
```

Notes that matter in production:

- **It scans.** EAN-13 uses three 7-module digit encodings (L / G / R) plus a
  parity table that lets the first digit ride along in the parity of the left
  group. The check digit is mod-10. Point a phone scanner at the screen to
  confirm.
- **No dependency, CSP-clean.** The bars are Svelte SVG rects - no `eval`, no
  `new Function`, no canvas. Keep the encoder out of your shared bundle if only
  a few grids need it.
- **Virtualization keeps it cheap.** Only the barcodes in the visible row
  window are ever in the DOM, so it scales to thousands of products. See
  [Cell components](../help/cells/cell-components.md) for the rendering model.

## Print-ready labels

Because every code is SVG, the same markup scales to a shelf label or asset tag
and prints razor-sharp. The [demo](https://svgrid.com/demos/112-barcode-cells)
pops a label preview on row click; pair it with the
[Pro print / export pack](../help/export.md) to generate pick lists or label
sheets from the grid.

## What about QR codes?

QR codes follow the same cell-renderer pattern, but a correct QR encoder needs
Reed-Solomon error correction and mask selection, so reach for a small library
(for example `qrcode`) rather than hand-rolling it, then render its SVG output
through `renderSnippet` exactly as above.

## Frequently asked questions

### Can SvGrid render barcodes in a data grid cell?

Yes. A column's `cell` renderer can return any Svelte markup, including an
inline SVG barcode. The example above renders a scannable EAN-13 per row with no
third-party library.

### Does rendering barcodes need a barcode library?

No, not for EAN-13 / UPC and other linear symbologies - the encoder is a small
pure function and the bars are SVG rects. QR codes are the exception: use a
library for the Reed-Solomon error correction.

### Will the rendered barcodes actually scan?

Yes. The encoder implements the GS1 EAN-13 specification (L/G/R digit encodings,
the first-digit parity table, and the mod-10 check digit), so a standard barcode
reader decodes it.

### Is it fast with thousands of rows?

Yes. The grid virtualizes rows, so only the barcodes in the visible window are
in the DOM regardless of how many products the grid holds.

## See also

- [Demo 112-barcode-cells source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/112-barcode-cells.svelte)
- [Cell components](../help/cells/cell-components.md) - the custom-cell rendering model
- [Sparkline cell renderer](./sparkline-cells.md) - the same SVG-in-a-cell pattern
- [Data export and printing - Pro](../help/export.md) - print labels and pick lists
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/benchmark-harness  (community)
     ================================================================== -->

# Benchmark harness

> Measure grid time-to-first-paint at every (row count × column count)
> you care about. Run on your branch, your machine, your data shape.
> Use the output to track regressions and to justify "this dataset
> needs server-side pagination".

## When

You're answering:

- "How slow does this get at 100k × 50?"
- "Did my refactor regress paint time?"
- "At what dataset size should I cut over to server-side pagination?"

The same matrix runs in CI as a perf gate, and locally before a PR.

## The harness

The pattern: a tiny `<SvGrid>` mounted in an off-screen probe div,
wrapped in `performance.now()` brackets. The probe unmounts between
measurements so each cell starts from a clean state.

```svelte
<script lang="ts">
  import {
    SvGrid, tableFeatures,
    rowSortingFeature, columnFilteringFeature, rowSelectionFeature,
    type ColumnDef,
  } from 'sv-grid-community'

  const ROW_SIZES = [100, 1_000, 10_000, 50_000, 100_000] as const
  const COL_SIZES = [5, 10, 20, 50] as const

  type Cell = { rows: number; cols: number; ms: number | null }
  const matrix = $state<Cell[][]>(ROW_SIZES.map((r) =>
    COL_SIZES.map((c) => ({ rows: r, cols: c, ms: null })),
  ))
  let busy = $state(false)
  let running = $state<{ r: number; c: number } | null>(null)

  type Row = Record<string, unknown> & { __id: number }
  const features = tableFeatures({
    rowSortingFeature,
    columnFilteringFeature,
    rowSelectionFeature,
  })

  /** Deterministic seeded data so the same matrix is reproducible. */
  function makeData(rows: number, cols: number) {
    let prng = 0xABCDEF >>> 0
    const rnd = () => (prng = (prng * 1664525 + 1013904223) >>> 0) / 0xFFFFFFFF
    const columns: ColumnDef<typeof features, Row>[] = []
    for (let i = 0; i < cols; i += 1)
      columns.push({ field: `c${i}` as keyof Row & string, header: `Col ${i + 1}`, width: 100 })
    const data: Row[] = new Array(rows)
    for (let i = 0; i < rows; i += 1) {
      const r: Row = { __id: i }
      for (let j = 0; j < cols; j += 1) r[`c${j}`] = Math.round(rnd() * 10000)
      data[i] = r
    }
    return { data, columns }
  }

  /** The off-screen probe. The grid mounts here for measurement. */
  type Probe = { data: Row[]; columns: ColumnDef<typeof features, Row>[] } | null
  let probe = $state<Probe>(null)

  async function runOne(rIdx: number, cIdx: number) {
    busy = true
    running = { r: rIdx, c: cIdx }
    matrix[rIdx]![cIdx]!.ms = null
    probe = null
    await new Promise((r) => requestAnimationFrame(() => r(null)))

    const { rows, cols } = matrix[rIdx]![cIdx]!
    // Generate data BEFORE the timer so the allocation doesn't
    // pollute the time-to-paint number. Yield once after so the
    // status-cell repaint doesn't get blocked by the alloc.
    const { data, columns } = makeData(rows, cols)
    await new Promise((r) => requestAnimationFrame(() => r(null)))

    const t0 = performance.now()
    probe = { data, columns }
    // One rAF = first paint with the new grid mounted. That's
    // "time to first paint".
    await new Promise((r) => requestAnimationFrame(() => r(null)))
    const t1 = performance.now()

    matrix[rIdx]![cIdx]!.ms = Math.round((t1 - t0) * 10) / 10
    running = null
    busy = false
  }

  async function runAll() {
    if (busy) return
    busy = true
    for (let r = 0; r < ROW_SIZES.length; r += 1)
      for (let c = 0; c < COL_SIZES.length; c += 1)
        await runOne(r, c)
    busy = false
  }

  function heatColor(ms: number | null): string {
    if (ms === null) return 'transparent'
    if (ms < 16)   return 'rgba(34,197,94,0.45)'
    if (ms < 50)   return 'rgba(132,204,22,0.55)'
    if (ms < 100)  return 'rgba(245,158,11,0.55)'
    if (ms < 250)  return 'rgba(249,115,22,0.65)'
    return 'rgba(239,68,68,0.75)'
  }
</script>

<button onclick={runAll} disabled={busy}>{busy ? 'Running…' : 'Run all'}</button>

<table>
  <thead>
    <tr><th></th>
      {#each COL_SIZES as c (c)}<th>{c} cols</th>{/each}
    </tr>
  </thead>
  <tbody>
    {#each matrix as row, rIdx (rIdx)}
      <tr>
        <th>{ROW_SIZES[rIdx]?.toLocaleString()} rows</th>
        {#each row as cell, cIdx (cIdx)}
          <td style="background: {heatColor(cell.ms)}">
            <button onclick={() => !busy && runOne(rIdx, cIdx)} disabled={busy}>
              {cell.ms === null ? '-' : cell.ms < 10 ? cell.ms.toFixed(1) + ' ms' : Math.round(cell.ms) + ' ms'}
            </button>
          </td>
        {/each}
      </tr>
    {/each}
  </tbody>
</table>

<!-- The off-screen probe. Mount target for measured timing brackets. -->
<div style="position: fixed; left: -9999px; top: -9999px; width: 800px; height: 400px; visibility: hidden;">
  {#if probe}
    <SvGrid
      data={probe.data}
      columns={probe.columns}
      features={features}
      showRowSelection={false}
      showPagination={false}
      enableInlineEditing={false}
      enableCellSelection={false}
      rowHeight={26}
      containerHeight="400px"
      fitColumns={false}
    />
  {/if}
</div>
```

## What the timing actually captures

- **`t0` is recorded JUST BEFORE** `probe = {...}` triggers a Svelte
  re-render. Data allocation happened before `t0`, on purpose.
- **`t1` is recorded AFTER one rAF.** The browser fires rAF callbacks
  right before the paint, so by the time `t1` runs, the new grid is
  mounted and its first frame is on screen.
- The number is **time to first paint with this dataset mounted**, NOT
  time to first interaction. Hovering and clicking happen on
  subsequent frames; those are virtually free if the grid virtualises.

The off-screen probe has `visibility: hidden` but real width / height
so the browser still computes layout - paint cost is real.

## Reading the matrix

Suggested thresholds for an internal "is this still good?" gauge:

| Size      | Healthy        | Server-side recommended above |
| --------- | -------------- | ----------------------------- |
| 100×5     | < 16 ms        | -                             |
| 1k×10     | < 50 ms        | -                             |
| 10k×20    | < 100 ms       | -                             |
| 50k×20    | < 250 ms       | dataset > 50k                 |
| 100k×50   | < 1 s          | absolutely yes                |

If a "healthy" cell jumps red between branches, you regressed
something - bisect with a smaller matrix.

## Run in CI

The same harness runs headless in Playwright. Mount the matrix page,
click "Run all", read the cells, fail the job if any cell exceeds the
threshold:

```ts
test('grid time-to-first-paint regression gate', async ({ page }) => {
  await page.goto('/dev/stress-matrix')
  await page.getByRole('button', { name: /Run all/ }).click()
  await page.waitForFunction(() => !document.querySelector('button[disabled]'))
  const cells = await page.locator('td button').allTextContents()
  // Smoke-check: every cell now has a number, none are placeholders.
  expect(cells.every((c) => /\d/.test(c))).toBe(true)
  // Project-specific gates here:
  //   expect(parseFloat(cells[0])).toBeLessThan(20)
  //   ...
})
```

## Demo

The runnable companion: [Demo 134 - Stress matrix (gallery)](https://svgrid.com/#/demos/134-stress-matrix) - this harness wrapped in a page, ready to click on your machine.

## See also

- [Profiling with a FPS HUD](./profiling-with-fps-hud.md) - the matching live tool
- [Bundle size reference](../reference/bundle-size.md) - the per-feature cost
- [Million rows recipe](./million-rows.md) - the engineering for very large grids

<!-- =================================================================
     /recipes/between-date-filter  (community)
     ================================================================== -->

# Between-operator filters for date ranges

> Live in [demo 64-filter-between-operator](https://svgrid.com/#/demos/64-filter-between-operator).

## When

"From / to" date range as one filter, not two.

## How

Key API surface:

- `api.setFilter(id, { operator: 'between', value, valueTo })`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 64-filter-between-operator source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/64-filter-between-operator.svelte)
- [Demo 64-filter-between-operator prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/64-filter-between-operator.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/build-a-feature-plugin  (community)
     ================================================================== -->

# Build your own feature plugin

> The pattern: `tableFeatures()` is an open registry. Library features
> (`rowSortingFeature`, `columnFilteringFeature`, ...) are nothing more
> than objects with three hooks. Your own feature plugs into the same
> surface.

## When

You want to inject behavior that applies to *every* row or column - a
computed accent class, an audit fingerprint, an inline diff badge, a
per-row policy gate - without forking the grid component or writing
the same `cell:` boilerplate on every column def.

## The contract

A feature is an object with three optional hooks:

```ts
type TableFeature = {
  /** Initial slice of state the engine merges into its store. */
  getInitialState?: () => Record<string, unknown>
  /** Default values for the options bag the consumer passes through. */
  getDefaultOptions?: <TData>() => Record<string, unknown>
  /** Runs once when the table is created. Wrap api methods here. */
  createTable?: <TFeatures extends TableFeatures, TData extends RowData>(table: {
    options: Record<string, unknown>
    getRowModel: () => { rows: Array<{ original: TData }> }
  }) => void
}
```

Drop the unused hooks. A read-only decorator only needs `createTable`.

## How

This 25-line plugin writes a computed `__rowAccent` string onto every
row in the row model. A user-supplied function decides the accent:

```ts
import { tableFeatures, rowSortingFeature, type RowData, type TableFeatures } from 'sv-grid-community'

type RowAccentFn<TData extends RowData> = (row: TData) => string | undefined

const rowAccentFeature = {
  getInitialState: () => ({}),
  getDefaultOptions: <TData extends RowData>() =>
    ({ rowAccent: undefined as RowAccentFn<TData> | undefined }),
  createTable: <TFeatures extends TableFeatures, TData extends RowData>(table: {
    options: { rowAccent?: RowAccentFn<TData> }
    getRowModel: () => { rows: Array<{ original: TData }> }
  }) => {
    // Wrap the row-model accessor so every row carries the computed
    // accent. Cheap O(visibleRows) per render.
    const orig = table.getRowModel.bind(table)
    table.getRowModel = () => {
      const model = orig()
      const fn = table.options.rowAccent
      if (!fn) return model
      for (const row of model.rows) {
        (row.original as Record<string, unknown>).__rowAccent =
          fn(row.original as TData)
      }
      return model
    }
  },
} as const
```

## Wire it up

Register the feature and supply `rowClass` to surface the accent in CSS:

```svelte
<script lang="ts">
  import { SvGrid, tableFeatures, rowSortingFeature } from 'sv-grid-community'

  type Deal = { company: string; health: number; __rowAccent?: string }

  const features = tableFeatures({ rowSortingFeature, rowAccentFeature })
  const deals: Deal[] = [/* ... */]

  function rowAccent(d: Deal): string | undefined {
    if (d.health >= 0.75) return 'good'
    if (d.health <  0.40) return 'bad'
    return 'warn'
  }
  function rowClass(ctx: { row: Deal; rowIndex: number }): string {
    const a = rowAccent(ctx.row)
    return a ? `accent-${a}` : ''
  }
</script>

<SvGrid {features} {columns} data={deals} {rowClass} />

<style>
  /* rowClass lands on the <tr>; <td> cells paint their own bg over it,
     so tint the cells via a descendant selector. */
  :global(.accent-good td.sv-grid-cell) { background: rgba(34,197,94,0.14) !important; }
  :global(.accent-warn td.sv-grid-cell) { background: rgba(245,158,11,0.16) !important; }
  :global(.accent-bad  td.sv-grid-cell) { background: rgba(239,68,68,0.18) !important; }
</style>
```

## Trade-offs

- **`createTable` runs once.** Mutating row data inside `getRowModel`
  works because the model is rebuilt on every state change - but it's a
  side effect on the consumer's `TData`. Use `__`-prefixed keys so it
  reads as a synthetic field, not a real one.
- **Don't put expensive work in `createTable`.** It runs for every
  feature in the registry on every table creation. Put expensive work
  on the consumer's option (`rowAccent: (d) => ...`) where the consumer
  controls the cost.
- **No reactivity from the feature itself.** Reactivity comes from the
  data the consumer hands the grid (Svelte 5 `$state`) - the feature is
  pure transform.

## See also

- [Features reference](../reference/features.md) - the full registry contract
- [Conditional row coloring recipe](./conditional-row-coloring.md) - same idea, no plugin
- [Architecture overview](../help/architecture.md)

<!-- =================================================================
     /recipes/bulk-edit-selected-rows  (community)
     ================================================================== -->

# Bulk-edit selected rows

Goal: the user selects N rows, opens a toolbar, picks a field + value,
and **every** selected row updates in one click. Standard back-office
workflow for status changes, reassignments, tag application.

## Implementation

The recipe is three pieces:

1. `selectionMode="row"` + `showRowSelection={true}` gives you the
   checkbox column and the multi-select keyboard model.
2. `onRowSelectionChange` keeps a `$state` array of selected rows.
3. A toolbar above the grid commits the bulk change to `internalData`
   via the api's `setCellValue` (one call per selected row).

```svelte
<script lang="ts">
  import {
    SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
    rowSelectionFeature, type ColumnDef, type SvGridApi,
  } from 'sv-grid-community'

  const features = tableFeatures({
    rowSortingFeature,
    columnFilteringFeature,
    rowSelectionFeature,
  })

  type Order = {
    id: string
    customer: string
    status: 'New' | 'In review' | 'Approved' | 'Shipped' | 'Cancelled'
    priority: 'Low' | 'Normal' | 'High'
    assignee: string
  }

  let rows = $state<Order[]>([/* ... */])
  let api  = $state<SvGridApi<typeof features, Order> | null>(null)
  let selected = $state<Order[]>([])

  // Per-action UI state.
  let action = $state<'status' | 'priority' | 'assignee'>('status')
  let value  = $state<string>('Approved')

  const STATUS_OPTIONS    = ['New', 'In review', 'Approved', 'Shipped', 'Cancelled'] as const
  const PRIORITY_OPTIONS  = ['Low', 'Normal', 'High'] as const
  const ASSIGNEE_OPTIONS  = ['Ada', 'Linus', 'Grace', 'Kathleen', '(unassigned)']

  function applyBulk() {
    if (!api || selected.length === 0) return
    // Resolve each selected row's index in the live data array and
    // write through setCellValue. `setCellValue` triggers a single
    // re-render after the batch via the wrapper's state-version bump.
    for (const row of selected) {
      const idx = rows.indexOf(row)
      if (idx < 0) continue
      api.setCellValue(idx, action, value)
    }
    // Refresh `rows` reference so $derived bindings outside the grid
    // (footer counts, etc.) update. The grid itself is already in sync.
    rows = [...rows]
  }
</script>

<header class="flex items-end gap-2 mb-3">
  <strong>{selected.length} selected</strong>
  <label>
    Field
    <select bind:value={action} onchange={() => {
      value = action === 'status'   ? 'Approved'
            : action === 'priority' ? 'Normal'
            :                         'Ada'
    }}>
      <option value="status">Status</option>
      <option value="priority">Priority</option>
      <option value="assignee">Assignee</option>
    </select>
  </label>
  <label>
    Value
    <select bind:value={value}>
      {#each (action === 'status'   ? STATUS_OPTIONS
            : action === 'priority' ? PRIORITY_OPTIONS
            :                         ASSIGNEE_OPTIONS) as opt}
        <option value={opt}>{opt}</option>
      {/each}
    </select>
  </label>
  <button onclick={applyBulk} disabled={selected.length === 0}>
    Apply to {selected.length} rows
  </button>
</header>

<SvGrid
  data={rows}
  columns={[
    { field: 'id',       header: 'Order',    width: 110 },
    { field: 'customer', header: 'Customer', width: 200 },
    { field: 'status',   header: 'Status',   width: 130 },
    { field: 'priority', header: 'Priority', width: 110 },
    { field: 'assignee', header: 'Assignee', width: 140 },
  ] satisfies ColumnDef<typeof features, Order>[]}
  features={features}
  selectionMode="row"
  showRowSelection={true}
  onApiReady={(next) => (api = next)}
  onRowSelectionChange={(_, selectedRows) => (selected = selectedRows)}
/>
```

## Variations

### Cycle through values per row

If the bulk action is "increment priority by one level", you read each
row's current value first:

```ts
const next = (cur: 'Low' | 'Normal' | 'High') =>
  cur === 'Low' ? 'Normal' : cur === 'Normal' ? 'High' : 'High'

for (const row of selected) {
  const idx = rows.indexOf(row)
  if (idx < 0) continue
  api.setCellValue(idx, 'priority', next(row.priority))
}
```

### Confirm before applying

For destructive bulk actions (cancel orders, delete rows), pop a
confirm dialog before the loop. Don't rely on the browser's native
`confirm()` - it's blocked by some embedded contexts. A Svelte
`<dialog>` element is the lowest-friction path.

### Server-side persistence

Pair the bulk write with a single `POST /api/orders/bulk-update`
request rather than N writes. The grid update is purely client-side;
the server roundtrip is independent. If the server fails, roll the
grid back by re-applying the previous values from a `before` snapshot.

```ts
async function applyBulkAndPersist() {
  const before = selected.map((r) => ({ ...r }))
  applyBulk() // optimistic local write
  try {
    await fetch('/api/orders/bulk-update', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ ids: selected.map((r) => r.id), [action]: value }),
    })
  } catch (err) {
    // Roll back
    for (const old of before) {
      const idx = rows.indexOf(rows.find((r) => r.id === old.id)!)
      if (idx >= 0) api?.setCellValue(idx, action, (old as any)[action])
    }
    throw err
  }
}
```

## Notes

- **`setCellValue` does not fire `onCellValueChange`.** That callback
  is for **user** edits via the inline editor. Bulk programmatic
  writes are silent - if you need them logged, log them yourself in
  the bulk handler.
- **Selection survives data shape changes** as long as the row
  references match. Swapping the entire `rows` array clears selection;
  immutable updates that keep most row references stable preserve it.
- **Keyboard**: Shift-click to extend, Ctrl/Cmd-click to toggle, the
  header checkbox toggles all visible. Standard a11y - no extra work.

## See also

- [`SvGridApi.setCellValue`](../reference/SvGridApi.md#setcellvaluerowindex-columnid-value)
- [Editing overview](../help/editing/overview.md)
- Demo [`23-bulk-actions`](../../examples/src/demos/23-bulk-actions.svelte) -
  a fuller version with confirm + undo

<!-- =================================================================
     /recipes/cell-renderer-patterns  (community)
     ================================================================== -->

# Cell renderer patterns

Every supported shape for the `cell:` slot on a `ColumnDef`, with the
trade-offs for each.

## The four shapes

`cell:` accepts one of:

| Shape                              | When to use                                                    |
| ---------------------------------- | -------------------------------------------------------------- |
| `string`                           | A literal placeholder ("TBD"). Rare.                           |
| `(ctx) => string \| number`        | Computed text, no DOM control.                                 |
| `(ctx) => renderSnippet(...)`      | Inline Svelte 5 snippet defined in the same file.              |
| `(ctx) => renderComponent(...)`    | Mount a real Svelte component imported from another file.      |

`ctx` is `{ row: Row<TData>, column, table, getValue }` - the same
context TanStack-style tables emit. Everywhere below `ctx.row.original`
is your `TData` row.

## 1. Literal string

```ts
{ field: 'amount', header: 'Amount', cell: 'TBD' }
```

Used when bootstrapping. The cell renders the literal across every row.

## 2. Computed function

```ts
{
  field: 'amount', header: 'Amount', align: 'right',
  cell: (ctx) => {
    const n = ctx.row.original.amount
    if (n >= 1_000_000) return `$${(n / 1_000_000).toFixed(1)}M`
    if (n >= 1_000)     return `$${Math.round(n / 1_000)}k`
    return `$${n}`
  },
}
```

Cheapest custom renderer. No DOM control - the grid wraps the return
value in its own `<td>`. Use for formatted text, status acronyms,
computed totals.

For built-in formats (currency, percent, date, units) prefer the
declarative [`format:`](../reference/ColumnDef.md#format) field - it
runs through `Intl.NumberFormat` cached per locale.

## 3. Inline snippet

```svelte
<script lang="ts">
  import { renderSnippet, type ColumnDef } from 'sv-grid-community'

  type Sale = { amount: number; up: boolean }
  const columns: ColumnDef<typeof features, Sale>[] = [
    {
      field: 'amount', header: 'Amount', align: 'right',
      cell: (ctx) => renderSnippet(Pill, { sale: ctx.row.original }),
    },
  ]
</script>

{#snippet Pill(props: { sale: Sale })}
  <span class="pill" class:up={props.sale.up} class:down={!props.sale.up}>
    {props.sale.up ? '▲' : '▼'} ${props.sale.amount.toLocaleString()}
  </span>
{/snippet}

<style>
  :global(.pill.up)   { background: rgba(34,197,94,0.18);  color: #15803d; }
  :global(.pill.down) { background: rgba(239,68,68,0.18);  color: #b91c1c; }
</style>
```

The snippet is local to the component, with access to its scope. Best
for one-off renderers that need DOM control but don't merit their own
file. The styles need `:global` because the snippet renders into the
grid's body, not the consumer's component subtree.

## 4. Imported component

```svelte
<script lang="ts">
  import { renderComponent } from 'sv-grid-community'
  import BadgeCell from './BadgeCell.svelte'

  const columns = [
    {
      field: 'amount', header: 'Amount',
      cell: (ctx) => renderComponent(BadgeCell, {
        label: `$${ctx.row.original.amount.toLocaleString()}`,
        tone:  ctx.row.original.up ? 'good' : 'bad',
      }),
    },
  ]
</script>
```

```svelte
<!-- BadgeCell.svelte -->
<script lang="ts">
  let { label, tone }: { label: string; tone: 'good' | 'bad' } = $props()
</script>
<span class="bc" class:good={tone === 'good'} class:bad={tone === 'bad'}>{label}</span>
```

Use when the renderer is reused across columns or grids, or when it
carries its own non-trivial state.

## Headers, footers, editors - same shapes

The `header:` and `footer:` fields on `ColumnDef` accept the same four
shapes - any function-valued header is rendered via the same path. So
you can plug your own `<HeaderToolbar />` component without forking
`<SvGrid>`.

Custom inline editors use `cellEditor:` and follow the
`(ctx) => renderSnippet(...)` pattern - see the [`84-editor-types`
demo](https://svgrid.com/#/demos/84-editor-types).

## See also

- [Sparkline-cells recipe](./sparkline-cells.md) - a non-trivial component cell
- [Heatmap-cells recipe](./heatmap-cells.md) - computed-function cell with conditional formatting
- [Barcode-cells recipe](./barcode-cells.md) - real SVG rendered per row
- [Conditional row coloring](./conditional-row-coloring.md) - styling without a custom renderer
- [`<SvGrid>` reference](../reference/SvGrid.md) - `renderSnippet` / `renderComponent` helpers

<!-- =================================================================
     /recipes/chartjs-sync  (community)
     ================================================================== -->

# Chart.js sync from grid filter state

> Live in [demo 73-chartjs-sync](https://svgrid.com/#/demos/73-chartjs-sync).

## When

A chart that re-renders from api.getDisplayedRows() on every filter / sort change.

## How

Key API surface:

- `api.getDisplayedRows()`
- `onFiltersChange / onSortingChange`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 73-chartjs-sync source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/73-chartjs-sync.svelte)
- [Demo 73-chartjs-sync prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/73-chartjs-sync.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/conditional-row-coloring  (community)
     ================================================================== -->

# Conditional row coloring

> Live in [demo 62-conditional-styling](https://svgrid.com/#/demos/62-conditional-styling).

## When

rowClass returns a class map per row; CSS does the rest.

## How

Key API surface:

- `<SvGrid rowClass={(ctx) => ({...})}>`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 62-conditional-styling source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/62-conditional-styling.svelte)
- [Demo 62-conditional-styling prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/62-conditional-styling.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/cursor-based-infinite-scroll  (community)
     ================================================================== -->

# Cursor-based infinite scroll

Sparse-load a 100k-row audit log without paginating. Pattern:
debounce on scroll, fetch the next chunk by cursor, splice into
`$state`.

```svelte
<script lang="ts">
  import { SvGrid, type SvGridApi } from 'sv-grid-community'

  type Event = { id: string; ts: string; actor: string; action: string }
  let rows = $state<Event[]>([])
  let cursor = $state<string | null>(null)
  let loading = $state(false)
  let exhausted = $state(false)

  async function loadMore() {
    if (loading || exhausted) return
    loading = true
    try {
      const r = await fetch(`/api/events?cursor=${cursor ?? ''}&limit=200`)
      const { items, next } = await r.json() as { items: Event[]; next: string | null }
      rows = [...rows, ...items]
      cursor = next
      if (!next || items.length === 0) exhausted = true
    } finally {
      loading = false
    }
  }

  $effect(() => { void loadMore() })

  /** Wire the wrapper's scroll container to trigger near the end. */
  function onScroll(el: HTMLElement) {
    if (el.scrollTop + el.clientHeight >= el.scrollHeight - 400) loadMore()
  }
</script>

<div onscroll={(e) => onScroll(e.currentTarget as HTMLElement)}
     style="height: 100%; overflow: auto;">
  <SvGrid data={rows} columns={columns} features={features}
    showPagination={false} virtualization={true} containerHeight="100%" />
  {#if loading}<p>Loading more…</p>{/if}
  {#if exhausted}<p>End of log.</p>{/if}
</div>
```

## Why cursor + not page number

For append-only logs (audit, time-series), page numbers shift
underneath you as new events arrive. Cursor (server-issued opaque
token) is stable.

## Cancellation

When the user filters mid-scroll, abort the in-flight fetch:

```ts
let controller: AbortController | null = null

async function loadMore() {
  controller?.abort()
  controller = new AbortController()
  const r = await fetch(`...`, { signal: controller.signal })
  ...
}
```

## See also

- [Demo 33 (Server-side infinite scroll)](https://svgrid.com/#/demos/33-server-infinite) - live
- [Server-side data](../help/server-side-data.md) - the full pattern catalog
- [Real-time / streaming](../help/real-time.md) - if events arrive PUSHED instead of PULLED

<!-- =================================================================
     /recipes/custom-filter-functions  (community)
     ================================================================== -->

# Custom filter functions

> Filter logic that the built-in `filterFns` (`includesString`,
> `equals`, `between`, ...) doesn't cover - semver ranges, CIDR / IP
> matching, fuzzy search, regex. The library doesn't expose a
> per-column `filterFn` field; the pattern is **pre-filter the data
> array** and hand the result to the grid.

## When

You need any of:

- semver-range matching (`^2.4.0` → `2.4.7` but not `3.0.0`)
- CIDR / IP subnet matching (`10.0.0.0/8` → `10.5.2.3`)
- acronym / fuzzy matching (`rct` → `react` AND `redact`)
- regex matching against a Tag column
- score-based ranking by relevance, not just a boolean filter

For exact-match, contains, range, and "in [list]" - prefer
[`api.setFilter`](../reference/SvGridApi.md#setfilter) with a built-in
operator.

## The pattern

Each filter is a pure `(value, spec) => boolean` function. Compose
them in a `$derived` that filters the data array before it reaches
`<SvGrid data={...}>`.

```svelte
<script lang="ts">
  import { SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature } from 'sv-grid-community'

  type FilterFn = (value: unknown, filterValue: string) => boolean

  const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })

  let services: Service[] = [/* ... */]
  let semverSpec = $state('')
  let cidrSpec   = $state('')
  let fuzzySpec  = $state('')
  let regexSpec  = $state('')

  const filtered = $derived(
    services.filter((s) =>
      semverInRange(s.semver, semverSpec)
      && cidrContainsIp(s.ip, cidrSpec)
      && fuzzySubstring(s.id, fuzzySpec)
      && regexMatch(s.tag, regexSpec)
    ),
  )
</script>

<SvGrid data={filtered} {columns} {features} />
```

The grid stays a plain consumer - all filters compose naturally and
empty inputs are no-ops.

## The four filter implementations

### Semver in range

```ts
/** Matches simple "^x.y.z" (compatible) and "~x.y.z" (patch-only). */
const semverInRange: FilterFn = (value, filterValue) => {
  const v = String(value ?? '')
  const spec = String(filterValue ?? '').trim()
  if (!spec) return true
  const parse = (s: string) =>
    s.split('.').map((n) => parseInt(n, 10) || 0) as [number, number, number]
  const op = spec[0]
  const base = parse(spec.slice(op === '^' || op === '~' ? 1 : 0))
  const cur  = parse(v)
  if (op === '^') return cur[0] === base[0] &&
    (cur[1] > base[1] || (cur[1] === base[1] && cur[2] >= base[2]))
  if (op === '~') return cur[0] === base[0] && cur[1] === base[1] && cur[2] >= base[2]
  return v === spec
}
```

### CIDR contains IP

```ts
const cidrContainsIp: FilterFn = (value, filterValue) => {
  const ip = String(value ?? '')
  const cidr = String(filterValue ?? '').trim()
  if (!cidr) return true
  const [net, bitsStr] = cidr.split('/')
  if (!net || !bitsStr) return false
  const bits = parseInt(bitsStr, 10)
  const toInt = (s: string) =>
    s.split('.').reduce((a, b) => (a << 8) + (parseInt(b, 10) || 0), 0) >>> 0
  const mask = bits === 0 ? 0 : (0xffffffff << (32 - bits)) >>> 0
  return (toInt(ip) & mask) === (toInt(net) & mask)
}
```

### Fuzzy substring (acronym OR contiguous)

```ts
const fuzzySubstring: FilterFn = (value, filterValue) => {
  const hay = String(value ?? '').toLowerCase()
  const needle = String(filterValue ?? '').toLowerCase().trim()
  if (!needle) return true
  if (hay.includes(needle)) return true
  // Acronym: every needle char appears in hay in order.
  let i = 0
  for (const ch of hay) {
    if (ch === needle[i]) i += 1
    if (i === needle.length) return true
  }
  return false
}
```

### Regex match

```ts
const regexMatch: FilterFn = (value, filterValue) => {
  const v = String(value ?? '')
  const pattern = String(filterValue ?? '').trim()
  if (!pattern) return true
  try { return new RegExp(pattern).test(v) }
  catch { return false }
}
```

## Performance notes

- Pre-filtering on the consumer side runs **before** the grid's own
  sort/group/page pipeline - so the engine sees fewer rows and does
  less work.
- For large datasets (>10k rows) keep filter functions allocation-free
  - no `.map().filter()` chains inside a hot path. The four above are
  all single-pass.
- Debounce the input bindings if a filter is heavy. `bind:value` fires
  every keystroke; wrap it in a `$derived` keyed off a debounced
  `$state` mirror if needed.

## See also

- [Locale-aware filtering recipe](./external-search.md)
- [Saved filter sets](./saved-filter-sets.md)
- [Between-operator filters for date ranges](./between-date-filter.md)
- [`SvGridApi.setFilter`](../reference/SvGridApi.md#setfilter) for built-in operator filters

<!-- =================================================================
     /recipes/dependent-dropdowns  (community)
     ================================================================== -->

# Dependent dropdowns (cascading editors)

`Country → State → City`. Editing one level resets downstream
levels; each cell's dropdown options come from the row's upstream
value.

```ts
const REGIONS: Record<string, Record<string, string[]>> = {
  USA:     { California: ['SF', 'LA', 'San Diego'], Texas: ['Austin', 'Dallas'] },
  Germany: { Bavaria: ['Munich', 'Nuremberg'],     Berlin: ['Berlin'] },
}

const columns: ColumnDef<typeof features, Region>[] = [
  { field: 'country', editorType: 'list',
    editorOptions: () => Object.keys(REGIONS) },
  { field: 'state', editorType: 'list',
    editorOptions: (row) => Object.keys(REGIONS[row.country] ?? {}) },
  { field: 'city', editorType: 'list',
    editorOptions: (row) => REGIONS[row.country]?.[row.state] ?? [] },
]
```

The `(row) => options` form is what makes the cascade work: every
cell re-computes its options from the row's current value at edit
time.

## Reset downstream on upstream change

When `country` changes, the row's `state` and `city` may now be
invalid. Catch the cell change and snap them to a sane default:

```svelte
<SvGrid
  {data} {columns} features={features}
  onCellValueChange={(e) => {
    if (!api) return
    if (e.columnId === 'country') {
      const newCountry = String(e.newValue)
      const firstState = Object.keys(REGIONS[newCountry] ?? {})[0] ?? ''
      const firstCity  = (REGIONS[newCountry]?.[firstState] ?? [])[0] ?? ''
      api.setCellValue(e.rowIndex, 'state', firstState)
      api.setCellValue(e.rowIndex, 'city',  firstCity)
    } else if (e.columnId === 'state') {
      const row = rows[e.rowIndex]
      const firstCity = (REGIONS[row.country]?.[String(e.newValue)] ?? [])[0] ?? ''
      api.setCellValue(e.rowIndex, 'city', firstCity)
    }
  }}
  onApiReady={(next) => (api = next)}
/>
```

Live in [demo 68 (Dependent dropdowns)](https://svgrid.com/#/demos/68-dependent-dropdowns)
- includes a typeahead combobox + a one-click "Fix" button when seed
data leaves the cascade in an inconsistent state.

## See also

- [Provided cell editors](../help/editing/provided-editors.md) - the built-in editor set
- [Edit components](../help/editing/edit-components.md) - rolling your own

<!-- =================================================================
     /recipes/drag-drop-columns  (community)
     ================================================================== -->

# Drag-drop columns to reorder

> Live in [demo 54-columns-hierarchy](https://svgrid.com/#/demos/54-columns-hierarchy).

## When

Re-order columns by dragging them in a side panel; live grid reflects the new order.

## How

Key API surface:

- `api.setColumnPinning({...})`
- `your reordering callback updates the columns prop`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 54-columns-hierarchy source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/54-columns-hierarchy.svelte)
- [Demo 54-columns-hierarchy prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/54-columns-hierarchy.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/external-search  (community)
     ================================================================== -->

# External search box with highlighted matches

> Live in [demo 69-highlighted-search](https://svgrid.com/#/demos/69-highlighted-search).

## When

A search input outside the grid filters the visible rows AND highlights matched substrings inline.

## How

Key API surface:

- `derived visibleRows`
- `custom cell snippet wraps matches in <mark>`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 69-highlighted-search source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/69-highlighted-search.svelte)
- [Demo 69-highlighted-search prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/69-highlighted-search.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/form-library-bridge  (community)
     ================================================================== -->

# Form library bridge

> Drive grid edits from a form library - Felte, Superforms, Formsnap,
> or a plain `<form>`. `api.setCellValue` is the single write surface;
> any UI that funnels through it stays consistent with inline editing.

## When

You want the same row to be editable two ways:

- **Inline** via the grid's built-in editors (commit on blur)
- **Drawer / modal** via a form library with its own validation

Both writers must update the SAME underlying data so users can edit
either way and not lose work. Common in admin tools, CRMs, and audit
queues where some fields are best inline (status pill) and others need
a real form (long-text + validation + dependent dropdowns).

## The pattern

```
┌──────────────────┐         setCellValue(idx, field, v)         ┌──────────┐
│  Inline editor   │ ──────────────────────────────────────────► │  data[]  │
└──────────────────┘                                             │  $state  │
                                                                 │          │
┌──────────────────┐         setCellValue(idx, field, v)         │          │
│  Drawer <form>   │ ──────────────────────────────────────────► │          │
└──────────────────┘                                             └──────────┘
```

Same write path. Same dirty tracking (count `onCellValueChange`
events). Whatever lives in `data[]` is the truth.

## Wire-up

```svelte
<script lang="ts">
  import { SvGrid, tableFeatures, rowSortingFeature, type SvGridApi } from 'sv-grid-community'

  type Employee = { id: string; name: string; email: string; team: 'Eng' | 'Sales' | 'Ops'; salary: number; remote: boolean }
  let employees = $state<Employee[]>([/* ... */])

  const features = tableFeatures({ rowSortingFeature })
  const columns = [
    { field: 'id',     header: 'ID',     editable: false },
    { field: 'name',   header: 'Name',   editorType: 'text' },
    { field: 'email',  header: 'Email',  editorType: 'text' },
    { field: 'team',   header: 'Team',   editorType: 'select',
      editorOptions: ['Eng', 'Sales', 'Ops'].map((v) => ({ value: v })) },
    { field: 'salary', header: 'Salary', editorType: 'number',
      format: { type: 'currency', currency: 'USD' } },
    { field: 'remote', header: 'Remote', editorType: 'checkbox' },
  ] as const

  let api = $state<SvGridApi<typeof features, Employee> | null>(null)
  let selectedId = $state<string>('E001')
  const selected = $derived(employees.find((e) => e.id === selectedId) ?? null)

  // Draft state for the drawer form
  type FormDraft = Omit<Employee, 'id'>
  let draft = $state<FormDraft | null>(null)
  let errors = $state<Partial<Record<keyof FormDraft, string>>>({})

  $effect(() => {
    if (selected) draft = { ...selected }
    else          draft = null
    errors = {}
  })

  function validate(d: FormDraft): Partial<Record<keyof FormDraft, string>> {
    const out: Partial<Record<keyof FormDraft, string>> = {}
    if (d.name.trim().length < 2) out.name = 'Name must be at least 2 characters'
    if (!/^\S+@\S+\.\S+$/.test(d.email)) out.email = 'Looks unlike an email'
    if (d.salary < 0 || d.salary > 10_000_000) out.salary = 'Salary out of range'
    return out
  }

  function isDirty(): boolean {
    if (!selected || !draft) return false
    return (Object.keys(draft) as Array<keyof FormDraft>)
      .some((k) => draft![k] !== selected[k])
  }

  function submit() {
    if (!api || !selected || !draft) return
    const e = validate(draft)
    errors = e
    if (Object.keys(e).length > 0) return
    // setCellValue takes a rowIndex (number), not an id.
    // In a real app, memoise this lookup.
    const rowIndex = employees.findIndex((emp) => emp.id === selected.id)
    if (rowIndex < 0) return
    for (const k of Object.keys(draft) as Array<keyof FormDraft>) {
      if (draft[k] !== selected[k]) {
        api.setCellValue(rowIndex, k as string, draft[k] as unknown)
      }
    }
  }

  // Dirty-state count: increment on every cell change from EITHER UI.
  let dirtyCount = $state(0)
  function onCellChanged() { dirtyCount += 1 }
</script>

<SvGrid
  data={employees}
  {columns}
  {features}
  enableInlineEditing
  getRowId={(r) => r.id}
  onApiReady={(a) => (api = a)}
  onCellValueChange={onCellChanged}
/>

{#if draft}
  <form onsubmit={(e) => { e.preventDefault(); submit() }}>
    <label>Name <input type="text" bind:value={draft.name} /></label>
    {#if errors.name}<em>{errors.name}</em>{/if}
    <label>Email <input type="email" bind:value={draft.email} /></label>
    {#if errors.email}<em>{errors.email}</em>{/if}
    <label>Salary <input type="number" bind:value={draft.salary} /></label>
    <button type="submit" disabled={!isDirty()}>Save → setCellValue</button>
  </form>
{/if}
```

## Plugging Felte / Superforms

Same pattern with the library's idiomatic surface:

- **Felte**: bind the form to `draft`; the library handles validation.
  In `onSubmit`, call `api.setCellValue` for each changed key.
- **Superforms**: pass `selected` as the initial form data; on submit,
  the validated `form.data` becomes the source of `setCellValue` calls.
- **Formsnap**: a Superforms shape with built-in field components.
  Same `onSubmit` plumbing.

The library doesn't care which form library renders the inputs - the
contract is just "after validation, call `api.setCellValue` per dirty
field".

## Tracking "dirty" across both UIs

Two valid strategies:

1. **Event count** (shown above) - simplest. Reset to 0 after a save.
2. **Snapshot diff** - keep an initial copy of the data array;
   `JSON.stringify(initial) !== JSON.stringify(api.getData())` is dirty.
   More accurate, more expensive.

Most apps want #1.

## See also

- [Side-drawer edit demo (97)](https://svgrid.com/#/demos/97-side-drawer-edit) - the slide-in pattern used as the form host
- [Submit-time validation recipe](./submit-time-validation.md) - similar bulk-commit-then-validate pattern
- [Undo / redo for grid edits](./undo-redo-edits.md) - layer history on top of the same `setCellValue` calls
- [`SvGridApi.setCellValue`](../reference/SvGridApi.md#setcellvalue)

<!-- =================================================================
     /recipes/grid-state-inspector  (community)
     ================================================================== -->

# Grid state inspector

> Mount a dev-only side panel that shows the live grid state - filters,
> selection, active cell, column order, pinning, visibility - updated
> every animation frame. The thing every dev wishes was always-on while
> debugging.

## When

You're stuck on one of:

- "Why isn't this filter narrowing the rows? Is it even applied?"
- "Did the column reorder write into the api state?"
- "What rowIndex is the active cell - so I can verify my onCellClick handler?"
- "Selection looks broken - is it the api or the renderer?"

Sticking `console.log(api.getXxx())` everywhere works once. A panel
that polls every reader every frame answers all of these at once.

## The contract

The `SvGridApi` exposes a snapshot getter for every piece of public
state you might care about:

| Reader                  | What it returns                                           |
| ----------------------- | --------------------------------------------------------- |
| `getFilters()`          | Per-column operator-filter clauses                        |
| `getSelectedRowIds()`   | Array of row ids currently selected                       |
| `getSelected()`         | Cell selection ranges `[r0,c0,r1,c1][]`                   |
| `getActiveCell()`       | The focused cell, or null                                 |
| `getColumnOrder()`      | Column ids in current visual order                        |
| `getColumnPinning()`    | `{ left: [], right: [] }`                                 |
| `getColumns()`          | Every column with `id`, `header`, `visible`               |
| `getDisplayedRows()`    | The post-pipeline visible rows                            |
| `getData()`             | The pre-pipeline data array                               |

Sort state is *event-driven only* (`onSortingChange`) - there is no
`getSorting()` getter. The pattern below tracks it locally in the
panel to fill the gap.

## Implementation

```svelte
<script lang="ts">
  import {
    SvGrid, tableFeatures,
    rowSortingFeature, columnFilteringFeature,
    rowSelectionFeature, rowExpandingFeature,
    type SvGridApi, type ColumnDef,
  } from 'sv-grid-community'

  type Row = { id: number; name: string; team: string; score: number; active: boolean }
  const rows: Row[] = [/* ... */]

  const features = tableFeatures({
    rowSortingFeature, columnFilteringFeature,
    rowSelectionFeature, rowExpandingFeature,
  })
  const columns: ColumnDef<typeof features, Row>[] = [/* ... */]

  let api = $state<SvGridApi<typeof features, Row> | null>(null)

  type Snapshot = {
    filters: unknown
    selectedRowIds: unknown
    activeCell: unknown
    columnOrder: unknown
    columnPinning: unknown
    columns: unknown
    displayedRowCount: number
    cellSelection: unknown
  }
  let snap = $state<Snapshot | null>(null)
  let running = $state(true)

  // Track sort locally - the api has no getSorting() reader.
  let sortField = $state<string | null>(null)
  let sortDesc  = $state(false)

  $effect(() => {
    if (!running) return
    let raf = 0
    function tick() {
      if (api) {
        snap = {
          filters:           api.getFilters(),
          selectedRowIds:    api.getSelectedRowIds(),
          activeCell:        api.getActiveCell(),
          columnOrder:       api.getColumnOrder(),
          columnPinning:     api.getColumnPinning(),
          columns:           api.getColumns().map((c) => ({
            id: c.id, header: c.header, visible: c.visible,
          })),
          displayedRowCount: api.getDisplayedRows().length,
          cellSelection:     api.getSelected(),
        }
      }
      raf = requestAnimationFrame(tick)
    }
    raf = requestAnimationFrame(tick)
    return () => cancelAnimationFrame(raf)
  })

  // "Click a leaf to mutate it back" - quick mutators that drive the
  // grid api from the panel. Sort goes asc → desc → off.
  function flipSort(field: string) {
    if (!api) return
    if (sortField === field) {
      if (!sortDesc) { sortDesc = true; api.setSort(field, 'desc') }
      else { sortField = null; api.clearSort() }
    } else {
      sortField = field; sortDesc = false
      api.setSort(field, 'asc')
    }
  }
  function clearAll() {
    if (!api) return
    api.clearSort()
    api.clearAllFilters()
    sortField = null; sortDesc = false
  }
</script>

<button onclick={() => flipSort('score')}>Flip score sort</button>
<button onclick={clearAll}>Clear</button>
<button onclick={() => (running = !running)}>
  {running ? '⏸ Pause' : '▶ Resume'}
</button>

<SvGrid
  data={rows}
  {columns}
  {features}
  enableCellSelection
  onApiReady={(a) => (api = a)}
/>

<aside class="devtools">
  <h3>Grid state · live</h3>
  {#if snap}
    {#each Object.entries(snap) as [k, v] (k)}
      <section>
        <span class="key">{k}</span>
        <pre><code>{JSON.stringify(v, null, 2)}</code></pre>
      </section>
    {/each}
  {/if}
</aside>
```

## Polling vs subscribing

This recipe polls every frame for simplicity - 16ms cadence, no
subscriptions to manage. For most dev panels that's fine; the cost is
a few JSON.stringify calls per frame.

If you want event-driven instead, hook the grid's `on*` callbacks:

```ts
<SvGrid
  ...
  onSortingChange={(sorting) => log('sort', sorting)}
  onFiltersChange={(filters) => log('filter', filters)}
  onCellSelectionChange={(ranges) => log('cellsel', ranges)}
  onColumnOrderChange={(order) => log('colorder', order)}
/>
```

Event-driven catches every mutation without missing intermediate states
that polling might skip over. Polling catches state changes that don't
have a callback (e.g. the active cell moving via keyboard).

A real devtools panel combines both: poll on rAF for the current
snapshot, plus a separate event log seeded from the callbacks.

## Don't ship to production

Wrap behind an env flag:

```svelte
{#if import.meta.env.DEV || localStorage.getItem('svgrid:devtools') === 'on'}
  <Devtools />
{/if}
```

Polling every frame and serialising the whole snapshot is fine in dev,
unnecessary in prod.

## Demo

The runnable companion: [Demo 135 - Devtools panel (gallery)](https://svgrid.com/#/demos/135-devtools-panel) - this panel running next to a real grid.

## See also

- [`SvGridApi` reference](../reference/SvGridApi.md) - every reader the panel calls
- [Profiling with a FPS HUD](./profiling-with-fps-hud.md) - the perf-focused twin
- [Headless engine reference](../reference/headless-engine.md) - skip the grid component entirely

<!-- =================================================================
     /recipes/heatmap-cells  (community)
     ================================================================== -->

# Heatmap-tinted numeric cells

> Live in [demo 60-pivot-expandable](https://svgrid.com/#/demos/60-pivot-expandable).

## When

Bucket cell values into red/amber/neutral/green tints based on per-column min/max.

## How

Key API surface:

- `cellClass returns heat-1..heat-5 bucket classes`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 60-pivot-expandable source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/60-pivot-expandable.svelte)
- [Demo 60-pivot-expandable prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/60-pivot-expandable.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/index  (community)
     ================================================================== -->

# Recipes / cookbook

Copy-paste patterns for sv-grid. Every recipe is a complete, runnable
snippet you can drop into your app. Each pairs with a live demo in
the [gallery](https://svgrid.com/#/demos).

> Looking for the conceptual story? Start with
> [Architecture](../help/architecture.md) and the
> [Help topic index](../help/index.md). Recipes are the "show me a
> working solution" angle on the same material.

## By task

### Loading + persistence
- [Server-side filter with TanStack Query](./server-side-filter-with-tanstack-query.md)
- [Loading data from REST + GraphQL](./loading-data.md)
- [Persist column layout to URL](./persist-column-layout-to-url.md)
- [Persist column layout to localStorage (saved views)](./saved-views.md)
- [Cursor-based infinite scroll](./cursor-based-infinite-scroll.md)
- [Auto-save edits with debounce](./autosave-with-debounce.md)

### Editing
- [Bulk-edit selected rows](./bulk-edit-selected-rows.md)
- [Submit-time validation with error summary](./submit-time-validation.md)
- [Dependent dropdowns (Country → State → City)](./dependent-dropdowns.md)
- [Undo / redo for grid edits](./undo-redo-edits.md)
- [Role-based editable columns](./role-based-editing.md)

### Layout
- [Two-grid master/detail](./two-grid-master-detail.md)
- [Kanban board over the same `$state`](./kanban-from-grid-data.md)
- [Mobile card view with grid-on-desktop](./mobile-card-pivot.md)
- [Drag-drop columns to reorder](./drag-drop-columns.md)
- [Pin first column on horizontal scroll](./pin-first-column.md)

### Filtering + search
- [External search box with highlighted matches](./external-search.md)
- [Saved filter sets](./saved-filter-sets.md)
- [Between-operator filters for date ranges](./between-date-filter.md)

### Visuals
- [Conditional row coloring](./conditional-row-coloring.md)
- [Heatmap-tinted numeric cells](./heatmap-cells.md)
- [Sparkline cell renderer](./sparkline-cells.md)
- [Barcode (EAN-13) label cells](./barcode-cells.md)
- [Theme tokens for Ant / MUI / Fluent / shadcn](./theme-presets.md)

### Real-time
- [WebSocket streaming with backpressure](./websocket-streaming.md)
- [Chart.js sync from grid filter state](./chartjs-sync.md)

### AI
- [Smart paste: CSV / TSV / free-form → typed rows](./smart-paste.md)
- [NL filter wired to your LLM](./nl-filter.md)

### Export + import
- [Theme-matched xlsx export](./theme-matched-export.md)
- [Multi-sheet xlsx export](./multi-sheet-export.md)

### Performance
- [1 million rows with virtualization](./million-rows.md)
- [Lazy-load expand on demand](./lazy-load-expand.md)

### Framework interop
- [Use SvGrid from React (custom-element bridge)](./use-svgrid-from-react.md)

### Developer recipes
- [Build your own feature plugin](./build-a-feature-plugin.md) - extend `tableFeatures()` with a row-accent or audit hook
- [Cell renderer patterns](./cell-renderer-patterns.md) - string / fn / `renderSnippet` / `renderComponent`
- [Custom filter functions](./custom-filter-functions.md) - semver, CIDR, fuzzy, regex
- [Form library bridge](./form-library-bridge.md) - drive grid edits from Felte / Superforms / native `<form>`
- [Testing your grid](./testing-your-grid.md) - Vitest unit, @testing-library/svelte, Playwright E2E
- [Profiling with a FPS HUD](./profiling-with-fps-hud.md) - live FPS + frame budget + DOM row count
- [Benchmark harness](./benchmark-harness.md) - measure paint time across (rows × cols) on your machine
- [Grid state inspector](./grid-state-inspector.md) - dev-only side panel polling every public api reader

## See also

- [Help topic pages](../help/index.md) - the conceptual story behind each recipe
- [Demo gallery](https://svgrid.com/#/demos) - every recipe runs live
- [API reference](../reference/index.md) - exhaustive prop / method tables

<!-- =================================================================
     /recipes/kanban-from-grid-data  (community)
     ================================================================== -->

# Kanban board over the same `$state`

> Live in [demo 76-kanban-board](https://svgrid.com/#/demos/76-kanban-board).

## When

One <SvGrid> with columns = lanes, rows pivoted by status. HTML5 drag-drop moves cards between lanes.

## How

Key API surface:

- `pivot the source array into row × lane slots`
- `drag/drop events on cells`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 76-kanban-board source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/76-kanban-board.svelte)
- [Demo 76-kanban-board prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/76-kanban-board.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/lazy-load-expand  (community)
     ================================================================== -->

# Lazy-load expand on demand

> Live in [demo 31-lazy-tree-load](https://svgrid.com/#/demos/31-lazy-tree-load).

## When

Tree rows where children are fetched only when the user expands their parent.

## How

Key API surface:

- `onExpand callback`
- `merge children into $state on resolve`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 31-lazy-tree-load source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/31-lazy-tree-load.svelte)
- [Demo 31-lazy-tree-load prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/31-lazy-tree-load.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/loading-data  (community)
     ================================================================== -->

# Loading data from REST + GraphQL

Three shapes. Pick the one that matches your back-end; the grid
doesn't care which.

## REST: fetch on mount

```svelte
<script lang="ts">
  import { SvGrid, tableFeatures, rowSortingFeature } from 'sv-grid-community'
  const features = tableFeatures({ rowSortingFeature })
  let rows = $state<Order[]>([])
  let loading = $state(true)
  let error = $state<string | null>(null)

  $effect(() => {
    (async () => {
      try {
        const r = await fetch('/api/orders')
        if (!r.ok) throw new Error(`HTTP ${r.status}`)
        rows = await r.json()
      } catch (e) {
        error = String(e)
      } finally {
        loading = false
      }
    })()
  })
</script>

<SvGrid data={rows} columns={columns} features={features} {loading} {error} />
```

The grid's `loading` + `error` props render a built-in overlay; you
don't need to gate the `<SvGrid>` mount.

## REST: server-side sort / filter / page

When the dataset is bigger than ~10k rows, push sort + filter to the
server and use `externalSort` / `externalFilter`:

```svelte
<SvGrid
  {data}
  columns={columns}
  features={features}
  externalSort={true}
  externalFilter={true}
  onSortingChange={async (clauses) => { data = await fetchPage({ sort: clauses }) }}
  onFiltersChange={async (f)       => { data = await fetchPage({ filters: f.columns }) }}
/>
```

See [server-side filter with TanStack Query](./server-side-filter-with-tanstack-query.md)
for cancellation, debounce, and request dedup.

## GraphQL

Same shape, different transport. The grid still receives a flat
array; the GraphQL layer is just how you obtain it.

```ts
import { request, gql } from 'graphql-request'

async function fetchOrders(vars: { page: number; sort?: string; filter?: object }) {
  const q = gql`
    query Orders($page: Int!, $sort: String, $filter: OrderFilter) {
      orders(page: $page, sort: $sort, filter: $filter) {
        items { id company product sellDate quantity price country }
        total
      }
    }
  `
  return request('/graphql', q, vars)
}
```

Live in [demo 72 (GraphQL adapter)](https://svgrid.com/#/demos/72-graphql-adapter)
- includes a side panel showing the generated GraphQL document.

## See also

- [Server-side data](../help/server-side-data.md)
- [Server-side filter with TanStack Query](./server-side-filter-with-tanstack-query.md)
- [Cursor-based infinite scroll](./cursor-based-infinite-scroll.md)

<!-- =================================================================
     /recipes/million-rows  (community)
     ================================================================== -->

# 1 million rows with virtualization

> Live in [demo 78-million-rows](https://svgrid.com/#/demos/78-million-rows).

## When

Row + column virtualization configured for very wide / very tall data.

## How

Key API surface:

- `virtualization={true}`
- `columnVirtualization={true}`
- `overscan + columnOverscan`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 78-million-rows source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/78-million-rows.svelte)
- [Demo 78-million-rows prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/78-million-rows.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/mobile-card-pivot  (community)
     ================================================================== -->

# Mobile card view with grid-on-desktop

> Live in [demo 81-mobile-card-view](https://svgrid.com/#/demos/81-mobile-card-view).

## When

Same data, two layouts. Auto-pivot below 720px or force one via a toolbar switch.

## How

Key API surface:

- `window.innerWidth listener`
- `shared $state array between the two views`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 81-mobile-card-view source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/81-mobile-card-view.svelte)
- [Demo 81-mobile-card-view prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/81-mobile-card-view.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/multi-sheet-export  (community)
     ================================================================== -->

# Multi-sheet xlsx export

> Live in [demo 59-export-multi-sheet](https://svgrid.com/#/demos/59-export-multi-sheet).

## When

One workbook, multiple tabs - one per group / region / period.

## How

Key API surface:

- `api.exportData({ format: 'xlsx', sheets: [{ label, rows }, ...] })`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 59-export-multi-sheet source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/59-export-multi-sheet.svelte)
- [Demo 59-export-multi-sheet prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/59-export-multi-sheet.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/nl-filter  (community)
     ================================================================== -->

# NL filter wired to your LLM

> Live in [demo 51-ai-assistant](https://svgrid.com/#/demos/51-ai-assistant).

## When

"show last quarter > $10k sorted by date" - one natural-language input drives setFilter + setSort.

## How

Key API surface:

- `api.ai.filter(query)`
- `setAIProvider(adapter)`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 51-ai-assistant source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/51-ai-assistant.svelte)
- [Demo 51-ai-assistant prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/51-ai-assistant.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/persist-column-layout-to-url  (community)
     ================================================================== -->

# Persist column layout to URL

Goal: when a user sorts, filters, or pages the grid, the URL updates so
that copy-pasting the link gives the recipient the same view. On
reload the grid restores from the URL.

## What lives in the URL

Stick to the slices that are cheap to serialise and unambiguous to
parse:

- **sort**: `Array<{ id, desc }>` → JSON
- **filters**: `Array<{ id, operator, value }>` → JSON
- **page** + **pageSize**: numbers

Column width, pinning, and visibility persist better in `localStorage`
than in the URL - they're per-user, not per-link. See
[Saved views](../help/saved-views.md) for that pattern.

## Implementation

```svelte
<script lang="ts">
  import {
    SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
    type SvGridApi,
  } from 'sv-grid-community'

  const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })

  type SortClause = { id: string; desc: boolean }
  type FilterClause = { id: string; operator: string; value: string }

  function readUrl() {
    if (typeof window === 'undefined') return { sort: [], filters: [], page: 0 }
    const p = new URLSearchParams(window.location.search)
    return {
      sort:    p.get('sort')    ? (JSON.parse(p.get('sort')!) as SortClause[])    : [],
      filters: p.get('filters') ? (JSON.parse(p.get('filters')!) as FilterClause[]) : [],
      page:    p.get('page')    ? Number(p.get('page')) : 0,
    }
  }
  const initial = readUrl()

  let sort    = $state<SortClause[]>(initial.sort)
  let filters = $state<FilterClause[]>(initial.filters)
  let page    = $state<number>(initial.page)
  let api     = $state<SvGridApi<typeof features, Order> | null>(null)

  // Debounced write-back so a rapid filter input doesn't hammer history.
  let writeTimer: ReturnType<typeof setTimeout> | null = null
  function writeUrl() {
    if (writeTimer) clearTimeout(writeTimer)
    writeTimer = setTimeout(() => {
      const p = new URLSearchParams()
      if (sort.length)    p.set('sort',    JSON.stringify(sort))
      if (filters.length) p.set('filters', JSON.stringify(filters))
      if (page > 0)       p.set('page',    String(page))
      const qs = p.toString()
      const next = qs ? `?${qs}` : window.location.pathname
      window.history.replaceState(null, '', next)
    }, 200)
  }

  $effect(() => { sort; filters; page; writeUrl() })

  // Restore on mount via the imperative API. The grid owns the UI
  // state; we re-apply through setSort/setFilter so the menus reflect
  // the restored values.
  function onApiReady(next: SvGridApi<typeof features, Order>) {
    api = next
    for (const s of initial.sort)    api.setSort(s.id, s.desc ? 'desc' : 'asc')
    for (const f of initial.filters) api.setFilter(f.id, { operator: f.operator as any, value: f.value })
  }
</script>

<SvGrid
  data={rows}
  columns={columns}
  features={features}
  filterMode="menu"
  showPagination={true}
  pageSize={25}
  onApiReady={onApiReady}
  onSortingChange={(next) => (sort = next)}
  onFiltersChange={(next) => (filters = next.columns)}
/>
```

## Notes

- **`replaceState` not `pushState`** - sort/filter changes shouldn't
  pollute the browser history. The user pressing Back should leave
  the page, not undo their last filter.
- **Debounce the write, not the read** - reading the URL on mount
  needs to be synchronous so the grid renders with the right state.
  The write-back is what's noisy.
- **`?sort=` URLs survive page reloads** without needing a server -
  the `URLSearchParams` parse happens client-side. Perfect for
  Vite/SvelteKit static deploys.
- **`hashchange`** is a fine alternative if your router uses `#/`
  (the gallery does). Replace `window.location.search` with
  `window.location.hash.split('?')[1]` and `window.history.replaceState`
  with `window.location.hash = ...`.
- **Sharing tip**: add a "Copy link" button next to the grid header
  that does `navigator.clipboard.writeText(window.location.href)`. The
  link is already the view.

## See also

- [Filter API](../help/filtering/filter-api.md)
- [Row sorting](../help/rows/row-sorting.md)
- [Saved views](../help/saved-views.md) - for the multi-view picker
  pattern beyond URL state

<!-- =================================================================
     /recipes/pin-first-column  (community)
     ================================================================== -->

# Pin first column on horizontal scroll

> Live in [demo 25-column-pinning](https://svgrid.com/#/demos/25-column-pinning).

## When

Wide grids where the row-label column must stay visible while the data scrolls horizontally.

## How

Key API surface:

- `api.setColumnPinning({ left: ['id'] })`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 25-column-pinning source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/25-column-pinning.svelte)
- [Demo 25-column-pinning prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/25-column-pinning.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/profiling-with-fps-hud  (community)
     ================================================================== -->

# Profiling with a live FPS HUD

> Drop a tiny perf HUD next to any grid in development. Measures FPS,
> last-frame budget, and live DOM row count - every animation frame.
> Behind a dev-only flag in production.

## When

You're trying to figure out:

- Why does sorting feel sluggish on this dataset?
- Is the row virtualiser actually working - or am I rendering 10k DOM rows?
- Which user action spikes my frame time over the 16.7ms budget?

A reload-and-check-Lighthouse loop is too slow for that. A live HUD
puts the numbers right next to the grid as you interact.

## The pattern

Three pieces:

1. **A `requestAnimationFrame` loop** that measures the delta between
   frames and pushes it onto a ring buffer.
2. **A live readout** (FPS, last-frame ms, budget bar) bound to that buffer.
3. **A DOM row counter** that queries `.sv-grid-row` to confirm
   virtualisation is keeping the live row count bounded.

## Implementation

```svelte
<script lang="ts">
  /** Number of recent frames to average over. ~60 = 1s @ 60Hz. */
  const WINDOW = 60
  /** Length of the trace ring buffer. ~120 = 2s @ 60Hz. */
  const TRACE_LEN = 120

  let fps         = $state<number>(60)
  let lastFrameMs = $state<number>(0)
  let visibleRows = $state<number>(0)
  let trace       = $state<number[]>(Array(TRACE_LEN).fill(0))
  let running     = $state<boolean>(true)

  $effect(() => {
    if (!running) return
    let last = performance.now()
    const frameTimes: number[] = []
    let raf = 0

    function tick(now: number) {
      const dt = now - last
      last = now
      lastFrameMs = Math.round(dt * 10) / 10
      frameTimes.push(dt)
      if (frameTimes.length > WINDOW) frameTimes.shift()

      const avg = frameTimes.reduce((a, b) => a + b, 0) / frameTimes.length
      fps = Math.round(1000 / avg)
      trace = [...trace.slice(1), Math.min(40, dt)]

      // Count actual rendered <tr>s. With virtualisation, this stays
      // bounded regardless of dataset size.
      const counted = document.querySelectorAll('.sv-grid-row').length
      if (counted > 0) visibleRows = counted

      raf = requestAnimationFrame(tick)
    }
    raf = requestAnimationFrame(tick)
    return () => cancelAnimationFrame(raf)
  })
</script>

{#if running}
  <aside class="hud">
    <div>FPS: <strong>{fps}</strong> / 60</div>
    <div class:warn={lastFrameMs > 16.7} class:bad={lastFrameMs > 33.3}>
      Frame: <strong>{lastFrameMs}</strong> ms
    </div>
    <div>DOM rows: <strong>{visibleRows}</strong></div>
    <svg viewBox="0 0 480 40" preserveAspectRatio="none">
      <!-- 16.7ms target line -->
      <line x1="0" y1="22" x2="480" y2="22" stroke="#94a3b8" stroke-dasharray="2 2" />
      <!-- Frame-time trace -->
      <path d={trace.map((p, i) => `${i === 0 ? 'M' : 'L'}${i * (480 / (TRACE_LEN - 1))},${40 - (Math.min(p, 40) / 40) * 36 - 2}`).join(' ')}
            fill="none" stroke="#6366f1" stroke-width="1.4" />
    </svg>
  </aside>
{/if}
```

## Stress your own grid

Wire toolbar buttons to spike the engine while you watch the trace:

```svelte
<script lang="ts">
  let api = $state<SvGridApi<TF, TD> | null>(null)

  function spamSort() {
    if (!api) return
    api.setSort('price', Math.random() > 0.5 ? 'desc' : 'asc')
  }
  function spamFilter() {
    if (!api) return
    const pick = ['AAPL', 'GOOG', 'NVDA', 'TSLA'][Math.floor(Math.random() * 4)]!
    api.setFilter('sym', { operator: 'equals', value: pick })
  }
  function clearAll() {
    if (!api) return
    api.clearSort()
    api.clearAllFilters()
  }
</script>
```

Each click should produce one visible spike on the trace. If a spike
sustains over multiple frames, the work is too heavy for a single
frame budget - move it off the main thread or memoise the inputs.

## Reading the numbers

| Metric          | Healthy        | Investigate                              |
| --------------- | -------------- | ---------------------------------------- |
| FPS             | ≥ 55           | < 30 during interaction = animation jank |
| Frame time      | ≤ 16.7 ms      | > 33 ms = consistently missed frames     |
| DOM rows        | < 100 always   | Growing with dataset = virtualiser off   |
| Frame trace     | flat baseline  | Sustained plateau = synchronous work     |

If DOM rows grows linearly with dataset size, double-check
`svelteVirtualizer` is in your `tableFeatures` and `containerHeight`
is bounded (not `auto`).

## Shipping behind a flag

Mount the HUD only when a dev flag is set:

```svelte
{#if import.meta.env.DEV && localStorage.getItem('svgrid:hud') === 'on'}
  <FpsHud />
{/if}
```

Toggle from the console: `localStorage.setItem('svgrid:hud', 'on')`.

## Demo

The runnable companion: [Demo 132 - Profiler dashboard (gallery)](https://svgrid.com/#/demos/132-profiler-dashboard) - drop this HUD around a 50,000-row grid and use the spam buttons.

## See also

- [Bundle size reference](../reference/bundle-size.md) - what each feature costs
- [Benchmark harness recipe](./benchmark-harness.md) - measure across grid sizes
- [Grid state inspector recipe](./grid-state-inspector.md) - the matching debug panel
- [Million rows recipe](./million-rows.md) - virtualisation in anger

<!-- =================================================================
     /recipes/role-based-editing  (community)
     ================================================================== -->

# Role-based editable columns

> Live in [demo 41-healthcare-emr](https://svgrid.com/#/demos/41-healthcare-emr).

## When

Different user roles can edit different cells; the grid hides editors per-row via the editable callback.

## How

Key API surface:

- `editable: (ctx) => ctx.row.original.allowedBy.includes(role)`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 41-healthcare-emr source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/41-healthcare-emr.svelte)
- [Demo 41-healthcare-emr prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/41-healthcare-emr.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/saved-filter-sets  (community)
     ================================================================== -->

# Saved filter sets

> Live in [demo 64-filter-between-operator](https://svgrid.com/#/demos/64-filter-between-operator).

## When

Name and recall named filter combinations; round-trip via api.getFilters / setFilter.

## How

Key API surface:

- `api.getFilters()`
- `api.setFilter(id, filter)`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 64-filter-between-operator source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/64-filter-between-operator.svelte)
- [Demo 64-filter-between-operator prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/64-filter-between-operator.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/saved-views  (community)
     ================================================================== -->

# Saved views (localStorage)

Per-user grid layouts. Each "view" snapshots column widths, pinning,
sort, filter, page index, and (optionally) grouping. Switching views
restores the snapshot.

```svelte
<script lang="ts">
  import { SvGrid, type SvGridApi } from 'sv-grid-community'

  type View = {
    name: string
    widths:  Record<string, number>
    pinning: { left: string[]; right: string[] }
    sort:    Array<{ id: string; desc: boolean }>
    filters: Record<string, { operator: string; value: string; valueTo?: string }>
  }

  const KEY = 'svgrid:views'
  let api = $state<SvGridApi<typeof features, Order> | null>(null)
  let views = $state<View[]>(JSON.parse(localStorage.getItem(KEY) ?? '[]'))

  function save(name: string) {
    if (!api) return
    const v: View = {
      name,
      widths:  api.getColumnWidths(),
      pinning: api.getColumnPinning(),
      sort:    [], // hook into your sort state
      filters: api.getFilters(),
    }
    views = [...views.filter((x) => x.name !== name), v]
    localStorage.setItem(KEY, JSON.stringify(views))
  }

  function load(v: View) {
    if (!api) return
    for (const [id, w] of Object.entries(v.widths)) api.setColumnWidth(id, w)
    api.setColumnPinning(v.pinning)
    for (const [id, f] of Object.entries(v.filters)) api.setFilter(id, f as never)
  }
</script>

<div class="view-bar">
  {#each views as v (v.name)}
    <button onclick={() => load(v)}>{v.name}</button>
  {/each}
  <button onclick={() => save(prompt('Name?') ?? 'View')}>Save current</button>
</div>

<SvGrid data={rows} columns={columns} features={features}
  onApiReady={(next) => (api = next)} />
```

## GDPR / HIPAA tip

The snapshot stores column STATE only - never row VALUES. If you
were to save `api.getDisplayedRows()` you'd land row data in
localStorage; don't. See [GDPR + data residency](../compliance/gdpr.md).

## See also

- [Demo 63 (Column layout API)](https://svgrid.com/#/demos/63-column-layout-api) - live
- [State maintenance](../help/state-maintenance.md) - undo/redo + bookmarks + JSON IO
- [Persist column layout to URL](./persist-column-layout-to-url.md) - shareable links

<!-- =================================================================
     /recipes/server-side-filter-with-tanstack-query  (community)
     ================================================================== -->

# Server-side filter with TanStack Query

Goal: drive the grid from a real API. Sort + filter + page round-trip
to the server; the response goes into [TanStack Query](https://tanstack.com/query)
so we get **caching, deduplication, request cancellation, retries,
optimistic updates, and stale-while-revalidate** for free.

The same pattern works with any data-fetching library (SWR for React,
swrev for Svelte, hand-rolled `$effect`). TanStack Query is what most
teams reach for in Svelte 5 today.

## Setup

```bash
pnpm add @tanstack/svelte-query@^5
```

```svelte
<!-- +layout.svelte (root) -->
<script lang="ts">
  import { QueryClient, QueryClientProvider } from '@tanstack/svelte-query'

  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 30_000,  // 30 s
        gcTime: 5 * 60_000, // 5 min
        retry: 1,
      },
    },
  })

  let { children } = $props()
</script>

<QueryClientProvider client={queryClient}>
  {@render children()}
</QueryClientProvider>
```

## The grid

The grid runs in `externalSort` + `externalFilter` mode so it records
the user's intent but doesn't try to re-order rows it didn't fetch.
Every change to sort / filter / page bumps the query key; TanStack
Query handles the rest.

```svelte
<script lang="ts">
  import {
    SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,
    type ColumnDef,
  } from 'sv-grid-community'
  import { createQuery } from '@tanstack/svelte-query'

  const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })

  type Person = { id: string; firstName: string; lastName: string; salary: number }

  type SortClause   = { id: string; desc: boolean }
  type FilterClause = { id: string; operator: string; value: string }

  let sort    = $state<SortClause[]>([])
  let filters = $state<FilterClause[]>([])
  let page    = $state(0)
  const pageSize = 25

  // The query key contains every input that affects the response.
  // TanStack Query caches per-key, so navigating back to a previous
  // sort/filter is instant.
  const query = createQuery({
    get queryKey() {
      return ['people', { sort, filters, page, pageSize }] as const
    },
    queryFn: async ({ signal }) => {
      const url = `/api/people?` + new URLSearchParams({
        sort:    JSON.stringify(sort),
        filters: JSON.stringify(filters),
        page:    String(page),
        size:    String(pageSize),
      })
      const res = await fetch(url, { signal })
      if (!res.ok) throw new Error(`HTTP ${res.status}`)
      return res.json() as Promise<{ rows: Person[]; total: number }>
    },
    // While a new query is in flight, keep showing the previous page's
    // rows so the grid doesn't blank out on every keystroke.
    placeholderData: (prev) => prev,
  })

  const columns: ColumnDef<typeof features, Person>[] = [
    { field: 'firstName', header: 'First',  width: 160 },
    { field: 'lastName',  header: 'Last',   width: 160 },
    { field: 'salary',    header: 'Salary', width: 140,
      format: { type: 'currency', currency: 'USD' } },
  ]
</script>

<SvGrid
  data={$query.data?.rows ?? []}
  columns={columns}
  features={features}
  filterMode="menu"
  externalSort={true}
  externalFilter={true}
  loading={$query.isFetching}
  showPagination={false}
  onSortingChange={(next) => { sort    = next;          page = 0 }}
  onFiltersChange={(next) => { filters = next.columns;  page = 0 }}
/>

<nav>
  <button onclick={() => (page = Math.max(0, page - 1))}
          disabled={page === 0 || $query.isFetching}>‹ Prev</button>
  <span>
    Page {page + 1} of {$query.data ? Math.max(1, Math.ceil($query.data.total / pageSize)) : '?'}
  </span>
  <button onclick={() => (page = page + 1)}
          disabled={!$query.data || (page + 1) * pageSize >= $query.data.total || $query.isFetching}>Next ›</button>
</nav>

{#if $query.error}
  <div class="error">{($query.error as Error).message}</div>
{/if}
```

## What TanStack Query gives you here

| Concern                            | How it's solved                                                   |
| ---------------------------------- | ----------------------------------------------------------------- |
| Cancelling a stale request         | `queryFn` receives `signal`; pass it to `fetch`.                  |
| Deduplicating duplicate fetches    | Same query key → one in-flight request.                           |
| Not blanking the grid on refetch   | `placeholderData: (prev) => prev`.                                |
| Caching a page so back-nav is instant | Per-key cache, `staleTime: 30_000` keeps the page fresh.       |
| Retrying transient errors          | `retry: 1` (or a custom retry-delay).                             |
| Showing a loading state            | `$query.isFetching` → `<SvGrid loading={...}>`.                   |
| Errors surfaced to the UI          | `$query.error` is the typed Error from `queryFn`.                 |

## Optimistic edits with `onCellValueChange`

Inline edits should write through immediately AND tell TanStack Query
to invalidate the affected query so the next refetch picks up the
server's authoritative answer.

```svelte
<script lang="ts">
  import { useQueryClient, createMutation } from '@tanstack/svelte-query'

  const qc = useQueryClient()

  const editMutation = createMutation({
    mutationFn: async (e: { rowId: string; columnId: string; value: unknown }) => {
      const res = await fetch(`/api/people/${e.rowId}`, {
        method: 'PATCH',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ [e.columnId]: e.value }),
      })
      if (!res.ok) throw new Error(`HTTP ${res.status}`)
    },
    // Mark every 'people' page stale - the next visible refetch
    // pulls the new value.
    onSuccess: () => qc.invalidateQueries({ queryKey: ['people'] }),
  })
</script>

<SvGrid
  data={$query.data?.rows ?? []}
  columns={columns}
  features={features}
  enableInlineEditing={true}
  onCellValueChange={(e) =>
    $editMutation.mutate({ rowId: e.row.id, columnId: e.columnId, value: e.newValue })
  }
/>
```

The grid has already written the new value into its working copy by
the time `onCellValueChange` fires - the mutation is fire-and-forget.
If the server rejects the change, TanStack Query's refetch restores
the canonical value.

### Explicit rollback (no refetch)

For lower-latency UX or when the server response carries the previous
value, roll back manually instead of waiting for the next refetch. The
pattern: capture the prior value before mutating, and on error call
`api.setCellValue(rowIndex, columnId, priorValue)` to revert the cell.

```ts
const editMutation = createMutation({
  mutationFn: async (e: { rowId: string; columnId: string; value: unknown }) => {
    const res = await fetch(`/api/people/${e.rowId}`, {
      method: 'PATCH',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ [e.columnId]: e.value }),
    })
    if (!res.ok) throw new Error(`HTTP ${res.status}`)
  },
  // Capture the prior cell value AND row index before the mutation
  // runs - we'll need both to rollback on error.
  onMutate: async (e) => {
    const prior = api?.getCellValue(e.rowIndex, e.columnId)
    return { prior, rowIndex: e.rowIndex, columnId: e.columnId }
  },
  onError: (_err, _vars, ctx) => {
    if (api && ctx) api.setCellValue(ctx.rowIndex, ctx.columnId, ctx.prior)
    // Surface the failure - a toast, an inline chip, etc.
  },
  onSuccess: () => qc.invalidateQueries({ queryKey: ['people'] }),
})

// In your <SvGrid onCellValueChange>:
//   $editMutation.mutate({
//     rowId: e.row.id, columnId: e.columnId,
//     value: e.newValue, rowIndex: e.rowIndex,
//   })
```

`api.setCellValue(rowIndex, ...)` takes the data-array index, not the
row id. `onCellValueChange` provides both - capture `e.rowIndex` and
hand it to the mutation context. This works for both inline editors
AND any drawer / modal that funnels through `api.setCellValue` (see
[Form library bridge recipe](./form-library-bridge.md)).

## Visualising the query cache

While debugging cache misses or unexpected refetches, a small side
panel that lists every entry in the cache with its state is invaluable.
The QueryClient exposes `getQueryCache().getAll()` for exactly this.

```svelte
<script lang="ts">
  import { useQueryClient } from '@tanstack/svelte-query'

  const qc = useQueryClient()

  type Snap = { key: string; state: 'fetching' | 'fresh' | 'stale' | 'error' }
  let cacheView = $state<Snap[]>([])

  $effect(() => {
    const cache = qc.getQueryCache()
    const refresh = () => {
      cacheView = cache.getAll().slice(0, 12).map((q) => ({
        key: JSON.stringify(q.queryKey),
        state:
          q.state.fetchStatus === 'fetching' ? 'fetching'
          : q.state.status === 'error'      ? 'error'
          : q.state.isInvalidated           ? 'stale'
          :                                   'fresh',
      }))
    }
    const unsub = cache.subscribe(refresh)
    refresh()
    return unsub
  })
</script>

<aside class="cache-panel">
  <h3>Query cache · {cacheView.length} entries</h3>
  <ul>
    {#each cacheView as q (q.key)}
      <li class="state-{q.state}">
        <code>{q.key}</code>
        <span>{q.state}</span>
      </li>
    {/each}
  </ul>
</aside>
```

The cache subscriber fires for every state transition - including
optimistic mutations, error rollbacks, and the auto-invalidation from
`invalidateQueries`. Pair this with the [grid state inspector](./grid-state-inspector.md)
to debug edge cases where the grid and the cache disagree.

For visual polish, color-code the rows by state: green for `fresh`,
amber for `stale` / `fetching`, red for `error`. The page background
of your devtools panel can use `rgba(99,102,241,0.06)` for an
unobtrusive contrast.

## Notes

- **The query key shape matters.** TanStack Query JSON-stringifies the
  key to compare equality. Use stable property order in the object you
  pass; the example above relies on `sort`, `filters`, `page`,
  `pageSize` in that order.
- **`placeholderData` vs `keepPreviousData`** - v5 renamed
  `keepPreviousData` to `placeholderData: (prev) => prev`. The example
  uses the new shape.
- **The grid is paginated server-side**; the wrapper's built-in pager
  is off (`showPagination={false}`). You render your own pager that
  bumps `page` - that's the only handle TanStack Query needs to
  re-fetch.
- **Total-row counts** are part of the server response. Without them
  the pager can't show "Page X of Y"; with them, the grid stays
  cheap on memory because only one page is in flight at a time.

## See also

- [Server-side data](../help/server-side-data.md) - the patterns
  that apply regardless of which data-fetching library you use
- [`onFiltersChange`](../reference/SvGrid.md#onfilterschangefilters)
- Demo [`09-server-side`](../../examples/src/demos/09-server-side.svelte) -
  the runnable example, without TanStack Query (mock endpoint, 60 ms
  fake latency, abort wiring)

<!-- =================================================================
     /recipes/smart-paste  (community)
     ================================================================== -->

# Smart paste: CSV / TSV / free-form → typed rows

> Live in [demo 75-ai-smart-paste](https://svgrid.com/#/demos/75-ai-smart-paste).

## When

Paste anything; the assistant infers columns and previews typed rows for accept/update/skip.

## How

Key API surface:

- `setAIProvider(...) once at boot`
- `your own parse + map flow`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 75-ai-smart-paste source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/75-ai-smart-paste.svelte)
- [Demo 75-ai-smart-paste prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/75-ai-smart-paste.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/sparkline-cells  (community)
     ================================================================== -->

# Sparkline cell renderer

> Live in [demo 11-stock-market](https://svgrid.com/#/demos/11-stock-market).

## When

In-cell mini-charts of a value series, rendered via inline SVG.

## How

Key API surface:

- `renderSnippet(SparklineCell, { points: row.trend })`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 11-stock-market source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/11-stock-market.svelte)
- [Demo 11-stock-market prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/11-stock-market.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/submit-time-validation  (community)
     ================================================================== -->

# Submit-time validation with error summary

Different from per-keystroke validation. The user edits freely; on
**Submit**, a row-level validator runs and highlights every invalid
cell with an aria-live summary panel.

```svelte
<script lang="ts">
  type Lead = { id: string; company: string; email: string; phone: string }
  type Issue = { rowId: string; field: keyof Lead; message: string }
  let rows = $state<Lead[]>([...])
  let errors = $state<Issue[]>([])
  let submitted = $state<string | null>(null)

  function validate(r: Lead): Issue[] {
    const out: Issue[] = []
    if (!r.company.trim())                                     out.push({ rowId: r.id, field: 'company', message: 'Required' })
    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(r.email))           out.push({ rowId: r.id, field: 'email',   message: 'Malformed' })
    if (r.phone.replace(/\D/g, '').length < 7)                 out.push({ rowId: r.id, field: 'phone',   message: '7+ digits' })
    return out
  }

  function submit() {
    errors = rows.flatMap(validate)
    if (errors.length === 0) submitted = `Submitted ${rows.length} leads`
  }

  const errorsByRow = $derived(() => {
    const m = new Map<string, Set<string>>()
    for (const e of errors) {
      if (!m.has(e.rowId)) m.set(e.rowId, new Set())
      m.get(e.rowId)!.add(e.field as string)
    }
    return m
  })
</script>

<button onclick={submit}>Submit</button>

{#if errors.length > 0}
  <div role="alert" aria-live="polite">
    <p>Fix {errors.length} issue{errors.length === 1 ? '' : 's'}:</p>
    <ul>{#each errors as e (`${e.rowId}-${e.field}`)}<li><code>{e.rowId}</code> · <strong>{e.field}</strong>: {e.message}</li>{/each}</ul>
  </div>
{/if}

<SvGrid {data} {columns} features={features}
  cellClass={(ctx) => errorsByRow().get(ctx.row.original.id)?.has(ctx.column.id) ? 'cell-invalid' : ''}
/>
```

```css
:global(td.cell-invalid) {
  background: rgba(244, 63, 94, 0.12);
  box-shadow: inset 0 0 0 1px #f43f5e;
}
```

Live in [demo 71 (Submit-time validation)](https://svgrid.com/#/demos/71-submit-validation).

## See also

- [Validation while editing](../help/editing/validation.md) - per-keystroke variant
- [Demo 24 (Validation)](https://svgrid.com/#/demos/24-validation) - rejecting bad values inline

<!-- =================================================================
     /recipes/testing-your-grid  (community)
     ================================================================== -->

# Testing your grid

Three strategies for testing a grid in your app. Pick the strategy
that matches the question you're answering.

## TL;DR

| Strategy            | Runner                            | Use for                                      | Cost           |
| ------------------- | --------------------------------- | -------------------------------------------- | -------------- |
| **Unit**            | Vitest                            | Reducer / aggregator / pivot logic           | < 1ms / test   |
| **Component**       | @testing-library/svelte + jsdom   | Mount-time behavior, ARIA, custom renderers  | 5-25ms / test  |
| **E2E**             | Playwright                        | Real browser, scrolling, downloads, screens  | 0.5-2s / test  |

The repo ships all three: vitest config in
`packages/sv-grid-community/vitest.config.ts`, component tests in
`*.behavior.test.ts` files, Playwright specs in `examples/e2e/*.spec.ts`.

## Strategy 1 - Vitest unit

Mock no DOM. Drive the engine directly via `createSvGrid` and assert
on the row model. Fastest, smallest blast radius - perfect for pure
logic (aggregators, custom filter fns, pivot models).

```ts
import { describe, it, expect } from 'vitest'
import {
  createSvGrid,
  createCoreRowModel,
  createSortedRowModel,
  tableFeatures,
  rowSortingFeature,
} from 'sv-grid-community'

const features = tableFeatures({ rowSortingFeature })

describe('row sorting', () => {
  it('sorts rows desc on api call', () => {
    type Row = { x: number }
    const data: Row[] = [{ x: 1 }, { x: 3 }, { x: 2 }]
    let sorting: Array<{ id: string; desc: boolean }> = []

    const table = createSvGrid({
      _features: features,
      _rowModels: {
        coreRowModel:   createCoreRowModel<Row>(),
        sortedRowModel: createSortedRowModel<Row>(),
      },
      data,
      columns: [{ field: 'x' }],
      state: { sorting },
      onSortingChange: (u) => {
        sorting = typeof u === 'function' ? (u as (s: typeof sorting) => typeof sorting)(sorting) : u
      },
      enableSorting: true,
    } as never)

    table.setSorting([{ id: 'x', desc: true }])
    const rows = table.getRowModel().rows.map((r) => (r.original as Row).x)
    expect(rows).toEqual([3, 2, 1])
  })
})
```

Notes:
- `_rowModels` must be passed explicitly when bypassing `<SvGrid>` -
  the component wires them for you, the headless path doesn't.

## Strategy 2 - Component (testing-library)

Mount the real `<SvGrid>` component into jsdom. Assert on accessible
names, roles, `aria-sort`, etc. This is where you catch
regressions in custom cell renderers and headers.

```ts
import { describe, it, expect } from 'vitest'
import { render, screen, fireEvent } from '@testing-library/svelte'
import { SvGrid, tableFeatures, rowSortingFeature } from 'sv-grid-community'

const features = tableFeatures({ rowSortingFeature })

describe('<SvGrid> header', () => {
  it('toggles aria-sort on column-header click', async () => {
    const props = {
      data: [{ x: 1 }, { x: 3 }, { x: 2 }],
      columns: [{ field: 'x', header: 'X' }],
      features,
    }
    render(SvGrid, props)
    const header = screen.getByRole('columnheader', { name: /X/ })
    expect(header).toHaveAttribute('aria-sort', 'none')
    await fireEvent.click(header)
    expect(header).toHaveAttribute('aria-sort', 'ascending')
  })
})
```

Notes:
- jsdom doesn't implement `ResizeObserver` or layout - so virtualisation
  numbers aren't realistic here. Component tests are about *behavior*,
  not perf.
- For ARIA assertions, lean on `@testing-library/jest-dom` matchers.

## Strategy 3 - Playwright E2E

Drive a real Chromium / WebKit / Firefox. Cover the things only a real
browser does correctly: scrolling, downloads, screenshots, multi-tab.

```ts
import { test, expect } from '@playwright/test'

test('large dataset paints the last row after scroll', async ({ page }) => {
  await page.goto('/demos/06-large-dataset')
  await expect(page.getByRole('grid')).toBeVisible()
  await page.locator('.sv-grid-body').evaluate((el) => {
    (el as HTMLElement).scrollTop = (el as HTMLElement).scrollHeight
  })
  await expect(page.getByText('Row 99999')).toBeVisible()
  await page.screenshot({ path: 'large-dataset-bottom.png' })
})

test('export button downloads xlsx', async ({ page }) => {
  await page.goto('/demos/21-export-and-print')
  const [download] = await Promise.all([
    page.waitForEvent('download'),
    page.getByRole('button', { name: /Export Excel/ }).click(),
  ])
  expect(download.suggestedFilename()).toContain('.xlsx')
})
```

Notes:
- Run `npx playwright install` once to pull the browsers.
- Use trace viewer (`--trace on`) when a test flakes - usually it's a
  missing `await page.waitForLoadState('networkidle')`.

## Picking by question

| Question                                                          | Strategy   |
| ----------------------------------------------------------------- | ---------- |
| Does my custom `cell:` function return the right value?           | Unit       |
| Does my `createPivotModel` config produce the right subtotals?    | Unit       |
| Does clicking the header set `aria-sort`?                         | Component  |
| Does my snippet render the badge for `status === 'overdue'`?      | Component  |
| Does scroll-to-bottom paint the last row of 100k?                 | E2E        |
| Does Export download an actual `.xlsx`?                           | E2E        |
| Does the grid still look right on a real laptop in Safari?        | E2E        |

## See also

- [`packages/sv-grid-community/vitest.config.ts`](https://github.com/sv-grid/sv-grid/blob/main/packages/sv-grid-community/vitest.config.ts) - the live config
- [`*.behavior.test.ts` files](https://github.com/sv-grid/sv-grid/tree/main/packages/sv-grid-community/src) - component-test examples
- [`examples/e2e/`](https://github.com/sv-grid/sv-grid/tree/main/examples/e2e) - Playwright specs
- [Architecture overview](../help/architecture.md) - what's headless vs what's rendered

<!-- =================================================================
     /recipes/theme-matched-export  (community)
     ================================================================== -->

# Theme-matched xlsx export

> Live in [demo 56-export-theme-matched](https://svgrid.com/#/demos/56-export-theme-matched).

## When

Excel file colours follow the same --sg-* tokens the grid renders with.

## How

Key API surface:

- `api.exportData({ format: 'xlsx', styles: { ... } })`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 56-export-theme-matched source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/56-export-theme-matched.svelte)
- [Demo 56-export-theme-matched prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/56-export-theme-matched.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/theme-presets  (community)
     ================================================================== -->

# Theme tokens for Ant / MUI / Fluent / shadcn

> Live in [demo 74-theme-integrations](https://svgrid.com/#/demos/74-theme-integrations).

## When

Map your design system's tokens to --sg-* and the grid re-skins.

## How

Key API surface:

- `CSS custom properties only - no JS API`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 74-theme-integrations source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/74-theme-integrations.svelte)
- [Demo 74-theme-integrations prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/74-theme-integrations.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/two-grid-master-detail  (community)
     ================================================================== -->

# Two-grid master / detail

Goal: one grid shows the **master** (parents - orders, customers,
projects, …), a second grid below shows the **detail** for whichever
row is selected (line items, contacts, tasks, …).

This is one of the highest-leverage patterns in any back-office UI.
Both halves are plain `<SvGrid>` instances; the wiring is one
`$derived` and one `onRowSelectionChange` callback.

## Implementation

```svelte
<script lang="ts">
  import {
    SvGrid, tableFeatures, rowSortingFeature, rowSelectionFeature,
    type ColumnDef,
  } from 'sv-grid-community'

  const features = tableFeatures({ rowSortingFeature, rowSelectionFeature })

  type Order = { id: string; customer: string; date: string; total: number }
  type LineItem = { sku: string; name: string; qty: number; unit: number }

  const orders: Order[] = [
    { id: 'O-1001', customer: 'Acme',    date: '2026-05-10', total: 1284.50 },
    { id: 'O-1002', customer: 'Globex',  date: '2026-05-11', total:  312.00 },
    { id: 'O-1003', customer: 'Initech', date: '2026-05-12', total: 5812.20 },
  ]
  const lines: Record<string, LineItem[]> = {
    'O-1001': [
      { sku: 'A-1', name: 'Widget',         qty: 4, unit:   12.00 },
      { sku: 'B-7', name: 'Sprocket',       qty: 2, unit:   25.50 },
      { sku: 'C-3', name: 'Gizmo Premium',  qty: 1, unit: 1186.50 },
    ],
    'O-1002': [{ sku: 'A-1', name: 'Widget', qty: 26, unit: 12.00 }],
    'O-1003': [
      { sku: 'D-2', name: 'Machined frame', qty: 1, unit: 4812.20 },
      { sku: 'E-9', name: 'Service plan',   qty: 1, unit: 1000.00 },
    ],
  }

  let selectedOrderId = $state<string | null>(orders[0]?.id ?? null)
  const detailRows = $derived(selectedOrderId ? lines[selectedOrderId] ?? [] : [])
</script>

<section class="flex flex-col gap-3 h-full">
  <div class="flex-1 min-h-0">
    <SvGrid
      data={orders}
      columns={[
        { field: 'id',       header: 'Order',    width: 120 },
        { field: 'customer', header: 'Customer', width: 200 },
        { field: 'date',     header: 'Date',     width: 120,
          format: { type: 'date', pattern: 'y-m-d' } },
        { field: 'total',    header: 'Total',    width: 130,
          format: { type: 'currency', currency: 'USD' } },
      ] satisfies ColumnDef<typeof features, Order>[]}
      features={features}
      selectionMode="row"
      showRowSelection={true}
      onRowSelectionChange={(_, selectedRows) => {
        selectedOrderId = selectedRows[0]?.id ?? null
      }}
      containerHeight="100%"
    />
  </div>

  <div class="flex-1 min-h-0">
    {#key selectedOrderId}
      <SvGrid
        data={detailRows}
        columns={[
          { field: 'sku',  header: 'SKU',  width: 100 },
          { field: 'name', header: 'Item', width: 220 },
          { field: 'qty',  header: 'Qty',  width:  80 },
          { field: 'unit', header: 'Unit', width: 130,
            format: { type: 'currency', currency: 'USD' } },
        ] satisfies ColumnDef<typeof features, LineItem>[]}
        features={features}
        containerHeight="100%"
      />
    {/key}
  </div>
</section>
```

## Why `{#key selectedOrderId}` around the detail grid

The detail grid's `data` prop is a different array reference per
selected order. The `{#key}` block forces Svelte to **remount** the
inner grid when `selectedOrderId` changes. That ensures:

- Sort + scroll + selection state in the detail grid **resets** to its
  defaults on every selection change (otherwise you scroll the new
  data with the previous grid's scroll position).
- Cell-edit state (if you have it) doesn't leak from one detail view
  to the next.

If you'd rather keep the detail grid's state across master selections
(rare but sometimes wanted), drop the `{#key}` block.

## Alternative: one grid with expansion

If the relationship is hierarchical and you want the line items
inline, use the [tree-rows](../help/rows/tree-rows.md) pattern with
`rowExpandingFeature`. The two-grid pattern shines when:

- The detail has **different columns** than the master.
- The detail needs **its own sort / filter / pagination**.
- You want the master to stay visible while the user scrolls
  through long detail lists.

## Multi-selection master, joined detail

When the user can select **multiple** master rows, the detail grid
shows the union of line items:

```svelte
<script lang="ts">
  let selectedOrders = $state<Order[]>([])
  const detailRows = $derived(selectedOrders.flatMap((o) => lines[o.id] ?? []))
</script>
```

You'll typically want an extra "Order" column on the detail grid so
the joined list stays attributable:

```ts
const detailColumns = [
  { field: 'orderId', header: 'Order', width: 120 },
  // ...
]
```

## See also

- [Row selection](../help/rows/styling-rows.md)
- [Tree rows](../help/rows/tree-rows.md) - one-grid alternative
- Demo [`08-tree-and-master-detail`](../../examples/src/demos/08-tree-and-master-detail.svelte)

<!-- =================================================================
     /recipes/undo-redo-edits  (community)
     ================================================================== -->

# Undo / redo for grid edits

> Live in [demo 55-state-maintenance](https://svgrid.com/#/demos/55-state-maintenance).

## When

Maintain a history stack of cell edits; Ctrl+Z / Ctrl+Y replay backwards / forwards.

## How

Key API surface:

- `onCellValueChange records {rowId, field, before, after}`
- `Ctrl+Z replays inverse`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 55-state-maintenance source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/55-state-maintenance.svelte)
- [Demo 55-state-maintenance prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/55-state-maintenance.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /recipes/use-svgrid-from-react  (community)
     ================================================================== -->

# Use SvGrid from React (custom-element bridge)

SvGrid is Svelte-5-native, but you can drop it into a React app via a thin **custom element** wrapper. The wrapper publishes one `<sv-grid-element>` tag, React renders it like any other DOM element, and data + columns cross the boundary as serialised properties.

> **When to choose this.** You have a React app and only need the grid in one place (an admin tool, a back-office screen). You want SvGrid's headless engine + virtualization + Excel-style filters without rewriting your stack in Svelte.
>
> **When NOT to choose this.** You need rich JSX cell renderers, React-Query / Recoil / Redux state inside cells, or you'd want to embed React Suspense / Portals in cell bodies. For deeper React integration, use our sister product [htmlelements.com](https://www.htmlelements.com) - purpose-built for React/Angular/Vue/web-components.

## What crosses the boundary

| Across cleanly | Needs a workaround |
| --- | --- |
| `data` (array of plain objects) | Snippet-based cell renderers (`renderSnippet`) - use `cellClass` + `format` + the HTML-string renderer below instead |
| `columns` (array of `ColumnDef` literals) | Svelte components as cell content |
| All built-in editors (`text`, `number`, `select`, `date`, `checkbox`, `textarea`, `list`, `chips`, `rich-select`) | React components inside the grid |
| Sort / filter / group / virtualization | React Suspense, Portals, Context inside cells |
| `onCellValueChange`, `onCellSelectionChange`, `onSortingChange`, `onFiltersChange`, `onRowSelectionChange`, `onColumnOrderChange` → `CustomEvent`s | Two-way `bind:` (use one-way property + event readback) |

## 1. Author the custom element

In your Svelte package (a thin wrapper over `sv-grid-community`):

```svelte
<!-- packages/sv-grid-element/src/SvGridElement.svelte -->
<svelte:options customElement={{
  tag: 'sv-grid-element',
  // Map DOM attributes / JS properties onto Svelte props.
  // 'json' types let React pass arrays / objects via .data = [...]
  props: {
    data:           { type: 'Object', reflect: false },  // Array<TData>
    columns:        { type: 'Object', reflect: false },  // Array<ColumnDef>
    rowHeight:      { type: 'Number', reflect: false },
    enableInlineEditing: { type: 'Boolean', reflect: false },
    enableCellSelection: { type: 'Boolean', reflect: false },
    filterLocale:   { type: 'String',  reflect: false },
    enableColumnReorder: { type: 'Boolean', reflect: false },
  },
}} />

<script lang="ts">
  import {
    SvGrid, tableFeatures,
    rowSortingFeature, columnFilteringFeature,
    rowSelectionFeature, rowPaginationFeature,
  } from 'sv-grid-community'

  // Re-export every prop the React side might want to set.
  let {
    data = [],
    columns = [],
    rowHeight = 32,
    enableInlineEditing = false,
    enableCellSelection = true,
    filterLocale = undefined,
    enableColumnReorder = false,
  }: {
    data: ReadonlyArray<Record<string, unknown>>
    columns: ReadonlyArray<unknown>
    rowHeight?: number
    enableInlineEditing?: boolean
    enableCellSelection?: boolean
    filterLocale?: string
    enableColumnReorder?: boolean
  } = $props()

  const features = tableFeatures({
    rowSortingFeature,
    columnFilteringFeature,
    rowSelectionFeature,
    rowPaginationFeature,
  })

  // Bridge SvGrid's callback props onto DOM CustomEvents so the React
  // side can do `el.addEventListener('cellvaluechange', ...)`.
  function emit(name: string, detail: unknown) {
    const host = (event?.currentTarget as HTMLElement | undefined) ?? document
    host.dispatchEvent(new CustomEvent(name, { detail, bubbles: true, composed: true }))
  }
</script>

<SvGrid
  data={data as never[]}
  columns={columns as never[]}
  {features}
  {rowHeight}
  {enableInlineEditing}
  {enableCellSelection}
  {filterLocale}
  {enableColumnReorder}
  filterMode="menu"
  containerHeight="100%"
  showPagination={false}
  enableRowSummaries={false}
  onCellValueChange={(e) => emit('cellvaluechange', e)}
  onCellSelectionChange={(ranges) => emit('cellselectionchange', { ranges })}
  onSortingChange={(s) => emit('sortingchange', { sorting: s })}
  onFiltersChange={(f) => emit('filterschange', f)}
  onRowSelectionChange={(sel, rows) => emit('rowselectionchange', { selection: sel, rows })}
  onColumnOrderChange={(order) => emit('columnorderchange', { order })}
/>
```

Build it (`vite build --lib`, `svelte-package`, or any custom-element target):

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { svelte } from '@sveltejs/vite-plugin-svelte'

export default defineConfig({
  plugins: [svelte({ compilerOptions: { customElement: true } })],
  build: {
    lib: {
      entry: 'src/SvGridElement.svelte',
      name:  'SvGridElement',
      formats: ['es'],
      fileName: 'sv-grid-element',
    },
  },
})
```

Publish as `@your-org/sv-grid-element` (or vendor the built file straight into your React app).

## 2. Use it from React

```tsx
// App.tsx
import { useEffect, useRef, useState } from 'react'
import '@your-org/sv-grid-element' // side-effect: registers <sv-grid-element>

type Row = { id: string; name: string; status: 'active' | 'inactive'; salary: number }

// Tell TypeScript the custom element is a valid JSX tag.
declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'sv-grid-element': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>
    }
  }
}

export default function GridScreen() {
  const ref = useRef<HTMLElement | null>(null)
  const [rows, setRows] = useState<Row[]>([
    { id: 'P-1', name: 'Ada Lovelace',  status: 'active',   salary: 145_000 },
    { id: 'P-2', name: 'Linus Torvalds', status: 'active',  salary: 188_000 },
    { id: 'P-3', name: 'Grace Hopper',   status: 'inactive', salary: 152_000 },
  ])

  // Push data + columns onto the custom element via .properties (not
  // attributes - attributes are strings, properties keep object identity).
  useEffect(() => {
    if (!ref.current) return
    ;(ref.current as any).data = rows
    ;(ref.current as any).columns = [
      { field: 'id',     header: 'ID',     width: 100, editable: false },
      { field: 'name',   header: 'Name',   width: 220, editorType: 'text' },
      { field: 'status', header: 'Status', width: 130, editorType: 'select',
        editorOptions: ['active', 'inactive'],
        // Built-in styling via cellClass survives the boundary fine - it's
        // a function, but plain JS without Svelte/React state inside.
        cellClass: (ctx: { getValue: () => unknown }) =>
          ctx.getValue() === 'active' ? 'pill ok' : 'pill bad' },
      { field: 'salary', header: 'Salary', width: 140, editorType: 'number',
        align: 'right',
        format: { type: 'number', options: { style: 'currency', currency: 'USD' } } },
    ]
  }, [rows])

  // Listen for grid events. CustomEvent.detail mirrors the callback
  // payloads from the Svelte API verbatim.
  useEffect(() => {
    const el = ref.current
    if (!el) return
    const onEdit = (e: Event) => {
      const { rowIndex, columnId, newValue } = (e as CustomEvent).detail
      setRows((prev) => prev.map((r, i) =>
        i === rowIndex ? { ...r, [columnId]: newValue } : r))
    }
    el.addEventListener('cellvaluechange', onEdit)
    return () => el.removeEventListener('cellvaluechange', onEdit)
  }, [])

  return (
    <div style={{ height: 480 }}>
      <sv-grid-element
        ref={ref as React.RefObject<HTMLElement>}
        // Boolean attrs in JSX: presence = true; pass strings for numbers
        // for SSR safety, then re-apply via property in the effect above.
      />
    </div>
  )
}
```

## 3. Custom cell content (HTML-string renderer)

The biggest constraint of the custom-element bridge is that you can't render a React component INSIDE a cell. For lightweight cases (badges, links, formatted numbers, sparklines built in inline SVG), declare an HTML-string renderer on the column:

```ts
{
  field: 'status',
  header: 'Status',
  width: 110,
  cell: (ctx: { getValue: () => unknown }) => {
    // The grid accepts a returned string and renders it via {@html}.
    const v = String(ctx.getValue())
    const cls = v === 'active' ? 'pill ok' : 'pill bad'
    return `<span class="${cls}">${v}</span>`
  },
}
```

CSS that styles `.pill` lives in your React app's stylesheet - the custom element inherits the page's CSS variables and global classes.

For anything richer (a React `<Avatar>` with hover card, a `<MUI/Chip>`, etc.) you'd need to **portal a React tree into a placeholder element** the grid renders. That's possible but fiddly, and at that point you're better served by [htmlelements.com](https://www.htmlelements.com), which has first-class React bindings.

## 4. Imperative API

`SvGrid`'s API surface - `setFilter`, `setColumnPinning`, `setColumnOrder`, `selectCells`, `getDisplayedRows`, `undo`, `redo`, `openFind`, … - works through `onApiReady`. To expose it across the custom-element boundary, add a `getApi()` method to the wrapper:

```svelte
<!-- inside SvGridElement.svelte -->
<script lang="ts">
  let api: any = null
  // Exposed on the host element as `el.getApi()`.
  export function getApi() { return api }
</script>

<SvGrid ... onApiReady={(next) => (api = next)} />
```

```tsx
// React side
const api = (ref.current as any)?.getApi?.()
api?.setColumnOrder(['id', 'salary', 'name', 'status'])
```

## Caveats - the honest version

- **No React state inside cells.** Cell renderers are HTML strings or built-in formatters; if you need a React component per cell, this bridge isn't enough.
- **No two-way `bind:`.** React sets properties; the wrapper emits `CustomEvent`s for changes. One-way data flow.
- **Theme tokens leak both ways.** The custom element inherits page CSS via the `--sg-*` variables. That's usually a feature; if it isn't, scope the element with a wrapping `<div style="--sg-bg: ...">`.
- **`composed: true` events** cross shadow boundaries. Make sure your React `addEventListener` is on the same element you handed to `ref` - otherwise events from other custom elements on the page can leak through bubbling.
- **Re-renders are coarse.** Reassigning `el.data` is what triggers a re-render. For high-frequency updates (streaming feeds, 10+ updates / sec), prefer setting a single property once per animation frame rather than per delta.

## See also

- [Architecture](../help/architecture.md) - why the engine is headless.
- [Use SvGrid imperatively from outside the component](../help/api-reference.md) - the same API the wrapper hands back.
- [htmlelements.com](https://www.htmlelements.com) - the recommended option for React-first apps.

<!-- =================================================================
     /recipes/websocket-streaming  (community)
     ================================================================== -->

# WebSocket streaming with backpressure

> Live in [demo 34-realtime-orders](https://svgrid.com/#/demos/34-realtime-orders).

## When

Live tick stream with pause / resume / disconnect-and-replay and per-tick delta merge.

## How

Key API surface:

- `onmessage merges into $state`
- `pause flag throttles applies`

See the demo source for the full implementation; this recipe pins the
pattern + the surface so you can copy-paste it confidently. The doc
page that explains the underlying feature in depth is linked from the
[recipes index](./index.md).

## See also

- [Demo 34-realtime-orders source](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/34-realtime-orders.svelte)
- [Demo 34-realtime-orders prompt sidecar](https://github.com/sv-grid/sv-grid/blob/main/examples/src/demos/prompts/34-realtime-orders.md) - drop into an LLM context window
- [Recipes index](./index.md)

<!-- =================================================================
     /reference/auto/index  (community)
     ================================================================== -->

# Auto-generated reference

_Generated from the published TypeScript sources. Do not edit by hand - rerun `node tools/build-reference.mjs`._

For the hand-curated reference (with defaults + behaviour tables),
see [the main reference index](../index.md).

## sv-grid-community

- [`sv-grid-community/core.ts`](./sv-grid-community-core.md) - 45 exports
- [`sv-grid-community/svgrid-wrapper.types.ts`](./sv-grid-community-svgrid-wrapper.types.md) - 3 exports

## sv-grid-pro

- [`sv-grid-pro/export.ts`](./sv-grid-pro-export.md) - 7 exports
- [`sv-grid-pro/pivot.ts`](./sv-grid-pro-pivot.md) - 10 exports
- [`sv-grid-pro/import.ts`](./sv-grid-pro-import.md) - 8 exports
- [`sv-grid-pro/ai.ts`](./sv-grid-pro-ai.md) - 19 exports
- [`sv-grid-pro/install.ts`](./sv-grid-pro-install.md) - 4 exports

<!-- =================================================================
     /reference/auto/sv-grid-community-core  (community)
     ================================================================== -->

# `sv-grid-community` · `core.ts`

Auto-generated. Source: `packages\sv-grid-community\src\core.ts`.

### `type RowData`

_No JSDoc yet._

```ts
export type RowData = Record<string, unknown>
```

### `type Updater`

_No JSDoc yet._

```ts
export type Updater<T> = T | ((prev: T) => T)
```

### `type SortingState`

_No JSDoc yet._

```ts
export type SortingState = Array<{ id: string; desc: boolean }>
```

### `type ColumnFilter`

_No JSDoc yet._

```ts
export type ColumnFilter = { id: string; value: unknown; fn?: keyof typeof filterFns }
```

### `type ColumnFiltersState`

_No JSDoc yet._

```ts
export type ColumnFiltersState = Array<ColumnFilter>
```

### `type PaginationState`

_No JSDoc yet._

```ts
export type PaginationState = { pageIndex: number; pageSize: number }
```

### `type GroupingState`

_No JSDoc yet._

```ts
export type GroupingState = Array<string>
```

### `type ExpandedState`

_No JSDoc yet._

```ts
export type ExpandedState = Record<string, boolean>
```

### `type RowSelectionState`

_No JSDoc yet._

```ts
export type RowSelectionState = Record<string, boolean>
```

### `type ActiveCellState`

_No JSDoc yet._

```ts
export type ActiveCellState = {
  rowIndex: number
  colIndex: number
  cellId: string | null
}
```

### `type TableFeatures`

_No JSDoc yet._

```ts
export type TableFeatures = Record<string, unknown>
```

### `type CellData`

_No JSDoc yet._

```ts
export type CellData = unknown
```

### `type HeaderContext`

_No JSDoc yet._

```ts
export type HeaderContext<TData extends RowData> = {
  header: Header<TData>
  column: Column<TData>
  table: SvGrid<TData>
}
```

### `type CellContext`

_No JSDoc yet._

```ts
export type CellContext<TData extends RowData> = {
  cell: Cell<TData>
  row: Row<TData>
  column: Column<TData>
  table: SvGrid<TData>
  getValue: () => unknown
}
```

### `type CellFormatConfig`

_No JSDoc yet._

```ts
export type CellFormatConfig =
```

### `type CellFormatter`

_No JSDoc yet._

```ts
export type CellFormatter<TData extends RowData> = (context: {
  value: unknown
  row: Row<TData>
  column: Column<TData>
  table: SvGrid<TData>
}) => string
```

### `type ColumnDefTemplate`

_No JSDoc yet._

```ts
export type ColumnDefTemplate<TContext> = string | ((context: TContext) => unknown)
```

### `type ColumnDef`

_No JSDoc yet._

```ts
export type ColumnDef<TFeatures extends TableFeatures, TData extends RowData> = {
  id?: string
  field?: keyof TData & string
  accessorFn?: (row: TData) => unknown
  header?: ColumnDefTemplate<HeaderContext<TData>>
  footer?: ColumnDefTemplate<HeaderContext<TData>>
  cell?: ColumnDefTemplate<CellContext<TData>>
  columns?: Array<ColumnDef<TFeatures, TData>>
  editorType?: 'text' | 'number' | 'date' | 'datetime' | 'checkbox' | 'list' | 'chips'
  /**
   * Gate editing per column or per cell.
   *
   *   - `true` (or omitted): the column is fully editable.
   *   - `false`: the column is read-only - double-click, type-to-edit,
   *     fill-handle drag, Delete, and clipboard paste all skip it.
   *   - `(ctx) => boolean`: evaluated for each cell, so you can lock
   *     individual rows (e.g. by role, status, ownership). Returning
   *     `false` opts the cell out of every editing path, identical to
   *     setting `editable: false` on the whole column for that row.
   *
   * The grid-wide `enableInlineEditing` prop still wins when set to
   * `false`.
   */
  editable?: boolean | ((context: CellContext<TData>) => boolean)
  /**
   * When `false`, this column never shows a sort indicator and clicking
   * its header is a no-op - `api.setSort(thisColumn, ...)` is also
   * ignored. Defaults to `true` (the column participates in sorting as
   * long as `rowSortingFeature` is registered).
   */
  sortable?: boolean
  /**
   * When `false`, this column never shows a filter funnel / menu and
   * `api.setFilter(thisColumn, ...)` is ignored. Defaults to `true` (the
   * column is filterable as long as `columnFilteringFeature` is
   * registered).
   */
  filterable?: boolean
  /**
   * Options for `editorType: 'list' | 'chips'`. Either bare values (the
   * string is both value and label) or `{ value, label }` objects.
   * For `chips` this is optional - when omitted, the chips editor becomes
   * free-form (user types and presses Enter to commit a chip).
   *
   * Pass a function `(row) => options` for row-dependent (cascading)
   * options - e.g. City options that depend on Country in the same row.
   */
  editorOptions?:
    | ReadonlyArray<
        string | number | { value: string | number; label?: string; color?: string }
      >
    | ((
        row: TData,
      ) => ReadonlyArray<
        string | number | { value: string | number; label?: string; color?: string }
      >)
  /** When true, list/chips allow multiple selections. Cell value becomes an array. */
  editorMultiple?: boolean
  /** Separator used when joining array values for the readonly cell display. Defaults to ', '. */
  editorSeparator?: string
  format?: CellFormatConfig
  formatter?: CellFormatter<TData>
  /** Initial column width in pixels. Falls back to the grid's `columnWidth` prop. */
  width?: number
  /**
   * Horizontal alignment for header and body cells. When omitted, the
   * default is inferred from `editorType`:
   *   - `'number' | 'date' | 'datetime'` → `'right'`
   *   - `'checkbox'`                     → `'center'`
   *   - everything else                  → `'left'`
   */
  align?: 'left' | 'center' | 'right'
  /**
   * Per-cell conditional CSS. Two shapes:
   *
   *   - **String** (or array of strings): class name(s) added to the
   *     cell's `<td>` for every row in this column.
   *   - **Function**: invoked per cell with the same `CellContext` shape
   *     the `cell` renderer receives. Return a string, an array of
   *     strings, or an object mapping class names to booleans.
   *
   * Use it for status tinting, conditional bold, "negative number"
   * coloring - anything that's a function of the row's value. Cells
   * still receive their format / cell renderer; the class just
   * augments the rendered `<td>`.
   */
  cellClass?:
    | string
    | ReadonlyArray<string>
    | ((ctx: CellContext<TData>) => string | ReadonlyArray<string> | Record<string, boolean> | undefined | null)
}
```

### `type Column`

_No JSDoc yet._

```ts
export type Column<TData extends RowData> = {
  id: string
  columnDef: ColumnDef<any, TData>
  depth: number
  parentId?: string
  getCanSort: () => boolean
  getCanFilter: () => boolean
  getIsSorted: () => false | 'asc' | 'desc'
  getToggleSortingHandler: () => () => void
}
```

### `type Header`

_No JSDoc yet._

```ts
export type Header<TData extends RowData> = {
  id: string
  isPlaceholder: boolean
  colSpan: number
  column: Column<TData>
  getContext: () => HeaderContext<TData>
}
```

### `type HeaderGroup`

_No JSDoc yet._

```ts
export type HeaderGroup<TData extends RowData> = {
  id: string
  headers: Array<Header<TData>>
}
```

### `type Cell`

_No JSDoc yet._

```ts
export type Cell<TData extends RowData> = {
  id: string
  row: Row<TData>
  column: Column<TData>
  getValue: () => unknown
  getContext: () => CellContext<TData>
}
```

### `type Row`

_No JSDoc yet._

```ts
export type Row<TData extends RowData> = {
  id: string
  index: number
  original: TData
  depth: number
  subRows?: Array<Row<TData>>
  /** Total leaf (data) rows under this group row. Undefined for data rows. */
  leafCount?: number
  getCanExpand: () => boolean
  getIsExpanded: () => boolean
  toggleExpanded: () => void
  getIsSelected: () => boolean
  toggleSelected: () => void
  getAllCells: () => Array<Cell<TData>>
  getCellValueByColumnId: (columnId: string) => unknown
}
```

### `type RowModel`

_No JSDoc yet._

```ts
export type RowModel<TData extends RowData> = {
  rows: Array<Row<TData>>
}
```

### `type Store`

_No JSDoc yet._

```ts
export type Store<T> = {
  readonly state: T
  setState: (updater: (prev: T) => T) => void
  subscribe: (listener: () => void) => () => void
}
```

### `const rowSortingFeature`

_No JSDoc yet._

```ts
export const rowSortingFeature = { key: 'rowSortingFeature' }
```

### `const columnFilteringFeature`

_No JSDoc yet._

```ts
export const columnFilteringFeature = { key: 'columnFilteringFeature' }
```

### `const rowPaginationFeature`

_No JSDoc yet._

```ts
export const rowPaginationFeature = { key: 'rowPaginationFeature' }
```

### `const columnGroupingFeature`

_No JSDoc yet._

```ts
export const columnGroupingFeature = { key: 'columnGroupingFeature' }
```

### `const rowSelectionFeature`

_No JSDoc yet._

```ts
export const rowSelectionFeature = { key: 'rowSelectionFeature' }
```

### `const rowExpandingFeature`

_No JSDoc yet._

```ts
export const rowExpandingFeature = { key: 'rowExpandingFeature' }
```

### `function tableFeatures`

_No JSDoc yet._

```ts
export function tableFeatures<T extends TableFeatures>(features: T): T {
  return features
}
```

### `const sortFns`

_No JSDoc yet._

```ts
export const sortFns = {
  auto: (a: unknown, b: unknown) => String(a).localeCompare(String(b)),
  number: (a: unknown, b: unknown) => Number(a ?? 0) - Number(b ?? 0),
  date: (a: unknown, b: unknown) => {
    const aa = new Date(a as any).getTime()
    const bb = new Date(b as any).getTime()
    return aa - bb
  },
}
```

### `const filterFns`

_No JSDoc yet._

```ts
export const filterFns = {
  includesString: (value: unknown, query: string) =>
    String(value).toLowerCase().includes(query.toLowerCase()),
  equals: (value: unknown, query: unknown) => value === query,
}
```

### `type RowModelFactory`

_No JSDoc yet._

```ts
export type RowModelFactory<TData extends RowData> = (args: {
  table: SvGrid<TData>
  rows: Array<Row<TData>>
}) => Array<Row<TData>>
```

### `function createCoreRowModel`

_No JSDoc yet._

```ts
export function createCoreRowModel<TData extends RowData>(): RowModelFactory<TData> {
  return ({ rows }) => rows
}
```

### `function createFilteredRowModel`

_No JSDoc yet._

```ts
export function createFilteredRowModel<TData extends RowData>(): RowModelFactory<TData> {
  return ({ table, rows }) => {
    const filters: ColumnFiltersState = table.getState().columnFilters ?? []
    if (!filters.length) return rows
    return rows.filter((row) => {
      return filters.every((filter) => {
        const cellValue = row
          .getAllCells()
          .find((cell) => cell.column.id === filter.id)
          ?.getValue()
        const filterFn = filter.fn ? filterFns[filter.fn] : filterFns.includesString
        return filterFn(cellValue, filter.value as any)
      })
    })
  }
}
```

### `function createPaginatedRowModel`

_No JSDoc yet._

```ts
export function createPaginatedRowModel<TData extends RowData>(): RowModelFactory<TData> {
  return ({ table, rows }) => {
    const pagination = table.getState().pagination ?? { pageIndex: 0, pageSize: rows.length || 10 }
    const start = pagination.pageIndex * pagination.pageSize
    return rows.slice(start, start + pagination.pageSize)
  }
}
```

### `function createGroupedRowModel`

_No JSDoc yet._

```ts
export function createGroupedRowModel<TData extends RowData>(): RowModelFactory<TData> {
  return ({ table, rows }) => {
    const grouping: GroupingState = table.getState().grouping ?? []
    if (!grouping.length) return rows
    const columns = table.getAllColumns()

    // Recursively bucket rows by each grouping column in turn. At every level a
    // group row is built that stands in for its children - a non-group column
    // resolves to the value shared by every leaf row, or to undefined when the
    // leaves disagree.
    function buildGroups(
      input: Array<Row<TData>>,
      levelIndex: number,
      depth: number,
      idPrefix: string,
    ): Array<Row<TData>> {
      if (levelIndex >= grouping.length) {
        // Leaves: actual data rows, with their nesting depth recorded.
        return input.map((row) => ({ ...row, depth }))
      }
      const groupKey = grouping[levelIndex]
      if (!groupKey) return input

      const buckets = new Map<string, Array<Row<TData>>>()
      for (const row of input) {
        const value = row.getCellValueByColumnId(groupKey)
        const key = String(value ?? '')
        const list = buckets.get(key) ?? []
        list.push(row)
        buckets.set(key, list)
      }

      const groupRows: Array<Row<TData>> = []
      let index = 0
      buckets.forEach((children, key) => {
        const id = `${idPrefix}_${groupKey}_${key}`
        const subRows = buildGroups(children, levelIndex + 1, depth + 1, id)
        const isDeepest = levelIndex + 1 >= grouping.length
        const leafCount = isDeepest
          ? subRows.length
          : subRows.reduce((sum, sub) => sum + (sub.leafCount ?? 0), 0)

        const resolveColumnValue = (columnId: string): unknown => {
          if (columnId === groupKey) return key
          let resolved: unknown
          let hasResolved = false
          for (const child of children) {
            const childValue = child.getCellValueByColumnId(columnId)
            if (!hasResolved) {
              resolved = childValue
              hasResolved = true
            } else if (childValue !== resolved) {
              return undefined
            }
          }
          return resolved
        }

        const groupOriginal: Record<string, unknown> = {}
        columns.forEach((column) => {
          const field = column.columnDef.field
          if (field) groupOriginal[field] = resolveColumnValue(column.id)
        })

        const groupRow: Row<TData> = {
          id,
          index: index++,
          original: groupOriginal as TData,
          depth,
          subRows,
          leafCount,
          getCanExpand: () => true,
          getIsExpanded: () => Boolean((table.getState().expanded ?? {})[id]),
          toggleExpanded: () => {
            table.setExpanded((prev) => ({ ...prev, [id]: !prev[id] }))
          },
          getIsSelected: () => Boolean((table.getState().rowSelection ?? {})[id]),
          toggleSelected: () => {
            table.setRowSelection((prev) => ({ ...prev, [id]: !prev[id] }))
          },
          getAllCells: () => [],
          getCellValueByColumnId: resolveColumnValue,
        }
        groupRows.push(groupRow)
      })
      return groupRows
    }

    return buildGroups(rows, 0, 0, 'group')
  }
}
```

### `function createExpandedRowModel`

_No JSDoc yet._

```ts
export function createExpandedRowModel<TData extends RowData>(): RowModelFactory<TData> {
  return ({ table, rows }) => {
    const expanded: ExpandedState = table.getState().expanded ?? {}
    const flattened: Array<Row<TData>> = []
    const visit = (row: Row<TData>) => {
      flattened.push(row)
      if (row.subRows?.length && expanded[row.id]) {
        for (const sub of row.subRows) visit(sub)
      }
    }
    for (const row of rows) visit(row)
    return flattened
  }
}
```

### `function createSortedRowModel`

_No JSDoc yet._

```ts
export function createSortedRowModel<TData extends RowData>(
```

### `type SvGridOptions`

_No JSDoc yet._

```ts
export type SvGridOptions<TFeatures extends TableFeatures, TData extends RowData> = {
  _features: TFeatures
  _rowModels?: {
    coreRowModel?: RowModelFactory<TData>
    filteredRowModel?: RowModelFactory<TData>
    sortedRowModel?: RowModelFactory<TData>
    paginatedRowModel?: RowModelFactory<TData>
    groupedRowModel?: RowModelFactory<TData>
    expandedRowModel?: RowModelFactory<TData>
  }
  columns: Array<ColumnDef<TFeatures, TData>>
  data: ReadonlyArray<TData>
  /**
   * Optional row-id resolver. When set, the value it returns becomes
   * `row.id` (and therefore the selection / expansion / edit key). When
   * omitted, ids fall back to the row's array index as a string. Use a
   * stable id (database PK, UUID, etc.) so selection survives reorders.
   */
  getRowId?: (row: TData, index: number) => string
  state?: Partial<Record<string, any>>
  onSortingChange?: (updater: Updater<SortingState>) => void
  onColumnFiltersChange?: (updater: Updater<ColumnFiltersState>) => void
  onPaginationChange?: (updater: Updater<PaginationState>) => void
  onGroupingChange?: (updater: Updater<GroupingState>) => void
  onExpandedChange?: (updater: Updater<ExpandedState>) => void
  onRowSelectionChange?: (updater: Updater<RowSelectionState>) => void
  onActiveCellChange?: (updater: Updater<ActiveCellState>) => void
}
```

### `type SvGrid`

_No JSDoc yet._

```ts
export type SvGrid<TData extends RowData> = {
  store: Store<Record<string, any>>
  optionsStore: Store<Record<string, any>>
  state: Record<string, any>
  getState: () => Record<string, any>
  setOptions: (updater: Updater<Record<string, any>>) => void
  setColumnFilters: (updater: Updater<ColumnFiltersState>) => void
  setPagination: (updater: Updater<PaginationState>) => void
  setGrouping: (updater: Updater<GroupingState>) => void
  setExpanded: (updater: Updater<ExpandedState>) => void
  setRowSelection: (updater: Updater<RowSelectionState>) => void
  setActiveCell: (updater: Updater<ActiveCellState>) => void
  moveActiveCell: (next: { rowDelta?: number; colDelta?: number }) => void
  getAllColumns: () => Array<Column<TData>>
  getHeaderGroups: () => Array<HeaderGroup<TData>>
  getFooterGroups: () => Array<HeaderGroup<TData>>
  getRowModel: () => RowModel<TData>
}
```

### `function createSvGridCore`

_No JSDoc yet._

```ts
export function createSvGridCore<TFeatures extends TableFeatures, TData extends RowData>(
```

### `function isFunction`

_No JSDoc yet._

```ts
export function isFunction(value: unknown): value is (...args: Array<any>) => any {
  return typeof value === 'function'
}
```

<!-- =================================================================
     /reference/auto/sv-grid-community-svgrid-wrapper.types  (community)
     ================================================================== -->

# `sv-grid-community` · `svgrid-wrapper.types.ts`

Auto-generated. Source: `packages\sv-grid-community\src\svgrid-wrapper.types.ts`.

### `type SvGridFilterOperator`

_No JSDoc yet._

```ts
export type SvGridFilterOperator =
```

### `type SvGridApi`

Imperative API exposed via the `<SvGrid onApiReady>` callback. Use it for
data, column, filter, sort, group, and visibility operations from outside
the component.

```ts
export type SvGridApi<
```

### `type SvGridWrapperProps`

_No JSDoc yet._

```ts
export type SvGridWrapperProps<
```

<!-- =================================================================
     /reference/auto/sv-grid-pro-ai  (community)
     ================================================================== -->

# `sv-grid-pro` · `ai.ts`

Auto-generated. Source: `packages\sv-grid-pro\src\ai.ts`.

### `type AIProvider`

Shape every consumer-provided model adapter must implement. Keeping this
tiny (one async call, two response formats) lets the same adapter drive
OpenAI's `chat.completions`, Anthropic's `messages`, a self-hosted
llama.cpp endpoint, or a server-side proxy. The grid only cares that the
provider eventually returns a string we can parse.

```ts
export type AIProvider = (request: AIRequest) => Promise<string>
```

### `type AIRequest`

_No JSDoc yet._

```ts
export type AIRequest = {
  /** Full prompt the grid built for the model. Already includes column
   *  schema and any sampled rows where applicable. */
  prompt: string
  /** When 'json', the provider should ask the model to return strict
   *  JSON only - no prose. We parse the response with JSON.parse and
   *  throw a typed error on failure. */
  responseFormat?: 'text' | 'json'
  /** Honored if the underlying transport supports cancellation. */
  signal?: AbortSignal
  /** Free-form tag for telemetry / logging. One of: 'filter',
   *  'smart-fill', 'summarize', 'classify'. */
  task: AITask
  /** Soft hint to the provider about how many tokens we expect back.
   *  Useful for routing small jobs to a cheaper model. */
  maxOutputTokens?: number
}
```

### `type AITask`

_No JSDoc yet._

```ts
export type AITask = 'filter' | 'smart-fill' | 'summarize' | 'classify'
```

### `function setAIProvider`

Register the model adapter every AI call will route through. Call once
at app boot. Passing `null` clears the provider and AI calls revert to
throwing "no provider" errors.

```ts
export function setAIProvider(p: AIProvider | null): void {
  provider = p
}
```

### `function getAIProvider`

_No JSDoc yet._

```ts
export function getAIProvider(): AIProvider | null {
  return provider
}
```

### `function hasAIProvider`

_No JSDoc yet._

```ts
export function hasAIProvider(): boolean {
  return provider != null
}
```

### `type AIFilterClause`

_No JSDoc yet._

```ts
export type AIFilterClause = {
  field: string
  operator: 'contains' | 'equals' | 'startsWith' | 'greaterThan' | 'lessThan' | 'isBlank'
  value?: string
}
```

### `type AISortClause`

_No JSDoc yet._

```ts
export type AISortClause = { field: string; desc: boolean }
```

### `type AIFilterResult`

_No JSDoc yet._

```ts
export type AIFilterResult = {
  filters: AIFilterClause[]
  sort: AISortClause[]
  /** Plain-English explanation of how the model interpreted the query.
   *  Surface this in the UI so the user can confirm or undo. */
  rationale: string
}
```

### `type AIFilterOptions`

_No JSDoc yet._

```ts
export type AIFilterOptions = {
  /**
   * When true, the helper not only RETURNS the plan but also applies it
   * to the grid via `api.setFilter` / `api.setSort`. Defaults to false
   * so callers can show a preview before committing.
   */
  apply?: boolean
  signal?: AbortSignal
}
```

### `type AISmartFillExample`

_No JSDoc yet._

```ts
export type AISmartFillExample = { input: Record<string, unknown>; output: unknown }
```

### `type AISmartFillResult`

_No JSDoc yet._

```ts
export type AISmartFillResult<TValue = unknown> = {
  field: string
  predictions: Array<{ rowIndex: number; value: TValue; confidence: number }>
  rationale: string
}
```

### `type AISmartFillOptions`

_No JSDoc yet._

```ts
export type AISmartFillOptions = {
  /** Target column - the one whose values we want filled. */
  field: string
  /** Index of rows the model should propose values for. If omitted, every
   *  row whose current `field` value is `null`, `undefined` or `''` is
   *  selected automatically. */
  targetRowIndices?: number[]
  /**
   * Worked examples the user has already filled in. Required - the
   * model needs at least one to know the pattern, two or more to lock
   * the schema. We don't pull these from the grid automatically because
   * "edited" vs "untouched" isn't a state SvGrid exposes today.
   */
  examples: AISmartFillExample[]
  signal?: AbortSignal
}
```

### `type AISummarizeTarget`

_No JSDoc yet._

```ts
export type AISummarizeTarget =
```

### `type AISummary`

_No JSDoc yet._

```ts
export type AISummary = {
  text: string
  bullets: string[]
  /** Field names the model thinks are the most load-bearing for the
   *  story it just told. UI can highlight those columns. */
  highlightedFields: string[]
}
```

### `type AISummarizeOptions`

_No JSDoc yet._

```ts
export type AISummarizeOptions = {
  target: AISummarizeTarget
  /** Optional question the user is trying to answer. Helps the model
   *  bias the summary toward the relevant columns. */
  question?: string
  signal?: AbortSignal
}
```

### `type AIClassifyOptions`

_No JSDoc yet._

```ts
export type AIClassifyOptions = {
  /** Column whose free-text we're classifying. */
  inputField: string
  /** Target column the model should write to. */
  outputField: string
  /** Allowed values. The model is constrained to pick one. */
  classes: string[]
  /** Optional one-line description of each class (acts as a labeling rubric). */
  classDescriptions?: Record<string, string>
  /** Rows to classify. Defaults to all. */
  targetRowIndices?: number[]
  signal?: AbortSignal
}
```

### `type AIClassifyResult`

_No JSDoc yet._

```ts
export type AIClassifyResult = {
  inputField: string
  outputField: string
  predictions: Array<{ rowIndex: number; value: string; confidence: number }>
}
```

### `const mockAIProvider`

A deterministic provider that returns canned, schema-shaped responses
for each task. Wire it in via `setAIProvider(mockAIProvider)` to make
the AI demo work end-to-end without a real model key. Not for production.

```ts
export const mockAIProvider: AIProvider = async (req) => {
  // Tiny artificial delay so the UI's "thinking" state is visible.
  await new Promise((r) => setTimeout(r, 350 + Math.random() * 400))

  if (req.task === 'filter') {
    const q = extractUserQuery(req.prompt)
    return JSON.stringify(buildMockFilter(req.prompt, q))
  }
  if (req.task === 'smart-fill') {
    return JSON.stringify(buildMockSmartFill(req.prompt))
  }
  if (req.task === 'summarize') {
    return JSON.stringify(buildMockSummary(req.prompt))
  }
  if (req.task === 'classify') {
    return JSON.stringify(buildMockClassify(req.prompt))
  }
  return '{}'
}
```

<!-- =================================================================
     /reference/auto/sv-grid-pro-export  (community)
     ================================================================== -->

# `sv-grid-pro` · `export.ts`

Auto-generated. Source: `packages\sv-grid-pro\src\export.ts`.

### `type ExportFormat`

_No JSDoc yet._

```ts
export type ExportFormat = 'xlsx' | 'pdf' | 'csv' | 'tsv' | 'html'
```

### `type ExportColumn`

_No JSDoc yet._

```ts
export type ExportColumn = {
  /** Data field name on the row object. */
  field: string
  /** Header label to render in the exported file. Defaults to `field`. */
  header?: string
}
```

### `type ExportCellStyle`

Per-cell style descriptor. Mirrors a subset of CSS; the keys the
underlying exporter honours are font / colour / background / border /
alignment. Anything else is ignored gracefully.

```ts
export type ExportCellStyle = {
  color?: string
  backgroundColor?: string
  fontWeight?: 'normal' | 'bold' | number
  fontStyle?: 'normal' | 'italic'
  fontSize?: number | string
  fontFamily?: string
  border?: string
  textAlign?: 'left' | 'right' | 'center'
  verticalAlign?: 'top' | 'middle' | 'bottom'
}
```

### `type ExportStyles`

Document-level style. Apply blanket styles to the header row, the
value rows, or selectively per cell-reference (e.g. `'B2'`).

```ts
export type ExportStyles = {
  /** Style applied to every header cell. */
  headerRow?: ExportCellStyle
  /** Style applied to every data row. Even / odd zebra are derived from this if `rowAlternate` is set. */
  rows?: ExportCellStyle
  /** Optional zebra background for odd-indexed rows. */
  rowAlternate?: ExportCellStyle
  /** Per-cell overrides keyed by Excel-style reference (`'A1'`, `'C3'`). */
  cells?: Record<string, ExportCellStyle>
}
```

### `type ExportHeaderFooterLine`

Header / footer entries for xlsx + pdf. Each line is rendered top to
bottom on the page. Embed an image with `{ image: dataUrl }`; embed
text with `{ text: '...', style?: ExportCellStyle }`.

```ts
export type ExportHeaderFooterLine =
```

### `type ExportSheet`

_No JSDoc yet._

```ts
export type ExportSheet<TData> = {
  /** Sheet/tab label. Required. */
  label: string
  /** Rows for this sheet. */
  rows: ReadonlyArray<TData>
  /** Per-sheet columns. Falls back to the top-level `columns` if omitted. */
  columns?: ReadonlyArray<ExportColumn>
  /** Per-sheet styles. */
  styles?: ExportStyles
}
```

### `type ExportOptions`

_No JSDoc yet._

```ts
export type ExportOptions<TData> = {
  format: ExportFormat
  /** Base filename (extension is appended if missing). Defaults to "grid". */
  filename?: string
  /**
   * Columns to include. If omitted, every key of the first row is exported
   * (in original object order) using the field name as the header label.
   */
  columns?: ReadonlyArray<ExportColumn>
  /**
   * Source rows. If omitted, the current displayed rows from the api are used.
   * Provide explicitly when you want to override (e.g. export the whole
   * dataset rather than the filtered view).
   */
  rows?: ReadonlyArray<TData>
  /** PDF only. Page orientation. Defaults to "portrait". */
  pageOrientation?: 'portrait' | 'landscape'
  /**
   * Cell + row styles. Apply once to match a light/dark theme, or per-cell
   * for conditional formatting. xlsx and pdf honour these; csv/tsv ignore
   * them; html bakes them into inline `style=` attributes.
   */
  styles?: ExportStyles
  /** Page header lines (xlsx, pdf, html). Logos go here as `{ image: ... }`. */
  header?: ReadonlyArray<ExportHeaderFooterLine>
  /** Page footer lines. Common pattern: page number on the right. */
  footer?: ReadonlyArray<ExportHeaderFooterLine>
  /**
   * Multi-sheet export (xlsx only). When set, each entry becomes one
   * sheet/tab. The top-level `rows` / `columns` are ignored.
   */
  sheets?: ReadonlyArray<ExportSheet<TData>>
  /**
   * If a row has a column whose value matches one of these field names
   * AND the value looks like a URL or data URL, the cell is exported as
   * an embedded image (xlsx). Defaults to `[]` (no auto-detection).
   */
  imageFields?: ReadonlyArray<string>
  /**
   * Pixel dimensions used when embedding images. Smart's xlsx writer
   * draws the image at this size relative to the cell origin. Defaults
   * to `{ width: 32, height: 32 }`. Set larger for thumbnails, smaller
   * for inline icons.
   */
  imageSize?: { width: number; height: number }
}
```

<!-- =================================================================
     /reference/auto/sv-grid-pro-import  (community)
     ================================================================== -->

# `sv-grid-pro` · `import.ts`

Auto-generated. Source: `packages\sv-grid-pro\src\import.ts`.

### `type ImportFormat`

_No JSDoc yet._

```ts
export type ImportFormat = 'xlsx' | 'csv' | 'tsv' | 'json' | 'auto'
```

### `type ImportColumnMap`

_No JSDoc yet._

```ts
export type ImportColumnMap = Record<string, string>
```

### `type ImportFieldType`

Declared data type per target field. When `columnTypes` is set on
`ImportOptions`, the parser tries to coerce each non-empty cell into
the declared shape and emits an `ImportRowError` when it can't -
stricter than the ad-hoc "looks like a number" fallback.

```ts
export type ImportFieldType =
```

### `type ImportColumnTypes`

_No JSDoc yet._

```ts
export type ImportColumnTypes = Record<string, ImportFieldType>
```

### `type ImportRowError`

_No JSDoc yet._

```ts
export type ImportRowError = {
  /** 0-based row index in the SOURCE file (excluding the header). */
  rowIndex: number
  /** Target field name (the grid's column field), or '*' for whole-row errors. */
  field: string
  message: string
}
```

### `type ImportValidator`

_No JSDoc yet._

```ts
export type ImportValidator<TData> = (
```

### `type ImportOptions`

_No JSDoc yet._

```ts
export type ImportOptions<TData> = {
  /** The file to read. A `File`/`Blob` works for xlsx; a string is treated as
   *  inline CSV/TSV/JSON text. */
  file: File | Blob | string
  /** When 'auto', the format is sniffed from `file.name`'s extension (Files
   *  only), otherwise the function inspects the first characters of the
   *  text payload. */
  format?: ImportFormat
  /**
   * Map source-header -> target-field. Missing entries fall back to the
   * source header verbatim (lowercased + trimmed). Pass `null` for a
   * source header you want to drop on the floor.
   */
  columnMap?: ImportColumnMap
  /**
   * Declared data types per target field. When set, the importer uses
   * strict per-type coercion (`'2024-03-15'` -> ISO date; `'$1,234'`
   * -> 1234 for `number` fields) and emits an `ImportRowError` whenever
   * a value can't be coerced. Fields not listed fall back to the
   * built-in best-effort coercion (currency / number / date sniffing
   * by value shape).
   */
  columnTypes?: ImportColumnTypes
  /** Per-row validator. Returned errors land in `result.errors`. */
  validator?: ImportValidator<TData>
  /** When true, the parsed rows are appended to the grid via
   *  `api.addRows(...)` automatically. Defaults to false (preview mode). */
  commit?: boolean
  /** Where to insert when `commit` is true. Defaults to 'bottom'. */
  commitAt?: 'top' | 'bottom' | number
}
```

### `type ImportResult`

_No JSDoc yet._

```ts
export type ImportResult<TData> = {
  /** Source headers as found in the file, in their original order. */
  headers: string[]
  /** Parsed + mapped rows. Order matches the source. */
  rows: TData[]
  /** All validation errors (zero-length if the file passed clean). */
  errors: ImportRowError[]
  /** Rows skipped because they were entirely blank. */
  skipped: number
  /** Total source rows the parser saw (including blanks and bad rows). */
  total: number
  /** Detected format (resolved from 'auto'). */
  format: Exclude<ImportFormat, 'auto'>
}
```

<!-- =================================================================
     /reference/auto/sv-grid-pro-install  (community)
     ================================================================== -->

# `sv-grid-pro` · `install.ts`

Auto-generated. Source: `packages\sv-grid-pro\src\install.ts`.

### `type ProAIApi`

_No JSDoc yet._

```ts
export type ProAIApi<TData extends RowData> = {
  /** Natural-language -> filter + sort plan (and optionally apply it). */
  filter(query: string, opts?: AIFilterOptions): Promise<AIFilterResult>
  /** Propose values for empty cells based on a few worked examples. */
  smartFill<TValue = unknown>(opts: AISmartFillOptions): Promise<AISmartFillResult<TValue>>
  /** One-paragraph + bullets summary of a row, selection, group, or the whole view. */
  summarize(opts: AISummarizeOptions): Promise<AISummary>
  /** Classify free-text cells into one of a known set of labels. */
  classify(opts: AIClassifyOptions): Promise<AIClassifyResult>
  // TData is referenced so the type stays bound to the row shape even
  // though the helpers all read through `api.getData()`. Lets callers
  // get correct inference downstream without explicit generics.
  readonly _rowType?: TData
}
```

### `type ProPivotApi`

_No JSDoc yet._

```ts
export type ProPivotApi<
```

### `type ProGridApi`

_No JSDoc yet._

```ts
export type ProGridApi<
```

### `function installPro`

Augment a SvGridApi instance with Pro methods (`exportData`, `print`,
`ai.*`). Mutates and returns the same object so existing references
keep working.

If no license key has been set, the Pro methods still function but the
grid shows a small "unlicensed" watermark linking to jqwidgets.com and
the console emits a one-time nudge. Revoked or malformed keys throw on
first call.

```ts
export function installPro<
```

<!-- =================================================================
     /reference/auto/sv-grid-pro-pivot  (community)
     ================================================================== -->

# `sv-grid-pro` · `pivot.ts`

Auto-generated. Source: `packages\sv-grid-pro\src\pivot.ts`.

### `type PivotAggregatorId`

_No JSDoc yet._

```ts
export type PivotAggregatorId =
```

### `type PivotAggregator`

_No JSDoc yet._

```ts
export type PivotAggregator = (values: ReadonlyArray<unknown>) => unknown
```

### `type PivotValueConfig`

_No JSDoc yet._

```ts
export type PivotValueConfig<TData> = {
  /** Row field whose values get aggregated. */
  field: keyof TData & string
  /** Built-in aggregator id, or a custom reducer. */
  agg: PivotAggregatorId | PivotAggregator
  /** Display name in the column header. Defaults to `${field} (${agg})`. */
  label?: string
  /** Optional cell formatter. */
  format?: CellFormatConfig
}
```

### `type PivotConfig`

_No JSDoc yet._

```ts
export type PivotConfig<TData> = {
  /** Outer-most first. Each entry becomes one level of row grouping. */
  rows: ReadonlyArray<keyof TData & string>
  /** Outer-most first. Each entry becomes one level of column grouping. */
  cols: ReadonlyArray<keyof TData & string>
  /** One or more measures aggregated under each column-axis leaf. */
  values: ReadonlyArray<PivotValueConfig<TData>>
  /** Grand-total row at the bottom. Default `true`. */
  grandTotalRow?: boolean
  /** Grand-total column on the right. Default `true`. */
  grandTotalCol?: boolean
  /** Subtotal rows between row groups. Default `true`. */
  rowSubtotals?: boolean
  /** Optional sort for column-axis values per dim level (defaults to alpha). */
  colSort?: (a: unknown, b: unknown, level: number) => number
  /** Optional sort for row-axis values per dim level (defaults to alpha). */
  rowSort?: (a: unknown, b: unknown, level: number) => number
}
```

### `type PivotRowKind`

_No JSDoc yet._

```ts
export type PivotRowKind = 'group' | 'subtotal' | 'leaf' | 'grandTotal'
```

### `type PivotRow`

Shape of one entry in `result.rows`. The first-column label lives at
`__pivotLabel`; every value cell lives at the column id matching the
leaf column generated for its (col-path × measure).

`__pivotParentId` is the `__pivotId` of the row's row-axis parent
(or `null` for top-level groups, the grand-total row, and the one
synthetic "All" row when no row dims are configured). Use it with
`filterCollapsedPivotRows` to hide leaves whose ancestor is
collapsed - that's how expandable pivots are built on top of the
model.

`__pivotExpandable` is `true` for `group` rows that have at least
one descendant. A renderer uses this to decide whether to show a
chevron next to the label.

```ts
export type PivotRow = {
  __pivotId: string
  __pivotKind: PivotRowKind
  __pivotDepth: number
  __pivotLabel: string
  __pivotParentId: string | null
  __pivotExpandable: boolean
  /** Aggregated value cells - keyed by leaf column id. */
  [columnId: string]: unknown
}
```

### `type PivotResult`

_No JSDoc yet._

```ts
export type PivotResult<TFeatures extends TableFeatures> = {
  rows: PivotRow[]
  columns: Array<ColumnDef<TFeatures, PivotRow>>
}
```

### `function createPivotModel`

_No JSDoc yet._

```ts
export function createPivotModel<
```

### `const pivotAggregators`

Public registry of built-in aggregators. Useful for surfacing the
available options in a pivot designer UI.

```ts
export const pivotAggregators: Record<PivotAggregatorId, PivotAggregator> = { ...BUILT_IN_AGGS }
```

### `function filterCollapsedPivotRows`

Filter a `result.rows` array down to only the rows the user should
see given the current expansion state. A row stays in the output if
its entire ancestor chain (via `__pivotParentId`) is in `expandedIds`.

Pass `true` to bypass filtering (everything visible - the default
shape `createPivotModel` already returns). Pass an empty array /
empty Set to collapse every group to its subtotal row.

The result is a new array; the input is not mutated.

```ts
export function filterCollapsedPivotRows(
```

<!-- =================================================================
     /reference/bundle-size  (community)
     ================================================================== -->

# Bundle size

What each feature costs in the final bundle, how to reproduce the
numbers on your branch, and what to do if size matters.

## Per-feature gzipped cost

Numbers from a `rollup -p terser` production build against
`packages/sv-grid-community/dist/`. Each feature is the marginal cost
*above* the baseline core when imported alone.

| Feature                       | gz kB  | Required? | Notes                                          |
| ----------------------------- | -----: | --------- | ---------------------------------------------- |
| **Baseline (engine + render)** | **9.2** | -        | `createSvGrid` + the `<SvGrid>` shell          |
| `rowSortingFeature`           | 1.4    | recommended | Core to the value of a grid                  |
| `columnFilteringFeature`      | 2.1    | recommended | Operator filters + the menu UI                |
| `rowSelectionFeature`         | 1.0    | recommended | Checkbox + range + keyboard shift             |
| `columnGroupingFeature`       | 1.8    | optional  | Group-by; tree-shaken if unused                |
| `rowExpandingFeature`         | 1.5    | optional  | Tree + master-detail expansion                |
| `columnPinningFeature`        | 0.9    | recommended | Pin-left / pin-right; sticky cells            |
| `paginationFeature`           | 0.7    | recommended | Paginated row model                            |
| `columnReorderFeature`        | 1.3    | optional  | Drag-to-reorder columns                        |
| `excelFilters`                | 4.2    | optional  | Set-list + facet count + Excel-style menu     |
| `cellEditing` (built-in)      | 5.8    | recommended | date / number / select / chips / etc.         |
| `fillHandle`                  | 2.6    | optional  | Excel-style fill handle + pattern detector     |
| `undoRedo`                    | 1.1    | optional  | Bounded 200-step history                       |
| `columnVirtualizer`           | 1.6    | recommended | Windowed column rendering                      |
| `svelteVirtualizer`           | 2.4    | recommended | Windowed row rendering                         |

A typical app importing the recommended set ships **~28 kB gzipped**
of grid code.

## sv-grid-pro

Pro pack (export + pivot + AI helpers + import + watermark) adds
~26.4 kB gzipped. xlsx export pulls JSZip as a peer dep
(~22 kB gzipped) on first call to `api.exportData({ format: 'xlsx' })`,
not at module load.

## Reproduce on your branch

```bash
# Build
corepack pnpm --filter sv-grid-community build

# Inspect the dist bundle
npx source-map-explorer packages/sv-grid-community/dist/index.js
```

A treemap opens in your browser. Each block is a source file scaled by
its byte cost in the final bundle. Hover a feature module to see how
much of the total weight it owns.

For a quick gzipped readout:

```bash
node -e "console.log((require('zlib').gzipSync(require('fs').readFileSync('packages/sv-grid-community/dist/index.js')).length / 1024).toFixed(1) + ' kB gz')"
```

## What to do if size matters

1. **Skip the optional features you don't use.** Each item marked
   `optional` in the table is fully tree-shaken when not imported.
2. **Code-split the Pro pack.** `installPro(api)` is async-safe;
   import it dynamically in the route that needs export, not at module
   load: `const { installPro } = await import('sv-grid-pro')`.
3. **Defer xlsx peer deps.** JSZip + pdfMake are imported on first
   `api.exportData` call. They aren't part of the synchronous bundle.
4. **Use the headless engine for read-only views.** When you only need
   to display server-side data with no interaction, `createSvGrid` +
   a 30-line `<table>` renderer saves the `<SvGrid>` shell entirely.
   See the [headless engine reference](./headless-engine.md).

## See also

- [Features reference](./features.md) - what each feature does
- [Headless engine reference](./headless-engine.md) - skip the renderer entirely
- [Going to production guide](../getting-started/6-going-to-production.md)

<!-- =================================================================
     /reference/ColumnDef  (community)
     ================================================================== -->

# `ColumnDef` reference

A column definition is the contract between the grid and one column of
data. Pass an array of these as the `columns` prop to `<SvGrid>`.

```ts
import type { ColumnDef } from 'sv-grid-community'

type Row = { id: string; firstName: string; salary: number; joinedAt: string }

const columns: ColumnDef<{}, Row>[] = [
  { field: 'firstName', header: 'First name' },
  {
    field: 'salary',
    header: 'Salary',
    format: { type: 'currency', currency: 'USD' },
    align: 'right',
  },
]
```

## Type

```ts
type ColumnDef<TFeatures, TData> = {
  // Identity
  id?: string
  field?: keyof TData & string
  accessorFn?: (row: TData) => unknown

  // Rendering
  header?: string | RenderFn
  footer?: string | RenderFn
  cell?:   string | RenderFn
  format?:    CellFormatConfig
  formatter?: CellFormatter<TData>

  // Layout
  width?: number
  align?: 'left' | 'right' | 'center'

  // Editing
  editorType?: 'text' | 'number' | 'date' | 'datetime' | 'checkbox'

  // Grouping (column groups - nested headers)
  columns?: Array<ColumnDef<TFeatures, TData>>
}
```

## Identity

One of `field`, `accessorFn`, or `id` must be set. The grid derives the
column id in that order:

1. Explicit `id` wins if present.
2. Otherwise `field` becomes the id.
3. Otherwise the column gets a synthetic id (`col_0_0`, etc.) - works
   but you can't reference it from the API.

| Field         | Type                              | Notes                                                                  |
| ------------- | --------------------------------- | ---------------------------------------------------------------------- |
| `id`          | `string`                          | Stable column id. Required when you use `accessorFn`.                  |
| `field`       | `keyof TData & string`            | Reads `row[field]`. The clean default.                                 |
| `accessorFn`  | `(row: TData) => unknown`         | Computed value. Pair with `id`.                                        |

## Rendering

| Field       | Type                                            | Notes                                                       |
| ----------- | ----------------------------------------------- | ----------------------------------------------------------- |
| `header`    | `string \| (ctx) => HeaderRender`               | Header label or render snippet/component.                   |
| `footer`    | `string \| (ctx) => HeaderRender`               | Footer label or render. Off by default.                     |
| `cell`      | `string \| (ctx) => CellRender`                 | Body cell render. Use `renderSnippet(YourSnippet, props)`.  |
| `format`    | `CellFormatConfig`                              | Built-in formatter; tree-shakeable. See below.              |
| `formatter` | `(value, row) => string`                        | One-off custom string. Cheaper than a `cell` render fn.     |

### `CellFormatConfig`

```ts
type CellFormatConfig =
  | { type: 'number';   options?: Intl.NumberFormatOptions; locales?: string | string[] }
  | { type: 'currency'; currency: string; options?: Intl.NumberFormatOptions; locales?: string | string[] }
  | { type: 'percent';  options?: Intl.NumberFormatOptions; locales?: string | string[] }
  | { type: 'date';     pattern?: string; options?: Intl.DateTimeFormatOptions; locales?: string | string[] }
  | { type: 'datetime'; pattern?: string; options?: Intl.DateTimeFormatOptions; locales?: string | string[] }
```

The grid caches the underlying `Intl.NumberFormat` /
`Intl.DateTimeFormat` instances by signature so format throughput stays
fast on large datasets.

### `pattern` for date/datetime

Built-in pattern tokens:

| Token  | Replaced with                |
| ------ | ---------------------------- |
| `y`    | 4-digit year                 |
| `yy`   | 2-digit year                 |
| `m`    | 2-digit month                |
| `mmm`  | Short month name             |
| `mmmm` | Long month name              |
| `d`    | 2-digit day                  |
| `H`    | 2-digit hour (24h)           |
| `h`    | 2-digit hour (12h)           |
| `M`    | 2-digit minute               |
| `s`    | 2-digit second               |
| `a`    | am / pm                      |

Example: `{ type: 'date', pattern: 'y-m-d' }` ⇒ `2026-06-05`.

## Layout

| Field   | Type                                 | Notes                                                                                 |
| ------- | ------------------------------------ | ------------------------------------------------------------------------------------- |
| `width` | `number`                             | Initial width in pixels. Falls back to the wrapper's `columnWidth` prop (default 140). |
| `align` | `'left' \| 'right' \| 'center'`      | Header + cell alignment. Inferred from `editorType` when omitted: number/date → right, checkbox → center, else left. |

## Editing

| Field        | Type                                                              | Notes                                                       |
| ------------ | ----------------------------------------------------------------- | ----------------------------------------------------------- |
| `editorType` | `'text' \| 'number' \| 'date' \| 'datetime' \| 'checkbox'`        | Required for the column to be inline-editable.              |

The grid uses `editorType` for two things: which inline editor to
mount when the user presses F2, AND which sort comparator to pick when
sorting. Set it even when you don't need editing if your column is
numeric or date-typed.

## Column groups

| Field     | Type                                       | Notes                                                       |
| --------- | ------------------------------------------ | ----------------------------------------------------------- |
| `columns` | `Array<ColumnDef<TFeatures, TData>>`       | Child columns. Renders this column-def as a header group.   |

Example:

```ts
const columns: ColumnDef<{}, Row>[] = [
  {
    id: 'name',
    header: 'Name',
    columns: [
      { field: 'firstName', header: 'First' },
      { field: 'lastName',  header: 'Last' },
    ],
  },
  { field: 'salary', header: 'Salary' },
]
```

## Custom-cell context

When `cell` is a function, it receives a `CellContext<TData>`:

```ts
type CellContext<TData> = {
  cell:    Cell<TData>
  row:     Row<TData>
  column:  Column<TData>
  table:   SvGrid<TData>
  getValue: () => unknown
}
```

You typically need `ctx.row.original` (the source row) and
`ctx.getValue()`:

```ts
import { renderSnippet } from 'sv-grid-community'

{
  id: 'name',
  header: 'Name',
  accessorFn: (r) => `${r.firstName} ${r.lastName}`,
  cell: (ctx) => renderSnippet(PersonCell, { row: ctx.row.original }),
}
```

## See also

- [`SvGrid`](./SvGrid.md) - where columns are passed in
- [`SvGridApi`](./SvGridApi.md) - imperative add/remove/visibility
- [Cell components](../help/cells/cell-components.md) - the snippet patterns
- [Cell data types](../help/cells/cell-data-types.md) - how `editorType` interacts with sort/filter

<!-- =================================================================
     /reference/features  (community)
     ================================================================== -->

# Features reference

A "feature" is a small bundle of state + helpers the grid engine
checks for when wiring its row-model pipeline. Register only what
you use - each feature ships about 1-2 KB gzipped and adds a small
per-update cost.

```ts
import {
  tableFeatures,
  rowSortingFeature,
  columnFilteringFeature,
  columnGroupingFeature,
  rowExpandingFeature,
  rowPaginationFeature,
  rowSelectionFeature,
} from 'sv-grid-community'

const features = tableFeatures({
  rowSortingFeature,
  columnFilteringFeature,
  rowSelectionFeature,
})
```

The `features` object is the contract the headless core checks for
optional capabilities. The wrapper reads it once at mount and wires
the matching row-model pipeline (core → filtered → sorted → grouped →
expanded). Features you don't register are tree-shaken out.

## The feature catalogue

| Feature                  | Enables                                                    | Topic                                                    |
| ------------------------ | ---------------------------------------------------------- | -------------------------------------------------------- |
| `rowSortingFeature`      | Click headers to sort; Shift-click for multi-sort.         | [Row sorting](../help/rows/row-sorting.md)               |
| `columnFilteringFeature` | Per-column filter menu, global search, filter row.         | [Filter overview](../help/filtering/overview.md)         |
| `rowPaginationFeature`   | Page slicing + the footer pager.                           | [Row pagination](../help/rows/row-pagination.md)         |
| `rowSelectionFeature`    | Checkbox column + Shift/Ctrl multi-select.                 | [Styling rows](../help/rows/styling-rows.md)             |
| `columnGroupingFeature`  | Group-by-column + aggregated footer summaries.             | [Grouping & aggregation](../help/grouping-aggregation.md)|
| `rowExpandingFeature`    | Tree / master-detail expand-collapse.                      | [Tree rows](../help/rows/tree-rows.md)                   |

## `tableFeatures(features)` factory

```ts
function tableFeatures<TFeatures extends Partial<TableFeatures>>(
  features: TFeatures,
): TFeatures
```

Identity at runtime - just a typed pass-through. Its job is to give
TypeScript a precise type for the `features` object that
`<SvGrid features={...}>` and `ColumnDef<TFeatures, TData>` both
consume.

## Row-model factories (headless)

Each feature has a matching row-model factory exported from the
package. When you use the `<SvGrid>` wrapper, the factories get wired
in for you. When you drop down to `createSvGrid` directly, register
them yourself:

```ts
import {
  createSvGrid,
  createCoreRowModel,
  createFilteredRowModel,
  createSortedRowModel,
  createGroupedRowModel,
  createExpandedRowModel,
  createPaginatedRowModel,
  tableFeatures,
  rowSortingFeature,
  columnFilteringFeature,
  rowPaginationFeature,
  sortFns,
  filterFns,
} from 'sv-grid-community'

const grid = createSvGrid({
  _features: tableFeatures({
    rowSortingFeature,
    columnFilteringFeature,
    rowPaginationFeature,
  }),
  _rowModels: {
    coreRowModel:       createCoreRowModel(),
    filteredRowModel:   createFilteredRowModel(),
    sortedRowModel:     createSortedRowModel(sortFns),
    paginatedRowModel:  createPaginatedRowModel(),
  },
  columns,
  data,
})
```

| Factory                    | Order in pipeline | Notes                                                              |
| -------------------------- | ----------------- | ------------------------------------------------------------------ |
| `createCoreRowModel`       | 1                 | Identity. Always required.                                         |
| `createFilteredRowModel`   | 2                 | Applies the grid's `columnFilters` state.                          |
| `createSortedRowModel`     | 3                 | Applies `sorting` state; comparator picked by column `editorType`.|
| `createGroupedRowModel`    | 4                 | Applies `grouping` state; emits group rows.                        |
| `createExpandedRowModel`   | 5                 | Filters out collapsed children.                                    |
| `createPaginatedRowModel`  | 6                 | Slices to the current page. NOT used by the wrapper - see below.   |

> **Wrapper pagination note.** The `<SvGrid>` wrapper does **not** put
> `paginatedRowModel` in the pipeline. It paginates **after** its own
> filter overlays so the filter UI sees the full dataset, not the
> visible page. See [Row pagination](../help/rows/row-pagination.md).

## Sort + filter function registries

### `sortFns`

```ts
import { sortFns } from 'sv-grid-community'

// sortFns.auto   - lexical (default for unknown / mixed types)
// sortFns.number - numeric, NaN-safe
// sortFns.date   - parsed via new Date(...)
```

Pick a comparator yourself by setting the column's `editorType` -
`'number'`, `'date'`, `'datetime'` map to `sortFns.number` /
`sortFns.date` automatically.

### `filterFns`

```ts
import { filterFns } from 'sv-grid-community'

// includesString, equalsString, arrIncludes,
// inNumberRange, isAfter, isBefore, isEmpty, isNotEmpty
```

Reference a filter function by name on a column-filter clause:

```ts
const columnFilters = [{ id: 'age', value: 30, fn: 'equals' }]
```

Extend the registry yourself - it's a plain mutable object:

```ts
import { filterFns } from 'sv-grid-community'

declare module 'sv-grid-community' {
  interface FilterFnsRegistry {
    inListCSV: (value: unknown, query: string) => boolean
  }
}

;(filterFns as any).inListCSV = (value, query) => {
  const items = String(query).split(',').map((s) => s.trim().toLowerCase())
  return items.includes(String(value ?? '').toLowerCase())
}
```

## See also

- [`<SvGrid>`](./SvGrid.md) - where features get passed in
- [`SvGridApi`](./SvGridApi.md) - imperative sort/filter/group setters
- [Why headless?](../why-headless.md) - when to use the row-model factories directly

<!-- =================================================================
     /reference/headless-engine  (community)
     ================================================================== -->

# Headless engine

> `<SvGrid>` is the renderer. `createSvGrid` is the engine that powers
> it. They are independent - you can use the engine without the
> renderer to build a custom UI, drive a server, run logic in a worker,
> or test reducer code.

## What you get from the headless API

`createSvGrid(options)` returns a table object with:

- `getRowModel(): { rows: Row<TData>[] }` - the final post-pipeline row
  list (filtered, sorted, grouped, expanded, paginated)
- `getHeaderGroups(): HeaderGroup<TData>[]` - the multi-level column
  header tree
- `getAllColumns(): Column<TData>[]` - every column object with
  metadata (id, visible, pinned, width)
- `setSorting`, `setColumnFilters`, `setRowSelection`, ... - imperative
  setters that update the engine's internal store

No DOM, no styles, no virtualisation. A `<SvGrid>` consumer never sees
these directly - the renderer reads the row model and emits the
markup.

## When to reach for headless

| Want to...                                       | Use                                         |
| ------------------------------------------------ | ------------------------------------------- |
| Render with a different framework (React, Vue)   | Embed via [`sv-grid-wc`](../help/wc.md) or wrap `createSvGrid` yourself |
| Render as `<table>` for print / email export     | Headless                                    |
| Drive a server-side row model from Node          | Headless                                    |
| Unit-test sort / filter / aggregator logic       | Headless                                    |
| Build a custom virtualised renderer              | Headless + the virtualiser exports          |

For the standard case (rich grid in a Svelte app), use `<SvGrid>`.

## Wiring up - the minimum surface

When you bypass `<SvGrid>`, you must wire the row models you want
explicitly. `<SvGrid>` does this for you under the hood.

```ts
import {
  createSvGrid,
  createCoreRowModel,
  createSortedRowModel,
  createFilteredRowModel,
  tableFeatures,
  rowSortingFeature,
  columnFilteringFeature,
  type ColumnDef,
} from 'sv-grid-community'

type Repo = { name: string; lang: string; stars: number }

const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
const columns: ColumnDef<typeof features, Repo>[] = [
  { field: 'name',  header: 'Name'  },
  { field: 'lang',  header: 'Lang'  },
  { field: 'stars', header: 'Stars' },
]
const data: Repo[] = [/* ... */]

// Reactive state - Svelte 5 $state lifts the engine into reactivity.
type Sort = { id: string; desc: boolean }
type Filter = { id: string; value: unknown }
let sorting       = $state<Sort[]>([])
let columnFilters = $state<Filter[]>([])

const table = $derived.by(() =>
  createSvGrid({
    _features: features,
    _rowModels: {
      coreRowModel:     createCoreRowModel<Repo>(),
      sortedRowModel:   createSortedRowModel<Repo>(),
      filteredRowModel: createFilteredRowModel<Repo>(),
    },
    data,
    columns,
    state: { sorting, columnFilters },
    onSortingChange: (u) =>
      (sorting = typeof u === 'function' ? (u as (s: Sort[]) => Sort[])(sorting) : u),
    onColumnFiltersChange: (u) =>
      (columnFilters = typeof u === 'function' ? (u as (f: Filter[]) => Filter[])(columnFilters) : u),
    enableSorting: true,
    enableColumnFilters: true,
  } as never),
)

const headerGroups = $derived(table.getHeaderGroups())
const rows         = $derived(table.getRowModel().rows)
```

The whole renderer is now under 30 lines of template:

```svelte
<table>
  <thead>
    {#each headerGroups as hg (hg.id)}
      <tr>
        {#each hg.headers as h (h.id)}
          <th onclick={() => toggleSort(h.column.id)}>
            {h.column.columnDef.header}{indicator(h.column.id)}
          </th>
        {/each}
      </tr>
    {/each}
  </thead>
  <tbody>
    {#each rows as r (r.id)}
      <tr>
        {#each columns as col (col.field)}
          <td>{(r.original as Repo)[col.field as keyof Repo] ?? ''}</td>
        {/each}
      </tr>
    {/each}
  </tbody>
</table>
```

## Row model pipeline

The pipeline runs in this order, each step lazy:

```
data → coreRowModel → filteredRowModel → sortedRowModel → groupedRowModel → expandedRowModel → paginatedRowModel
```

Pass only the steps you need into `_rowModels`. Unused steps are
tree-shaken. The example above skips grouping and pagination because
the demo doesn't need them.

## The `state` channel is controlled

Pass `state` in, get change callbacks out. The engine never mutates
your state - it calls your `onXxxChange` handler with the next value
(or an updater function) and re-reads `state` on the next render.

That's why this pattern works with Svelte 5's `$state`: the engine
reads from reactive state and emits to reactive setters; the row model
re-derives on every change.

## See also

- [Features reference](./features.md) - what each feature contributes
- [Architecture overview](../help/architecture.md) - why headless first
- [Build your own feature plugin recipe](../recipes/build-a-feature-plugin.md)
- [Bundle size reference](./bundle-size.md) - what you save by skipping the renderer

<!-- =================================================================
     /reference/index  (community)
     ================================================================== -->

# API reference

The exhaustive surface of the published packages. For walkthroughs +
patterns see [Help](../help/index.md); for first contact see
[Getting started](../getting-started.md).

## sv-grid-community

| Page                          | What's in it                                                          |
| ----------------------------- | --------------------------------------------------------------------- |
| [`<SvGrid>`](./SvGrid.md)     | Every prop and callback on the render component.                      |
| [`SvGridApi`](./SvGridApi.md) | The imperative API: data, columns, sort, filter, group, selection.   |
| [`ColumnDef`](./ColumnDef.md) | Every field on a column definition + the sub-types.                   |
| [Features](./features.md)     | The feature registry + the row-model factory pipeline.                |
| [Headless engine](./headless-engine.md) | `createSvGrid` without `<SvGrid>` - the renderer-free path.  |
| [Bundle size](./bundle-size.md) | Per-feature gzipped cost + reproduction command.                    |

## sv-grid-pro

| Page                  | What's in it                                                          |
| --------------------- | --------------------------------------------------------------------- |
| [Pro reference](./pro.md) | Export, print, import, AI helpers, pivot - the full Pro surface.  |

## Conventions

- **Required props** are listed without a default column.
- **Defaults** in the tables are the values the wrapper supplies when
  you omit the prop. `derived` means the value is computed from
  another prop.
- **Callbacks** all take fully-typed payload objects; the type tables
  show the inferred signature.
- **`TFeatures`** is the type produced by `tableFeatures({...})` -
  pass `typeof features` to keep column-level inference honest.

<!-- =================================================================
     /reference/pro  (pro)
     ================================================================== -->

# Pro reference

Everything that `sv-grid-pro` adds on top of the Community surface.
Install + license: see [Pro feature pack](../pro/README.md).

```ts
import {
  installPro, setLicenseKey,
  exportGrid, printGrid, importData,
  createPivotModel, pivotAggregators,
  setAIProvider, aiFilter, aiSmartFill, aiSummarize, aiClassify,
  type ProGridApi, type ExportOptions, type ImportOptions, type PivotConfig,
} from 'sv-grid-pro'
```

## License

### `setLicenseKey(key)` / `clearLicenseKey()` / `isLicenseKeySet()`

```ts
setLicenseKey('SVPRO-XXXX-XXXX-XXXX')
```

Call once at app startup. Without a key the Pro methods still work
but the grid shows an "unlicensed" watermark + a one-time console
nudge.

### `dismissUnlicensedNudge()`

Hide the console nudge for the rest of the session (useful in tests).

## Augmenting the API

### `installPro(api)`

```ts
function installPro<TFeatures, TData>(
  api: SvGridApi<TFeatures, TData>,
): ProGridApi<TFeatures, TData>
```

Mutates and returns the same api object. After install, the api has
the new methods listed below.

```svelte
<SvGrid
  data={rows} columns={columns} features={features}
  onApiReady={(next) => (api = installPro(next))}
/>
```

## Export

### `pro.exportData(opts)`

```ts
exportData(opts: ExportOptions<TData>): Promise<void>
```

Writes the current view to a file and triggers a download.

```ts
type ExportOptions<TData> = {
  format: 'xlsx' | 'pdf' | 'csv' | 'tsv' | 'html'
  filename?: string                        // base name; extension auto-appended
  columns?: ReadonlyArray<ExportColumn>    // defaults to every key on the first row
  rows?: ReadonlyArray<TData>              // defaults to api.getDisplayedRows()
  pageOrientation?: 'portrait' | 'landscape'  // pdf only

  // Style + branding
  styles?: ExportStyles
  header?: ReadonlyArray<ExportHeaderFooterLine>
  footer?: ReadonlyArray<ExportHeaderFooterLine>

  // Embedded images
  imageFields?: ReadonlyArray<string>

  // Multi-sheet workbook (xlsx only)
  sheets?: ReadonlyArray<ExportSheet<TData>>
}
```

See [Data export](../help/export.md) for the option-by-option
walk-through and the demo links.

### `pro.print(opts?)`

```ts
print(opts?: PrintOptions<TData>): Promise<void>
```

Opens a printable view in a new window with repeat-on-page headers,
optional cover page, configurable page-size + orientation, and a
print-CSS theme.

### Static helpers

If you don't want to install Pro onto the api, use the module-level
helpers directly:

```ts
import { exportGrid, printGrid } from 'sv-grid-pro'
await exportGrid(api, { format: 'xlsx' })
await printGrid(api)
```

## Import

### `pro.importData(opts)`

```ts
importData(opts: ImportOptions<TData>): Promise<ImportResult<TData>>

type ImportOptions<TData> = {
  format?: ImportFormat                   // auto-detected from filename/MIME
  source: File | Blob | string            // file picker result, drag-drop, or inline text
  columns?: ImportColumnMap<TData>        // header-row → field map
  types?: ImportColumnTypes<TData>        // per-field type coercion
  validate?: ImportValidator<TData>       // per-row validation
  preview?: boolean                       // return parsed rows + errors; do NOT commit
}

type ImportResult<TData> = {
  rows: ReadonlyArray<TData>
  errors: ReadonlyArray<ImportRowError>
  summary: { read: number; accepted: number; rejected: number }
}
```

See [Data import](../help/import.md).

## AI

### `setAIProvider(provider)`

```ts
type AIProvider = (req: AIRequest) => Promise<unknown>

setAIProvider(async (req) => {
  // call your model - OpenAI, Anthropic, Ollama, local. ANY provider.
  return { /* shape depends on req.task */ }
})
```

You write one adapter; the four helpers below route through it.

### `pro.ai.filter(query, opts?)`

Natural-language to filter + sort plan.

```ts
await pro.ai.filter('show me churned customers from Q3 sorted by ARR', {
  apply: true,   // also call api.setFilter/setSort with the result
})
```

### `pro.ai.smartFill(opts)`

Propose values for empty cells from a few worked examples.

### `pro.ai.summarize(opts)`

One-paragraph + bullets summary of a row, selection, group, or the
whole view.

### `pro.ai.classify(opts)`

Classify free-text cells into one of a known label set.

Full options + return shapes: [AI assistant](../help/ai.md).

## Pivot

### `createPivotModel(data, config)`

```ts
function createPivotModel<TFeatures, TData>(
  data: ReadonlyArray<TData>,
  config: PivotConfig<TData>,
): PivotResult<TFeatures>

type PivotResult<TFeatures> = {
  rows: PivotRow[]
  columns: Array<ColumnDef<TFeatures, PivotRow>>
}
```

Pure - no DOM, no api required. Hand the result to a regular
`<SvGrid>` instance.

### `pro.pivot.build(config)` / `pro.pivot.buildFrom(data, config)`

Same model, with the live api's `getData()` (or an arbitrary array)
as the source.

### `pivotAggregators`

```ts
type PivotAggregatorId =
  | 'sum' | 'avg' | 'min' | 'max'
  | 'count' | 'countDistinct'
  | 'first' | 'last'
```

A custom aggregator is a plain function: `agg: (values) => something`.

Full reference: [Pivot tables](../help/pivot.md).

## Subpath imports

The package ships per-feature subpaths so you can tree-shake:

```ts
import { exportGrid }      from 'sv-grid-pro/export'
import { importData }      from 'sv-grid-pro/import'
import { aiFilter }        from 'sv-grid-pro/ai'
import { createPivotModel } from 'sv-grid-pro/pivot'
```

If you only need export, the AI plumbing, pivot engine, and import
parser don't ship in your bundle.

## Types

```ts
import type {
  ProGridApi,            // SvGridApi + Pro methods
  ProAIApi,              // .ai namespace shape
  ProPivotApi,           // .pivot namespace shape

  ExportFormat,
  ExportOptions,
  ExportColumn,
  ExportCellStyle,
  ExportStyles,
  ExportHeaderFooterLine,
  ExportSheet,

  ImportFormat,
  ImportOptions,
  ImportResult,
  ImportColumnMap,
  ImportColumnTypes,
  ImportRowError,
  ImportValidator,
  ImportFieldType,

  PivotAggregator,
  PivotAggregatorId,
  PivotConfig,
  PivotResult,
  PivotRow,
  PivotRowKind,
  PivotValueConfig,

  AIProvider,
  AIRequest,
  AITask,
  AIFilterOptions,
  AIFilterResult,
  AIFilterClause,
  AISortClause,
  AISmartFillOptions,
  AISmartFillResult,
  AISmartFillExample,
  AISummarizeOptions,
  AISummarizeTarget,
  AISummary,
  AIClassifyOptions,
  AIClassifyResult,
} from 'sv-grid-pro'
```

<!-- =================================================================
     /reference/SvGrid  (community)
     ================================================================== -->

# `<SvGrid>` reference

The render component. One `<SvGrid>` element per grid instance.

```svelte
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  filterMode="menu"
  showPagination={true}
  pageSize={25}
  onApiReady={(api) => (gridApi = api)}
/>
```

## Required props

| Prop       | Type                                       | Notes                                                                  |
| ---------- | ------------------------------------------ | ---------------------------------------------------------------------- |
| `data`     | `ReadonlyArray<TData>`                     | The row source. Re-rendering on `data` reference change is automatic.   |
| `columns`  | `Array<ColumnDef<TFeatures, TData>>`       | See [ColumnDef reference](./ColumnDef.md).                              |
| `features` | `TFeatures`                                | Build with `tableFeatures({...})`. See [features reference](./features.md). |

## Data state

| Prop           | Type                  | Default              | Notes                                                       |
| -------------- | --------------------- | -------------------- | ----------------------------------------------------------- |
| `loading`      | `boolean`             | `false`              | Shows a built-in loading overlay.                           |
| `error`        | `string \| null`      | `null`               | Shows an error banner inside the shell.                     |
| `emptyMessage` | `string`              | `"No data"`          | Replaces the empty-state copy.                              |

## Layout

| Prop                 | Type                 | Default     | Notes                                                                  |
| -------------------- | -------------------- | ----------- | ---------------------------------------------------------------------- |
| `containerHeight`    | `number \| string`   | `520`       | Pixels (number) or any CSS height (string). Use `'100%'` inside a flex parent. |
| `rowHeight`          | `number`             | `36`        | In pixels. Drives virtualizer math when virtualization is on.          |
| `columnWidth`        | `number`             | `140`       | Default for columns without an explicit `width`.                       |
| `fitColumns`         | `boolean`            | `false`     | Scale columns proportionally to fill the viewport; residue absorbed in the last column. Shrinks down to 85% of natural widths; beyond that the user gets a horizontal scrollbar. |
| `showRowNumbers`     | `boolean`            | `false`     | Leading 1-based row-number column.                                     |
| `rowNumberWidth`     | `number`             | `56`        | Width (px) of the row-number column. Default fits up to "99,999"; bump it for six-figure row counts so the largest number stays fully visible at the bottom of a long scroll. |
| `initialColumnPinning` | `{ left?, right? }`| -           | Seed left/right pinning at mount.                                      |

## Virtualization

| Prop                   | Type      | Default | Notes                                              |
| ---------------------- | --------- | ------- | -------------------------------------------------- |
| `virtualization`       | `boolean` | `true`  | Row virtualization.                                |
| `columnVirtualization` | `boolean` | `true`  | Column virtualization. Disable for sticky-column pinning. |
| `overscan`             | `number`  | `8`     | Rows kept rendered above + below the viewport.     |
| `columnOverscan`       | `number`  | `3`     | Columns kept rendered left + right of the viewport. |

## Filter UI

| Prop                | Type                                       | Default   | Notes                                                                  |
| ------------------- | ------------------------------------------ | --------- | ---------------------------------------------------------------------- |
| `filterMode`        | `'menu' \| 'row' \| 'global' \| 'none'`    | `'menu'`  | Umbrella prop. Overridden per-surface by the three below.              |
| `showGlobalFilter`  | `boolean`                                  | derived   | Show the global search input.                                          |
| `showColumnFilters` | `boolean`                                  | derived   | Show the column-menu filter funnel.                                    |
| `showFilterRow`     | `boolean`                                  | derived   | Show the per-column filter row under the header.                       |
| `showFilterMenu`    | `boolean`                                  | derived   | (Legacy alias for `showColumnFilters`.)                                |
| `externalFilter`    | `boolean`                                  | `false`   | Grid records filter UI state but does NOT filter rows. Pair with `onFiltersChange`. |

## Selection

| Prop                 | Type                                       | Default | Notes                                                |
| -------------------- | ------------------------------------------ | ------- | ---------------------------------------------------- |
| `selectionMode`      | `'both' \| 'row' \| 'cell' \| 'none'`      | `'both'`| Umbrella prop. Overridden per-surface by the two below. |
| `showRowSelection`   | `boolean`                                  | derived | Checkbox column.                                     |
| `enableCellSelection`| `boolean`                                  | derived | Click-and-drag range selection.                      |

## Editing

| Prop                  | Type      | Default | Notes                                                  |
| --------------------- | --------- | ------- | ------------------------------------------------------ |
| `enableInlineEditing` | `boolean` | `false` | Per-column `editorType` still required for a column to be editable. |
| `enableRowSummaries`  | `boolean` | `false` | Footer row with sum/avg/count summaries.               |

## Sort

| Prop           | Type      | Default | Notes                                                          |
| -------------- | --------- | ------- | -------------------------------------------------------------- |
| `externalSort` | `boolean` | `false` | Grid records sort state but does NOT re-order rows. Pair with `onSortingChange`. |

## Pagination

| Prop             | Type      | Default | Notes                                                          |
| ---------------- | --------- | ------- | -------------------------------------------------------------- |
| `showPagination` | `boolean` | `false` | Show the footer pager.                                         |
| `pageSize`       | `number`  | `10`    | Initial page size.                                             |

## Grouping

| Prop                   | Type      | Default | Notes                            |
| ---------------------- | --------- | ------- | -------------------------------- |
| `showGroupingControls` | `boolean` | `false` | Show the group-by toolbar.       |

## Callbacks

All callbacks are optional. None of them are required for the grid to
function - they exist for parents that want to observe or override.

### `onApiReady(api)`

Fires once after mount with the [`SvGridApi`](./SvGridApi.md) for
imperative operations.

### `onSortingChange(sorting)`

```ts
onSortingChange?: (sorting: Array<{ id: string; desc: boolean }>) => void
```

Fires when the user clicks a sort header. With `externalSort={true}`,
this is your hook to re-fetch / re-order the source data.

### `onFiltersChange(filters)`

```ts
onFiltersChange?: (filters: {
  global: string
  columns: Array<{
    id: string
    operator: 'contains' | 'equals' | 'startsWith' | 'greaterThan' | 'lessThan' | 'isBlank'
    value: string
    selectedValues?: Array<string>
  }>
}) => void
```

Fires when the global filter, any column operator filter, or any facet
checklist changes. With `externalFilter={true}`, this is your hook to
re-fetch.

### `onRowSelectionChange(selection, rows)`

```ts
onRowSelectionChange?: (
  selection: Record<string, boolean>,
  rows: TData[],
) => void
```

`selection` is keyed by row index; `rows` is the materialised array of
selected rows.

### `onCellValueChange(event)`

```ts
onCellValueChange?: (event: {
  rowIndex: number
  columnId: string
  oldValue: unknown
  newValue: unknown
  row: TData
}) => void
```

Fires after the grid has written the parsed value back into the row.
Use this for cascading recomputes (line totals, derived columns) and
for sending edits to a server. See [Saving values](../help/editing/saving-values.md).

### `onActiveCellChange(cell)`

```ts
onActiveCellChange?: (cell: {
  rowIndex: number
  colIndex: number
  columnId: string
}) => void
```

Fires every time the active cell changes - click, keyboard move,
Tab, Page Up/Down. Toolbar / ribbon UIs use this to stay synced with
the grid's selection without polling.

## See also

- [`SvGridApi`](./SvGridApi.md) - the imperative API exposed via `onApiReady`
- [`ColumnDef`](./ColumnDef.md) - column-definition shape
- [features](./features.md) - the feature registry
- [Pro extensions](./pro.md) - what `installPro(api)` adds

<!-- =================================================================
     /reference/SvGridApi  (community)
     ================================================================== -->

# `SvGridApi` reference

The imperative API exposed via `<SvGrid onApiReady={(api) => ...}>`.
Use it for data, column, filter, sort, group, selection, and
visibility operations from outside the component.

```ts
import type { SvGridApi } from 'sv-grid-community'

let api = $state<SvGridApi<typeof features, Order> | null>(null)
```

```svelte
<SvGrid
  data={rows}
  columns={columns}
  features={features}
  onApiReady={(next) => (api = next)}
/>

<button onclick={() => api?.addRow({ /* ... */ })}>Add row</button>
```

## Cells

### `getCellValue(rowIndex, columnId)`

```ts
getCellValue(rowIndex: number, columnId: string): unknown
```

Read a cell value from the underlying data. Returns `undefined` when
either argument doesn't resolve.

### `setCellValue(rowIndex, columnId, value)`

```ts
setCellValue(rowIndex: number, columnId: string, value: unknown): void
```

Write a cell value through the column's `field`. Triggers a re-render.
Does NOT fire `onCellValueChange` - that callback is for **user**
edits.

## Rows

### `addRow(row, position?)`

```ts
addRow(row: TData, position?: 'top' | 'bottom' | number): void
```

`position` defaults to `'bottom'`. A numeric index inserts before that
index.

### `addRows(rows, position?)`

```ts
addRows(rows: ReadonlyArray<TData>, position?: 'top' | 'bottom' | number): void
```

Batched insert. Cheaper than calling `addRow` in a loop for hundreds
of rows.

### `removeRow(rowIndex)` / `removeRows(rowIndices)`

```ts
removeRow(rowIndex: number): void
removeRows(rowIndices: ReadonlyArray<number>): void
```

Remove by data-array index (the same index `onCellValueChange` reports).

## Columns

### `addColumn(column, position?)` / `addColumns(columns, position?)`

```ts
addColumn(column: ColumnDef<TFeatures, TData>, position?: 'left' | 'right' | number): void
addColumns(columns: ReadonlyArray<ColumnDef<TFeatures, TData>>, position?: 'left' | 'right' | number): void
```

`position` defaults to `'right'`.

### `removeColumn(columnId)`

```ts
removeColumn(columnId: string): void
```

By id (or `field` when no id was provided).

## Visibility

### `setColumnVisible(columnId, visible)` / `isColumnVisible(columnId)`

```ts
setColumnVisible(columnId: string, visible: boolean): void
isColumnVisible(columnId: string): boolean
```

Hidden columns stay in the column array but don't render.

## Sort

### `setSort(columnId, direction)`

```ts
setSort(columnId: string, direction: 'asc' | 'desc' | null): void
```

Replaces any existing sort. Pass `null` to clear sort on that column.
Multi-sort through the API is on the
[Missing features](../help/missing-features.md) list - the user can
build it themselves with Shift-click on headers.

### `clearSort()`

```ts
clearSort(): void
```

Clear all sort clauses.

## Group

### `setGroupBy(columnIds)`

```ts
setGroupBy(columnIds: ReadonlyArray<string>): void
```

Group by zero or more columns. Replaces any existing group config.

## Filter

### `setFilter(columnId, filter)`

```ts
setFilter(
  columnId: string,
  filter: { operator: SvGridFilterOperator; value?: string } | null,
): void
```

Where `SvGridFilterOperator` is:

```ts
type SvGridFilterOperator =
  | 'contains' | 'equals' | 'startsWith'
  | 'greaterThan' | 'lessThan' | 'isBlank'
```

Pass `null` to clear.

### `clearFilter(columnId)`

```ts
clearFilter(columnId: string): void
```

Clear a single column's filter. (A `clearAllFilters()` helper is on
the [Missing features](../help/missing-features.md) list.)

## Data snapshot

### `getData()`

```ts
getData(): ReadonlyArray<TData>
```

Snapshot of the current internal data array - the grid's working
copy, which reflects every cell edit and `addRow` / `removeRow` since
mount.

### `getDisplayedRows()`

```ts
getDisplayedRows(): ReadonlyArray<TData>
```

Returns the rows that are currently **visible** in the grid - after
filter, sort, and pagination. Use for `pro.exportData(...)` when you
want to export the current view.

## Pro extensions

After `installPro(api)`, the same object also exposes:

```ts
api.exportData(opts)   // see Pro export reference
api.print(opts)
api.importData(opts)
api.ai.filter(...)
api.ai.smartFill(...)
api.ai.summarize(...)
api.ai.classify(...)
api.pivot.build(config)
api.pivot.buildFrom(data, config)
```

See [Pro reference](./pro.md).

<!-- =================================================================
     /why-headless  (community)
     ================================================================== -->

# Why headless?

SvGrid is **headless at the core**, with a fully-styled Svelte component
shipped on top. That two-layer split is deliberate, and worth
understanding before you reach for either.

## What "headless" actually means here

The core - `createSvGrid` from `sv-grid-community/core` - knows about
rows, columns, sorting, filtering, grouping, pagination, expansion, and
selection. It does **not** know about pixels, DOM, ARIA, or CSS. It is
a state machine over your data that you query and mutate from Svelte.

The component - `<SvGrid>` - is one (opinionated) way to render that
state machine into a `<table>`. It is itself written against the
headless core, so the same hooks are available to you if you want to
write your own renderer.

```text
┌──────────────────────────────────────────────────────┐
│  Your app                                            │
└───────────────┬──────────────────────────────────────┘
                │
                ▼
       ┌─────────────────────┐
       │   <SvGrid> (Svelte) │   ← default renderer, ARIA,
       │   FlexRender        │     keyboard, drag handles,
       │   formatters, menus │     theme tokens
       └─────────┬───────────┘
                 │
                 ▼
       ┌─────────────────────┐
       │  createSvGrid()     │   ← rows × cols × state
       │  row models         │     sort / filter / page /
       │  features           │     group / expand
       └─────────────────────┘
```

## What you get from headless

**1. The renderer is replaceable.** Want a virtualised React grid? A
canvas-based renderer for 1 M rows? A read-only `<table>` for a printed
report? `createSvGrid` returns the same state machine for all of them.
You write the markup, you keep the headless brain.

```ts
import { createSvGrid, createCoreRowModel, createSortedRowModel,
         tableFeatures, rowSortingFeature, sortFns } from 'sv-grid-community'

const grid = createSvGrid({
  _features: tableFeatures({ rowSortingFeature }),
  _rowModels: {
    coreRowModel: createCoreRowModel(),
    sortedRowModel: createSortedRowModel(sortFns),
  },
  columns,
  data,
})

// Your own render loop:
for (const row of grid.getRowModel().rows) {
  for (const cell of row.getAllCells()) drawCell(cell)
}
```

**2. Features are opt-in modules.** Monolithic grid libraries ship everything
in one bundle. With SvGrid you only register what you use:

```ts
import { tableFeatures, rowSortingFeature } from 'sv-grid-community'

// no filtering, no grouping, no pagination - none of that code is
// reachable from this grid instance
const features = tableFeatures({ rowSortingFeature })
```

The features object is the contract the headless core checks for
optional capabilities. Each feature ships a small chunk of state +
helpers; if it's not in `tableFeatures()`, the core never asks for it
and Vite tree-shakes away the rest.

**3. Tests are fast and DOM-free.** `createSvGrid` runs without a
browser:

```ts
import { createSvGrid, ... } from 'sv-grid-community'

test('sorts by salary descending', () => {
  const grid = createSvGrid({ ..., state: { sorting: [{ id: 'salary', desc: true }] } })
  const rows = grid.getRowModel().rows
  expect(rows[0]!.getValue('salary')).toBeGreaterThan(rows[1]!.getValue('salary'))
})
```

No JSDOM, no Playwright, no test renderer. The headless contract is the
unit of test.

**4. Server-side rendering is a non-feature.** Because the core has no
DOM, you can call `grid.getRowModel().rows` inside a SvelteKit
`+page.server.ts` and pre-bake the table HTML before it ever reaches
the browser. Demo [`19-ssr`](../examples/src/demos/19-ssr.svelte)
walks through that.

**5. State is yours to own.** Sort clauses, filter predicates, expansion
state, selection state - all of it lives in a `store` you can serialise
to a URL, sync to a query string, or restore from `localStorage`. The
default `<SvGrid>` wires this up for you, but the wires are visible:

```ts
// Persist
localStorage.setItem('grid', JSON.stringify(grid.getState()))

// Restore
const saved = JSON.parse(localStorage.getItem('grid')!)
grid.store.setState((prev) => ({ ...prev, ...saved }))
```

## When the wrapper is the right tool anyway

You won't usually write a custom renderer. `<SvGrid>` is the default
because the 80% case is "I want a table, with sort and filter, that
looks correct". The wrapper:

- handles WAI-ARIA grid semantics, keyboard navigation, focus
  management, copy/paste, range selection;
- wires virtualisation, column resize, fit-to-width, pinning, the
  filter menu, the column menu, the row-number column;
- exposes a `SvGridApi` for data + columns + sort + filter +
  visibility mutations;
- emits callbacks (`onSortingChange`, `onFiltersChange`,
  `onRowSelectionChange`, `onCellValueChange`) for parents that want to
  observe.

Reach for the headless core when:

- you need a renderer the default cannot produce (canvas, mobile-only,
  Excel-export-only),
- you're embedding the grid in an environment without a real DOM (SSR,
  static-site generators, PDF pipelines),
- you want to drive multiple coordinated grids from one state store,
- you're building a higher-level abstraction on top of SvGrid and want
  the headless API as your foundation.

## The trade-off, named

Headless costs you a default theme. You can't `npm install` a
"complete-looking grid" and have it match your app out of the box;
every grid library that promises that has to ship CSS and DOM
assumptions you'll eventually fight.

SvGrid splits the difference: the headless core is its own thing, and
`<SvGrid>` is a *reference renderer* you can copy and modify. The
shipped CSS uses `--sg-*` custom properties so you can re-theme it
without forking. See [Tailwind integration](./help/tailwind.md) for a
worked example.

## See also

- [Getting started](./getting-started.md) - the wrapper-first walkthrough
- [Column definitions](./help/columns/column-definitions.md) - the contract the headless core enforces
- [Filter API](./help/filtering/filter-api.md) - example of headless state surfaced through the wrapper
- [`createSvGrid` source](../packages/sv-grid-community/src/createGrid.svelte.ts)
- Demo [`19-ssr`](../examples/src/demos/19-ssr.svelte) - SSR with the headless core