@svgrid/mcp 3.0.31 → 3.0.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/data.js CHANGED
@@ -909,7 +909,7 @@ export const examples = [
909
909
  "title": "Ai Export And Anomalies",
910
910
  "category": "Data Export & Import",
911
911
  "blurb": "203. AI export + anomaly detection (Enterprise) Natural-language export - type \"export orders over $300 as a grouped PDF by country\" and the AI provider turns it into a { format, filters, groupBy }",
912
- "source": "<script lang=\"ts\">\n /**\n * 203. AI export + anomaly detection (Enterprise)\n * -----------------------------------------------\n * Natural-language export - type \"export orders over $300 as a grouped PDF by\n * country\" and the AI provider turns it into a { format, filters, groupBy }\n * plan that's applied to the grid and downloaded. Plus a one-click anomaly\n * scan over the current view. Wired to the bundled `mockAIProvider` so it\n * runs with no API key; swap in `setAIProvider(yourAdapter)` for a real model.\n */\n import {\n SvGrid,\n tableFeatures,\n rowSortingFeature,\n columnFilteringFeature,\n columnGroupingFeature,\n rowExpandingFeature,\n setAIProvider,\n mockAIProvider,\n aiExport,\n aiFindAnomalies,\n type GridColumns,\n type SvGridApi,\n type AIExportPlan,\n type AIAnomaly,\n } from '@svgrid/grid'\n // Enterprise only supplies the EXPORT ENGINE here (xlsx / pdf). The AI itself\n // is built-in + free above; installEnterprise registers the export engine so\n // the AI's planned export can actually write the file.\n import {\n installEnterprise,\n type EnterpriseGridApi,\n } from '@svgrid/enterprise'\n import { makeOrders, type Order } from '../shared/seed'\n\n setAIProvider(mockAIProvider) // deterministic canned model for the demo\n\n const features = tableFeatures({\n rowSortingFeature,\n columnFilteringFeature,\n columnGroupingFeature,\n rowExpandingFeature,\n })\n\n let rows = $state<Order[]>(makeOrders(200))\n let api = $state<EnterpriseGridApi<typeof features, Order> | null>(null)\n let query = $state('export orders over $300 as a grouped PDF by country')\n let busy = $state(false)\n let plan = $state<AIExportPlan | null>(null)\n let anomalies = $state<AIAnomaly[]>([])\n let anomalySummary = $state('')\n let scanned = $state(false)\n let errorMsg = $state<string | null>(null)\n\n const columns: GridColumns<Order> = [\n { field: 'country', header: 'Country', width: 110 },\n { field: 'company', header: 'Company', width: 150 },\n { field: 'product', header: 'Product', width: 160 },\n { field: 'quantity', header: 'Qty', width: 80, align: 'right', cellDataType: 'number',\n format: { type: 'number', options: { maximumFractionDigits: 0 } } },\n { field: 'price', header: 'Price', width: 110, align: 'right', cellDataType: 'number',\n format: { type: 'currency', currency: 'USD' } },\n ]\n\n function onReady(next: SvGridApi<typeof features, Order>) {\n api = installEnterprise(next)\n }\n\n async function runExport() {\n if (!api || busy) return\n busy = true\n errorMsg = null\n plan = null\n try {\n plan = await aiExport(api, query, { filename: 'ai-export' })\n } catch (err) {\n errorMsg = err instanceof Error ? err.message : String(err)\n } finally {\n busy = false\n }\n }\n\n async function findAnomalies() {\n if (!api || busy) return\n busy = true\n errorMsg = null\n anomalies = []\n anomalySummary = ''\n scanned = false\n try {\n const res = await aiFindAnomalies(api, { target: { kind: 'all' } })\n anomalies = res.anomalies\n anomalySummary = res.summary\n scanned = true\n } catch (err) {\n errorMsg = err instanceof Error ? err.message : String(err)\n } finally {\n busy = false\n }\n }\n</script>\n\n<section class=\"flex flex-col flex-1 min-h-0 gap-3\">\n <div class=\"ai-muted text-sm shrink-0\">\n Describe an export in plain English - the AI turns it into a filter + group +\n format plan and downloads the file (the grid stays as-is). Or scan the view\n for anomalies. Running on the bundled mock model (no API key).\n </div>\n\n <div class=\"flex flex-wrap items-center gap-2 shrink-0\">\n <input\n bind:value={query}\n placeholder=\"e.g. export orders over $300 as a grouped PDF by country\"\n class=\"ai-input flex-1 min-w-[280px] rounded border px-3 py-1.5 text-sm\"\n onkeydown={(e) => e.key === 'Enter' && runExport()}\n />\n <button class=\"btn btn-primary\" disabled={!api || busy} onclick={runExport}>\n {busy ? 'Thinking…' : 'AI export'}\n </button>\n <button class=\"btn\" disabled={!api || busy} onclick={findAnomalies}>Find anomalies</button>\n </div>\n\n {#if errorMsg}\n <p class=\"text-xs text-red-600 dark:text-red-400 shrink-0\">{errorMsg}</p>\n {/if}\n\n {#if plan}\n <div class=\"ai-card shrink-0\">\n <strong>Plan:</strong> format <code>{plan.format}</code>\n {#if plan.groupBy.length}· group by <code>{plan.groupBy.join(', ')}</code>{/if}\n {#if plan.filters.length}· {plan.filters.length} filter(s){/if}\n <div class=\"ai-muted mt-1\">{plan.rationale}</div>\n </div>\n {/if}\n\n {#if scanned}\n <div class=\"ai-card shrink-0\">\n <strong>Anomalies:</strong>\n {anomalySummary || (anomalies.length ? `${anomalies.length} found` : 'No anomalies found in the sample.')}\n {#if anomalies.length}\n <ul class=\"mt-1 list-disc pl-5\">\n {#each anomalies as a, i (i)}\n <li>\n <span class=\"sev sev-{a.severity}\">{a.severity}</span>\n <code>{a.field}</code>{#if a.value != null} = {a.value}{/if} — {a.reason}\n </li>\n {/each}\n </ul>\n {/if}\n </div>\n {/if}\n\n <div class=\"flex-1 min-h-0\">\n <SvGrid responsive={true}\n columnResize\n data={rows}\n columns={columns}\n features={features}\n showGroupingControls={true}\n rowHeight={34}\n containerHeight=\"100%\"\n fitColumns={true}\n onApiReady={onReady}\n />\n </div>\n\n <footer class=\"ai-muted text-xs shrink-0\">\n Built-in + free. <code>aiExport(api, ...)</code> and\n <code>aiFindAnomalies(api, ...)</code> route through your registered\n <code>AIProvider</code> - the grid bundles no model client. This demo uses\n <code>mockAIProvider</code>; the plans are heuristic, not a real model.\n Writing the xlsx / PDF uses the @svgrid/enterprise export engine.\n </footer>\n</section>\n\n<style>\n .ai-muted { color: var(--sg-muted, rgb(100 116 139)); }\n .ai-input {\n border-color: var(--sg-input-border, var(--sg-border, rgb(203 213 225)));\n background: var(--sg-input-bg, var(--sg-bg, #fff));\n color: var(--sg-fg, rgb(15 23 42));\n }\n .btn {\n border-radius: 0.375rem;\n border: 1px solid var(--sg-border, rgb(203 213 225));\n padding: 0.375rem 0.85rem;\n font-size: 0.85rem;\n font-weight: 500;\n background: var(--sg-bg, #fff);\n color: var(--sg-fg, rgb(15 23 42));\n cursor: pointer;\n }\n .btn:disabled { opacity: 0.5; }\n .btn-primary {\n border-color: var(--sg-accent, rgb(79 70 229));\n background: var(--sg-accent, rgb(79 70 229));\n color: var(--sg-on-accent, #fff);\n }\n .ai-card {\n border: 1px solid var(--sg-border, rgb(203 213 225));\n background: var(--sg-header-bg, rgb(248 250 252));\n border-radius: 0.5rem;\n padding: 0.6rem 0.8rem;\n font-size: 0.8rem;\n }\n .sev { font-size: 0.65rem; text-transform: uppercase; font-weight: 700; padding: 1px 6px; border-radius: 999px; margin-right: 4px; }\n .sev-high { background: #fee2e2; color: #991b1b; }\n .sev-medium { background: #fef9c3; color: #854d0e; }\n .sev-low { background: #dcfce7; color: #166534; }\n</style>\n"
912
+ "source": "<script lang=\"ts\">\n /**\n * 203. AI export + anomaly detection (Enterprise)\n * -----------------------------------------------\n * Natural-language export - type \"export orders over $300 as a grouped PDF by\n * country\" and the AI provider turns it into a { format, filters, groupBy }\n * plan that's applied to the grid and downloaded. Plus a one-click anomaly\n * scan over the current view. Wired to the bundled `mockAIProvider` so it\n * runs with no API key; swap in `setAIProvider(yourAdapter)` for a real model.\n */\n import {\n SvGrid,\n tableFeatures,\n rowSortingFeature,\n columnFilteringFeature,\n columnGroupingFeature,\n rowExpandingFeature,\n setAIProvider,\n mockAIProvider,\n aiExport,\n aiFindAnomalies,\n type GridColumns,\n type SvGridApi,\n type AIExportPlan,\n type AIAnomaly,\n } from '@svgrid/grid'\n // Enterprise only supplies the EXPORT ENGINE here (xlsx / pdf). The AI itself\n // is built-in + free above; installEnterprise registers the export engine so\n // the AI's planned export can actually write the file.\n import {\n installEnterprise,\n type EnterpriseGridApi,\n } from '@svgrid/enterprise'\n import { makeOrders, type Order } from '../shared/seed'\n\n setAIProvider(mockAIProvider) // deterministic canned model for the demo\n\n const features = tableFeatures({\n rowSortingFeature,\n columnFilteringFeature,\n columnGroupingFeature,\n rowExpandingFeature,\n })\n\n let rows = $state<Order[]>(makeOrders(200))\n let api = $state<EnterpriseGridApi<typeof features, Order> | null>(null)\n let query = $state('export orders over $300 as a grouped PDF by country')\n let busy = $state(false)\n let plan = $state<AIExportPlan | null>(null)\n let anomalies = $state<AIAnomaly[]>([])\n let anomalySummary = $state('')\n let scanned = $state(false)\n let errorMsg = $state<string | null>(null)\n\n const columns: GridColumns<Order> = [\n { field: 'country', header: 'Country', width: 110 },\n { field: 'company', header: 'Company', width: 150 },\n { field: 'product', header: 'Product', width: 160 },\n { field: 'quantity', header: 'Qty', width: 80, align: 'right', cellDataType: 'number',\n format: { type: 'number', options: { maximumFractionDigits: 0 } } },\n { field: 'price', header: 'Price', width: 110, align: 'right', cellDataType: 'number',\n format: { type: 'currency', currency: 'USD' } },\n ]\n\n function onReady(next: SvGridApi<typeof features, Order>) {\n api = installEnterprise(next)\n }\n\n async function runExport() {\n if (!api || busy) return\n busy = true\n errorMsg = null\n plan = null\n try {\n plan = await aiExport(api, query, { filename: 'ai-export' })\n } catch (err) {\n errorMsg = err instanceof Error ? err.message : String(err)\n } finally {\n busy = false\n }\n }\n\n async function findAnomalies() {\n if (!api || busy) return\n busy = true\n errorMsg = null\n anomalies = []\n anomalySummary = ''\n scanned = false\n try {\n const res = await aiFindAnomalies(api, { target: { kind: 'all' } })\n anomalies = res.anomalies\n anomalySummary = res.summary\n scanned = true\n } catch (err) {\n errorMsg = err instanceof Error ? err.message : String(err)\n } finally {\n busy = false\n }\n }\n</script>\n\n<section class=\"flex flex-col flex-1 min-h-0 gap-3\">\n <div class=\"ai-muted text-sm shrink-0\">\n Describe an export in plain English - the AI turns it into a filter + group +\n format plan and downloads the file (the grid stays as-is). Or scan the view\n for anomalies. Running on the bundled mock model (no API key).\n </div>\n\n <div class=\"flex flex-wrap items-center gap-2 shrink-0\">\n <input\n bind:value={query}\n placeholder=\"e.g. export orders over $300 as a grouped PDF by country\"\n class=\"ai-input flex-1 min-w-[280px] rounded border px-3 py-1.5 text-sm\"\n onkeydown={(e) => e.key === 'Enter' && runExport()}\n />\n <button class=\"btn btn-primary\" disabled={!api || busy} onclick={runExport}>\n {busy ? 'Thinking…' : 'AI export'}\n </button>\n <button class=\"btn\" disabled={!api || busy} onclick={findAnomalies}>Find anomalies</button>\n </div>\n\n {#if errorMsg}\n <p class=\"text-xs text-red-600 dark:text-red-400 shrink-0\">{errorMsg}</p>\n {/if}\n\n {#if plan}\n <div class=\"ai-card shrink-0\">\n <strong>Plan:</strong> format <code>{plan.format}</code>\n {#if plan.groupBy.length}· group by <code>{plan.groupBy.join(', ')}</code>{/if}\n {#if plan.filters.length}· {plan.filters.length} filter(s){/if}\n <div class=\"ai-muted mt-1\">{plan.rationale}</div>\n </div>\n {/if}\n\n {#if scanned}\n <div class=\"ai-card shrink-0\">\n <strong>Anomalies:</strong>\n {anomalySummary || (anomalies.length ? `${anomalies.length} found` : 'No anomalies found in the sample.')}\n {#if anomalies.length}\n <ul class=\"mt-1 list-disc pl-5\">\n {#each anomalies as a, i (i)}\n <li>\n <span class=\"sev sev-{a.severity}\">{a.severity}</span>\n <code>{a.field}</code>{#if a.value != null} = {a.value}{/if} - {a.reason}\n </li>\n {/each}\n </ul>\n {/if}\n </div>\n {/if}\n\n <div class=\"flex-1 min-h-0\">\n <SvGrid responsive={true}\n columnResize\n data={rows}\n columns={columns}\n features={features}\n showGroupingControls={true}\n rowHeight={34}\n containerHeight=\"100%\"\n fitColumns={true}\n onApiReady={onReady}\n />\n </div>\n\n <footer class=\"ai-muted text-xs shrink-0\">\n Built-in + free. <code>aiExport(api, ...)</code> and\n <code>aiFindAnomalies(api, ...)</code> route through your registered\n <code>AIProvider</code> - the grid bundles no model client. This demo uses\n <code>mockAIProvider</code>; the plans are heuristic, not a real model.\n Writing the xlsx / PDF uses the @svgrid/enterprise export engine.\n </footer>\n</section>\n\n<style>\n .ai-muted { color: var(--sg-muted, rgb(100 116 139)); }\n .ai-input {\n border-color: var(--sg-input-border, var(--sg-border, rgb(203 213 225)));\n background: var(--sg-input-bg, var(--sg-bg, #fff));\n color: var(--sg-fg, rgb(15 23 42));\n }\n .btn {\n border-radius: 0.375rem;\n border: 1px solid var(--sg-border, rgb(203 213 225));\n padding: 0.375rem 0.85rem;\n font-size: 0.85rem;\n font-weight: 500;\n background: var(--sg-bg, #fff);\n color: var(--sg-fg, rgb(15 23 42));\n cursor: pointer;\n }\n .btn:disabled { opacity: 0.5; }\n .btn-primary {\n border-color: var(--sg-accent, rgb(79 70 229));\n background: var(--sg-accent, rgb(79 70 229));\n color: var(--sg-on-accent, #fff);\n }\n .ai-card {\n border: 1px solid var(--sg-border, rgb(203 213 225));\n background: var(--sg-header-bg, rgb(248 250 252));\n border-radius: 0.5rem;\n padding: 0.6rem 0.8rem;\n font-size: 0.8rem;\n }\n .sev { font-size: 0.65rem; text-transform: uppercase; font-weight: 700; padding: 1px 6px; border-radius: 999px; margin-right: 4px; }\n .sev-high { background: #fee2e2; color: #991b1b; }\n .sev-medium { background: #fef9c3; color: #854d0e; }\n .sev-low { background: #dcfce7; color: #166534; }\n</style>\n"
913
913
  },
914
914
  {
915
915
  "id": "204-import-dialog",
@@ -1789,7 +1789,7 @@ export const examples = [
1789
1789
  "title": "Pglite Northwind",
1790
1790
  "category": "Studio",
1791
1791
  "blurb": "338. Northwind on PGlite - a real relational Postgres in the browser The classic Northwind sample DB (categories, customers, products, orders, order_details) seeded into PGlite (WASM Postgres). No server, no keys.",
1792
- "source": "<script lang=\"ts\">\n /**\n * 338. Northwind on PGlite - a real relational Postgres in the browser\n * --------------------------------------------------------------------\n * The classic Northwind sample DB (categories, customers, products, orders,\n * order_details) seeded into PGlite (WASM Postgres). No server, no keys.\n *\n * Switch between three entities, each backed by `createSqlDataSource` over\n * the same in-browser database:\n * - Order lines - a five-table JOIN exposed as a VIEW (read-only). The rich\n * denormalized grid a single flat table can't give you.\n * - Products / Customers - base tables with full CRUD; new rows get an\n * auto-generated id from a Postgres IDENTITY sequence.\n *\n * Sort / filter / page all round-trip as real parameterized SQL - watch the\n * statement under the toolbar change as you interact.\n */\n import { PGlite } from '@electric-sql/pglite'\n import { SvGrid, createServerDataSource, type ServerState } from '@svgrid/grid'\n import { SvGridEditPanel, createSqlDataSource, schemaToColumns, type EntitySchema } from '@svgrid/enterprise'\n import SvGridStudio from '../shared/SvGridStudio.svelte'\n import { NORTHWIND_SQL, productsSchema, customersSchema, orderLinesSchema } from '../shared/northwind'\n\n type Row = Record<string, unknown>\n type EntityKey = 'order_lines' | 'products' | 'customers'\n type Entity = { key: EntityKey; label: string; schema: EntitySchema<Row>; editable: boolean; hint: string }\n\n const ENTITIES: Entity[] = [\n { key: 'order_lines', label: 'Order lines', schema: orderLinesSchema as unknown as EntitySchema<Row>, editable: false, hint: 'A five-table JOIN, read-only' },\n { key: 'products', label: 'Products', schema: productsSchema as unknown as EntitySchema<Row>, editable: true, hint: 'Base table, full CRUD' },\n { key: 'customers', label: 'Customers', schema: customersSchema as unknown as EntitySchema<Row>, editable: true, hint: 'Base table, full CRUD' },\n ]\n\n let db: PGlite\n let ready = $state(false)\n let activeKey = $state<EntityKey>('order_lines')\n let lastSql = $state('')\n let editing = $state<Row | null | undefined>(undefined)\n let selected = $state<Row[]>([])\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n let controller: any\n\n let view = $state<ServerState<Row>>({\n rows: [], total: 0, loading: false, saving: false, error: null,\n pageIndex: 0, pageSize: 10, pageCount: 1, sortModel: [], filterModel: {},\n })\n\n const active = $derived(ENTITIES.find((e) => e.key === activeKey)!)\n const columns = $derived(schemaToColumns(active.schema))\n\n function bind(entity: Entity) {\n controller?.dispose()\n editing = undefined\n selected = []\n lastSql = ''\n const source = createSqlDataSource<Row>({\n schema: entity.schema,\n table: entity.key,\n dialect: { placeholders: '$', ilike: true },\n execute: async (text, params) => {\n if (!text.startsWith('SELECT COUNT(')) lastSql = text\n const res = await db.query(text, params)\n return res.rows as Row[]\n },\n })\n controller = createServerDataSource<Row>(source, {\n pageSize: 10,\n optimistic: true,\n getRowId: (r) => String(r.id),\n onChange: (s) => (view = s),\n })\n controller.refresh()\n }\n\n function switchTo(key: EntityKey) {\n if (key === activeKey && ready) return\n activeKey = key\n if (ready) bind(ENTITIES.find((e) => e.key === key)!)\n }\n\n async function init() {\n db = new PGlite() // in-memory Postgres (WASM)\n await db.exec(NORTHWIND_SQL)\n ready = true\n bind(active)\n }\n init()\n\n async function save({ mode, id, values }: { mode: 'create' | 'edit'; id: string | null; values: Partial<Row> }) {\n if (mode === 'create') {\n await controller.createRow(values)\n controller.setPage(view.pageCount - 1)\n } else if (id) {\n await controller.updateRow(id, values)\n }\n editing = undefined\n }\n async function removeSelected() {\n for (const row of selected) await controller.deleteRow(String(row.id))\n selected = []\n }\n</script>\n\n<SvGridStudio\n title=\"Northwind on PGlite\"\n subtitle=\"The classic Northwind database as a real Postgres in your browser (<code>PGlite</code>, WASM). Every sort, filter, page, and edit is actual SQL.\"\n>\n {#snippet actions()}\n <span class=\"st-badge st-badge--live\">● Postgres · WASM · no server</span>\n {/snippet}\n\n {#if !ready}\n <div class=\"live__loading\">Booting Postgres in the browser…</div>\n {:else}\n <div class=\"nw__tabs\">\n {#each ENTITIES as e (e.key)}\n <button class=\"nw__tab\" class:nw__tab--active={e.key === activeKey} onclick={() => switchTo(e.key)}>\n {e.label}\n <span class=\"nw__hint\">{e.hint}</span>\n </button>\n {/each}\n </div>\n\n <div class=\"st__toolbar\">\n {#if active.editable}\n <button class=\"st-btn st-btn--primary\" onclick={() => (editing = null)}>+ New {active.schema.label?.toLowerCase()}</button>\n <button class=\"st-btn\" disabled={selected.length === 0} onclick={removeSelected}>\n Delete{selected.length ? ` (${selected.length})` : ''}\n </button>\n {:else}\n <span class=\"nw__readonly\">Read-only view — switch to Products or Customers to edit.</span>\n {/if}\n </div>\n\n <div class=\"live__sql\"><span>SQL</span> <code>{lastSql}</code></div>\n\n <SvGrid responsive={true}\n columnResize\n data={view.rows}\n {columns}\n loading={view.loading}\n fitColumns\n showRowSelection={active.editable}\n sortable\n externalSort\n onSortingChange={(s) => controller.setSort(s)}\n filterable\n filterMode=\"row\"\n externalFilter\n onFiltersChange={(f) =>\n controller.setFilter({\n global: f.global || undefined,\n columns: Object.fromEntries(\n f.columns.map((c) => [c.id, { operator: c.operator, value: c.value, valueTo: c.valueTo, selectedValues: c.selectedValues }]),\n ),\n })}\n onRowDoubleClick={(e) => active.editable && (editing = e.row)}\n onRowSelectionChange={(_sel, rows) => (selected = rows)}\n showPagination\n externalPagination\n rowCount={view.total}\n pageIndex={view.pageIndex}\n pageSize={view.pageSize}\n onPaginationChange={({ pageIndex, pageSize }) => {\n if (pageSize !== view.pageSize) controller.setPageSize(pageSize)\n else controller.setPage(pageIndex)\n }}\n containerHeight={340}\n />\n\n {#if editing !== undefined && active.editable}\n <SvGridEditPanel schema={active.schema} row={editing} presentation=\"modal\" persistKey=\"northwind\" onSubmit={save} onCancel={() => (editing = undefined)} />\n {/if}\n {/if}\n</SvGridStudio>\n\n<style>\n .live__loading { padding: 40px; text-align: center; color: var(--sg-muted, #888); }\n .live__sql { display: flex; align-items: center; gap: 8px; font-size: 12px; overflow: auto; }\n .live__sql span { flex: 0 0 auto; font-weight: 700; color: var(--sg-muted, #888); }\n .live__sql code { white-space: nowrap; color: var(--sg-fg, inherit); background: var(--sg-header-bg, #f6f6f6); padding: 4px 8px; border-radius: 6px; }\n .nw__tabs { display: flex; gap: 6px; flex-wrap: wrap; margin-bottom: 10px; }\n .nw__tab {\n display: flex; flex-direction: column; align-items: flex-start; gap: 2px;\n padding: 8px 14px; border: 1px solid var(--sg-border, #e2e2e2); border-radius: 8px;\n background: var(--sg-bg, #fff); color: var(--sg-fg, inherit); cursor: pointer;\n font-size: 13px; font-weight: 600; line-height: 1.2;\n }\n .nw__tab--active { border-color: var(--site-accent, #2563eb); box-shadow: inset 0 0 0 1px var(--site-accent, #2563eb); }\n .nw__hint { font-size: 11px; font-weight: 400; color: var(--sg-muted, #888); }\n .nw__readonly { font-size: 12px; color: var(--sg-muted, #888); }\n</style>\n"
1792
+ "source": "<script lang=\"ts\">\n /**\n * 338. Northwind on PGlite - a real relational Postgres in the browser\n * --------------------------------------------------------------------\n * The classic Northwind sample DB (categories, customers, products, orders,\n * order_details) seeded into PGlite (WASM Postgres). No server, no keys.\n *\n * Switch between three entities, each backed by `createSqlDataSource` over\n * the same in-browser database:\n * - Order lines - a five-table JOIN exposed as a VIEW (read-only). The rich\n * denormalized grid a single flat table can't give you.\n * - Products / Customers - base tables with full CRUD; new rows get an\n * auto-generated id from a Postgres IDENTITY sequence.\n *\n * Sort / filter / page all round-trip as real parameterized SQL - watch the\n * statement under the toolbar change as you interact.\n */\n import { PGlite } from '@electric-sql/pglite'\n import { SvGrid, createServerDataSource, type ServerState } from '@svgrid/grid'\n import { SvGridEditPanel, createSqlDataSource, schemaToColumns, type EntitySchema } from '@svgrid/enterprise'\n import SvGridStudio from '../shared/SvGridStudio.svelte'\n import { NORTHWIND_SQL, productsSchema, customersSchema, orderLinesSchema } from '../shared/northwind'\n\n type Row = Record<string, unknown>\n type EntityKey = 'order_lines' | 'products' | 'customers'\n type Entity = { key: EntityKey; label: string; schema: EntitySchema<Row>; editable: boolean; hint: string }\n\n const ENTITIES: Entity[] = [\n { key: 'order_lines', label: 'Order lines', schema: orderLinesSchema as unknown as EntitySchema<Row>, editable: false, hint: 'A five-table JOIN, read-only' },\n { key: 'products', label: 'Products', schema: productsSchema as unknown as EntitySchema<Row>, editable: true, hint: 'Base table, full CRUD' },\n { key: 'customers', label: 'Customers', schema: customersSchema as unknown as EntitySchema<Row>, editable: true, hint: 'Base table, full CRUD' },\n ]\n\n let db: PGlite\n let ready = $state(false)\n let activeKey = $state<EntityKey>('order_lines')\n let lastSql = $state('')\n let editing = $state<Row | null | undefined>(undefined)\n let selected = $state<Row[]>([])\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n let controller: any\n\n let view = $state<ServerState<Row>>({\n rows: [], total: 0, loading: false, saving: false, error: null,\n pageIndex: 0, pageSize: 10, pageCount: 1, sortModel: [], filterModel: {},\n })\n\n const active = $derived(ENTITIES.find((e) => e.key === activeKey)!)\n const columns = $derived(schemaToColumns(active.schema))\n\n function bind(entity: Entity) {\n controller?.dispose()\n editing = undefined\n selected = []\n lastSql = ''\n const source = createSqlDataSource<Row>({\n schema: entity.schema,\n table: entity.key,\n dialect: { placeholders: '$', ilike: true },\n execute: async (text, params) => {\n if (!text.startsWith('SELECT COUNT(')) lastSql = text\n const res = await db.query(text, params)\n return res.rows as Row[]\n },\n })\n controller = createServerDataSource<Row>(source, {\n pageSize: 10,\n optimistic: true,\n getRowId: (r) => String(r.id),\n onChange: (s) => (view = s),\n })\n controller.refresh()\n }\n\n function switchTo(key: EntityKey) {\n if (key === activeKey && ready) return\n activeKey = key\n if (ready) bind(ENTITIES.find((e) => e.key === key)!)\n }\n\n async function init() {\n db = new PGlite() // in-memory Postgres (WASM)\n await db.exec(NORTHWIND_SQL)\n ready = true\n bind(active)\n }\n init()\n\n async function save({ mode, id, values }: { mode: 'create' | 'edit'; id: string | null; values: Partial<Row> }) {\n if (mode === 'create') {\n await controller.createRow(values)\n controller.setPage(view.pageCount - 1)\n } else if (id) {\n await controller.updateRow(id, values)\n }\n editing = undefined\n }\n async function removeSelected() {\n for (const row of selected) await controller.deleteRow(String(row.id))\n selected = []\n }\n</script>\n\n<SvGridStudio\n title=\"Northwind on PGlite\"\n subtitle=\"The classic Northwind database as a real Postgres in your browser (<code>PGlite</code>, WASM). Every sort, filter, page, and edit is actual SQL.\"\n>\n {#snippet actions()}\n <span class=\"st-badge st-badge--live\">● Postgres · WASM · no server</span>\n {/snippet}\n\n {#if !ready}\n <div class=\"live__loading\">Booting Postgres in the browser…</div>\n {:else}\n <div class=\"nw__tabs\">\n {#each ENTITIES as e (e.key)}\n <button class=\"nw__tab\" class:nw__tab--active={e.key === activeKey} onclick={() => switchTo(e.key)}>\n {e.label}\n <span class=\"nw__hint\">{e.hint}</span>\n </button>\n {/each}\n </div>\n\n <div class=\"st__toolbar\">\n {#if active.editable}\n <button class=\"st-btn st-btn--primary\" onclick={() => (editing = null)}>+ New {active.schema.label?.toLowerCase()}</button>\n <button class=\"st-btn\" disabled={selected.length === 0} onclick={removeSelected}>\n Delete{selected.length ? ` (${selected.length})` : ''}\n </button>\n {:else}\n <span class=\"nw__readonly\">Read-only view - switch to Products or Customers to edit.</span>\n {/if}\n </div>\n\n <div class=\"live__sql\"><span>SQL</span> <code>{lastSql}</code></div>\n\n <SvGrid responsive={true}\n columnResize\n data={view.rows}\n {columns}\n loading={view.loading}\n fitColumns\n showRowSelection={active.editable}\n sortable\n externalSort\n onSortingChange={(s) => controller.setSort(s)}\n filterable\n filterMode=\"row\"\n externalFilter\n onFiltersChange={(f) =>\n controller.setFilter({\n global: f.global || undefined,\n columns: Object.fromEntries(\n f.columns.map((c) => [c.id, { operator: c.operator, value: c.value, valueTo: c.valueTo, selectedValues: c.selectedValues }]),\n ),\n })}\n onRowDoubleClick={(e) => active.editable && (editing = e.row)}\n onRowSelectionChange={(_sel, rows) => (selected = rows)}\n showPagination\n externalPagination\n rowCount={view.total}\n pageIndex={view.pageIndex}\n pageSize={view.pageSize}\n onPaginationChange={({ pageIndex, pageSize }) => {\n if (pageSize !== view.pageSize) controller.setPageSize(pageSize)\n else controller.setPage(pageIndex)\n }}\n containerHeight={340}\n />\n\n {#if editing !== undefined && active.editable}\n <SvGridEditPanel schema={active.schema} row={editing} presentation=\"modal\" persistKey=\"northwind\" onSubmit={save} onCancel={() => (editing = undefined)} />\n {/if}\n {/if}\n</SvGridStudio>\n\n<style>\n .live__loading { padding: 40px; text-align: center; color: var(--sg-muted, #888); }\n .live__sql { display: flex; align-items: center; gap: 8px; font-size: 12px; overflow: auto; }\n .live__sql span { flex: 0 0 auto; font-weight: 700; color: var(--sg-muted, #888); }\n .live__sql code { white-space: nowrap; color: var(--sg-fg, inherit); background: var(--sg-header-bg, #f6f6f6); padding: 4px 8px; border-radius: 6px; }\n .nw__tabs { display: flex; gap: 6px; flex-wrap: wrap; margin-bottom: 10px; }\n .nw__tab {\n display: flex; flex-direction: column; align-items: flex-start; gap: 2px;\n padding: 8px 14px; border: 1px solid var(--sg-border, #e2e2e2); border-radius: 8px;\n background: var(--sg-bg, #fff); color: var(--sg-fg, inherit); cursor: pointer;\n font-size: 13px; font-weight: 600; line-height: 1.2;\n }\n .nw__tab--active { border-color: var(--site-accent, #2563eb); box-shadow: inset 0 0 0 1px var(--site-accent, #2563eb); }\n .nw__hint { font-size: 11px; font-weight: 400; color: var(--sg-muted, #888); }\n .nw__readonly { font-size: 12px; color: var(--sg-muted, #888); }\n</style>\n"
1793
1793
  },
1794
1794
  {
1795
1795
  "id": "339-status-display",
@@ -2005,7 +2005,7 @@ export const examples = [
2005
2005
  "title": "Pivot Mode Grid",
2006
2006
  "category": "Pivot Grid",
2007
2007
  "blurb": "360. Pivot mode grid (Enterprise) - <SvPivotDesigner panelPosition=\"right\"> The classic \"enterprise data grid\" experience, built entirely on the shipped `<SvPivotDesigner>` component - no bespoke panel. Three designer",
2008
- "source": "<!-- Documented in: docs/help/pivot.md -->\n<script lang=\"ts\">\n /**\n * 360. Pivot mode grid (Enterprise) - <SvPivotDesigner panelPosition=\"right\">\n * ---------------------------------------------------------------------------\n * The classic \"enterprise data grid\" experience, built entirely on the\n * shipped `<SvPivotDesigner>` component - no bespoke panel. Three designer\n * features drive the docked tool-panel look:\n *\n * - `panelPosition=\"right\"` docks the field picker + Column/Row/Values\n * wells as a vertical tool panel on the right of the grid.\n * - `pivotMode` (bindable) + `flatColumns` add the PIVOT MODE toggle:\n * OFF shows the flat participant grid (column groups, flags, stars,\n * inline filter row); ON shows the live pivot.\n * - `decorateColumns` heat-tints the value cells low -> high.\n *\n * The layout is pre-seeded (Language -> Country rows x Game columns, avg\n * measures) so flipping Pivot Mode on immediately yields a real cross-tab.\n */\n import {\n SvGrid,\n tableFeatures,\n rowSortingFeature,\n columnFilteringFeature,\n renderSnippet,\n type ColumnDef,\n type GridColumns,\n } from '@svgrid/grid'\n import {\n SvPivotDesigner,\n type PivotField,\n type PivotLayout,\n type PivotRow,\n } from '@svgrid/enterprise'\n\n // ---- Domain ----------------------------------------------------------\n const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'] as const\n type Month = typeof MONTHS[number]\n\n type Participant = {\n id: number\n name: string\n language: string\n country: string\n game: string\n bought: boolean\n bankBalance: number\n rating: number\n totalWinnings: number\n } & Record<Month, number>\n\n const PLACES: Array<{ country: string; flag: string; language: string }> = [\n { country: 'Ireland', flag: '🇮🇪', language: 'English' },\n { country: 'Sweden', flag: '🇸🇪', language: 'Swedish' },\n { country: 'Uruguay', flag: '🇺🇾', language: 'Spanish' },\n { country: 'France', flag: '🇫🇷', language: 'French' },\n { country: 'Portugal', flag: '🇵🇹', language: 'Portuguese' },\n { country: 'Colombia', flag: '🇨🇴', language: 'Spanish' },\n { country: 'Malta', flag: '🇲🇹', language: 'Maltese' },\n { country: 'Germany', flag: '🇩🇪', language: 'German' },\n { country: 'Japan', flag: '🇯🇵', language: 'Japanese' },\n { country: 'Spain', flag: '🇪🇸', language: 'Spanish' },\n { country: 'Brazil', flag: '🇧🇷', language: 'Portuguese' },\n { country: 'USA', flag: '🇺🇸', language: 'English' },\n ]\n const FLAG = new Map(PLACES.map((p) => [p.country, p.flag]))\n const GAMES = ['Chess', 'Bul', 'Rithmomachy', 'Kalah', 'Game of the Generals', 'Hare and Hounds', 'Sugoroku', \"Nine Men's Morris\", 'Blockade', 'Go', 'Draughts', 'Backgammon']\n const FIRST = ['Tony', 'Andrew', 'Kevin', 'Bricker', 'Harper', 'Noel', 'Sophie', 'Isabelle', 'Emily', 'Oliver', 'Mia', 'Lucas', 'Ava', 'Ethan', 'Grace', 'Leo']\n const LAST = ['Smith', 'Connell', 'Flanagan', 'McGee', 'Thornton', 'Lopes', 'Beckham', 'Black', 'Braxton', 'Hughes', 'Nguyen', 'Rossi', 'Kane', 'Webb', 'Frost', 'Reed']\n\n let prng = 0x1a2b3c4d >>> 0\n const rnd = () => { prng = (prng * 1664525 + 1013904223) >>> 0; return prng / 0xffffffff }\n const pick = <U,>(arr: readonly U[]): U => arr[Math.floor(rnd() * arr.length)]!\n\n function seed(): Participant[] {\n const out: Participant[] = []\n for (let id = 1; id <= 1000; id += 1) {\n const place = pick(PLACES)\n const row = {\n id,\n name: `${pick(FIRST)} ${pick(LAST)}`,\n language: place.language,\n country: place.country,\n game: pick(GAMES),\n bought: rnd() > 0.45,\n bankBalance: Math.round(1000 + rnd() * 98_000),\n rating: Math.floor(rnd() * 6),\n totalWinnings: Math.round(400_000 + rnd() * 500_000),\n } as Participant\n for (const m of MONTHS) row[m] = Math.round(5_000 + rnd() * 85_000)\n out.push(row)\n }\n return out\n }\n const rows = seed()\n\n const money = { type: 'currency', currency: 'USD', options: { maximumFractionDigits: 0 } } as const\n const ratingFmt = { type: 'number', options: { minimumFractionDigits: 1, maximumFractionDigits: 1 } } as const\n\n // ---- Fields for the designer's picker + wells ------------------------\n const fields: PivotField<Participant>[] = [\n { field: 'name', label: 'Name', kind: 'dimension', group: 'Participant' },\n { field: 'language', label: 'Language', kind: 'dimension', group: 'Participant' },\n { field: 'country', label: 'Country', kind: 'dimension', group: 'Participant' },\n { field: 'game', label: 'Game Name', kind: 'dimension', group: 'Game of Choice' },\n { field: 'bought', label: 'Bought', kind: 'dimension', group: 'Game of Choice' },\n { field: 'bankBalance', label: 'Bank Balance', kind: 'measure', group: 'Performance', defaultAgg: 'avg', format: money },\n { field: 'rating', label: 'Rating', kind: 'measure', group: 'Performance', defaultAgg: 'avg', format: ratingFmt },\n { field: 'totalWinnings', label: 'Total Winnings', kind: 'measure', group: 'Winnings', defaultAgg: 'sum', format: money },\n ...MONTHS.map((m): PivotField<Participant> => ({\n field: m, label: m[0]!.toUpperCase() + m.slice(1), kind: 'measure', group: 'Monthly Breakdown', defaultAgg: 'sum', format: money,\n })),\n ]\n\n // Pre-seeded so Pivot Mode ON is instantly a real cross-tab. language ->\n // country is a genuine 1-to-many fan-out, so the row groups expand.\n let layout = $state<PivotLayout>({\n rows: ['language', 'country'],\n cols: ['game'],\n values: [\n { field: 'bankBalance', agg: 'avg', label: 'Bank Balance', format: money },\n { field: 'rating', agg: 'avg', label: 'Rating', format: ratingFmt },\n ],\n filters: [],\n })\n let pivotMode = $state(false)\n\n // ---- Flat (pivot-off) columns: AG-style groups + custom cells --------\n const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })\n const flatColumns: GridColumns<Participant> = [\n {\n id: 'g-participant', header: 'Participant', columns: [\n { field: 'name', header: 'Name', width: 150 },\n { field: 'language', header: 'Language', width: 120 },\n { field: 'country', header: 'Country', width: 140, cell: (ctx) => renderSnippet(CountryCell, { value: String(ctx.getValue()) }) },\n ],\n } as ColumnDef<typeof features, Participant>,\n {\n id: 'g-game', header: 'Game of Choice', columns: [\n { field: 'game', header: 'Game Name', width: 170 },\n { field: 'bought', header: 'Bought', width: 90, align: 'center', cell: (ctx) => renderSnippet(BoughtCell, { on: Boolean(ctx.getValue()) }) },\n ],\n } as ColumnDef<typeof features, Participant>,\n {\n id: 'g-performance', header: 'Performance', columns: [\n { field: 'bankBalance', header: 'Bank Balance', width: 150, align: 'right', format: money },\n { field: 'rating', header: 'Rating', width: 120, cell: (ctx) => renderSnippet(RatingCell, { n: Number(ctx.getValue()) }) },\n ],\n } as ColumnDef<typeof features, Participant>,\n { field: 'totalWinnings', header: 'Total Winnings', width: 150, align: 'right', format: money },\n {\n id: 'g-months', header: 'Monthly Breakdown',\n columns: MONTHS.map((m): ColumnDef<typeof features, Participant> => ({\n field: m, header: m[0]!.toUpperCase() + m.slice(1), width: 100, align: 'right', format: money,\n })),\n } as ColumnDef<typeof features, Participant>,\n ]\n\n // ---- Heatmap: per-measure range over the current pivot leaves --------\n let pivotRows = $state<PivotRow[]>([])\n const measureRanges = $derived.by(() => {\n const ranges: Record<string, { lo: number; hi: number }> = {}\n for (const r of pivotRows) {\n if (r.__pivotKind !== 'leaf') continue\n for (const [k, v] of Object.entries(r)) {\n const m = k.match(/__m(\\d+)$/)\n if (!m) continue\n const n = Number(v)\n if (!Number.isFinite(n)) continue\n const cur = ranges[m[1]!] ?? { lo: Infinity, hi: -Infinity }\n if (n < cur.lo) cur.lo = n\n if (n > cur.hi) cur.hi = n\n ranges[m[1]!] = cur\n }\n }\n return ranges\n })\n function heatClass(colId: string, value: unknown): string {\n const m = colId.match(/__m(\\d+)$/)\n if (!m) return ''\n const range = measureRanges[m[1]!]\n if (!range || range.lo === range.hi) return ''\n const n = Number(value)\n if (!Number.isFinite(n)) return ''\n const t = (n - range.lo) / (range.hi - range.lo)\n if (t < 0.2) return 'heat-1'\n if (t < 0.4) return 'heat-2'\n if (t < 0.6) return 'heat-3'\n if (t < 0.8) return 'heat-4'\n return 'heat-5'\n }\n // Right-align + heat-tint the value LEAF columns (nested under group cols).\n function decorate(cols: GridColumns<PivotRow>): GridColumns<PivotRow> {\n return cols.map((c) => {\n const kids = (c as { columns?: GridColumns<PivotRow> }).columns\n if (kids?.length) return { ...c, columns: decorate(kids) } as ColumnDef<typeof features, PivotRow>\n const colId = c.id ?? ''\n if (!/__m\\d+$/.test(colId)) return c\n return {\n ...c,\n align: 'right' as const,\n cellClass: (ctx: { row: { original: PivotRow }; getValue: () => unknown }) => {\n const k = ctx.row.original.__pivotKind\n if (k === 'grandTotal') return 'pm-grand'\n if (k !== 'leaf') return ''\n return `pm-leaf ${heatClass(colId, ctx.getValue())}`\n },\n } as ColumnDef<typeof features, PivotRow>\n })\n }\n</script>\n\n{#snippet CountryCell(props: { value: string })}\n <span class=\"pm-country\"><span class=\"pm-flag\">{FLAG.get(props.value) ?? '🏳️'}</span>{props.value}</span>\n{/snippet}\n{#snippet BoughtCell(props: { on: boolean })}\n <input type=\"checkbox\" checked={props.on} disabled class=\"pm-check\" aria-label={props.on ? 'bought' : 'not bought'} />\n{/snippet}\n{#snippet RatingCell(props: { n: number })}\n <span class=\"pm-stars\" aria-label={`${props.n} of 5`}>{'★'.repeat(props.n)}<span class=\"pm-stars-empty\">{'★'.repeat(5 - props.n)}</span></span>\n{/snippet}\n\n<section class=\"pm flex flex-col flex-1 min-h-0 gap-3\">\n <div class=\"shrink-0 rounded-lg border px-4 py-3\" style=\"border-color: var(--sg-border); background: var(--sg-header-bg);\">\n <p class=\"text-sm font-semibold\" style=\"color: var(--sg-fg);\">\n &lt;SvPivotDesigner panelPosition=\"right\"&gt; — enterprise pivot panel\n </p>\n <p class=\"mt-0.5 text-xs\" style=\"color: var(--sg-muted);\">\n Flip <strong>Pivot Mode</strong> in the right panel: OFF shows the flat participant grid\n (column groups, flags, ratings, inline filter row); ON pivots\n <strong>Language → Country</strong> down the side and <strong>Game</strong> across the top,\n heat-tinted low → high. The right panel has <strong>Columns</strong> (a column-group tree with\n visibility checkboxes) and <strong>Filters</strong> tabs (Add Filter → pick a column → tick which\n values pass). Drag fields between the Columns / Rows / Values wells to re-pivot, or\n <strong>right-click</strong> a field, a chip, or the grid for a context menu.\n </p>\n </div>\n\n <div class=\"pm-host flex-1 min-h-0\">\n <SvPivotDesigner\n data={rows}\n {fields}\n bind:layout\n bind:pivotMode\n {flatColumns}\n panelPosition=\"right\"\n showToolbar={false}\n showFiltersWell={false}\n gridFitColumns={false}\n columnTree\n toolTabs\n expandable\n decorateColumns={(cols) => decorate(cols)}\n onPivot={(r) => (pivotRows = r)}\n />\n </div>\n</section>\n\n<style>\n .pm-host :global(.pm-country) { display: inline-flex; align-items: center; gap: 7px; }\n .pm-host :global(.pm-flag) { font-size: 14px; line-height: 1; }\n .pm-host :global(.pm-check) { accent-color: var(--sg-accent, #4338ca); width: 15px; height: 15px; }\n .pm-host :global(.pm-stars) { color: #f59e0b; letter-spacing: 1px; font-size: 13px; }\n .pm-host :global(.pm-stars-empty) { color: var(--sg-border, #cbd5e1); }\n\n /* Heat tinting on pivot value leaf cells */\n .pm-host :global(td.pm-leaf.heat-1) { background: rgba(239,68,68,0.16); color: #b91c1c; }\n .pm-host :global(td.pm-leaf.heat-2) { background: rgba(239,68,68,0.06); }\n .pm-host :global(td.pm-leaf.heat-3) { background: transparent; }\n .pm-host :global(td.pm-leaf.heat-4) { background: rgba(16,185,129,0.07); }\n .pm-host :global(td.pm-leaf.heat-5) { background: rgba(16,185,129,0.20); color: #047857; font-weight: 600; }\n :global([data-theme=\"dark\"]) .pm-host :global(td.pm-leaf.heat-1) { background: rgba(239,68,68,0.28); color: #fecaca; }\n :global([data-theme=\"dark\"]) .pm-host :global(td.pm-leaf.heat-2) { background: rgba(239,68,68,0.14); }\n :global([data-theme=\"dark\"]) .pm-host :global(td.pm-leaf.heat-4) { background: rgba(16,185,129,0.16); }\n :global([data-theme=\"dark\"]) .pm-host :global(td.pm-leaf.heat-5) { background: rgba(16,185,129,0.34); color: #a7f3d0; }\n</style>\n"
2008
+ "source": "<!-- Documented in: docs/help/pivot.md -->\n<script lang=\"ts\">\n /**\n * 360. Pivot mode grid (Enterprise) - <SvPivotDesigner panelPosition=\"right\">\n * ---------------------------------------------------------------------------\n * The classic \"enterprise data grid\" experience, built entirely on the\n * shipped `<SvPivotDesigner>` component - no bespoke panel. Three designer\n * features drive the docked tool-panel look:\n *\n * - `panelPosition=\"right\"` docks the field picker + Column/Row/Values\n * wells as a vertical tool panel on the right of the grid.\n * - `pivotMode` (bindable) + `flatColumns` add the PIVOT MODE toggle:\n * OFF shows the flat participant grid (column groups, flags, stars,\n * inline filter row); ON shows the live pivot.\n * - `decorateColumns` heat-tints the value cells low -> high.\n *\n * The layout is pre-seeded (Language -> Country rows x Game columns, avg\n * measures) so flipping Pivot Mode on immediately yields a real cross-tab.\n */\n import {\n SvGrid,\n tableFeatures,\n rowSortingFeature,\n columnFilteringFeature,\n renderSnippet,\n type ColumnDef,\n type GridColumns,\n } from '@svgrid/grid'\n import {\n SvPivotDesigner,\n type PivotField,\n type PivotLayout,\n type PivotRow,\n } from '@svgrid/enterprise'\n\n // ---- Domain ----------------------------------------------------------\n const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'] as const\n type Month = typeof MONTHS[number]\n\n type Participant = {\n id: number\n name: string\n language: string\n country: string\n game: string\n bought: boolean\n bankBalance: number\n rating: number\n totalWinnings: number\n } & Record<Month, number>\n\n const PLACES: Array<{ country: string; flag: string; language: string }> = [\n { country: 'Ireland', flag: '🇮🇪', language: 'English' },\n { country: 'Sweden', flag: '🇸🇪', language: 'Swedish' },\n { country: 'Uruguay', flag: '🇺🇾', language: 'Spanish' },\n { country: 'France', flag: '🇫🇷', language: 'French' },\n { country: 'Portugal', flag: '🇵🇹', language: 'Portuguese' },\n { country: 'Colombia', flag: '🇨🇴', language: 'Spanish' },\n { country: 'Malta', flag: '🇲🇹', language: 'Maltese' },\n { country: 'Germany', flag: '🇩🇪', language: 'German' },\n { country: 'Japan', flag: '🇯🇵', language: 'Japanese' },\n { country: 'Spain', flag: '🇪🇸', language: 'Spanish' },\n { country: 'Brazil', flag: '🇧🇷', language: 'Portuguese' },\n { country: 'USA', flag: '🇺🇸', language: 'English' },\n ]\n const FLAG = new Map(PLACES.map((p) => [p.country, p.flag]))\n const GAMES = ['Chess', 'Bul', 'Rithmomachy', 'Kalah', 'Game of the Generals', 'Hare and Hounds', 'Sugoroku', \"Nine Men's Morris\", 'Blockade', 'Go', 'Draughts', 'Backgammon']\n const FIRST = ['Tony', 'Andrew', 'Kevin', 'Bricker', 'Harper', 'Noel', 'Sophie', 'Isabelle', 'Emily', 'Oliver', 'Mia', 'Lucas', 'Ava', 'Ethan', 'Grace', 'Leo']\n const LAST = ['Smith', 'Connell', 'Flanagan', 'McGee', 'Thornton', 'Lopes', 'Beckham', 'Black', 'Braxton', 'Hughes', 'Nguyen', 'Rossi', 'Kane', 'Webb', 'Frost', 'Reed']\n\n let prng = 0x1a2b3c4d >>> 0\n const rnd = () => { prng = (prng * 1664525 + 1013904223) >>> 0; return prng / 0xffffffff }\n const pick = <U,>(arr: readonly U[]): U => arr[Math.floor(rnd() * arr.length)]!\n\n function seed(): Participant[] {\n const out: Participant[] = []\n for (let id = 1; id <= 1000; id += 1) {\n const place = pick(PLACES)\n const row = {\n id,\n name: `${pick(FIRST)} ${pick(LAST)}`,\n language: place.language,\n country: place.country,\n game: pick(GAMES),\n bought: rnd() > 0.45,\n bankBalance: Math.round(1000 + rnd() * 98_000),\n rating: Math.floor(rnd() * 6),\n totalWinnings: Math.round(400_000 + rnd() * 500_000),\n } as Participant\n for (const m of MONTHS) row[m] = Math.round(5_000 + rnd() * 85_000)\n out.push(row)\n }\n return out\n }\n const rows = seed()\n\n const money = { type: 'currency', currency: 'USD', options: { maximumFractionDigits: 0 } } as const\n const ratingFmt = { type: 'number', options: { minimumFractionDigits: 1, maximumFractionDigits: 1 } } as const\n\n // ---- Fields for the designer's picker + wells ------------------------\n const fields: PivotField<Participant>[] = [\n { field: 'name', label: 'Name', kind: 'dimension', group: 'Participant' },\n { field: 'language', label: 'Language', kind: 'dimension', group: 'Participant' },\n { field: 'country', label: 'Country', kind: 'dimension', group: 'Participant' },\n { field: 'game', label: 'Game Name', kind: 'dimension', group: 'Game of Choice' },\n { field: 'bought', label: 'Bought', kind: 'dimension', group: 'Game of Choice' },\n { field: 'bankBalance', label: 'Bank Balance', kind: 'measure', group: 'Performance', defaultAgg: 'avg', format: money },\n { field: 'rating', label: 'Rating', kind: 'measure', group: 'Performance', defaultAgg: 'avg', format: ratingFmt },\n { field: 'totalWinnings', label: 'Total Winnings', kind: 'measure', group: 'Winnings', defaultAgg: 'sum', format: money },\n ...MONTHS.map((m): PivotField<Participant> => ({\n field: m, label: m[0]!.toUpperCase() + m.slice(1), kind: 'measure', group: 'Monthly Breakdown', defaultAgg: 'sum', format: money,\n })),\n ]\n\n // Pre-seeded so Pivot Mode ON is instantly a real cross-tab. language ->\n // country is a genuine 1-to-many fan-out, so the row groups expand.\n let layout = $state<PivotLayout>({\n rows: ['language', 'country'],\n cols: ['game'],\n values: [\n { field: 'bankBalance', agg: 'avg', label: 'Bank Balance', format: money },\n { field: 'rating', agg: 'avg', label: 'Rating', format: ratingFmt },\n ],\n filters: [],\n })\n let pivotMode = $state(false)\n\n // ---- Flat (pivot-off) columns: AG-style groups + custom cells --------\n const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })\n const flatColumns: GridColumns<Participant> = [\n {\n id: 'g-participant', header: 'Participant', columns: [\n { field: 'name', header: 'Name', width: 150 },\n { field: 'language', header: 'Language', width: 120 },\n { field: 'country', header: 'Country', width: 140, cell: (ctx) => renderSnippet(CountryCell, { value: String(ctx.getValue()) }) },\n ],\n } as ColumnDef<typeof features, Participant>,\n {\n id: 'g-game', header: 'Game of Choice', columns: [\n { field: 'game', header: 'Game Name', width: 170 },\n { field: 'bought', header: 'Bought', width: 90, align: 'center', cell: (ctx) => renderSnippet(BoughtCell, { on: Boolean(ctx.getValue()) }) },\n ],\n } as ColumnDef<typeof features, Participant>,\n {\n id: 'g-performance', header: 'Performance', columns: [\n { field: 'bankBalance', header: 'Bank Balance', width: 150, align: 'right', format: money },\n { field: 'rating', header: 'Rating', width: 120, cell: (ctx) => renderSnippet(RatingCell, { n: Number(ctx.getValue()) }) },\n ],\n } as ColumnDef<typeof features, Participant>,\n { field: 'totalWinnings', header: 'Total Winnings', width: 150, align: 'right', format: money },\n {\n id: 'g-months', header: 'Monthly Breakdown',\n columns: MONTHS.map((m): ColumnDef<typeof features, Participant> => ({\n field: m, header: m[0]!.toUpperCase() + m.slice(1), width: 100, align: 'right', format: money,\n })),\n } as ColumnDef<typeof features, Participant>,\n ]\n\n // ---- Heatmap: per-measure range over the current pivot leaves --------\n let pivotRows = $state<PivotRow[]>([])\n const measureRanges = $derived.by(() => {\n const ranges: Record<string, { lo: number; hi: number }> = {}\n for (const r of pivotRows) {\n if (r.__pivotKind !== 'leaf') continue\n for (const [k, v] of Object.entries(r)) {\n const m = k.match(/__m(\\d+)$/)\n if (!m) continue\n const n = Number(v)\n if (!Number.isFinite(n)) continue\n const cur = ranges[m[1]!] ?? { lo: Infinity, hi: -Infinity }\n if (n < cur.lo) cur.lo = n\n if (n > cur.hi) cur.hi = n\n ranges[m[1]!] = cur\n }\n }\n return ranges\n })\n function heatClass(colId: string, value: unknown): string {\n const m = colId.match(/__m(\\d+)$/)\n if (!m) return ''\n const range = measureRanges[m[1]!]\n if (!range || range.lo === range.hi) return ''\n const n = Number(value)\n if (!Number.isFinite(n)) return ''\n const t = (n - range.lo) / (range.hi - range.lo)\n if (t < 0.2) return 'heat-1'\n if (t < 0.4) return 'heat-2'\n if (t < 0.6) return 'heat-3'\n if (t < 0.8) return 'heat-4'\n return 'heat-5'\n }\n // Right-align + heat-tint the value LEAF columns (nested under group cols).\n function decorate(cols: GridColumns<PivotRow>): GridColumns<PivotRow> {\n return cols.map((c) => {\n const kids = (c as { columns?: GridColumns<PivotRow> }).columns\n if (kids?.length) return { ...c, columns: decorate(kids) } as ColumnDef<typeof features, PivotRow>\n const colId = c.id ?? ''\n if (!/__m\\d+$/.test(colId)) return c\n return {\n ...c,\n align: 'right' as const,\n cellClass: (ctx: { row: { original: PivotRow }; getValue: () => unknown }) => {\n const k = ctx.row.original.__pivotKind\n if (k === 'grandTotal') return 'pm-grand'\n if (k !== 'leaf') return ''\n return `pm-leaf ${heatClass(colId, ctx.getValue())}`\n },\n } as ColumnDef<typeof features, PivotRow>\n })\n }\n</script>\n\n{#snippet CountryCell(props: { value: string })}\n <span class=\"pm-country\"><span class=\"pm-flag\">{FLAG.get(props.value) ?? '🏳️'}</span>{props.value}</span>\n{/snippet}\n{#snippet BoughtCell(props: { on: boolean })}\n <input type=\"checkbox\" checked={props.on} disabled class=\"pm-check\" aria-label={props.on ? 'bought' : 'not bought'} />\n{/snippet}\n{#snippet RatingCell(props: { n: number })}\n <span class=\"pm-stars\" aria-label={`${props.n} of 5`}>{'★'.repeat(props.n)}<span class=\"pm-stars-empty\">{'★'.repeat(5 - props.n)}</span></span>\n{/snippet}\n\n<section class=\"pm flex flex-col flex-1 min-h-0 gap-3\">\n <div class=\"shrink-0 rounded-lg border px-4 py-3\" style=\"border-color: var(--sg-border); background: var(--sg-header-bg);\">\n <p class=\"text-sm font-semibold\" style=\"color: var(--sg-fg);\">\n &lt;SvPivotDesigner panelPosition=\"right\"&gt; - enterprise pivot panel\n </p>\n <p class=\"mt-0.5 text-xs\" style=\"color: var(--sg-muted);\">\n Flip <strong>Pivot Mode</strong> in the right panel: OFF shows the flat participant grid\n (column groups, flags, ratings, inline filter row); ON pivots\n <strong>Language → Country</strong> down the side and <strong>Game</strong> across the top,\n heat-tinted low → high. The right panel has <strong>Columns</strong> (a column-group tree with\n visibility checkboxes) and <strong>Filters</strong> tabs (Add Filter → pick a column → tick which\n values pass). Drag fields between the Columns / Rows / Values wells to re-pivot, or\n <strong>right-click</strong> a field, a chip, or the grid for a context menu.\n </p>\n </div>\n\n <div class=\"pm-host flex-1 min-h-0\">\n <SvPivotDesigner\n data={rows}\n {fields}\n bind:layout\n bind:pivotMode\n {flatColumns}\n panelPosition=\"right\"\n showToolbar={false}\n showFiltersWell={false}\n gridFitColumns={false}\n columnTree\n toolTabs\n expandable\n decorateColumns={(cols) => decorate(cols)}\n onPivot={(r) => (pivotRows = r)}\n />\n </div>\n</section>\n\n<style>\n .pm-host :global(.pm-country) { display: inline-flex; align-items: center; gap: 7px; }\n .pm-host :global(.pm-flag) { font-size: 14px; line-height: 1; }\n .pm-host :global(.pm-check) { accent-color: var(--sg-accent, #4338ca); width: 15px; height: 15px; }\n .pm-host :global(.pm-stars) { color: #f59e0b; letter-spacing: 1px; font-size: 13px; }\n .pm-host :global(.pm-stars-empty) { color: var(--sg-border, #cbd5e1); }\n\n /* Heat tinting on pivot value leaf cells */\n .pm-host :global(td.pm-leaf.heat-1) { background: rgba(239,68,68,0.16); color: #b91c1c; }\n .pm-host :global(td.pm-leaf.heat-2) { background: rgba(239,68,68,0.06); }\n .pm-host :global(td.pm-leaf.heat-3) { background: transparent; }\n .pm-host :global(td.pm-leaf.heat-4) { background: rgba(16,185,129,0.07); }\n .pm-host :global(td.pm-leaf.heat-5) { background: rgba(16,185,129,0.20); color: #047857; font-weight: 600; }\n :global([data-theme=\"dark\"]) .pm-host :global(td.pm-leaf.heat-1) { background: rgba(239,68,68,0.28); color: #fecaca; }\n :global([data-theme=\"dark\"]) .pm-host :global(td.pm-leaf.heat-2) { background: rgba(239,68,68,0.14); }\n :global([data-theme=\"dark\"]) .pm-host :global(td.pm-leaf.heat-4) { background: rgba(16,185,129,0.16); }\n :global([data-theme=\"dark\"]) .pm-host :global(td.pm-leaf.heat-5) { background: rgba(16,185,129,0.34); color: #a7f3d0; }\n</style>\n"
2009
2009
  },
2010
2010
  {
2011
2011
  "id": "361-dock-layout",
@@ -2445,7 +2445,7 @@ export const examples = [
2445
2445
  "title": "Tree Data",
2446
2446
  "category": "Sorting & Grouping",
2447
2447
  "blurb": "426. Tree data `treeData` nests rows into an expandable hierarchy by parent id: treeData={{ parentField: 'managerId', column: 'name' }}",
2448
- "source": "<!-- Documented in: docs/help/rows/tree-data.md -->\n<script lang=\"ts\">\n /**\n * 426. Tree data\n * --------------\n * `treeData` nests rows into an expandable hierarchy by parent id:\n *\n * treeData={{ parentField: 'managerId', column: 'name' }}\n *\n * Tree rows stay REAL data rows - own cells, formatting, editing, selection -\n * and only gain an expander plus indent in the tree column. (Row grouping is\n * the other shape: there the parent is a synthetic full-width banner.)\n *\n * Two input shapes, one model:\n * FLAT - rows already carry a parent id. Use it directly.\n * NESTED - objects hold a `children` array. `flattenTreeData` stamps\n * `__parentId` on each child and returns one flat list.\n */\n import {\n SvGrid,\n flattenTreeData,\n tableFeatures,\n rowSortingFeature,\n type GridColumns,\n type SvGridApi,\n } from '@svgrid/grid'\n\n const features = tableFeatures({ rowSortingFeature })\n\n // ---- Flat source: an org chart, each row naming its manager -------------\n type Person = {\n id: number\n managerId: number | null\n name: string\n title: string\n location: string\n reports: number\n budget: number\n }\n\n const people: Person[] = [\n { id: 1, managerId: null, name: 'Ada Lovelace', title: 'Chief Executive', location: 'London', reports: 10, budget: 4_200_000 },\n { id: 2, managerId: 1, name: 'Grace Hopper', title: 'VP Engineering', location: 'New York', reports: 5, budget: 1_850_000 },\n { id: 3, managerId: 2, name: 'Alan Turing', title: 'Principal Engineer', location: 'Cambridge', reports: 2, budget: 540_000 },\n { id: 4, managerId: 3, name: 'Barbara Liskov', title: 'Staff Engineer', location: 'Boston', reports: 0, budget: 210_000 },\n { id: 5, managerId: 3, name: 'Ken Thompson', title: 'Staff Engineer', location: 'Remote', reports: 0, budget: 205_000 },\n { id: 6, managerId: 2, name: 'Dennis Ritchie', title: 'Engineering Manager',location: 'New York', reports: 1, budget: 420_000 },\n { id: 7, managerId: 6, name: 'Brian Kernighan', title: 'Senior Engineer', location: 'Princeton', reports: 0, budget: 190_000 },\n { id: 8, managerId: 1, name: 'Margaret Hamilton', title: 'VP Operations', location: 'Houston', reports: 2, budget: 1_100_000 },\n { id: 9, managerId: 8, name: 'Katherine Johnson', title: 'Operations Lead', location: 'Houston', reports: 1, budget: 380_000 },\n { id: 10, managerId: 9, name: 'Dorothy Vaughan', title: 'Operations Engineer',location: 'Houston', reports: 0, budget: 175_000 },\n { id: 11, managerId: 1, name: 'Linus Torvalds', title: 'VP Infrastructure', location: 'Portland', reports: 0, budget: 950_000 },\n ]\n\n // ---- Nested source: a file tree with children arrays --------------------\n type Node = {\n id: number\n name: string\n title: string\n location: string\n reports: number\n budget: number\n children?: Node[]\n }\n\n const fileTree: Node[] = [\n {\n id: 100, name: 'src', title: 'folder', location: '—', reports: 5, budget: 0,\n children: [\n {\n id: 101, name: 'components', title: 'folder', location: '—', reports: 2, budget: 0,\n children: [\n { id: 102, name: 'Grid.svelte', title: 'component', location: '18.4 KB', reports: 0, budget: 0 },\n { id: 103, name: 'Toolbar.svelte', title: 'component', location: '6.1 KB', reports: 0, budget: 0 },\n ],\n },\n {\n id: 104, name: 'lib', title: 'folder', location: '—', reports: 2, budget: 0,\n children: [\n { id: 105, name: 'utils.ts', title: 'module', location: '3.2 KB', reports: 0, budget: 0 },\n { id: 106, name: 'format.ts', title: 'module', location: '1.8 KB', reports: 0, budget: 0 },\n ],\n },\n { id: 107, name: 'main.ts', title: 'entry', location: '0.9 KB', reports: 0, budget: 0 },\n ],\n },\n {\n id: 200, name: 'docs', title: 'folder', location: '—', reports: 2, budget: 0,\n children: [\n { id: 201, name: 'readme.md', title: 'markdown', location: '2.4 KB', reports: 0, budget: 0 },\n { id: 202, name: 'changelog.md', title: 'markdown', location: '5.7 KB', reports: 0, budget: 0 },\n ],\n },\n ]\n\n // One call converts the nested shape into the flat parent-id shape the model\n // consumes. `__parentId` is the link field it stamps on by default.\n const flattenedFiles = flattenTreeData(fileTree, { childrenField: 'children' })\n\n type Source = 'org' | 'files'\n let source = $state<Source>('org')\n\n const orgColumns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 240 },\n { field: 'title', header: 'Title', width: 190 },\n { field: 'location', header: 'Location', width: 130 },\n { field: 'reports', header: 'Reports', width: 100, align: 'right' },\n {\n field: 'budget', header: 'Budget', width: 140, align: 'right',\n format: { type: 'currency', currency: 'USD', options: { maximumFractionDigits: 0 } },\n },\n ]\n\n const fileColumns: GridColumns<Node> = [\n { field: 'name', header: 'Name', width: 280 },\n { field: 'title', header: 'Kind', width: 140 },\n { field: 'location', header: 'Size', width: 120, align: 'right' },\n ]\n\n // `expandAllGroups` / `collapseAllGroups` walk the row model's `subRows`,\n // which is exactly what the tree model builds - so they drive a tree too.\n let api = $state<SvGridApi<typeof features, Person | Node> | null>(null)\n</script>\n\n<section class=\"flex flex-col flex-1 min-h-0 gap-3\">\n <div\n class=\"shrink-0 rounded-lg border px-4 py-3\"\n style=\"border-color: var(--sg-border); background: var(--sg-header-bg);\"\n >\n <p class=\"text-sm font-semibold\" style=\"color: var(--sg-fg);\">\n Hierarchical rows via <code>treeData</code>\n </p>\n <p class=\"mt-1 text-xs\" style=\"color: var(--sg-muted);\">\n Click a chevron, or focus a row and press <kbd>→</kbd> / <kbd>←</kbd>. The\n grid uses the <code>treegrid</code> role with <code>aria-level</code> and\n <code>aria-expanded</code>, so screen readers announce the depth. Rows keep\n their own cells - sort by Budget and the hierarchy still holds.\n </p>\n\n <div class=\"mt-3 flex flex-wrap items-center gap-2\">\n <div class=\"inline-flex overflow-hidden rounded-md border\" style=\"border-color: var(--sg-border);\">\n <button\n type=\"button\" class=\"px-3 py-1 text-xs\"\n style={source === 'org'\n ? 'background: var(--sg-accent, #2563eb); color: var(--sg-on-accent, #fff);'\n : 'background: transparent; color: var(--sg-fg);'}\n onclick={() => (source = 'org')}\n >Flat (parent id)</button>\n <button\n type=\"button\" class=\"px-3 py-1 text-xs\"\n style={source === 'files'\n ? 'background: var(--sg-accent, #2563eb); color: var(--sg-on-accent, #fff);'\n : 'background: transparent; color: var(--sg-fg);'}\n onclick={() => (source = 'files')}\n >Nested (flattened)</button>\n </div>\n\n <button\n type=\"button\" class=\"rounded-md border px-3 py-1 text-xs\"\n style=\"border-color: var(--sg-border); color: var(--sg-fg);\"\n onclick={() => api?.expandAllGroups()}\n >Expand all</button>\n <button\n type=\"button\" class=\"rounded-md border px-3 py-1 text-xs\"\n style=\"border-color: var(--sg-border); color: var(--sg-fg);\"\n onclick={() => api?.collapseAllGroups()}\n >Collapse all</button>\n\n <span class=\"text-xs\" style=\"color: var(--sg-muted);\">\n {#if source === 'org'}\n <code>parentField: 'managerId'</code>\n {:else}\n <code>flattenTreeData(tree, &lbrace; childrenField: 'children' &rbrace;)</code>\n {/if}\n </span>\n </div>\n </div>\n\n <div class=\"flex-1 min-h-0\">\n {#if source === 'org'}\n <SvGrid\n columnResize\n responsive={true}\n data={people}\n columns={orgColumns}\n {features}\n treeData={{ parentField: 'managerId', column: 'name' }}\n selectionMode=\"none\"\n rowHeight={34}\n containerHeight=\"100%\"\n fitColumns={true}\n onApiReady={(a) => (api = a as never)}\n />\n {:else}\n <SvGrid\n columnResize\n responsive={true}\n data={flattenedFiles}\n columns={fileColumns}\n {features}\n treeData={{ parentField: '__parentId', column: 'name' }}\n selectionMode=\"none\"\n rowHeight={34}\n containerHeight=\"100%\"\n fitColumns={true}\n onApiReady={(a) => (api = a as never)}\n />\n {/if}\n </div>\n</section>\n"
2448
+ "source": "<!-- Documented in: docs/help/rows/tree-data.md -->\n<script lang=\"ts\">\n /**\n * 426. Tree data\n * --------------\n * `treeData` nests rows into an expandable hierarchy by parent id:\n *\n * treeData={{ parentField: 'managerId', column: 'name' }}\n *\n * Tree rows stay REAL data rows - own cells, formatting, editing, selection -\n * and only gain an expander plus indent in the tree column. (Row grouping is\n * the other shape: there the parent is a synthetic full-width banner.)\n *\n * Two input shapes, one model:\n * FLAT - rows already carry a parent id. Use it directly.\n * NESTED - objects hold a `children` array. `flattenTreeData` stamps\n * `__parentId` on each child and returns one flat list.\n */\n import {\n SvGrid,\n flattenTreeData,\n tableFeatures,\n rowSortingFeature,\n type GridColumns,\n type SvGridApi,\n } from '@svgrid/grid'\n\n const features = tableFeatures({ rowSortingFeature })\n\n // ---- Flat source: an org chart, each row naming its manager -------------\n type Person = {\n id: number\n managerId: number | null\n name: string\n title: string\n location: string\n reports: number\n budget: number\n }\n\n const people: Person[] = [\n { id: 1, managerId: null, name: 'Ada Lovelace', title: 'Chief Executive', location: 'London', reports: 10, budget: 4_200_000 },\n { id: 2, managerId: 1, name: 'Grace Hopper', title: 'VP Engineering', location: 'New York', reports: 5, budget: 1_850_000 },\n { id: 3, managerId: 2, name: 'Alan Turing', title: 'Principal Engineer', location: 'Cambridge', reports: 2, budget: 540_000 },\n { id: 4, managerId: 3, name: 'Barbara Liskov', title: 'Staff Engineer', location: 'Boston', reports: 0, budget: 210_000 },\n { id: 5, managerId: 3, name: 'Ken Thompson', title: 'Staff Engineer', location: 'Remote', reports: 0, budget: 205_000 },\n { id: 6, managerId: 2, name: 'Dennis Ritchie', title: 'Engineering Manager',location: 'New York', reports: 1, budget: 420_000 },\n { id: 7, managerId: 6, name: 'Brian Kernighan', title: 'Senior Engineer', location: 'Princeton', reports: 0, budget: 190_000 },\n { id: 8, managerId: 1, name: 'Margaret Hamilton', title: 'VP Operations', location: 'Houston', reports: 2, budget: 1_100_000 },\n { id: 9, managerId: 8, name: 'Katherine Johnson', title: 'Operations Lead', location: 'Houston', reports: 1, budget: 380_000 },\n { id: 10, managerId: 9, name: 'Dorothy Vaughan', title: 'Operations Engineer',location: 'Houston', reports: 0, budget: 175_000 },\n { id: 11, managerId: 1, name: 'Linus Torvalds', title: 'VP Infrastructure', location: 'Portland', reports: 0, budget: 950_000 },\n ]\n\n // ---- Nested source: a file tree with children arrays --------------------\n type Node = {\n id: number\n name: string\n title: string\n location: string\n reports: number\n budget: number\n children?: Node[]\n }\n\n const fileTree: Node[] = [\n {\n id: 100, name: 'src', title: 'folder', location: '-', reports: 5, budget: 0,\n children: [\n {\n id: 101, name: 'components', title: 'folder', location: '-', reports: 2, budget: 0,\n children: [\n { id: 102, name: 'Grid.svelte', title: 'component', location: '18.4 KB', reports: 0, budget: 0 },\n { id: 103, name: 'Toolbar.svelte', title: 'component', location: '6.1 KB', reports: 0, budget: 0 },\n ],\n },\n {\n id: 104, name: 'lib', title: 'folder', location: '-', reports: 2, budget: 0,\n children: [\n { id: 105, name: 'utils.ts', title: 'module', location: '3.2 KB', reports: 0, budget: 0 },\n { id: 106, name: 'format.ts', title: 'module', location: '1.8 KB', reports: 0, budget: 0 },\n ],\n },\n { id: 107, name: 'main.ts', title: 'entry', location: '0.9 KB', reports: 0, budget: 0 },\n ],\n },\n {\n id: 200, name: 'docs', title: 'folder', location: '-', reports: 2, budget: 0,\n children: [\n { id: 201, name: 'readme.md', title: 'markdown', location: '2.4 KB', reports: 0, budget: 0 },\n { id: 202, name: 'changelog.md', title: 'markdown', location: '5.7 KB', reports: 0, budget: 0 },\n ],\n },\n ]\n\n // One call converts the nested shape into the flat parent-id shape the model\n // consumes. `__parentId` is the link field it stamps on by default.\n const flattenedFiles = flattenTreeData(fileTree, { childrenField: 'children' })\n\n type Source = 'org' | 'files'\n let source = $state<Source>('org')\n\n const orgColumns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 240 },\n { field: 'title', header: 'Title', width: 190 },\n { field: 'location', header: 'Location', width: 130 },\n { field: 'reports', header: 'Reports', width: 100, align: 'right' },\n {\n field: 'budget', header: 'Budget', width: 140, align: 'right',\n format: { type: 'currency', currency: 'USD', options: { maximumFractionDigits: 0 } },\n },\n ]\n\n const fileColumns: GridColumns<Node> = [\n { field: 'name', header: 'Name', width: 280 },\n { field: 'title', header: 'Kind', width: 140 },\n { field: 'location', header: 'Size', width: 120, align: 'right' },\n ]\n\n // `expandAllGroups` / `collapseAllGroups` walk the row model's `subRows`,\n // which is exactly what the tree model builds - so they drive a tree too.\n let api = $state<SvGridApi<typeof features, Person | Node> | null>(null)\n</script>\n\n<section class=\"flex flex-col flex-1 min-h-0 gap-3\">\n <div\n class=\"shrink-0 rounded-lg border px-4 py-3\"\n style=\"border-color: var(--sg-border); background: var(--sg-header-bg);\"\n >\n <p class=\"text-sm font-semibold\" style=\"color: var(--sg-fg);\">\n Hierarchical rows via <code>treeData</code>\n </p>\n <p class=\"mt-1 text-xs\" style=\"color: var(--sg-muted);\">\n Click a chevron, or focus a row and press <kbd>→</kbd> / <kbd>←</kbd>. The\n grid uses the <code>treegrid</code> role with <code>aria-level</code> and\n <code>aria-expanded</code>, so screen readers announce the depth. Rows keep\n their own cells - sort by Budget and the hierarchy still holds.\n </p>\n\n <div class=\"mt-3 flex flex-wrap items-center gap-2\">\n <div class=\"inline-flex overflow-hidden rounded-md border\" style=\"border-color: var(--sg-border);\">\n <button\n type=\"button\" class=\"px-3 py-1 text-xs\"\n style={source === 'org'\n ? 'background: var(--sg-accent, #2563eb); color: var(--sg-on-accent, #fff);'\n : 'background: transparent; color: var(--sg-fg);'}\n onclick={() => (source = 'org')}\n >Flat (parent id)</button>\n <button\n type=\"button\" class=\"px-3 py-1 text-xs\"\n style={source === 'files'\n ? 'background: var(--sg-accent, #2563eb); color: var(--sg-on-accent, #fff);'\n : 'background: transparent; color: var(--sg-fg);'}\n onclick={() => (source = 'files')}\n >Nested (flattened)</button>\n </div>\n\n <button\n type=\"button\" class=\"rounded-md border px-3 py-1 text-xs\"\n style=\"border-color: var(--sg-border); color: var(--sg-fg);\"\n onclick={() => api?.expandAllGroups()}\n >Expand all</button>\n <button\n type=\"button\" class=\"rounded-md border px-3 py-1 text-xs\"\n style=\"border-color: var(--sg-border); color: var(--sg-fg);\"\n onclick={() => api?.collapseAllGroups()}\n >Collapse all</button>\n\n <span class=\"text-xs\" style=\"color: var(--sg-muted);\">\n {#if source === 'org'}\n <code>parentField: 'managerId'</code>\n {:else}\n <code>flattenTreeData(tree, &lbrace; childrenField: 'children' &rbrace;)</code>\n {/if}\n </span>\n </div>\n </div>\n\n <div class=\"flex-1 min-h-0\">\n {#if source === 'org'}\n <SvGrid\n columnResize\n responsive={true}\n data={people}\n columns={orgColumns}\n {features}\n treeData={{ parentField: 'managerId', column: 'name' }}\n selectionMode=\"none\"\n rowHeight={34}\n containerHeight=\"100%\"\n fitColumns={true}\n onApiReady={(a) => (api = a as never)}\n />\n {:else}\n <SvGrid\n columnResize\n responsive={true}\n data={flattenedFiles}\n columns={fileColumns}\n {features}\n treeData={{ parentField: '__parentId', column: 'name' }}\n selectionMode=\"none\"\n rowHeight={34}\n containerHeight=\"100%\"\n fitColumns={true}\n onApiReady={(a) => (api = a as never)}\n />\n {/if}\n </div>\n</section>\n"
2449
2449
  },
2450
2450
  {
2451
2451
  "id": "427-group-footers",
@@ -4388,7 +4388,7 @@ export const docs = [
4388
4388
  "path": "docs/changelog.md",
4389
4389
  "title": "Changelog",
4390
4390
  "section": "Overview",
4391
- "markdown": "# Changelog\n\nThe user-facing log of what shipped. Format follows\n[Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/);\nversioning follows [Semantic Versioning](https://semver.org/).\n\nEvery release has up to six sections:\n- **Added** - new features\n- **Changed** - existing functionality, behaviour changes\n- **Deprecated** - soon-to-be-removed features\n- **Removed** - features removed in this release\n- **Fixed** - bug fixes\n- **Security** - vulnerability patches (with CVE ids when applicable)\n\nPre-release entries live under `## [Unreleased]`. They graduate to a\ndated heading on publish via `pnpm changeset version` (see\n[.changeset/README.md](../.changeset/README.md)).\n\nFor machine-readable releases, fetch\n[`/changelog.json`](/changelog.json) - same content, parseable shape.\n\n## [Unreleased]\n\n### @svgrid/grid\n\n#### Added\n\n- **`chartSpecToTable`.** The rows and columns a spec amounts to, in the\n shape `SvGrid` takes: one row per category with a column per series (a\n grouped axis adds a Group column, a histogram From and To, candles their\n four prices, a box plot its five numbers), per point for a scatter, per\n link for a sankey or chord, per leaf for a tree map or sunburst with a\n column per level, per day for a calendar, one row for a gauge. Number\n columns carry the chart's format (a right-axis series its axis's) and a\n date axis is a date column. The gallery demos' Chart | Grid switch is this\n behind a sortable grid.\n\n- **The Chart panel charts the pivot in pivot mode.** With `pivot` and\n `charting` on one grid, the pivot bar carries the Chart toggle and the\n panel draws the pivot on screen: row groups as categories (nested rows a\n grouped axis), column groups as series, the measures' format on the axis,\n totals left out. The data pickers step aside with a note and the Type\n select keeps the shapes a pivot can take; Stacked, 100%, Horizontal, the\n Format tab, the builder, saved charts, export and Describe still apply. A\n click on a bar filters the innermost row dimension when the grid has a\n column for it, which re-runs the pivot. It used to chart the source rows by\n the source columns whatever was on screen. The mapping is\n `pivotResultToChartSpec` (with `pivotChartType`, `pivotFilterColumn`)\n in the lazy chart engine; enterprise's `pivotToChartSpec` is the same\n function. `bucketsToChartSpec` (server aggregates as a spec) moved there\n from the controller, which kept the base bundle at 86.4 KB.\n\n- **Scatter points select.** A click or Enter on a scatter or bubble point\n selects it the way a bar selects: the point's `label` (or its series) is\n the category, its y the value, and `selectable`, `bind:selected`,\n `onSelectionChange` and `onSelect` all apply. The dots had no click\n handler, so on a scatter chart those props did nothing.\n- **`ChartPointRef.index`.** A selected bar carries its category index\n beside its label, and two refs with an index match only on the same one.\n A grouped axis repeats its leaf labels (Q1 to Q4 under each year), so a\n click on the second Q2 used to select the first Q2 with it. A ref written\n without an index still matches by label.\n- **Data labels on a 100% chart read the share.** Under `stacked100` the\n axis is already a share whatever `valueFormat` says; the labels on the\n bars now say \"18%\" as well, rather than \"$18\", or \"1800%\" when the format\n was percent. A `dataLabels.formatter` still receives the raw value and the\n tooltip keeps it.\n- **A series on the right axis reads in that axis's format.** The tooltip,\n the screen-reader table, the live region and the data labels format a\n series with `axis: 'right'` through `y2Axis.format` or `formatter`, so a\n margin of 0.29 beside a revenue in dollars reads \"29%\" and not \"$0.29\".\n Without a format of its own the right axis is plain numbers, as its ticks\n are.\n- **The breadcrumb survives `toolbar={false}`.** A drilled sunburst, tree\n map or pie with the toolbar off still shows its breadcrumb in a strip of\n its own; it used to have no way back up.\n- **Chart axis model.** `xAxis`, `yAxis` and `y2Axis` on a spec take\n `min`, `max`, `nice`, `tickCount`, `tickInterval`, `format` or a\n `formatter`, `title`, `gridLines`, `labelRotation`, `reversed` and, for\n the x axis, `type: 'number'` for a numeric axis that spreads categories by\n value. `referenceBands` shade a range on either axis, `referenceLines` can\n be vertical, `title` / `subtitle` / `caption` frame the chart. Series\n gained `marker` shapes and per-point `markers` / `colors`, `strokeWidth`,\n `dash`, `opacity`, `gradient`, `step` lines, `connectNulls` and a\n `nullAs` policy; `dataLabels` takes a placement, a formatter and overlap\n hiding; the component takes a `tooltip` snippet, `tooltipFormat`,\n `tooltipMode: 'single'`, a `legend` side and a `legendItem` snippet, and\n `autosize`. `rowsToChartSpec` reduces with `min`, `max`, `median`,\n `first`, `last`, `countDistinct` and `pN` and buckets a date dimension by\n `day` / `week` / `month` / `quarter` / `year`.\n- **Decimation for long series.** `decimate: 'auto'` (the default) thins a\n line or area with more points than pixels through LTTB, which keeps the\n shape; `{ method: 'minmax' }` keeps every spike. Zoom is applied first, so\n zooming into 300 of 100,000 points shows all 300. `lttb`, `minMaxIndices`,\n `decimateSpec` and `pickCategories` are exported.\n- **Thirteen more chart types**: `histogram` (with `binValues` and\n `rowsToHistogramSpec`), `range-bar`, `range-area`, `lollipop`,\n `dumbbell`, `pareto` (`paretoSpec`), `stream` (`stackOffset: 'wiggle'` or\n `'silhouette'`), `sunburst`, `radial-bar`, `radial-column`,\n `nightingale`, `chord` and `bullet`; plus hollow and Heikin-Ashi candles\n (`candleStyle`) and pyramid / cone funnels (`funnelShape`). All of them are\n in the grid panel's picker, gated on what the current columns can feed.\n- **Zoom, pan and presets.** `zoomable` takes an object: `wheel` (`true` or\n `'modifier'` for Ctrl + wheel), `pinch`, `pan` (`'shift'`, `'mode'` or\n both) and `axis` (`'x'`, `'y'`, `'xy'`). The window is a bindable\n `zoom` prop of category indices with `zoomTo` / `resetZoom` on the\n component and an `onZoom` callback; `rangePresets` puts 1W / 1M / 3M / 6M /\n YTD / 1Y / All in the toolbar on a time axis.\n- **Synchronized charts.** Charts with the same `syncGroup` share their\n crosshair and zoom window, matched by label and then by date. The grid\n panel's `syncTabs` keeps one window across its chart tabs.\n- **Context menu, animation, drilldown, selection, keyboard.** `contextMenu`\n (built-in export / zoom / series items, your own `MenuItem`s, or a function\n of the clicked point; Shift + F10 opens it), `animate` (a data-update tween\n and `'fade'` / `'grow'` / `'wipe'` enter effects, off under reduced\n motion), `drillable` + `drillPath` for tree maps and sunbursts with a\n breadcrumb, `selectable` + `selected` + `onSelectionChange` for point\n selection with dimming, Up / Down stepping through series with a polite live\n region (`announce`).\n- **Financial toolkit.** `bollingerBands`, `rsi`, `macd`, `vwap`, `atr`,\n `stochastic`, `wma` and `obv`, NaN-padded like the moving averages;\n `'wma:N'`, `'bb:N:K'` (a shaded band) and `'vwap'` overlays;\n `indicatorPane` and `SvChartPanes`, which stacks indicator panes under a\n price chart with one x axis, one gutter and one crosshair; `rowsToOhlcSpec`\n and `resampleOhlc` (daily bars to weeks / months); `lastPriceLine`;\n annotation `shape` (`'flag'`, `'pin'`, `'square'`) with a tooltip\n `text`; `volumes` on a series.\n- **Drawing tools.** `drawable` puts trend line, horizontal ray, Fibonacci\n retracement, rectangle, arrow and note tools in the toolbar; the drawings\n are data points (`spec.drawings`, `onDrawingsChange`) so they survive a\n zoom, a resize or new data. A selected drawing has draggable handles and\n Delete removes it.\n- **PDF and print** with no PDF library: `chartToPdfBlob`, `downloadChartPdf`\n (a one-page A4 or Letter PDF with the chart as a JPEG and the titles as\n text) and `printChart`, in the toolbar, the context menu and the panel's\n export menu.\n- **Chart builder in the grid panel.** The Build button opens a modal with a\n type gallery (a live thumbnail per type), the data pickers and a Format tab\n (titles, legend and label placement, axis title / min / max / format / grid\n lines, per-series colour / type / axis / marker / width). The format is\n `ChartFormatState` on the chart tab, applied by `applyChartFormat` to every\n derived spec, saved with the view and reachable through\n `configureChart({ format })`. A link toggle unlinks a chart from the grid\n (`configureChart({ frozen: true })`) so it keeps its data while you filter.\n `charting.onChartCreated` / `onChartChanged` report the panel's lifecycle;\n `charting` also takes `zoom`, `rangePresets`, `syncGroup`, `syncTabs`,\n `contextMenu` and `animate`.\n- **Candlesticks from the grid panel.** Pick Candlestick or OHLC bars and the\n panel finds the Date, Open, High, Low, Close and Volume columns by name;\n Indicators chips add panes and overlays; `configureChart({ ohlc,\n indicators })` and the AI chart plan reach the same thing.\n- **A scatter series' `overlay` is a regression of y on x.** Until now the\n scatter layout ignored `overlay` (the fits ran on the index, which a\n scatter has no use for). The regressions (`linearFit`, `polynomialFit`,\n `exponentialFit`, `logarithmicFit`, `powerFit`) take an optional `xs`\n and return `predict(x)`; `regressionFit(values, overlay, xs)` names one by\n its overlay string; a scatter series with `overlay` gets the curve drawn\n across the plot (sampled evenly in log space on a log axis) and its\n equation and R-squared in the point tooltip.\n- **Chart gallery: fourteen full-size demos, one per family, and a docs page\n for them.** Bars, lines, areas, pie / donut / sunburst, scatter and bubble,\n combination, histogram and box plot, heat map and calendar, radar and\n radial, tree map and sunburst, sankey and chord, waterfall / funnel /\n pareto, gauges and bullets, and an annotated chart (demos 438 to 451),\n each with its own data and the switches that family needs, embedded on\n `help/charts/gallery` and the type pages.\n- **Grid chart panel: a deeper Format tab, one set of pickers, a\n localized panel and saved charts.** The builder's Format tab adds series\n labels, the crosshair's axis pills, a compact rule below a width\n (`compactBelow`, through `CHART_RESPONSIVE_PRESETS.compact`), a stack\n group per bar or area series and the chart's font, size, background and\n text colour (`ChartFormatState.seriesLabels` / `crosshairLabels` /\n `compactBelow` / `series[].stack` / `style`). The panel's pickers and the\n builder's Data tab are one component (`SvGridChartPickers`), so the two\n cannot disagree about what a type needs. Every string the panel and the\n builder show is a `chart*` key on `localization.text`\n (`GridChartPanelMessages`, loaded with the panel; `GridMessages` is now\n the chrome map and the panel map together). `api.saveChart(name)`,\n `applySavedChart`, `removeSavedChart`, `getSavedCharts` and\n `configureChart({ saved })` keep a tab's whole configuration under a name;\n the panel has a popover for them and `getState()` carries `savedCharts`\n when there are any.\n- **Chart diagnostics, a plain-language description, live feeds and a JSON\n schema.** `validateChartSpec` returns what is off about a spec (unknown\n keys with the nearest name, an unknown type, a series short of the\n categories, a log axis at zero, an overlay the engine does not read, an\n anchor naming no category, and more); `SvChart` logs the findings once per\n spec in development, `aiChart` attaches the errors to its plan, and the\n MCP server's `svgrid_check_code` applies the rules to a static spec\n literal with a rename for a misspelt key. `chartSummary` reads a chart in\n a sentence (trend, extremes, shares, correlation, last close) and\n `SvChart` hands it to assistive technology as `aria-description` and the\n table caption (`describe`), the context menu and the panel copy it, and\n `aiExplainChart` grounds an Explain button on it. `appendPoints` builds\n the next spec of a feed with every per-category array kept in step and a\n rolling window, and `live` on the chart skips the tween and enter effect.\n `docs/schemas/chart-spec.json` is generated from the types, served at\n svgrid.com/schemas and by `svgrid_get`, and a test keeps it equal to the\n validator's lists.\n- **Series and interaction depth.** Areas join `stack` groups like bars\n (`stacked100` and `stackOffset` run per pile); a numeric x axis takes\n `scale: 'log'` (even decades, 2 / 5 minors, non-positive categories\n dropped, decimation in log positions); regression overlays `poly:N`,\n `exp`, `log` and `power` next to `linear`, each carrying `r2` and\n `equation` on the overlay line and read in the tooltip, with\n `linearFit` / `polynomialFit` / `exponentialFit` / `logarithmicFit` /\n `powerFit` / `rSquared` / `computeOverlayFit` / `overlayName` exported\n and `charting.trend` accepting the new names; hovering a mark dims the\n other series (`hoverHighlight`, on by default, snapping within 18px) and\n `onHover` reports the point once per change; `tooltipPosition` parks the\n tooltip in a plot corner and `tooltipSticky` pins it on a click; data\n labels take `rotation` and `connector` (pushed clear of a collision with\n a leader line); `spec.style` sets a chart's font, size, background and\n text / grid colours over the tokens (`chartStyleVars`), honoured by the\n exports.\n- **Accessibility pass on the chart.** Every non-cartesian family (pie,\n sunburst and the radial charts, heat map, calendar, tree map, funnel,\n sankey nodes and links, radar, scatter) is one Tab stop with a roving\n focus: arrows walk the marks (a heat map by row and column, a calendar by\n day and week), Home / End / PageUp / PageDown jump, the focused mark\n raises its tooltip, Enter / Space select or drill, and every mark is named\n and has a focus ring. Zoom from the keyboard: `+` / `-` / `0` on a\n focused category and Shift + arrows to pan, and the brush is a `slider`\n (arrows pan and resize, Home / End, `0`). The toolbar is a `toolbar`, the\n tooltip a `tooltip`, decorative icons are hidden from the tree. Forced\n colors (Windows High Contrast) keep the data colours and repaint the\n chrome with the system palette. `localeText` on `SvChart` (and\n `charting.localeText` for the grid panel) translates every string the\n chart renders itself, with `ChartMessages`, `defaultChartMessages`,\n `resolveChartMessages` and `chartMessage` exported. A new\n `tests/e2e/chart-a11y.spec.ts` runs axe-core against the rendered chart\n on three demos and drives the keyboard model in a real browser.\n- **Stack groups, series labels, responsive rules, pie callouts.** `stack`\n on a bar series names the pile it joins, so plan and actual stack side by\n side in each category and the axis fits the tallest stack; `seriesLabels`\n names each line at its last point in a reserved gutter, pushed apart where\n lines end together; `responsive` patches the spec by the rendered size\n (axes merge one level deep, a rule's `legend` moves or hides the\n component's legend; `resolveResponsive` and `matchResponsiveRules` are\n exported); `dataLabels: { placement: 'outside' }` on a pie draws callout\n labels with leaders instead of percentages, and a spec can carry its own\n `dataLabels`; `visible: false` starts a series hidden with its legend chip\n dimmed; the crosshair reads off the axes with a category pill and a value\n pill (`crosshairLabels={false}` turns them off).\n- **`moveCells` - drag a selected range to move or copy it.** Grab a selected\n range by its border and drop it somewhere else. Move by default, copy with\n Ctrl / Cmd, and the modifier is read at DROP time so it can be pressed or\n released mid-drag. On whenever cell selection is on; `moveCells={false}`\n opts out. A drop is refused outright - nothing changes - when it would land\n off-grid or when any source or destination cell is read-only, rather than\n moving the part that fits and silently dropping the rest.\n- **`selectionBar` - a floating bar over the grid while rows are selected**,\n showing the count and the actions that apply to the whole selection. `true`\n gives the count and a Clear button; an array is shorthand for `{ actions }`;\n the object form also sets `position` (`'bottom'` default, or `'top'`),\n `maxVisible` and `hideClear`. The prop and its types are free; the bar\n itself is an Enterprise renderer, and without it the grid shows a short upsell\n in its place, the same way the scheduler and board views do.\n- **Edge auto-scroll for every drag that extends a rectangle** - the fill\n handle, the range move, and plain drag-select. All three were previously\n capped at whatever was already on screen when the drag began, which on a grid\n built for 100k rows meant the gesture mostly did not work. One shared rAF loop\n scrolls the container when the pointer is inside a 40px edge band, on a linear\n ramp to 20px/frame, in both axes. It keeps scrolling with the pointer parked\n still, which is the whole point of holding at an edge.\n- **Row and column resizing, both opt-in** (`rowResize`, `columnResize`).\n `columnResize` gives every header a drag handle: drag the edge, double-click\n it to size the column to its content, or focus it and use Left/Right (Shift\n for a 1px step). `rowResize` does the same vertically and brings the\n row-header column with it, since that is where the grip belongs; the grid\n stores the heights itself, so neither needs a function-valued `rowHeight`.\n Both load their code on demand, so a grid that leaves them off downloads\n neither.\n- **`ColumnDef.resizable`** - per-column opt-out, consulted only when the grid\n has `columnResize` on. `resizable: false` removes that column's handle\n entirely, so the drag, the arrow keys and double-click-to-autosize all go with\n it, and the column menu drops its Autosize item. For the columns whose width\n is part of the layout: a row-number gutter, a checkbox column, a fixed icon\n column. Programmatic sizing (`api.setColumnWidth`, `api.autosizeColumn`,\n `fitColumns`) still applies.\n- **`SvGridViewState` is exported.** It is the return type of the public\n `api.getState()`, so writing a typed \"named views\" feature previously meant\n either re-declaring the shape or reaching into an internal path.\n- **Form layer depth in `SvForm` / `createForm`.** Schema-driven forms gained:\n conditional / dependent fields (`visible` and `disabled` accept a\n `(values) => boolean` predicate; hidden fields drop out of validation and the\n submit payload), grouped **sections** and a multi-step **wizard** (`stepper`,\n with per-step validation gating), repeatable **field arrays**\n (`type: 'array'` with `itemFields`, plus `addItem` / `removeItem` / `moveItem`),\n **async validation** (debounced, stale-response-guarded, per-field\n `validating` state), **dirty tracking + `reset()`**, and **submit states**\n (`isSubmitting`, an async `onSubmit`, and `setErrors()` for server-side field\n errors). New demos: dynamic form, wizard, and field array.\n- **Public headless cores for the menu / select family** (`createMenu`,\n `createPopoverSelect`, shared `list-nav`), so the popup pickers can be driven\n headlessly and composed into custom UI.\n- **`color` on `ListOption`** - render a small color swatch before the label in\n `SvListBox` and `SvDropDownList`.\n- **`block` on `SvDateTimePicker`** - stretch the field to fill its container\n (100% width), so it fills a grid cell when used as an editor.\n- **`onClosed` on `SvDrawer`** - fires after the exit animation ends and the\n drawer leaves the DOM.\n- **`loading` on `SvField`**, and **`locked`** on `SvDockLayout` /\n `SvDockManager`.\n- **`summary` on `<SvGrid>`** - shortcut alias for `enableRowSummaries`,\n which turns on the footer row that aggregates every filtered row. It wins\n when both are set, the same precedence `selectable` has over\n `enableCellSelection`.\n- **`summary` on a column** - choose that column's footer aggregate\n (`'sum'`, `'avg'`, `'min'`, `'max'`, `'count'`, `'countDistinct'`,\n `'extent'`, `'first'`, or a custom function), or `false` to leave the cell\n blank. Without it a column keeps the old default: sum a numeric column,\n `Count: N` otherwise.\n- **Development-time configuration checks.** The grid used to fail silently on\n the most common mistakes - a misspelled `field` rendered a column of blank\n cells and printed nothing. It now warns once per problem, in dev builds only:\n\n - a column `field`, `groupBy` entry, `treeData.parentField` / `idField` or\n `treeData.column` that does not exist (with a \"did you mean\" for near misses),\n - two columns resolving to the same id,\n - `pageSize` set when pagination was never turned on,\n - a column marked `sortable` while sorting is not enabled,\n - `initialColumnPinning` while column virtualization is on, which silently\n prevents the columns from sticking,\n - `externalPagination` without `rowCount`, `externalSort` without\n `onSortingChange`, and `externalFilter` without `onFiltersChange`.\n\n The checks live in a lazy chunk behind a dev-only branch, so a production\n build never loads them and the base bundle is unchanged.\n\n#### Changed\n\n- **BREAKING: column resizing is now off by default.** Every column used to have\n a drag handle unconditionally - there was no prop, no per-column option and no\n way to turn it off, so a `width` you set was only ever a starting value a user\n could drag away. Set `columnResize` to get the handles back; the 241 demos in\n this repo that want them now say so. Sorting and filtering have always been\n opt-in behind `sortable` / `filterable`, and resizing was the odd one out.\n- **BREAKING: the footer summary row is now off by default.**\n `enableRowSummaries` used to default to `true`, so a plain\n `<SvGrid {data} {columns} />` grew an aggregate footer nobody asked for and\n every caller that did not want one had to opt out - 375 call sites in this\n repo passed `enableRowSummaries={false}` against 6 that opted in, and the\n API reference already documented the default as `false`. If you were\n relying on the old behaviour, add `summary` (or `enableRowSummaries`).\n- **Ember is now the default theme preset** (`defaultThemePreset` in\n `@svgrid/grid/themes`). It is what the demo gallery and svgrid.com open on, so\n a scaffolded or Studio-generated app now looks like the demos unless you pick\n a preset. Previously the default was Tailwind.\n- **Popup editors keep themselves on screen.** `SvAutoComplete`, `SvComboBox`,\n `SvDropDownList` and the date pickers now measure the space to the viewport\n edge: the panel flips up when there is not enough room below and clamps its\n `max-height` to the available height, so a picker opened near the bottom of the\n window no longer spills off screen.\n- **Dock manager pop-out to a new window is now off by default**\n (`allowPopout={false}`); opt in explicitly. Added a dedicated pop-out demo.\n\n#### Fixed\n\n- **Arrow keys lagged whenever the active cell had to scroll.** On the\n 10,000 x 53 large-dataset demo one ArrowDown at the bottom of the viewport\n cost about 37 ms of main-thread work and painted over two frames; it is now\n about 8 ms and paints once. Five things added up. Every rendered row was\n measured with `getBoundingClientRect` on each scroll tick, on a grid that\n had no `autoRowHeight` to use the number for, which forced a table layout\n per row (about 30 per key press). The scroll geometry the custom scrollbar\n reads was pulled inside a derived at the start of the flush, forcing a\n second full table layout that the row writes then invalidated. The\n virtualizer keyed rows by their position in the window, so a one-row\n scroll rewrote all ~30 rows x every rendered column; rows are now keyed\n `index mod windowLength`, so the rows that stay keep their `<tr>` untouched\n and the one that entered is moved with a single `insertBefore`. The row\n window only updated after the browser's `scroll` event and a\n `requestAnimationFrame`, a frame after the key press; keyboard navigation\n now syncs the virtualizer inline, since it knows where it scrolled. And\n each cell carried three selection-dependent deriveds plus the fill handle's\n `{#if}`, re-marked on every move; they are one `{@const}` now, `null` for\n a plain cell. Also closed on the way: `key in editedCellValues` on a deep\n `$state` proxy created a signal per rendered cell that never went away, and\n the header checkbox's tri-state walked every row on each arrow key.\n\n- **A heat map drew a series legend in colours its cells never use.** The\n ramp on the right is its key; the row of palette chips under it (and a\n calendar's) is gone.\n\n- **A time axis put its ticks on nothing in particular.** `xType: 'time'`\n stepped a fixed 30 or 365 days from the Unix epoch, so a tick labelled\n \"2025\" stood weeks from New Year, a \"Jun 25\" tick sat mid-June, and a\n thirty-month axis carried two labels on a plot with room for eight. Ticks\n now land on calendar boundaries in UTC (days, Mondays, the first of a\n month, quarter or year, or every few years) at about one label per 90px,\n and each label is sized to the gap between ticks rather than the axis span,\n so a quarterly axis no longer reads \"2024, 2024, 2024, 2025\". The labels\n are read in UTC too: a local-time read of a 'YYYY-MM-DD' category in the\n Americas labelled every tick with the day before.\n- **The tooltip echoed the ISO date.** On a time or ordinal-time axis the\n tooltip title, the crosshair pill and the live region wrote \"2025-06-01\";\n they write \"Jun 2025\" when every category is the first of a month, \"2025\"\n when every one is New Year, and \"Jun 1, 2025\" otherwise, through\n `xAxis.formatter` when one is set. A calendar cell names its day the same\n way. The category in `onHover`, `onSelect` and `selected` is unchanged.\n- **The screen-reader table and the CSV read \"NaN\".** A NaN gap (the way a\n forecast series marks the months before it starts) wrote the word \"NaN\"\n into the hidden data table and the CSV export, and a `null` fell back to\n 0, which told a screen reader the outage month had no sign-ups. Both are\n empty cells now.\n- **\"Double-click again to clear\" left a legend chip isolated and hidden.**\n A double-click arrives as click, click, dblclick: with a chip isolated the\n first click cleared the isolation, the second hid the chip and the dblclick\n isolated it again. A click that clears an isolation is remembered for a\n moment, and the double-click that follows it on the same chip clears; on\n another chip it moves the isolation there.\n- **A radar ignored `yAxis.min` / `max`.** The rim was always the data\n maximum, so scores out of 100 filled the dial to whatever the best score\n was and two radars could not be compared. The rim honours a pinned axis,\n a value past it sits on it, and a pinned minimum is the centre.\n- **A pie sized its gutters by the widest label on either side.** Small\n slices with long names on the left kept the same room on the right for a\n \"Chrome 62%\", and the pie drew at half the radius the pane had. The\n gutters are per side, the pie sits centred in what they leave, the floor\n radius is a quarter of the short side, and each side truncates to its own\n room.\n- **A waterfall tooltip read \"$0\" on a total.** A total bar holds 0 in the\n data and its running sum in the geometry; the tooltip and the\n screen-reader table now read the drawn value. Its x labels also tilt by\n the same fit rule as a bar chart's, with the angle the renderer needs:\n they were flagged as rotated with no angle and drew truncated instead.\n- **Histogram edges read \"1.3k, 1.3k\".** Bin edges are written at the\n precision their width needs (whole numbers with separators for a 44ms\n bin, two decimals for a 0.2 bin) rather than in the compact tick form that\n gave two neighbouring edges one label.\n- **A heat map ignored `dataLabels` in the spec.** The cell label read the\n component prop alone, so `dataLabels: { show: true }` in the spec drew\n nothing. Colour legends on heat maps and calendars also round their steps\n to the precision the range earns (\"20, 94, 167\", not \"20, 93.5, 167\").\n- **The range area read as three lines.** Its band filled at the wash an\n area under a line gets, with both edges at full stroke. The band is the\n mark: it fills at 0.35 and its edges are thin.\n- **Annotate mode pinned a tooltip instead of a note** when `tooltipSticky`\n was on too; the annotate click now owns the click.\n- **Drawings on a time axis warned on every point.** The drawing tools write\n a timestamp for every pointer position, and the spec validator matched\n those against the category list. It skips the check on a time or number\n axis, as it already did for reference lines and annotations.\n- **The panel's export menu and saved-charts dialog ignored Escape.** Both\n close on Escape and hand focus back to the button that opened them.\n- **A gauge wrote \"99.2 %\".** A symbol unit (%, degrees) hugs the number; a\n word unit (\"ms\") keeps its space.\n- **The right axis title was clipped.** Its glyphs point outward under the\n rotation and ran past the edge of the SVG.\n- **Pie callout labels ran off the chart in a narrow pane.** The pie kept a\n fixed 34px margin for its outside labels whatever their length, so a\n \"Samsung Internet 3%\" in a 380px pane was clipped to \"%\" and \"Cl\". The\n radius now makes room for the widest label on each side, keeps at least a\n fifth of the short side, and hands the renderer a per-side character\n budget to truncate to when even that is not enough.\n- **The brush strip inherited the chart's titles, axis labels and marks.**\n A title and subtitle took 45 of the strip's 88 pixels and the x labels\n another 30, leaving the mini-map a five-pixel smear under an empty band.\n The brush spec now mutes titles, axis titles and labels, reference lines\n and bands, annotations, drawings, series labels and data labels.\n- **A category chart tilted its x labels by count, not by fit.** More than\n eight categories, or any label over nine characters, tilted every label\n to -40 degrees even on a thousand-pixel chart with room to spare. `auto`\n now tilts only when the widest label does not fit its slot.\n- **A heat map wrote every column label whatever the cell width**, so\n twenty-four hours at 33px a cell read \"00:0001:0002:00\". The column\n labels thin out the way a bar chart's do.\n- **A calendar labelled the padding days of the next year.** The grid pads\n the range to a full week, and a December ending on a Thursday picked up a\n \"Jan\" tick for the two padding days. Month labels stay inside the range.\n- **A waterfall could not open on a value.** A total bar always read the\n running sum, so \"Revenue 4300\" marked as a total drew as zero and every\n bar after it hung below the axis. A total with a value now sets the sum;\n a total with 0 still reads it.\n- **`rowsToChartSpec` with `topN` duplicated a category called \"Other\".**\n A real \"Other\" in the data came out beside the folded one, two categories\n with one name, which the renderer threw on as a duplicate key. The tail\n now folds into that category.\n- **A pin annotation showed \"O…\" and nothing else.** The head held\n `truncate(label, 2)`, an initial plus an ellipsis, and no label was written\n beside it. The head carries the initial and the label sits beside the pin\n like a dot's does.\n- **A chart's hidden data table took up to 17,000px of scrollable space.**\n The screen-reader table (one row per category, capped at 1,000) carried the\n visually-hidden recipe itself, but on a `<table>` `height: 1px` and\n `width: 1px` are minimums and `overflow: hidden` does not clip, so the\n table was invisible and as tall as its rows, and every scroll container\n around a chart (the demo pages first of all) scrolled on through that much\n empty space. The clip now sits on a wrapping div; the table keeps its id,\n which the svg still points at.\n- **Two ARIA faults the axe audit found.** The chart's SVG was\n `role=\"img\"`, whose children are presentational to assistive technology,\n so the focusable marks inside it (category zones, slices, a drawing) were\n a nested-interactive violation and could be skipped by a screen reader; an\n interactive chart is a labelled `group` now (a thumbnail with\n `interactive={false}` stays an image). Sankey links carried an\n `aria-label` with no role, which ARIA prohibits; they are named images in\n the focus order.\n- **A tree map ignored `spec.tree`.** The field is documented as an alias of\n `treemap` and the sunburst honoured it; the tree map read only `treemap`.\n- **An autosized chart with a side legend grew without end in a plain block.**\n `legend=\"left\"` / `\"right\"` lays the chart out as a three-row grid, and a\n grid puts a gap between every track whether or not the toolbar and brush\n rows have anything in them. The autosize maths counted a gap only for the\n chrome that existed, so in a parent that does not pin the height, the host\n measured 8 or 16px taller than the plot it was told to fit, the plot grew\n into it, and the next measurement grew again - a few hundred pixels a\n second until the page ran out. Hiding the legend at runtime had the\n opposite fault: a dimension binding keeps its last value once its element\n is gone, so the vanished legend went on being subtracted and the plot\n ratcheted down to its 120px floor. Both fixed; a fixed-height parent hid\n them, which is why the docs' sizing example never showed either.\n- **`block` did nothing on eight editors.** The prop is declared once in\n `SvEditorProps`, and its own doc comment describes the symptom: \"in a form\n grid a row of inputs each stopping at a different width reads as broken\".\n `SvDropDownList`, `SvComboBox`, `SvMultiSelect`, `SvTreeSelect`,\n `SvGridSelect`, `SvAutoComplete`, `SvTextArea` and `SvDateRangeInput`\n accepted it by type and ignored it, so they stopped at their own 200-280px\n default while the text inputs beside them filled the row. `<SvForm>` was\n also not passing it to seven of the controls it mounts - both halves had to be\n fixed for a form row to line up.\n- **`cellDataType: 'dateString'` stored a timestamp after an edit.**\n Committing ran through the shared date coercion (`new Date(v).toISOString()`),\n so picking Christmas stored `2026-12-25T01:00:00.000Z` and the cell showed a\n timestamp beside neighbours showing plain dates - on a calendar day that\n depended on the user's timezone, since the conversion went through UTC. The\n picked date is now kept as the picked date.\n- **The filter row mounted a native date input** while the cell editor mounted\n the grid's own picker, so one column looked like two different products\n depending on where you touched it. Both use the grid's picker now.\n- **`editorType: 'number'` dropped the character you were typing.** The\n editor mounted `<input type=\"number\">`, whose value sanitization reports\n `\"\"` for anything not already a valid float - so `12.` read as empty, and\n typing `12.5` produced `125`. Same for a lone `-` and `1e`. It is a\n text input with `inputmode=\"decimal\"` and a digit filter now; the trade is\n the native spinner.\n- **Cell context menus and the comment editor floated at stale coordinates\n after a scroll.** Both are positioned at raw cursor coordinates and rendered\n `position: fixed`, but neither was in the scroll effect's gate, so they hung\n over unrelated cells. The comment editor SAVES on scroll rather than\n discarding - backdrop-click and Escape are the gestures that mean \"throw this\n away\"; a scroll is not, and must not destroy typed text.\n- **The footer summary row server-rendered as empty cells.** The totals were\n assigned from an `$effect`, and effects never run during SSR - so the server\n emitted a summary row that took up space and drew its border but held no\n numbers. They appeared only after hydration (a visible pop-in), and never at\n all for a reader with JavaScript off. A grid under the aggregation cell\n limit now derives its totals synchronously, so they ship with the HTML; a\n very large grid keeps the rAF-deferred effect so it still paints before it\n totals. `pnpm ssr:check` asserts the real aggregate now.\n- **The grid painted one unmeasured frame on every mount.** `hasMeasured`\n gates the custom scrollbars, the 16px scrollbar gutter on a trailing\n right-aligned column and the top pager (which carries a `border-top`), but\n it only flipped inside the `ResizeObserver` callback - and that callback is\n deliberately deferred by one `requestAnimationFrame`, so the browser was\n guaranteed to paint a frame with those missing and correct it on the next.\n On a first load that was the \"flashing scrollbar\"; in an app that recreates\n the grid per navigation (a `{#key}` around it, or a route that remounts) it\n showed up as the grid flashing on every sort / filter / page change, with a\n stray border line. The container is now measured synchronously in the mount\n effect - before the first paint - and the observer still handles later\n resizes. Covered by an e2e regression test, since jsdom has no layout to\n miss a paint with.\n- **Pager page-size trigger rendered as a stock button until first click.** The\n closed trigger is a placeholder until the lazy dropdown chunk loads, but its\n box styling only existed in that chunk's scoped CSS, so server-rendered and\n freshly-mounted pagers showed a UA-bordered, left-hugging `<button>` inside the\n bordered box. The placeholder now gets the same rules from `SvGrid.css`.\n- **Virtualized lists no longer flash blank on a fast scrollbar-thumb drag.**\n A fast drag can move the viewport into the windowed list's off-screen padding\n faster than JS can re-render the rows there; the padding now paints faint row\n skeletons, so `SvListBox` / `SvDropDownList` stay visually filled at any scroll\n speed. Also removed an app-wide `flushSync` from the scroll handler that could\n stall the very first scroll.\n- **Dock manager auto-hide now shows every tab of a multi-tab leaf.** Sending a\n leaf with two or more tabs to auto-hide created a single edge tab; it now\n creates one edge tab per pane.\n\n### @svgrid/enterprise\n\n#### Added\n\n- **The pivot designer's Chart view grew up.** It offers every shape a pivot\n can take (bar, line, area, lollipop, pareto, the three radial forms, pie,\n funnel, waterfall, radar, heat map, stream) in the panel's groups, with\n Stacked, 100% and Horizontal where the type uses them, the chart's own\n toolbar (PNG, SVG, PDF, print, copy), its spoken summary and a legend\n under the plot. It had six types and a Stacked box.\n\n- **`pivotToChartSpec` carries the measure's format and name.** Pass the\n value chip's `format` and the chart reads \"$470k\" on the axis and\n \"$469,662\" in the tooltip, in the measure's currency and locale; percentage\n points get a formatter that appends the sign. With one measure the value\n axis is named after it (`yAxisTitle` overrides, `null` for none). The\n designer's Chart view passes the format when its measures agree, and\n formats plainly when a layout mixes a currency and a count.\n\n- **PDF export with charts and a KPI strip.** `pdf.charts` prints charts with\n the table: a rendered chart's element is rasterised on export through the\n grid chart's PNG path, or pass an image data URL; each takes a title, a\n caption and a width, and goes above the table or below it\n (`chartsPosition`). `pdf.kpis` prints a strip of headline numbers, each a\n label over a big value with an optional coloured delta line. Roadmap\n discussion 36.\n- **The selection bar renderer, plus bulk edit.** `enableSelectionBar()`\n (or `installEnterprise`) registers the renderer behind the free\n `selectionBar` prop. The bar carries a count chip, your actions, an overflow\n menu past `maxVisible`, and Clear; at phone width it collapses to icons and\n keeps an accessible name on each. **Edit fields** opens a drawer that edits\n one or many rows at once: a field the selection disagrees on opens blank and\n stays per-row unless you touch it, so applying to 40 rows does not flatten the\n values you did not mean to change.\n- **Scheduler booking rules and conflict detection.** New model helpers\n (`overlapCount` for per-resource overlaps, `overlapsBands` for working-hours\n bands) back resource double-booking checks and business-hours enforcement.\n New demos: booking rules, financial trading hours, and HR shift coverage.\n\n#### Fixed\n\n- **A pivot chart drew an empty cell as a zero bar.** An average over no rows\n is `null` in the pivot and the bridge read it as 0; it is a gap on the\n chart now. A sum over no rows stays the 0 the engine wrote.\n\n- **PDF export depended on pdfmake's fonts registering themselves.**\n `pdfmake/build/vfs_fonts` registers its font map only as a side effect of\n being imported while a global `pdfMake` already exists, and the export's\n own lookup for the map never matched the shape the module has shipped since\n pdfmake 0.2.8 (the module is the map), so it registered nothing and relied\n on that side effect. Under a bundler the global can be a stale instance (a\n dev server re-optimising its dependencies mid-session is enough), and the\n export then failed with \"File 'Roboto-Medium.ttf' not found in virtual file\n system\" while its promise never settled. The map is now found in every\n shape the module has had (`resolvePdfVfs`) and handed to the instance that\n creates the document (`registerPdfFonts`, through `addVirtualFileSystem`\n and the `vfs` property), and an installed pdfmake whose fonts module has\n no map is reported instead of failing later.\n- **Studio emitted no theme for the fragment export and the CLI `add`\n scaffolds.** Only the full app's `+layout.svelte` carried the `--sg-*` tokens;\n `eject --fragment` (which drops that file) shipped an `app.css` with one\n hard-coded accent, and `svgrid-studio add` / `add --all` wrote none at all. The\n tokens now come from one helper (`themeTokenCss`): `src/app.css` carries them\n for the full app and the fragment, and the `add` scaffolds emit them in\n `<svelte:head>`. Drop-in outputs wrap them in `@layer svgrid-studio`, so a host\n app that already defines its own tokens keeps its look. `add` also honours\n `--theme` / `--dark`, and a project with no theme picked gets Ember (the demo\n theme) instead of Tailwind.\n- **Scheduler column alignment.** The all-day lane, day/time-grid header, and\n body columns now reserve the scrollbar width consistently, so the columns line\n up instead of drifting by the scrollbar's width.\n- **Excel export color-scale conditional formatting.** A color scale's `min` /\n `mid` / `max` are optional, so the export could build an `(string | undefined)[]`\n where a `string[]` was expected; it now falls back to the same `#ffffff` /\n `#000000` defaults the grid renders with. Because `@svgrid/enterprise` ships its\n `src`, this had surfaced as a stray `svelte-check` error in consuming apps - a\n clean app now type-checks with zero errors.\n\n### @svgrid/grid-wc\n\n#### Added\n\n- **`<sv-chart>`**, the standalone chart as a custom element, at\n `@svgrid/grid-wc/chart` with React (`/react/chart`), Vue (`/vue/chart`)\n and Angular (`SvChartComponent`) wrappers. Its surface is generated from\n `SvChart`'s own props type the way `<sv-grid>`'s is from the grid's, so the\n 26 props and 7 events stay in step; `spec` is a property, the primitives\n are attributes, and a prop that takes a boolean or a string (`legend`) keeps\n a string attribute where a bare attribute means true. Its own build in\n `dist/chart` carries none of the grid.\n- **Typed event handlers.** Each wrapper's `on<Event>` prop used to be\n `(detail: unknown) => void`, so reading `newValue` meant casting first -\n a poor advertisement for a typed wrapper. The detail type is now lifted from\n the grid's own callback signature, so 16 of the 19 events arrive fully typed\n (`TData` degrades to `Record<string, unknown>`; anything referring to a\n type that only exists inside `@svgrid/grid` stays `unknown` rather than\n naming something a consumer cannot resolve).\n\n- **React, Vue and Angular components**, as subpath imports:\n `@svgrid/grid-wc/react`, `/vue` and `/angular`. Each is generated from the\n same surface as the elements, so all 98 properties and 20 events are typed\n props on every one of them and none can drift from the grid. Each framework is\n an OPTIONAL peer dependency, so a plain-HTML consumer installs none of them,\n and the wrappers are 1.3-3.7 KB gzip because they reuse the one element bundle\n rather than shipping a second copy of the grid.\n\n They exist because a raw custom element is genuinely awkward in each:\n **React 18 and earlier stringify object props onto attributes**, so\n `columns={cols}` silently becomes `\"[object Object]\"` and the grid renders\n empty; **Vue** needs `isCustomElement` build config and a `.prop` modifier\n on every object binding; **Angular** needs `CUSTOM_ELEMENTS_SCHEMA` in every\n component that shows a grid, and gets no typed inputs. The Angular wrapper is\n compiled with ng-packagr in partial-Ivy mode, so it is consumable by a normal\n Angular build, and its selector is the element's own tag - `<sv-grid>` and\n `<sv-grid-shadow>` - with no template of its own, so there is no extra wrapper\n element in the DOM and the tag is the same one you write in plain HTML.\n\n All three also handle two ordering problems a hand-written wrapper meets:\n the element renders BEFORE a framework assigns properties in an effect, and\n `apiready` fires once during that first mount - before React can bind a\n listener at all. The handle is parked on the element and each wrapper replays\n it.\n- **The package ships TypeScript declarations.** It previously had none, so\n `import '@svgrid/grid-wc'` was an error under `moduleResolution: bundler`\n and `document.querySelector('sv-grid')` came back as a bare `Element`. The\n generated `.d.ts` augments `HTMLElementTagNameMap` and\n `HTMLElementEventMap`, so the element and its events are typed without\n hand-written declarations.\n- **`<sv-grid-shadow>` - the grid in an open shadow root**, so a host page's\n CSS cannot reach it. Same properties, attributes and events as `<sv-grid>`;\n a separate element rather than an attribute because Svelte resolves\n `customElement.shadow` at compile time, so no runtime flag can switch it.\n Isolation is one-directional and the docs say so: page CSS stops at the\n boundary, but the grid's own stylesheet is still injected into the document,\n because about twenty overlay surfaces portal to `document.body` on purpose\n to escape ancestor clipping. `--sg-*` theme tokens reach in unchanged,\n including a theme file's dark variant - custom properties are inherited, and\n inheritance crosses a shadow boundary.\n- **The elements now expose the whole grid.** `<sv-grid>` declared **7 props\n and 2 events** by hand against a `Props` type with 100 props and 19\n callbacks, so grouping, pagination, pinning, tree data, master/detail, board,\n scheduler and every Enterprise feature were unreachable from a non-Svelte\n host - while the docs said they \"all come along\". The surface is now\n **generated** from `<SvGrid>`'s own types: **98 properties** (72 with\n kebab-case attributes, 26 property-only) and **20 events**, with CI failing if\n the two drift. Costs 1.6 KiB gzip.\n- **Every grid callback is a DOM `CustomEvent`**, `detail` being the\n callback's argument - or, for the one callback taking two, an object keyed by\n its parameter names. `onApiReady` also parks the imperative handle on the\n element as `el.api`, because an event fires once and a host binding a\n listener later would otherwise never reach it.\n\n#### Fixed\n\n- **The React wrapper re-did all its work on every parent render.** Both of its\n effects had no dependency array, so any state change anywhere in the parent\n reassigned all 98 properties and rebound all 20 event listeners - 40 listener\n mutations per keystroke. It now writes only values that actually changed and\n binds listeners once through a handler ref. Measured: 20 no-op re-renders\n produce 0 listener adds, 0 removes and 0 property writes.\n\n- **The element threw when it rendered before its props were assigned.**\n Generating the prop list replaced the elements' own `data = []` /\n `columns = []` defaults with a bare `$props()`, so a consumer that assigns\n properties AFTER the element upgrades - which is what React and Angular both\n do, in an effect - got\n `TypeError: Cannot read properties of undefined (reading 'map')` and a grid\n that never rendered. Only a real framework app was late enough to reproduce\n it; an HTML fixture sets the properties in the same tick and never sees it.\n\n#### Changed\n\n- **Only arrays, objects and functions changed shape: they are property-only.**\n An HTML attribute is a string, so `columns='[object Object]'` cannot work\n and no attribute is offered for the 26 props that are not primitives. The\n published `rowclick` and `selectionchange` events keep the exact\n `detail` they shipped with, and `selectable` keeps meaning row-selection\n checkboxes - `<SvGrid>`'s prop of that name is an alias of\n `enableCellSelection`, and forwarding it would have silently repointed a\n published attribute at a different feature.\n- **Styles arrive with the code that needs them.** The build used to put every\n stylesheet in the bundle, lazy chunks included, into the entry, so a page\n that never opened the chart, a date picker or a menu still downloaded their\n CSS. Each chunk now carries its own styles and adds them to the document\n and to every open shadow root when it loads. `<sv-grid>`'s entry went from\n 107 KiB to 98.5 KiB gzip while the chart grew.\n\n### Tooling & docs\n\n#### Added\n\n- **Every chart gallery demo switches between Chart and Grid.** A segmented\n control first in each demo's toolbar flips every pane to a sortable grid\n of the rows the chart was drawn from, and back, the way the board demos\n switch Board and Table. The from-the-grid page shows the pattern in a\n runnable.\n\n- **Charting a pivot is documented.** The pivot page has a section on\n `pivotToChartSpec` (the mapping, every option, a runnable that pivots\n orders and charts them by quarter) and on the designer's Chart view\n (`chartable`, `defaultView`); the charts hub and the from-the-grid page\n link to it, the /api pivot section lists the function, and the generated\n reference covers `pivot-chart.ts`. Demo 359's data now puts every\n country in every quarter and category, so its groups are four bars, not\n one.\n\n- **27 runnable framework examples**, nine each for React, Vue and Angular:\n a first grid, sorting and filtering, editing and saving, row selection,\n grouping and totals, pagination, server-side data, theming, and Excel export\n from the Enterprise pack. Every one has\n an **Open in StackBlitz** button that boots a full editable project - no local\n install - and a new\n [React, Vue or Angular](/docs/help/web-components/frameworks) landing page\n puts the thirty-second path first.\n\n They are real apps in the repository (`packages/grid-wc/examples/`), not\n snippets, and CI compiles all of them with each framework's own compiler -\n including `ngc --strictTemplates`, so a wrong Angular binding fails the\n build. The doc listings are generated from those files, so a page cannot\n describe a version of an example that no longer exists.\n\n The Vue templates get an extra check of their own: Vue treats an unknown\n attribute as a legal fallthrough, so `<SvGrid sortabel />` type-checks\n cleanly and silently does nothing. Verified - the same typo fails the React\n and Angular compilers and passes `vue-tsc` - so the Vue examples are also\n checked against the generated surface.\n\n- **A Web Components docs category.** Eight pages under\n `help/web-components/` - quick start, a generated `<sv-grid>` reference,\n shadow DOM, React, Vue, Angular, TypeScript and limitations - replacing a\n single page that was filed under \"Layout & Styling\". The reference tables are\n generated from the grid's types, and a guard checks that the counts quoted in\n prose still match the surface.\n- **The docs run.** A `svelte` code fence tagged `{runnable}` is extracted at build time\n into a real component, so a doc page shows the source and the working result\n together rather than highlighted text. 504 examples across the corpus, taking\n the median doc page from 1 example to 3; each one is compiled by `svelte-check`\n in CI, so an example that stops working fails the build instead of rotting in\n place.\n- **`@svgrid/ui` recipe scaffolder** - `npx @svgrid/ui add <component>` drops a\n ready-to-edit starter (e.g. `add calendar`) into your app, complementing the\n shadcn-style component pages (Preview / Code, install tabs) across the UI kit.\n- **See a component before you wire it in** (`@svgrid/ui` 0.3.x).\n `npx @svgrid/ui try <component>` spins up a zero-setup Vite + Svelte sandbox and\n opens the component in your browser; `add --preview` writes a\n `src/routes/preview/<id>` route (plus a `/preview` index) in a SvelteKit app.\n `add` now installs `@svgrid/grid` by default (`--no-install` to opt out) and\n prints the exact `try` command for whatever you just added, so the \"see it\"\n step is never a dead end.\n- **AI coding Skill** (`skills/svgrid`, installable with\n `npx skills add sv-grid/sv-grid`) - an always-on house-style guidance layer\n that complements `@svgrid/mcp`.\n- **The rest of the toolkit is findable.** `packages/grid/README.md` gained an\n \"Also in the box\" section, and the site footer gained a **Toolkit** column\n (SvGrid UI, Kanban board, Scheduler, Dock layout, Studio, Web components).\n The 84 SvGrid UI components have always been exported from `@svgrid/grid`\n itself - `SvButton`, `SvCalendar`, `SvDateTimePicker`, `SvDockLayout`,\n `SvToaster` and the rest are already installed for every grid user - but\n nothing on the highest-traffic surfaces said so.\n\n#### Changed\n\n- **Doc examples show code and result at once.** The runnable card used to be a\n Preview / Code toggle with an in-page editor; it is now the source above the\n live example, both visible, with Copy. A tab hides half of a teaching example\n and makes comparing the two a click, and dropping the editor took the\n on-demand TypeScript compiler chunk off every docs page with it.\n- **`npm create @svgrid` starts on Ember** (the demo theme) instead of Tailwind,\n for every template; `--theme <id>` still picks any preset. The `sveltekit`\n template is now listed on the starters page, and the `sv add @svgrid` demo route\n imports the Ember stylesheet so it no longer renders unthemed.\n\n#### Fixed\n\n- **`build:lib` in the enterprise package deleted the node bundle.**\n `svelte-package` wipes `dist/`, so a library build alone removed\n `dist/node/studio.js` and the MCP server failed to start until\n `build:node` was run by hand. The library build rebuilds the bundle it\n removed.\n\n- **Docs images and tutorial media 404'd under a site base.** The markdown\n writes them root-absolute (`/docs-media/...`, `/tutorials/...`), which is\n right at svgrid.com and wrong under the `/sv-grid/` base the e2e server\n uses: every docs image and tutorial poster was missing there. The page\n prefixes the base in the HTML before it paints, and an e2e spec loads a\n page with both and checks nothing under those roots 404s.\n\n- **Twenty-one links on the chart pages went to GitHub 404s.** The split\n wrote every cross-link with one `../` too many, and the site's link\n resolver falls back to a GitHub URL for a page it does not know. Fixed on\n the pages, and every relative link under docs/ is now a test\n (`tools/docs-relative-links.test.ts`); the link checker existed but only\n ran by hand before a release.\n- **Links into the generated reference tree went to GitHub too.** The tree\n is hidden from the docs routes; a link to it lands on the /api page, on the\n module's section where it has one.\n- **The chart gallery said \"the source is under each example\" and it was\n not.** Each gallery card now carries the demo's own script and markup on a\n Code tab, written by `tools/gallery-doc-code.mjs` from the demo file and\n guarded by a drift test, so the code beside a preview is the code that\n renders it.\n- **A demo page flattened a bulleted banner into one paragraph**, dashes and\n backticks included. The page reads the pitch as blocks: a list where the\n banner wrote one, `<code>` where it wrote backticks, on the prerendered\n and the hydrated page alike.\n- **`demo-doc-embed` skipped a demo the page only linked to**, so a\n placement for it never landed, and it opened a new \"More examples\" section\n below \"See also\", which the coverage test requires to be last. Present\n means embedded, and the section opens above \"See also\".\n- **Regenerating the doc snippets took the dev server's file watcher with\n it.** The extractor removed and recreated its output directory, and on\n Windows the watch did not re-attach, so an edited runnable kept serving\n its old chunk while the source beside it showed the new code. It writes in\n place and removes only what no longer belongs.\n- **The Getting started chart page had no live example.** Its code blocks\n were `ts` and a Svelte block referencing rows it never declared; four of\n them run now, and the hub's first example runs with its own rows and a\n filter row, so the chart is seen following the grid.\n\n- **The e2e suite adopted any server on :5180.** Playwright reuses whatever\n answers on the port, and a Vite dev server returns the app shell for any\n path, so a website dev server started by hand (base `/`) passed the\n readiness check and the fourteen path-routed and module-importing specs\n failed with nothing pointing at the server. The config now probes the port\n first (`tests/e2e/lib/site-server-probe.mjs` reads the base off Vite's\n client script tag), reuses a server that serves the site under `/sv-grid/`,\n skips one that serves anything else with a line saying so, and starts its\n own on the next free port; `SVGRID_E2E_PORT` pins one.\n- **The website dev server re-optimised dependencies mid-session.** The\n search index, the docs renderer, the /api runner's compilers, the PDF\n exporter and the grid's `esm-env` sit behind dynamic imports the start-up\n scan does not reach, so the first page to touch each one triggered\n \"optimized dependencies changed. reloading\" on every open page. In the e2e\n suite that reload landed mid-test on a cold cache and failed whichever spec\n was on a page at the time. They are pre-bundled at start-up now\n (`optimizeDeps.include`), and `esm-env` is a declared devDependency of the\n website so it resolves from there.\n- **The /api runner check sampled an example's outcome two frames after\n Run.** An example awaiting an export or a fetch was still running, so a\n failure that arrived later, or one thrown inside a library callback the\n runner's try/catch cannot see, passed. The check now waits for the runner\n to report an outcome and counts an uncaught error or rejection during the\n run as a failure of that example.\n- **181 doc pages had content stranded below \"See also\".** Authoring passes\n appended new sections to the end of the file, which buried them under what\n reads as the page footer: on `help/filtering/number-filter`, for instance, the\n `between` example sat below the link list and a reader would never reach it.\n The footer is back at the bottom on every page, and a test now fails if a\n section lands under it.\n- **The documented way to lock one column's width never worked.**\n `docs/help/columns/column-sizing.md` matched headers on `data-col-id`, which is\n the attribute on *body* cells - the selector matched nothing. Header cells\n carry `data-svgrid-header-col`. (`ColumnDef.resizable` is now the real answer.)\n- **`blockKey` was missing from `tools/lib/md-snippets.d.mts`.** The function was\n exported from the `.mjs` and worked at runtime, so nothing caught it until the\n website was type-checked.\n- **`@svgrid/mcp` reports its real version.** The MCP server's\n `serverInfo.version` was hardcoded to `0.1.0`; it now reads the package version.\n- **`@svgrid/create-studio` scaffold builds out of the box.** The generated app\n shipped an orphaned `/products` route referencing an entity that was never\n defined; the `Product` schema, seed, data source, nav, and home card are now\n complete, so `npm run build` succeeds on a fresh scaffold.\n- **API-docs accuracy pass across all 74 UI-component pages.** Corrected the\n `SvDockLayout`, `SvDockManager`, and `SvDateTimePicker` prop tables (added 13\n missing dock-layout props; removed a `size` prop `SvDateTimePicker` never had),\n and filled scattered gaps (`loading`, `onClosed`, `min` / `max`, `dir`,\n `width` / `height`, `ariaLabel`, and the shared field-contract on\n `SvFileUpload`).\n\n## [1.0.0] - 2026-06-16\n\nInitial public release - the Svelte 5-native data grid: `@svgrid/grid`\n(MIT core) and `@svgrid/enterprise` (the paid feature pack).\n\n### @svgrid/grid\n\n- **New** `onCellValueChange` callback on `<SvGrid>`. Fires after every\n inline edit commits with `{ rowIndex, columnId, oldValue, newValue,\n row }`. The recommended hook for server-side persistence and cascading\n recomputes; see demo `18-cascade-editing` and\n [Saving values](./help/editing/saving-values.md).\n- **New** `externalSort` + `externalFilter` props. Grid records the UI\n state but does NOT re-order / filter rows - the consumer owns the\n pipeline. Paired with `onSortingChange` / `onFiltersChange` for\n server-side data and tree-data scenarios.\n- **New** `onSortingChange(sorting)` / `onFiltersChange(filters)`\n callbacks. Fire on every change with the consolidated payload shapes\n documented in the [SvGrid reference](./reference/SvGrid.md).\n- **New** `onRowSelectionChange(selection, rows)` and\n `onActiveCellChange(cell)` callbacks.\n- **New** `fitColumns` prop. Scales column widths to fill the viewport,\n with rounding-residue absorbed in the last scalable column. Shrinks\n down to 85 % of natural widths; beyond that a horizontal scrollbar\n appears.\n- **New** `showRowNumbers` prop. Leading 1-based row-number column,\n rendered before any selection column.\n- **New** `pageSize` prop on `<SvGrid>`. Initial page size for the\n built-in pager.\n- **Improved** column virtualizer now detects per-item size changes,\n not just total size. Fixes a regression where resizing a column under\n `fitColumns` left other columns stale.\n- **Improved** the wrapper-managed filter pipeline no longer applies\n filters to the pre-paginated view - the filter UI always sees the\n full dataset, not just the visible page. (Removed\n `paginatedRowModel` from the engine pipeline; pagination is applied\n AFTER filters by the wrapper.)\n\n### @svgrid/enterprise\n\n- **New** package. The paid feature pack adds:\n - **Export** to xlsx / pdf / csv / tsv / html, with theme-matched\n styles, multi-sheet workbooks, header + footer with logo, embedded\n cell images. See [Export](./help/export.md).\n - **Print** with repeat-on-page headers, optional cover page,\n page-size + orientation.\n - **Import** from xlsx / csv / tsv / json with column mapping +\n per-row validation. See [Import](./help/import.md).\n - **AI assistant**: provider-agnostic helpers for natural-language\n filter, smart fill, summarize, and classify. Bring your own model\n adapter. See [AI](./help/ai.md).\n - **Pivot tables** via `createPivotModel(data, config)` and\n `pro.pivot.build(config)`. Row + column axes, 8 built-in\n aggregators or custom, grand-total row + column, subtotals,\n custom axis sort. See [Pivot tables](./help/pivot.md).\n- **New** `installEnterprise(api)` augments a `SvGridApi` with `exportData`,\n `print`, `importData`, `ai.*`, and `pivot.*` methods.\n- **Soft-gated licensing**: features run unlicensed but the grid shows\n a small watermark + a one-time console nudge. `setLicenseKey('SVENTERPRISE-…')`\n at app startup clears both.\n\n### Examples gallery\n\n- **New demos** (56-59): theme-matched export, branded export with\n header + footer + logo, export with cell images, multi-sheet export.\n- **New demos** (52-pivot-table, 51-ai-assistant, 53-excel-import):\n reference implementations for each Enterprise feature.\n- **New demos** for industry verticals: stock market (live ticks),\n HR team, finances ledger, industrial IoT, localization, CSP\n compliant, accessibility, cascade editing, server-side rendering,\n industrial dashboard, healthcare EMR, logistics, compliance queue,\n field service, gantt, scheduler, CRM, admin dashboard, seller panel.\n- **New** \"Source\" button on every demo opens the raw `.svelte` file\n in a modal with a Copy-to-clipboard button. Wired via\n `import.meta.glob('../demos/*.svelte', { query: '?raw' })` so it\n picks up new demos automatically.\n\n### Docs\n\n- **New** [Enterprise feature pack](./enterprise/README.md) landing page.\n- **New** [API reference](./reference/index.md) with hand-curated\n pages for `<SvGrid>`, `SvGridApi`, `ColumnDef`, features, and the\n full Enterprise surface.\n- **New** [Why headless?](./why-headless.md) explains the layered\n architecture and when to drop down to the headless core.\n- **New** [Tailwind integration](./help/tailwind.md) walks the\n `--sg-*` token surface, dark-mode wiring via `data-theme`, and the\n override hooks for the stable `.sv-grid-*` class names.\n- **Split** [Getting started](./getting-started.md) into six short\n pages (install / first-grid / data-and-columns / features /\n theme-and-density / going-to-production); the old single-page\n version is preserved at\n [getting-started-full.md](./getting-started-full.md).\n- **Cleaned** every code sample against the live library surface.\n Removed phantom APIs: `state={...}`, `rowModels={...}`,\n `initialState={...}`, `manualFiltering`, `manualSorting`,\n `manualPagination`, `onColumnFiltersChange`, the wrapper `getRowId`\n prop, per-column `enableSorting` / `enableColumnFilter` /\n `enableGrouping` flags, the never-shipped\n `@svgrid/grid/themes/default.css` import.\n- **Em-dashes globally swept to hyphens** (`-` → `-`) across all\n source-controlled text. Codified as a rule for new content.\n\n## How we version\n\n| Tier | What it means |\n| ----------------- | -------------------------------------------------------------------------------------------------------------- |\n| **Major** (1.x) | Breaking change to a Stable API. Includes prop / method renames, type-narrowing, default-behaviour changes. |\n| **Minor** | New Stable API. New Experimental API. New demo. Doc rewrites that touch the public-facing claims. |\n| **Patch** | Bug fixes. Type-only fixes. Internal refactors with no public surface change. Doc typo fixes. |\n\nThe [API stability page](./help/api-stability.md) annotates each export\nwith its current tier (`Stable`, `Experimental`, `Internal`). As of 1.0,\n`Stable` APIs follow semver; `Experimental` APIs may still change in a\nminor release.\n"
4391
+ "markdown": "# Changelog\n\nThe user-facing log of what shipped. Format follows\n[Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/);\nversioning follows [Semantic Versioning](https://semver.org/).\n\nEvery release has up to six sections:\n- **Added** - new features\n- **Changed** - existing functionality, behaviour changes\n- **Deprecated** - soon-to-be-removed features\n- **Removed** - features removed in this release\n- **Fixed** - bug fixes\n- **Security** - vulnerability patches (with CVE ids when applicable)\n\nPre-release entries live under `## [Unreleased]`. They graduate to a\ndated heading on publish via `pnpm changeset version` (see\n[.changeset/README.md](../.changeset/README.md)).\n\nFor machine-readable releases, fetch\n[`/changelog.json`](/changelog.json) - same content, parseable shape.\n\n## [Unreleased]\n\n### @svgrid/grid\n\n#### Added\n\n- **`chartSpecToTable`.** The rows and columns a spec amounts to, in the\n shape `SvGrid` takes: one row per category with a column per series (a\n grouped axis adds a Group column, a histogram From and To, candles their\n four prices, a box plot its five numbers), per point for a scatter, per\n link for a sankey or chord, per leaf for a tree map or sunburst with a\n column per level, per day for a calendar, one row for a gauge. Number\n columns carry the chart's format (a right-axis series its axis's) and a\n date axis is a date column. The gallery demos' Chart | Grid switch is this\n behind a sortable grid.\n\n- **The Chart panel charts the pivot in pivot mode.** With `pivot` and\n `charting` on one grid, the pivot bar carries the Chart toggle and the\n panel draws the pivot on screen: row groups as categories (nested rows a\n grouped axis), column groups as series, the measures' format on the axis,\n totals left out. The data pickers step aside with a note and the Type\n select keeps the shapes a pivot can take; Stacked, 100%, Horizontal, the\n Format tab, the builder, saved charts, export and Describe still apply. A\n click on a bar filters the innermost row dimension when the grid has a\n column for it, which re-runs the pivot. It used to chart the source rows by\n the source columns whatever was on screen. The mapping is\n `pivotResultToChartSpec` (with `pivotChartType`, `pivotFilterColumn`)\n in the lazy chart engine; enterprise's `pivotToChartSpec` is the same\n function. `bucketsToChartSpec` (server aggregates as a spec) moved there\n from the controller, which kept the base bundle at 86.4 KB.\n\n- **Scatter points select.** A click or Enter on a scatter or bubble point\n selects it the way a bar selects: the point's `label` (or its series) is\n the category, its y the value, and `selectable`, `bind:selected`,\n `onSelectionChange` and `onSelect` all apply. The dots had no click\n handler, so on a scatter chart those props did nothing.\n- **`ChartPointRef.index`.** A selected bar carries its category index\n beside its label, and two refs with an index match only on the same one.\n A grouped axis repeats its leaf labels (Q1 to Q4 under each year), so a\n click on the second Q2 used to select the first Q2 with it. A ref written\n without an index still matches by label.\n- **Data labels on a 100% chart read the share.** Under `stacked100` the\n axis is already a share whatever `valueFormat` says; the labels on the\n bars now say \"18%\" as well, rather than \"$18\", or \"1800%\" when the format\n was percent. A `dataLabels.formatter` still receives the raw value and the\n tooltip keeps it.\n- **A series on the right axis reads in that axis's format.** The tooltip,\n the screen-reader table, the live region and the data labels format a\n series with `axis: 'right'` through `y2Axis.format` or `formatter`, so a\n margin of 0.29 beside a revenue in dollars reads \"29%\" and not \"$0.29\".\n Without a format of its own the right axis is plain numbers, as its ticks\n are.\n- **The breadcrumb survives `toolbar={false}`.** A drilled sunburst, tree\n map or pie with the toolbar off still shows its breadcrumb in a strip of\n its own; it used to have no way back up.\n- **Chart axis model.** `xAxis`, `yAxis` and `y2Axis` on a spec take\n `min`, `max`, `nice`, `tickCount`, `tickInterval`, `format` or a\n `formatter`, `title`, `gridLines`, `labelRotation`, `reversed` and, for\n the x axis, `type: 'number'` for a numeric axis that spreads categories by\n value. `referenceBands` shade a range on either axis, `referenceLines` can\n be vertical, `title` / `subtitle` / `caption` frame the chart. Series\n gained `marker` shapes and per-point `markers` / `colors`, `strokeWidth`,\n `dash`, `opacity`, `gradient`, `step` lines, `connectNulls` and a\n `nullAs` policy; `dataLabels` takes a placement, a formatter and overlap\n hiding; the component takes a `tooltip` snippet, `tooltipFormat`,\n `tooltipMode: 'single'`, a `legend` side and a `legendItem` snippet, and\n `autosize`. `rowsToChartSpec` reduces with `min`, `max`, `median`,\n `first`, `last`, `countDistinct` and `pN` and buckets a date dimension by\n `day` / `week` / `month` / `quarter` / `year`.\n- **Decimation for long series.** `decimate: 'auto'` (the default) thins a\n line or area with more points than pixels through LTTB, which keeps the\n shape; `{ method: 'minmax' }` keeps every spike. Zoom is applied first, so\n zooming into 300 of 100,000 points shows all 300. `lttb`, `minMaxIndices`,\n `decimateSpec` and `pickCategories` are exported.\n- **Thirteen more chart types**: `histogram` (with `binValues` and\n `rowsToHistogramSpec`), `range-bar`, `range-area`, `lollipop`,\n `dumbbell`, `pareto` (`paretoSpec`), `stream` (`stackOffset: 'wiggle'` or\n `'silhouette'`), `sunburst`, `radial-bar`, `radial-column`,\n `nightingale`, `chord` and `bullet`; plus hollow and Heikin-Ashi candles\n (`candleStyle`) and pyramid / cone funnels (`funnelShape`). All of them are\n in the grid panel's picker, gated on what the current columns can feed.\n- **Zoom, pan and presets.** `zoomable` takes an object: `wheel` (`true` or\n `'modifier'` for Ctrl + wheel), `pinch`, `pan` (`'shift'`, `'mode'` or\n both) and `axis` (`'x'`, `'y'`, `'xy'`). The window is a bindable\n `zoom` prop of category indices with `zoomTo` / `resetZoom` on the\n component and an `onZoom` callback; `rangePresets` puts 1W / 1M / 3M / 6M /\n YTD / 1Y / All in the toolbar on a time axis.\n- **Synchronized charts.** Charts with the same `syncGroup` share their\n crosshair and zoom window, matched by label and then by date. The grid\n panel's `syncTabs` keeps one window across its chart tabs.\n- **Context menu, animation, drilldown, selection, keyboard.** `contextMenu`\n (built-in export / zoom / series items, your own `MenuItem`s, or a function\n of the clicked point; Shift + F10 opens it), `animate` (a data-update tween\n and `'fade'` / `'grow'` / `'wipe'` enter effects, off under reduced\n motion), `drillable` + `drillPath` for tree maps and sunbursts with a\n breadcrumb, `selectable` + `selected` + `onSelectionChange` for point\n selection with dimming, Up / Down stepping through series with a polite live\n region (`announce`).\n- **Financial toolkit.** `bollingerBands`, `rsi`, `macd`, `vwap`, `atr`,\n `stochastic`, `wma` and `obv`, NaN-padded like the moving averages;\n `'wma:N'`, `'bb:N:K'` (a shaded band) and `'vwap'` overlays;\n `indicatorPane` and `SvChartPanes`, which stacks indicator panes under a\n price chart with one x axis, one gutter and one crosshair; `rowsToOhlcSpec`\n and `resampleOhlc` (daily bars to weeks / months); `lastPriceLine`;\n annotation `shape` (`'flag'`, `'pin'`, `'square'`) with a tooltip\n `text`; `volumes` on a series.\n- **Drawing tools.** `drawable` puts trend line, horizontal ray, Fibonacci\n retracement, rectangle, arrow and note tools in the toolbar; the drawings\n are data points (`spec.drawings`, `onDrawingsChange`) so they survive a\n zoom, a resize or new data. A selected drawing has draggable handles and\n Delete removes it.\n- **PDF and print** with no PDF library: `chartToPdfBlob`, `downloadChartPdf`\n (a one-page A4 or Letter PDF with the chart as a JPEG and the titles as\n text) and `printChart`, in the toolbar, the context menu and the panel's\n export menu.\n- **Chart builder in the grid panel.** The Build button opens a modal with a\n type gallery (a live thumbnail per type), the data pickers and a Format tab\n (titles, legend and label placement, axis title / min / max / format / grid\n lines, per-series colour / type / axis / marker / width). The format is\n `ChartFormatState` on the chart tab, applied by `applyChartFormat` to every\n derived spec, saved with the view and reachable through\n `configureChart({ format })`. A link toggle unlinks a chart from the grid\n (`configureChart({ frozen: true })`) so it keeps its data while you filter.\n `charting.onChartCreated` / `onChartChanged` report the panel's lifecycle;\n `charting` also takes `zoom`, `rangePresets`, `syncGroup`, `syncTabs`,\n `contextMenu` and `animate`.\n- **Candlesticks from the grid panel.** Pick Candlestick or OHLC bars and the\n panel finds the Date, Open, High, Low, Close and Volume columns by name;\n Indicators chips add panes and overlays; `configureChart({ ohlc,\n indicators })` and the AI chart plan reach the same thing.\n- **A scatter series' `overlay` is a regression of y on x.** Until now the\n scatter layout ignored `overlay` (the fits ran on the index, which a\n scatter has no use for). The regressions (`linearFit`, `polynomialFit`,\n `exponentialFit`, `logarithmicFit`, `powerFit`) take an optional `xs`\n and return `predict(x)`; `regressionFit(values, overlay, xs)` names one by\n its overlay string; a scatter series with `overlay` gets the curve drawn\n across the plot (sampled evenly in log space on a log axis) and its\n equation and R-squared in the point tooltip.\n- **Chart gallery: fourteen full-size demos, one per family, and a docs page\n for them.** Bars, lines, areas, pie / donut / sunburst, scatter and bubble,\n combination, histogram and box plot, heat map and calendar, radar and\n radial, tree map and sunburst, sankey and chord, waterfall / funnel /\n pareto, gauges and bullets, and an annotated chart (demos 438 to 451),\n each with its own data and the switches that family needs, embedded on\n `help/charts/gallery` and the type pages.\n- **Grid chart panel: a deeper Format tab, one set of pickers, a\n localized panel and saved charts.** The builder's Format tab adds series\n labels, the crosshair's axis pills, a compact rule below a width\n (`compactBelow`, through `CHART_RESPONSIVE_PRESETS.compact`), a stack\n group per bar or area series and the chart's font, size, background and\n text colour (`ChartFormatState.seriesLabels` / `crosshairLabels` /\n `compactBelow` / `series[].stack` / `style`). The panel's pickers and the\n builder's Data tab are one component (`SvGridChartPickers`), so the two\n cannot disagree about what a type needs. Every string the panel and the\n builder show is a `chart*` key on `localization.text`\n (`GridChartPanelMessages`, loaded with the panel; `GridMessages` is now\n the chrome map and the panel map together). `api.saveChart(name)`,\n `applySavedChart`, `removeSavedChart`, `getSavedCharts` and\n `configureChart({ saved })` keep a tab's whole configuration under a name;\n the panel has a popover for them and `getState()` carries `savedCharts`\n when there are any.\n- **Chart diagnostics, a plain-language description, live feeds and a JSON\n schema.** `validateChartSpec` returns what is off about a spec (unknown\n keys with the nearest name, an unknown type, a series short of the\n categories, a log axis at zero, an overlay the engine does not read, an\n anchor naming no category, and more); `SvChart` logs the findings once per\n spec in development, `aiChart` attaches the errors to its plan, and the\n MCP server's `svgrid_check_code` applies the rules to a static spec\n literal with a rename for a misspelt key. `chartSummary` reads a chart in\n a sentence (trend, extremes, shares, correlation, last close) and\n `SvChart` hands it to assistive technology as `aria-description` and the\n table caption (`describe`), the context menu and the panel copy it, and\n `aiExplainChart` grounds an Explain button on it. `appendPoints` builds\n the next spec of a feed with every per-category array kept in step and a\n rolling window, and `live` on the chart skips the tween and enter effect.\n `docs/schemas/chart-spec.json` is generated from the types, served at\n svgrid.com/schemas and by `svgrid_get`, and a test keeps it equal to the\n validator's lists.\n- **Series and interaction depth.** Areas join `stack` groups like bars\n (`stacked100` and `stackOffset` run per pile); a numeric x axis takes\n `scale: 'log'` (even decades, 2 / 5 minors, non-positive categories\n dropped, decimation in log positions); regression overlays `poly:N`,\n `exp`, `log` and `power` next to `linear`, each carrying `r2` and\n `equation` on the overlay line and read in the tooltip, with\n `linearFit` / `polynomialFit` / `exponentialFit` / `logarithmicFit` /\n `powerFit` / `rSquared` / `computeOverlayFit` / `overlayName` exported\n and `charting.trend` accepting the new names; hovering a mark dims the\n other series (`hoverHighlight`, on by default, snapping within 18px) and\n `onHover` reports the point once per change; `tooltipPosition` parks the\n tooltip in a plot corner and `tooltipSticky` pins it on a click; data\n labels take `rotation` and `connector` (pushed clear of a collision with\n a leader line); `spec.style` sets a chart's font, size, background and\n text / grid colours over the tokens (`chartStyleVars`), honoured by the\n exports.\n- **Accessibility pass on the chart.** Every non-cartesian family (pie,\n sunburst and the radial charts, heat map, calendar, tree map, funnel,\n sankey nodes and links, radar, scatter) is one Tab stop with a roving\n focus: arrows walk the marks (a heat map by row and column, a calendar by\n day and week), Home / End / PageUp / PageDown jump, the focused mark\n raises its tooltip, Enter / Space select or drill, and every mark is named\n and has a focus ring. Zoom from the keyboard: `+` / `-` / `0` on a\n focused category and Shift + arrows to pan, and the brush is a `slider`\n (arrows pan and resize, Home / End, `0`). The toolbar is a `toolbar`, the\n tooltip a `tooltip`, decorative icons are hidden from the tree. Forced\n colors (Windows High Contrast) keep the data colours and repaint the\n chrome with the system palette. `localeText` on `SvChart` (and\n `charting.localeText` for the grid panel) translates every string the\n chart renders itself, with `ChartMessages`, `defaultChartMessages`,\n `resolveChartMessages` and `chartMessage` exported. A new\n `tests/e2e/chart-a11y.spec.ts` runs axe-core against the rendered chart\n on three demos and drives the keyboard model in a real browser.\n- **Stack groups, series labels, responsive rules, pie callouts.** `stack`\n on a bar series names the pile it joins, so plan and actual stack side by\n side in each category and the axis fits the tallest stack; `seriesLabels`\n names each line at its last point in a reserved gutter, pushed apart where\n lines end together; `responsive` patches the spec by the rendered size\n (axes merge one level deep, a rule's `legend` moves or hides the\n component's legend; `resolveResponsive` and `matchResponsiveRules` are\n exported); `dataLabels: { placement: 'outside' }` on a pie draws callout\n labels with leaders instead of percentages, and a spec can carry its own\n `dataLabels`; `visible: false` starts a series hidden with its legend chip\n dimmed; the crosshair reads off the axes with a category pill and a value\n pill (`crosshairLabels={false}` turns them off).\n- **`moveCells` - drag a selected range to move or copy it.** Grab a selected\n range by its border and drop it somewhere else. Move by default, copy with\n Ctrl / Cmd, and the modifier is read at DROP time so it can be pressed or\n released mid-drag. On whenever cell selection is on; `moveCells={false}`\n opts out. A drop is refused outright - nothing changes - when it would land\n off-grid or when any source or destination cell is read-only, rather than\n moving the part that fits and silently dropping the rest.\n- **`selectionBar` - a floating bar over the grid while rows are selected**,\n showing the count and the actions that apply to the whole selection. `true`\n gives the count and a Clear button; an array is shorthand for `{ actions }`;\n the object form also sets `position` (`'bottom'` default, or `'top'`),\n `maxVisible` and `hideClear`. The prop and its types are free; the bar\n itself is an Enterprise renderer, and without it the grid shows a short upsell\n in its place, the same way the scheduler and board views do.\n- **Edge auto-scroll for every drag that extends a rectangle** - the fill\n handle, the range move, and plain drag-select. All three were previously\n capped at whatever was already on screen when the drag began, which on a grid\n built for 100k rows meant the gesture mostly did not work. One shared rAF loop\n scrolls the container when the pointer is inside a 40px edge band, on a linear\n ramp to 20px/frame, in both axes. It keeps scrolling with the pointer parked\n still, which is the whole point of holding at an edge.\n- **Row and column resizing, both opt-in** (`rowResize`, `columnResize`).\n `columnResize` gives every header a drag handle: drag the edge, double-click\n it to size the column to its content, or focus it and use Left/Right (Shift\n for a 1px step). `rowResize` does the same vertically and brings the\n row-header column with it, since that is where the grip belongs; the grid\n stores the heights itself, so neither needs a function-valued `rowHeight`.\n Both load their code on demand, so a grid that leaves them off downloads\n neither.\n- **`ColumnDef.resizable`** - per-column opt-out, consulted only when the grid\n has `columnResize` on. `resizable: false` removes that column's handle\n entirely, so the drag, the arrow keys and double-click-to-autosize all go with\n it, and the column menu drops its Autosize item. For the columns whose width\n is part of the layout: a row-number gutter, a checkbox column, a fixed icon\n column. Programmatic sizing (`api.setColumnWidth`, `api.autosizeColumn`,\n `fitColumns`) still applies.\n- **`SvGridViewState` is exported.** It is the return type of the public\n `api.getState()`, so writing a typed \"named views\" feature previously meant\n either re-declaring the shape or reaching into an internal path.\n- **Form layer depth in `SvForm` / `createForm`.** Schema-driven forms gained:\n conditional / dependent fields (`visible` and `disabled` accept a\n `(values) => boolean` predicate; hidden fields drop out of validation and the\n submit payload), grouped **sections** and a multi-step **wizard** (`stepper`,\n with per-step validation gating), repeatable **field arrays**\n (`type: 'array'` with `itemFields`, plus `addItem` / `removeItem` / `moveItem`),\n **async validation** (debounced, stale-response-guarded, per-field\n `validating` state), **dirty tracking + `reset()`**, and **submit states**\n (`isSubmitting`, an async `onSubmit`, and `setErrors()` for server-side field\n errors). New demos: dynamic form, wizard, and field array.\n- **Public headless cores for the menu / select family** (`createMenu`,\n `createPopoverSelect`, shared `list-nav`), so the popup pickers can be driven\n headlessly and composed into custom UI.\n- **`color` on `ListOption`** - render a small color swatch before the label in\n `SvListBox` and `SvDropDownList`.\n- **`block` on `SvDateTimePicker`** - stretch the field to fill its container\n (100% width), so it fills a grid cell when used as an editor.\n- **`onClosed` on `SvDrawer`** - fires after the exit animation ends and the\n drawer leaves the DOM.\n- **`loading` on `SvField`**, and **`locked`** on `SvDockLayout` /\n `SvDockManager`.\n- **`summary` on `<SvGrid>`** - shortcut alias for `enableRowSummaries`,\n which turns on the footer row that aggregates every filtered row. It wins\n when both are set, the same precedence `selectable` has over\n `enableCellSelection`.\n- **`summary` on a column** - choose that column's footer aggregate\n (`'sum'`, `'avg'`, `'min'`, `'max'`, `'count'`, `'countDistinct'`,\n `'extent'`, `'first'`, or a custom function), or `false` to leave the cell\n blank. Without it a column keeps the old default: sum a numeric column,\n `Count: N` otherwise.\n- **Development-time configuration checks.** The grid used to fail silently on\n the most common mistakes - a misspelled `field` rendered a column of blank\n cells and printed nothing. It now warns once per problem, in dev builds only:\n\n - a column `field`, `groupBy` entry, `treeData.parentField` / `idField` or\n `treeData.column` that does not exist (with a \"did you mean\" for near misses),\n - two columns resolving to the same id,\n - `pageSize` set when pagination was never turned on,\n - a column marked `sortable` while sorting is not enabled,\n - `initialColumnPinning` while column virtualization is on, which silently\n prevents the columns from sticking,\n - `externalPagination` without `rowCount`, `externalSort` without\n `onSortingChange`, and `externalFilter` without `onFiltersChange`.\n\n The checks live in a lazy chunk behind a dev-only branch, so a production\n build never loads them and the base bundle is unchanged.\n\n#### Changed\n\n- **BREAKING: column resizing is now off by default.** Every column used to have\n a drag handle unconditionally - there was no prop, no per-column option and no\n way to turn it off, so a `width` you set was only ever a starting value a user\n could drag away. Set `columnResize` to get the handles back; the 241 demos in\n this repo that want them now say so. Sorting and filtering have always been\n opt-in behind `sortable` / `filterable`, and resizing was the odd one out.\n- **BREAKING: the footer summary row is now off by default.**\n `enableRowSummaries` used to default to `true`, so a plain\n `<SvGrid {data} {columns} />` grew an aggregate footer nobody asked for and\n every caller that did not want one had to opt out - 375 call sites in this\n repo passed `enableRowSummaries={false}` against 6 that opted in, and the\n API reference already documented the default as `false`. If you were\n relying on the old behaviour, add `summary` (or `enableRowSummaries`).\n- **Ember is now the default theme preset** (`defaultThemePreset` in\n `@svgrid/grid/themes`). It is what the demo gallery and svgrid.com open on, so\n a scaffolded or Studio-generated app now looks like the demos unless you pick\n a preset. Previously the default was Tailwind.\n- **Popup editors keep themselves on screen.** `SvAutoComplete`, `SvComboBox`,\n `SvDropDownList` and the date pickers now measure the space to the viewport\n edge: the panel flips up when there is not enough room below and clamps its\n `max-height` to the available height, so a picker opened near the bottom of the\n window no longer spills off screen.\n- **Dock manager pop-out to a new window is now off by default**\n (`allowPopout={false}`); opt in explicitly. Added a dedicated pop-out demo.\n\n#### Fixed\n\n- **Arrow keys lagged whenever the active cell had to scroll.** On the\n 10,000 x 53 large-dataset demo one ArrowDown at the bottom of the viewport\n cost about 37 ms of main-thread work and painted over two frames; it is now\n about 8 ms and paints once. Five things added up. Every rendered row was\n measured with `getBoundingClientRect` on each scroll tick, on a grid that\n had no `autoRowHeight` to use the number for, which forced a table layout\n per row (about 30 per key press). The scroll geometry the custom scrollbar\n reads was pulled inside a derived at the start of the flush, forcing a\n second full table layout that the row writes then invalidated. The\n virtualizer keyed rows by their position in the window, so a one-row\n scroll rewrote all ~30 rows x every rendered column; rows are now keyed\n `index mod windowLength`, so the rows that stay keep their `<tr>` untouched\n and the one that entered is moved with a single `insertBefore`. The row\n window only updated after the browser's `scroll` event and a\n `requestAnimationFrame`, a frame after the key press; keyboard navigation\n now syncs the virtualizer inline, since it knows where it scrolled. And\n each cell carried three selection-dependent deriveds plus the fill handle's\n `{#if}`, re-marked on every move; they are one `{@const}` now, `null` for\n a plain cell. Also closed on the way: `key in editedCellValues` on a deep\n `$state` proxy created a signal per rendered cell that never went away, and\n the header checkbox's tri-state walked every row on each arrow key.\n\n- **A heat map drew a series legend in colours its cells never use.** The\n ramp on the right is its key; the row of palette chips under it (and a\n calendar's) is gone.\n\n- **A time axis put its ticks on nothing in particular.** `xType: 'time'`\n stepped a fixed 30 or 365 days from the Unix epoch, so a tick labelled\n \"2025\" stood weeks from New Year, a \"Jun 25\" tick sat mid-June, and a\n thirty-month axis carried two labels on a plot with room for eight. Ticks\n now land on calendar boundaries in UTC (days, Mondays, the first of a\n month, quarter or year, or every few years) at about one label per 90px,\n and each label is sized to the gap between ticks rather than the axis span,\n so a quarterly axis no longer reads \"2024, 2024, 2024, 2025\". The labels\n are read in UTC too: a local-time read of a 'YYYY-MM-DD' category in the\n Americas labelled every tick with the day before.\n- **The tooltip echoed the ISO date.** On a time or ordinal-time axis the\n tooltip title, the crosshair pill and the live region wrote \"2025-06-01\";\n they write \"Jun 2025\" when every category is the first of a month, \"2025\"\n when every one is New Year, and \"Jun 1, 2025\" otherwise, through\n `xAxis.formatter` when one is set. A calendar cell names its day the same\n way. The category in `onHover`, `onSelect` and `selected` is unchanged.\n- **The screen-reader table and the CSV read \"NaN\".** A NaN gap (the way a\n forecast series marks the months before it starts) wrote the word \"NaN\"\n into the hidden data table and the CSV export, and a `null` fell back to\n 0, which told a screen reader the outage month had no sign-ups. Both are\n empty cells now.\n- **\"Double-click again to clear\" left a legend chip isolated and hidden.**\n A double-click arrives as click, click, dblclick: with a chip isolated the\n first click cleared the isolation, the second hid the chip and the dblclick\n isolated it again. A click that clears an isolation is remembered for a\n moment, and the double-click that follows it on the same chip clears; on\n another chip it moves the isolation there.\n- **A radar ignored `yAxis.min` / `max`.** The rim was always the data\n maximum, so scores out of 100 filled the dial to whatever the best score\n was and two radars could not be compared. The rim honours a pinned axis,\n a value past it sits on it, and a pinned minimum is the centre.\n- **A pie sized its gutters by the widest label on either side.** Small\n slices with long names on the left kept the same room on the right for a\n \"Chrome 62%\", and the pie drew at half the radius the pane had. The\n gutters are per side, the pie sits centred in what they leave, the floor\n radius is a quarter of the short side, and each side truncates to its own\n room.\n- **A waterfall tooltip read \"$0\" on a total.** A total bar holds 0 in the\n data and its running sum in the geometry; the tooltip and the\n screen-reader table now read the drawn value. Its x labels also tilt by\n the same fit rule as a bar chart's, with the angle the renderer needs:\n they were flagged as rotated with no angle and drew truncated instead.\n- **Histogram edges read \"1.3k, 1.3k\".** Bin edges are written at the\n precision their width needs (whole numbers with separators for a 44ms\n bin, two decimals for a 0.2 bin) rather than in the compact tick form that\n gave two neighbouring edges one label.\n- **A heat map ignored `dataLabels` in the spec.** The cell label read the\n component prop alone, so `dataLabels: { show: true }` in the spec drew\n nothing. Colour legends on heat maps and calendars also round their steps\n to the precision the range earns (\"20, 94, 167\", not \"20, 93.5, 167\").\n- **The range area read as three lines.** Its band filled at the wash an\n area under a line gets, with both edges at full stroke. The band is the\n mark: it fills at 0.35 and its edges are thin.\n- **Annotate mode pinned a tooltip instead of a note** when `tooltipSticky`\n was on too; the annotate click now owns the click.\n- **Drawings on a time axis warned on every point.** The drawing tools write\n a timestamp for every pointer position, and the spec validator matched\n those against the category list. It skips the check on a time or number\n axis, as it already did for reference lines and annotations.\n- **The panel's export menu and saved-charts dialog ignored Escape.** Both\n close on Escape and hand focus back to the button that opened them.\n- **A gauge wrote \"99.2 %\".** A symbol unit (%, degrees) hugs the number; a\n word unit (\"ms\") keeps its space.\n- **The right axis title was clipped.** Its glyphs point outward under the\n rotation and ran past the edge of the SVG.\n- **Pie callout labels ran off the chart in a narrow pane.** The pie kept a\n fixed 34px margin for its outside labels whatever their length, so a\n \"Samsung Internet 3%\" in a 380px pane was clipped to \"%\" and \"Cl\". The\n radius now makes room for the widest label on each side, keeps at least a\n fifth of the short side, and hands the renderer a per-side character\n budget to truncate to when even that is not enough.\n- **The brush strip inherited the chart's titles, axis labels and marks.**\n A title and subtitle took 45 of the strip's 88 pixels and the x labels\n another 30, leaving the mini-map a five-pixel smear under an empty band.\n The brush spec now mutes titles, axis titles and labels, reference lines\n and bands, annotations, drawings, series labels and data labels.\n- **A category chart tilted its x labels by count, not by fit.** More than\n eight categories, or any label over nine characters, tilted every label\n to -40 degrees even on a thousand-pixel chart with room to spare. `auto`\n now tilts only when the widest label does not fit its slot.\n- **A heat map wrote every column label whatever the cell width**, so\n twenty-four hours at 33px a cell read \"00:0001:0002:00\". The column\n labels thin out the way a bar chart's do.\n- **A calendar labelled the padding days of the next year.** The grid pads\n the range to a full week, and a December ending on a Thursday picked up a\n \"Jan\" tick for the two padding days. Month labels stay inside the range.\n- **A waterfall could not open on a value.** A total bar always read the\n running sum, so \"Revenue 4300\" marked as a total drew as zero and every\n bar after it hung below the axis. A total with a value now sets the sum;\n a total with 0 still reads it.\n- **`rowsToChartSpec` with `topN` duplicated a category called \"Other\".**\n A real \"Other\" in the data came out beside the folded one, two categories\n with one name, which the renderer threw on as a duplicate key. The tail\n now folds into that category.\n- **A pin annotation showed \"O…\" and nothing else.** The head held\n `truncate(label, 2)`, an initial plus an ellipsis, and no label was written\n beside it. The head carries the initial and the label sits beside the pin\n like a dot's does.\n- **A chart's hidden data table took up to 17,000px of scrollable space.**\n The screen-reader table (one row per category, capped at 1,000) carried the\n visually-hidden recipe itself, but on a `<table>` `height: 1px` and\n `width: 1px` are minimums and `overflow: hidden` does not clip, so the\n table was invisible and as tall as its rows, and every scroll container\n around a chart (the demo pages first of all) scrolled on through that much\n empty space. The clip now sits on a wrapping div; the table keeps its id,\n which the svg still points at.\n- **Two ARIA faults the axe audit found.** The chart's SVG was\n `role=\"img\"`, whose children are presentational to assistive technology,\n so the focusable marks inside it (category zones, slices, a drawing) were\n a nested-interactive violation and could be skipped by a screen reader; an\n interactive chart is a labelled `group` now (a thumbnail with\n `interactive={false}` stays an image). Sankey links carried an\n `aria-label` with no role, which ARIA prohibits; they are named images in\n the focus order.\n- **A tree map ignored `spec.tree`.** The field is documented as an alias of\n `treemap` and the sunburst honoured it; the tree map read only `treemap`.\n- **An autosized chart with a side legend grew without end in a plain block.**\n `legend=\"left\"` / `\"right\"` lays the chart out as a three-row grid, and a\n grid puts a gap between every track whether or not the toolbar and brush\n rows have anything in them. The autosize maths counted a gap only for the\n chrome that existed, so in a parent that does not pin the height, the host\n measured 8 or 16px taller than the plot it was told to fit, the plot grew\n into it, and the next measurement grew again - a few hundred pixels a\n second until the page ran out. Hiding the legend at runtime had the\n opposite fault: a dimension binding keeps its last value once its element\n is gone, so the vanished legend went on being subtracted and the plot\n ratcheted down to its 120px floor. Both fixed; a fixed-height parent hid\n them, which is why the docs' sizing example never showed either.\n- **`block` did nothing on eight editors.** The prop is declared once in\n `SvEditorProps`, and its own doc comment describes the symptom: \"in a form\n grid a row of inputs each stopping at a different width reads as broken\".\n `SvDropDownList`, `SvComboBox`, `SvMultiSelect`, `SvTreeSelect`,\n `SvGridSelect`, `SvAutoComplete`, `SvTextArea` and `SvDateRangeInput`\n accepted it by type and ignored it, so they stopped at their own 200-280px\n default while the text inputs beside them filled the row. `<SvForm>` was\n also not passing it to seven of the controls it mounts - both halves had to be\n fixed for a form row to line up.\n- **`cellDataType: 'dateString'` stored a timestamp after an edit.**\n Committing ran through the shared date coercion (`new Date(v).toISOString()`),\n so picking Christmas stored `2026-12-25T01:00:00.000Z` and the cell showed a\n timestamp beside neighbours showing plain dates - on a calendar day that\n depended on the user's timezone, since the conversion went through UTC. The\n picked date is now kept as the picked date.\n- **The filter row mounted a native date input** while the cell editor mounted\n the grid's own picker, so one column looked like two different products\n depending on where you touched it. Both use the grid's picker now.\n- **`editorType: 'number'` dropped the character you were typing.** The\n editor mounted `<input type=\"number\">`, whose value sanitization reports\n `\"\"` for anything not already a valid float - so `12.` read as empty, and\n typing `12.5` produced `125`. Same for a lone `-` and `1e`. It is a\n text input with `inputmode=\"decimal\"` and a digit filter now; the trade is\n the native spinner.\n- **Cell context menus and the comment editor floated at stale coordinates\n after a scroll.** Both are positioned at raw cursor coordinates and rendered\n `position: fixed`, but neither was in the scroll effect's gate, so they hung\n over unrelated cells. The comment editor SAVES on scroll rather than\n discarding - backdrop-click and Escape are the gestures that mean \"throw this\n away\"; a scroll is not, and must not destroy typed text.\n- **The footer summary row server-rendered as empty cells.** The totals were\n assigned from an `$effect`, and effects never run during SSR - so the server\n emitted a summary row that took up space and drew its border but held no\n numbers. They appeared only after hydration (a visible pop-in), and never at\n all for a reader with JavaScript off. A grid under the aggregation cell\n limit now derives its totals synchronously, so they ship with the HTML; a\n very large grid keeps the rAF-deferred effect so it still paints before it\n totals. `pnpm ssr:check` asserts the real aggregate now.\n- **The grid painted one unmeasured frame on every mount.** `hasMeasured`\n gates the custom scrollbars, the 16px scrollbar gutter on a trailing\n right-aligned column and the top pager (which carries a `border-top`), but\n it only flipped inside the `ResizeObserver` callback - and that callback is\n deliberately deferred by one `requestAnimationFrame`, so the browser was\n guaranteed to paint a frame with those missing and correct it on the next.\n On a first load that was the \"flashing scrollbar\"; in an app that recreates\n the grid per navigation (a `{#key}` around it, or a route that remounts) it\n showed up as the grid flashing on every sort / filter / page change, with a\n stray border line. The container is now measured synchronously in the mount\n effect - before the first paint - and the observer still handles later\n resizes. Covered by an e2e regression test, since jsdom has no layout to\n miss a paint with.\n- **Pager page-size trigger rendered as a stock button until first click.** The\n closed trigger is a placeholder until the lazy dropdown chunk loads, but its\n box styling only existed in that chunk's scoped CSS, so server-rendered and\n freshly-mounted pagers showed a UA-bordered, left-hugging `<button>` inside the\n bordered box. The placeholder now gets the same rules from `SvGrid.css`.\n- **Virtualized lists no longer flash blank on a fast scrollbar-thumb drag.**\n A fast drag can move the viewport into the windowed list's off-screen padding\n faster than JS can re-render the rows there; the padding now paints faint row\n skeletons, so `SvListBox` / `SvDropDownList` stay visually filled at any scroll\n speed. Also removed an app-wide `flushSync` from the scroll handler that could\n stall the very first scroll.\n- **Dock manager auto-hide now shows every tab of a multi-tab leaf.** Sending a\n leaf with two or more tabs to auto-hide created a single edge tab; it now\n creates one edge tab per pane.\n- **Ticking one row in a large grid took over a second.** Once any row was\n selected, every change walked all rows through the lazy row list to work out\n the header checkbox. At 1,000,000 rows (jsdom) one tick went from 1.3-1.8 s\n to 4-36 ms, and select-all from 4.2 s to 0.4 s.\n- **Tab never left the grid.** Every Tab was consumed and the cursor clamped\n at the last cell, so no key moved focus out (WCAG 2.1.2). Tab on the last\n cell and Shift+Tab on the first now leave the grid.\n- **No focus indicator when the grid is reached by Tab, or under forced\n colors.** The active-cell ring stayed hidden until a click, and Windows High\n Contrast removed it (it is a box-shadow). It now shows on keyboard focus, and\n forced colors get a `Highlight` outline.\n- **The cell editor had no accessible name.** The text, number and multi-line\n editors are now labelled with their column's header.\n\n#### Security\n\n- **CSV / formula injection in exports.** `exportCsv`, `exportTsv` and the\n chart's CSV download wrote text such as `=HYPERLINK(...)` as is, which a\n spreadsheet runs as a formula. Text starting with `=`, `+`, `-`, `@`, a tab\n or a carriage return is now written with a leading `'`; numbers and signed\n numbers in text form (`-12.50`) are unchanged. `escapeFormulas: false` turns\n it off; `copyToClipboard` takes `escapeFormulas: true` to turn it on.\n\n### @svgrid/enterprise\n\n#### Added\n\n- **The pivot designer's Chart view grew up.** It offers every shape a pivot\n can take (bar, line, area, lollipop, pareto, the three radial forms, pie,\n funnel, waterfall, radar, heat map, stream) in the panel's groups, with\n Stacked, 100% and Horizontal where the type uses them, the chart's own\n toolbar (PNG, SVG, PDF, print, copy), its spoken summary and a legend\n under the plot. It had six types and a Stacked box.\n\n- **`pivotToChartSpec` carries the measure's format and name.** Pass the\n value chip's `format` and the chart reads \"$470k\" on the axis and\n \"$469,662\" in the tooltip, in the measure's currency and locale; percentage\n points get a formatter that appends the sign. With one measure the value\n axis is named after it (`yAxisTitle` overrides, `null` for none). The\n designer's Chart view passes the format when its measures agree, and\n formats plainly when a layout mixes a currency and a count.\n\n- **PDF export with charts and a KPI strip.** `pdf.charts` prints charts with\n the table: a rendered chart's element is rasterised on export through the\n grid chart's PNG path, or pass an image data URL; each takes a title, a\n caption and a width, and goes above the table or below it\n (`chartsPosition`). `pdf.kpis` prints a strip of headline numbers, each a\n label over a big value with an optional coloured delta line. Roadmap\n discussion 36.\n- **The selection bar renderer, plus bulk edit.** `enableSelectionBar()`\n (or `installEnterprise`) registers the renderer behind the free\n `selectionBar` prop. The bar carries a count chip, your actions, an overflow\n menu past `maxVisible`, and Clear; at phone width it collapses to icons and\n keeps an accessible name on each. **Edit fields** opens a drawer that edits\n one or many rows at once: a field the selection disagrees on opens blank and\n stays per-row unless you touch it, so applying to 40 rows does not flatten the\n values you did not mean to change.\n- **Scheduler booking rules and conflict detection.** New model helpers\n (`overlapCount` for per-resource overlaps, `overlapsBands` for working-hours\n bands) back resource double-booking checks and business-hours enforcement.\n New demos: booking rules, financial trading hours, and HR shift coverage.\n\n#### Fixed\n\n- **A pivot chart drew an empty cell as a zero bar.** An average over no rows\n is `null` in the pivot and the bridge read it as 0; it is a gap on the\n chart now. A sum over no rows stays the 0 the engine wrote.\n\n- **PDF export depended on pdfmake's fonts registering themselves.**\n `pdfmake/build/vfs_fonts` registers its font map only as a side effect of\n being imported while a global `pdfMake` already exists, and the export's\n own lookup for the map never matched the shape the module has shipped since\n pdfmake 0.2.8 (the module is the map), so it registered nothing and relied\n on that side effect. Under a bundler the global can be a stale instance (a\n dev server re-optimising its dependencies mid-session is enough), and the\n export then failed with \"File 'Roboto-Medium.ttf' not found in virtual file\n system\" while its promise never settled. The map is now found in every\n shape the module has had (`resolvePdfVfs`) and handed to the instance that\n creates the document (`registerPdfFonts`, through `addVirtualFileSystem`\n and the `vfs` property), and an installed pdfmake whose fonts module has\n no map is reported instead of failing later.\n- **Studio emitted no theme for the fragment export and the CLI `add`\n scaffolds.** Only the full app's `+layout.svelte` carried the `--sg-*` tokens;\n `eject --fragment` (which drops that file) shipped an `app.css` with one\n hard-coded accent, and `svgrid-studio add` / `add --all` wrote none at all. The\n tokens now come from one helper (`themeTokenCss`): `src/app.css` carries them\n for the full app and the fragment, and the `add` scaffolds emit them in\n `<svelte:head>`. Drop-in outputs wrap them in `@layer svgrid-studio`, so a host\n app that already defines its own tokens keeps its look. `add` also honours\n `--theme` / `--dark`, and a project with no theme picked gets Ember (the demo\n theme) instead of Tailwind.\n- **Scheduler column alignment.** The all-day lane, day/time-grid header, and\n body columns now reserve the scrollbar width consistently, so the columns line\n up instead of drifting by the scrollbar's width.\n- **Excel export color-scale conditional formatting.** A color scale's `min` /\n `mid` / `max` are optional, so the export could build an `(string | undefined)[]`\n where a `string[]` was expected; it now falls back to the same `#ffffff` /\n `#000000` defaults the grid renders with. Because `@svgrid/enterprise` ships its\n `src`, this had surfaced as a stray `svelte-check` error in consuming apps - a\n clean app now type-checks with zero errors.\n\n### @svgrid/grid-wc\n\n#### Added\n\n- **`<sv-chart>`**, the standalone chart as a custom element, at\n `@svgrid/grid-wc/chart` with React (`/react/chart`), Vue (`/vue/chart`)\n and Angular (`SvChartComponent`) wrappers. Its surface is generated from\n `SvChart`'s own props type the way `<sv-grid>`'s is from the grid's, so the\n 26 props and 7 events stay in step; `spec` is a property, the primitives\n are attributes, and a prop that takes a boolean or a string (`legend`) keeps\n a string attribute where a bare attribute means true. Its own build in\n `dist/chart` carries none of the grid.\n- **Typed event handlers.** Each wrapper's `on<Event>` prop used to be\n `(detail: unknown) => void`, so reading `newValue` meant casting first -\n a poor advertisement for a typed wrapper. The detail type is now lifted from\n the grid's own callback signature, so 16 of the 19 events arrive fully typed\n (`TData` degrades to `Record<string, unknown>`; anything referring to a\n type that only exists inside `@svgrid/grid` stays `unknown` rather than\n naming something a consumer cannot resolve).\n\n- **React, Vue and Angular components**, as subpath imports:\n `@svgrid/grid-wc/react`, `/vue` and `/angular`. Each is generated from the\n same surface as the elements, so all 98 properties and 20 events are typed\n props on every one of them and none can drift from the grid. Each framework is\n an OPTIONAL peer dependency, so a plain-HTML consumer installs none of them,\n and the wrappers are 1.3-3.7 KB gzip because they reuse the one element bundle\n rather than shipping a second copy of the grid.\n\n They exist because a raw custom element is genuinely awkward in each:\n **React 18 and earlier stringify object props onto attributes**, so\n `columns={cols}` silently becomes `\"[object Object]\"` and the grid renders\n empty; **Vue** needs `isCustomElement` build config and a `.prop` modifier\n on every object binding; **Angular** needs `CUSTOM_ELEMENTS_SCHEMA` in every\n component that shows a grid, and gets no typed inputs. The Angular wrapper is\n compiled with ng-packagr in partial-Ivy mode, so it is consumable by a normal\n Angular build, and its selector is the element's own tag - `<sv-grid>` and\n `<sv-grid-shadow>` - with no template of its own, so there is no extra wrapper\n element in the DOM and the tag is the same one you write in plain HTML.\n\n All three also handle two ordering problems a hand-written wrapper meets:\n the element renders BEFORE a framework assigns properties in an effect, and\n `apiready` fires once during that first mount - before React can bind a\n listener at all. The handle is parked on the element and each wrapper replays\n it.\n- **The package ships TypeScript declarations.** It previously had none, so\n `import '@svgrid/grid-wc'` was an error under `moduleResolution: bundler`\n and `document.querySelector('sv-grid')` came back as a bare `Element`. The\n generated `.d.ts` augments `HTMLElementTagNameMap` and\n `HTMLElementEventMap`, so the element and its events are typed without\n hand-written declarations.\n#### Security\n\n- **A crafted .xlsx could crash the tab.** `importData` and the spreadsheet's\n File > Open filled every gap before a cell with blanks, sized by the cell\n reference in the file: `<c r=\"ZZZZZZZ1\">` asked for about eight billion.\n `importData` now rejects a cell past column XFD; the spreadsheet skips a cell\n outside the sheet, as it does other malformed parts. Both refuse a sheet that\n would need more than ten million blank cells to lay out.\n- **CSV and TSV from `exportData` neutralise formula-like text**, through the\n same `@svgrid/grid` serializer (see the grid's Security entry).\n\n- **`<sv-grid-shadow>` - the grid in an open shadow root**, so a host page's\n CSS cannot reach it. Same properties, attributes and events as `<sv-grid>`;\n a separate element rather than an attribute because Svelte resolves\n `customElement.shadow` at compile time, so no runtime flag can switch it.\n Isolation is one-directional and the docs say so: page CSS stops at the\n boundary, but the grid's own stylesheet is still injected into the document,\n because about twenty overlay surfaces portal to `document.body` on purpose\n to escape ancestor clipping. `--sg-*` theme tokens reach in unchanged,\n including a theme file's dark variant - custom properties are inherited, and\n inheritance crosses a shadow boundary.\n- **The elements now expose the whole grid.** `<sv-grid>` declared **7 props\n and 2 events** by hand against a `Props` type with 100 props and 19\n callbacks, so grouping, pagination, pinning, tree data, master/detail, board,\n scheduler and every Enterprise feature were unreachable from a non-Svelte\n host - while the docs said they \"all come along\". The surface is now\n **generated** from `<SvGrid>`'s own types: **98 properties** (72 with\n kebab-case attributes, 26 property-only) and **20 events**, with CI failing if\n the two drift. Costs 1.6 KiB gzip.\n- **Every grid callback is a DOM `CustomEvent`**, `detail` being the\n callback's argument - or, for the one callback taking two, an object keyed by\n its parameter names. `onApiReady` also parks the imperative handle on the\n element as `el.api`, because an event fires once and a host binding a\n listener later would otherwise never reach it.\n\n#### Fixed\n\n- **The React wrapper re-did all its work on every parent render.** Both of its\n effects had no dependency array, so any state change anywhere in the parent\n reassigned all 98 properties and rebound all 20 event listeners - 40 listener\n mutations per keystroke. It now writes only values that actually changed and\n binds listeners once through a handler ref. Measured: 20 no-op re-renders\n produce 0 listener adds, 0 removes and 0 property writes.\n\n- **The element threw when it rendered before its props were assigned.**\n Generating the prop list replaced the elements' own `data = []` /\n `columns = []` defaults with a bare `$props()`, so a consumer that assigns\n properties AFTER the element upgrades - which is what React and Angular both\n do, in an effect - got\n `TypeError: Cannot read properties of undefined (reading 'map')` and a grid\n that never rendered. Only a real framework app was late enough to reproduce\n it; an HTML fixture sets the properties in the same tick and never sees it.\n\n#### Changed\n\n- **Only arrays, objects and functions changed shape: they are property-only.**\n An HTML attribute is a string, so `columns='[object Object]'` cannot work\n and no attribute is offered for the 26 props that are not primitives. The\n published `rowclick` and `selectionchange` events keep the exact\n `detail` they shipped with, and `selectable` keeps meaning row-selection\n checkboxes - `<SvGrid>`'s prop of that name is an alias of\n `enableCellSelection`, and forwarding it would have silently repointed a\n published attribute at a different feature.\n- **Styles arrive with the code that needs them.** The build used to put every\n stylesheet in the bundle, lazy chunks included, into the entry, so a page\n that never opened the chart, a date picker or a menu still downloaded their\n CSS. Each chunk now carries its own styles and adds them to the document\n and to every open shadow root when it loads. `<sv-grid>`'s entry went from\n 107 KiB to 98.5 KiB gzip while the chart grew.\n\n### Tooling & docs\n\n#### Added\n\n- **Every chart gallery demo switches between Chart and Grid.** A segmented\n control first in each demo's toolbar flips every pane to a sortable grid\n of the rows the chart was drawn from, and back, the way the board demos\n switch Board and Table. The from-the-grid page shows the pattern in a\n runnable.\n\n- **Charting a pivot is documented.** The pivot page has a section on\n `pivotToChartSpec` (the mapping, every option, a runnable that pivots\n orders and charts them by quarter) and on the designer's Chart view\n (`chartable`, `defaultView`); the charts hub and the from-the-grid page\n link to it, the /api pivot section lists the function, and the generated\n reference covers `pivot-chart.ts`. Demo 359's data now puts every\n country in every quarter and category, so its groups are four bars, not\n one.\n\n- **27 runnable framework examples**, nine each for React, Vue and Angular:\n a first grid, sorting and filtering, editing and saving, row selection,\n grouping and totals, pagination, server-side data, theming, and Excel export\n from the Enterprise pack. Every one has\n an **Open in StackBlitz** button that boots a full editable project - no local\n install - and a new\n [React, Vue or Angular](/docs/help/web-components/frameworks) landing page\n puts the thirty-second path first.\n\n They are real apps in the repository (`packages/grid-wc/examples/`), not\n snippets, and CI compiles all of them with each framework's own compiler -\n including `ngc --strictTemplates`, so a wrong Angular binding fails the\n build. The doc listings are generated from those files, so a page cannot\n describe a version of an example that no longer exists.\n\n The Vue templates get an extra check of their own: Vue treats an unknown\n attribute as a legal fallthrough, so `<SvGrid sortabel />` type-checks\n cleanly and silently does nothing. Verified - the same typo fails the React\n and Angular compilers and passes `vue-tsc` - so the Vue examples are also\n checked against the generated surface.\n\n- **A Web Components docs category.** Eight pages under\n `help/web-components/` - quick start, a generated `<sv-grid>` reference,\n shadow DOM, React, Vue, Angular, TypeScript and limitations - replacing a\n single page that was filed under \"Layout & Styling\". The reference tables are\n generated from the grid's types, and a guard checks that the counts quoted in\n prose still match the surface.\n- **The docs run.** A `svelte` code fence tagged `{runnable}` is extracted at build time\n into a real component, so a doc page shows the source and the working result\n together rather than highlighted text. 504 examples across the corpus, taking\n the median doc page from 1 example to 3; each one is compiled by `svelte-check`\n in CI, so an example that stops working fails the build instead of rotting in\n place.\n- **`@svgrid/ui` recipe scaffolder** - `npx @svgrid/ui add <component>` drops a\n ready-to-edit starter (e.g. `add calendar`) into your app, complementing the\n shadcn-style component pages (Preview / Code, install tabs) across the UI kit.\n- **See a component before you wire it in** (`@svgrid/ui` 0.3.x).\n `npx @svgrid/ui try <component>` spins up a zero-setup Vite + Svelte sandbox and\n opens the component in your browser; `add --preview` writes a\n `src/routes/preview/<id>` route (plus a `/preview` index) in a SvelteKit app.\n `add` now installs `@svgrid/grid` by default (`--no-install` to opt out) and\n prints the exact `try` command for whatever you just added, so the \"see it\"\n step is never a dead end.\n- **AI coding Skill** (`skills/svgrid`, installable with\n `npx skills add sv-grid/sv-grid`) - an always-on house-style guidance layer\n that complements `@svgrid/mcp`.\n- **The rest of the toolkit is findable.** `packages/grid/README.md` gained an\n \"Also in the box\" section, and the site footer gained a **Toolkit** column\n (SvGrid UI, Kanban board, Scheduler, Dock layout, Studio, Web components).\n The 84 SvGrid UI components have always been exported from `@svgrid/grid`\n itself - `SvButton`, `SvCalendar`, `SvDateTimePicker`, `SvDockLayout`,\n `SvToaster` and the rest are already installed for every grid user - but\n nothing on the highest-traffic surfaces said so.\n\n#### Changed\n\n- **Doc examples show code and result at once.** The runnable card used to be a\n Preview / Code toggle with an in-page editor; it is now the source above the\n live example, both visible, with Copy. A tab hides half of a teaching example\n and makes comparing the two a click, and dropping the editor took the\n on-demand TypeScript compiler chunk off every docs page with it.\n- **`npm create @svgrid` starts on Ember** (the demo theme) instead of Tailwind,\n for every template; `--theme <id>` still picks any preset. The `sveltekit`\n template is now listed on the starters page, and the `sv add @svgrid` demo route\n imports the Ember stylesheet so it no longer renders unthemed.\n\n#### Fixed\n\n- **`build:lib` in the enterprise package deleted the node bundle.**\n `svelte-package` wipes `dist/`, so a library build alone removed\n `dist/node/studio.js` and the MCP server failed to start until\n `build:node` was run by hand. The library build rebuilds the bundle it\n removed.\n\n- **Docs images and tutorial media 404'd under a site base.** The markdown\n writes them root-absolute (`/docs-media/...`, `/tutorials/...`), which is\n right at svgrid.com and wrong under the `/sv-grid/` base the e2e server\n uses: every docs image and tutorial poster was missing there. The page\n prefixes the base in the HTML before it paints, and an e2e spec loads a\n page with both and checks nothing under those roots 404s.\n\n- **Twenty-one links on the chart pages went to GitHub 404s.** The split\n wrote every cross-link with one `../` too many, and the site's link\n resolver falls back to a GitHub URL for a page it does not know. Fixed on\n the pages, and every relative link under docs/ is now a test\n (`tools/docs-relative-links.test.ts`); the link checker existed but only\n ran by hand before a release.\n- **Links into the generated reference tree went to GitHub too.** The tree\n is hidden from the docs routes; a link to it lands on the /api page, on the\n module's section where it has one.\n- **The chart gallery said \"the source is under each example\" and it was\n not.** Each gallery card now carries the demo's own script and markup on a\n Code tab, written by `tools/gallery-doc-code.mjs` from the demo file and\n guarded by a drift test, so the code beside a preview is the code that\n renders it.\n- **A demo page flattened a bulleted banner into one paragraph**, dashes and\n backticks included. The page reads the pitch as blocks: a list where the\n banner wrote one, `<code>` where it wrote backticks, on the prerendered\n and the hydrated page alike.\n- **`demo-doc-embed` skipped a demo the page only linked to**, so a\n placement for it never landed, and it opened a new \"More examples\" section\n below \"See also\", which the coverage test requires to be last. Present\n means embedded, and the section opens above \"See also\".\n- **Regenerating the doc snippets took the dev server's file watcher with\n it.** The extractor removed and recreated its output directory, and on\n Windows the watch did not re-attach, so an edited runnable kept serving\n its old chunk while the source beside it showed the new code. It writes in\n place and removes only what no longer belongs.\n- **The Getting started chart page had no live example.** Its code blocks\n were `ts` and a Svelte block referencing rows it never declared; four of\n them run now, and the hub's first example runs with its own rows and a\n filter row, so the chart is seen following the grid.\n\n- **The e2e suite adopted any server on :5180.** Playwright reuses whatever\n answers on the port, and a Vite dev server returns the app shell for any\n path, so a website dev server started by hand (base `/`) passed the\n readiness check and the fourteen path-routed and module-importing specs\n failed with nothing pointing at the server. The config now probes the port\n first (`tests/e2e/lib/site-server-probe.mjs` reads the base off Vite's\n client script tag), reuses a server that serves the site under `/sv-grid/`,\n skips one that serves anything else with a line saying so, and starts its\n own on the next free port; `SVGRID_E2E_PORT` pins one.\n- **The website dev server re-optimised dependencies mid-session.** The\n search index, the docs renderer, the /api runner's compilers, the PDF\n exporter and the grid's `esm-env` sit behind dynamic imports the start-up\n scan does not reach, so the first page to touch each one triggered\n \"optimized dependencies changed. reloading\" on every open page. In the e2e\n suite that reload landed mid-test on a cold cache and failed whichever spec\n was on a page at the time. They are pre-bundled at start-up now\n (`optimizeDeps.include`), and `esm-env` is a declared devDependency of the\n website so it resolves from there.\n- **The /api runner check sampled an example's outcome two frames after\n Run.** An example awaiting an export or a fetch was still running, so a\n failure that arrived later, or one thrown inside a library callback the\n runner's try/catch cannot see, passed. The check now waits for the runner\n to report an outcome and counts an uncaught error or rejection during the\n run as a failure of that example.\n- **181 doc pages had content stranded below \"See also\".** Authoring passes\n appended new sections to the end of the file, which buried them under what\n reads as the page footer: on `help/filtering/number-filter`, for instance, the\n `between` example sat below the link list and a reader would never reach it.\n The footer is back at the bottom on every page, and a test now fails if a\n section lands under it.\n- **The documented way to lock one column's width never worked.**\n `docs/help/columns/column-sizing.md` matched headers on `data-col-id`, which is\n the attribute on *body* cells - the selector matched nothing. Header cells\n carry `data-svgrid-header-col`. (`ColumnDef.resizable` is now the real answer.)\n- **`blockKey` was missing from `tools/lib/md-snippets.d.mts`.** The function was\n exported from the `.mjs` and worked at runtime, so nothing caught it until the\n website was type-checked.\n- **`@svgrid/mcp` reports its real version.** The MCP server's\n `serverInfo.version` was hardcoded to `0.1.0`; it now reads the package version.\n- **`@svgrid/create-studio` scaffold builds out of the box.** The generated app\n shipped an orphaned `/products` route referencing an entity that was never\n defined; the `Product` schema, seed, data source, nav, and home card are now\n complete, so `npm run build` succeeds on a fresh scaffold.\n- **API-docs accuracy pass across all 74 UI-component pages.** Corrected the\n `SvDockLayout`, `SvDockManager`, and `SvDateTimePicker` prop tables (added 13\n missing dock-layout props; removed a `size` prop `SvDateTimePicker` never had),\n and filled scattered gaps (`loading`, `onClosed`, `min` / `max`, `dir`,\n `width` / `height`, `ariaLabel`, and the shared field-contract on\n `SvFileUpload`).\n\n## [1.0.0] - 2026-06-16\n\nInitial public release - the Svelte 5-native data grid: `@svgrid/grid`\n(MIT core) and `@svgrid/enterprise` (the paid feature pack).\n\n### @svgrid/grid\n\n- **New** `onCellValueChange` callback on `<SvGrid>`. Fires after every\n inline edit commits with `{ rowIndex, columnId, oldValue, newValue,\n row }`. The recommended hook for server-side persistence and cascading\n recomputes; see demo `18-cascade-editing` and\n [Saving values](./help/editing/saving-values.md).\n- **New** `externalSort` + `externalFilter` props. Grid records the UI\n state but does NOT re-order / filter rows - the consumer owns the\n pipeline. Paired with `onSortingChange` / `onFiltersChange` for\n server-side data and tree-data scenarios.\n- **New** `onSortingChange(sorting)` / `onFiltersChange(filters)`\n callbacks. Fire on every change with the consolidated payload shapes\n documented in the [SvGrid reference](./reference/SvGrid.md).\n- **New** `onRowSelectionChange(selection, rows)` and\n `onActiveCellChange(cell)` callbacks.\n- **New** `fitColumns` prop. Scales column widths to fill the viewport,\n with rounding-residue absorbed in the last scalable column. Shrinks\n down to 85 % of natural widths; beyond that a horizontal scrollbar\n appears.\n- **New** `showRowNumbers` prop. Leading 1-based row-number column,\n rendered before any selection column.\n- **New** `pageSize` prop on `<SvGrid>`. Initial page size for the\n built-in pager.\n- **Improved** column virtualizer now detects per-item size changes,\n not just total size. Fixes a regression where resizing a column under\n `fitColumns` left other columns stale.\n- **Improved** the wrapper-managed filter pipeline no longer applies\n filters to the pre-paginated view - the filter UI always sees the\n full dataset, not just the visible page. (Removed\n `paginatedRowModel` from the engine pipeline; pagination is applied\n AFTER filters by the wrapper.)\n\n### @svgrid/enterprise\n\n- **New** package. The paid feature pack adds:\n - **Export** to xlsx / pdf / csv / tsv / html, with theme-matched\n styles, multi-sheet workbooks, header + footer with logo, embedded\n cell images. See [Export](./help/export.md).\n - **Print** with repeat-on-page headers, optional cover page,\n page-size + orientation.\n - **Import** from xlsx / csv / tsv / json with column mapping +\n per-row validation. See [Import](./help/import.md).\n - **AI assistant**: provider-agnostic helpers for natural-language\n filter, smart fill, summarize, and classify. Bring your own model\n adapter. See [AI](./help/ai.md).\n - **Pivot tables** via `createPivotModel(data, config)` and\n `pro.pivot.build(config)`. Row + column axes, 8 built-in\n aggregators or custom, grand-total row + column, subtotals,\n custom axis sort. See [Pivot tables](./help/pivot.md).\n- **New** `installEnterprise(api)` augments a `SvGridApi` with `exportData`,\n `print`, `importData`, `ai.*`, and `pivot.*` methods.\n- **Soft-gated licensing**: features run unlicensed but the grid shows\n a small watermark + a one-time console nudge. `setLicenseKey('SVENTERPRISE-…')`\n at app startup clears both.\n\n### Examples gallery\n\n- **New demos** (56-59): theme-matched export, branded export with\n header + footer + logo, export with cell images, multi-sheet export.\n- **New demos** (52-pivot-table, 51-ai-assistant, 53-excel-import):\n reference implementations for each Enterprise feature.\n- **New demos** for industry verticals: stock market (live ticks),\n HR team, finances ledger, industrial IoT, localization, CSP\n compliant, accessibility, cascade editing, server-side rendering,\n industrial dashboard, healthcare EMR, logistics, compliance queue,\n field service, gantt, scheduler, CRM, admin dashboard, seller panel.\n- **New** \"Source\" button on every demo opens the raw `.svelte` file\n in a modal with a Copy-to-clipboard button. Wired via\n `import.meta.glob('../demos/*.svelte', { query: '?raw' })` so it\n picks up new demos automatically.\n\n### Docs\n\n- **New** [Enterprise feature pack](./enterprise/README.md) landing page.\n- **New** [API reference](./reference/index.md) with hand-curated\n pages for `<SvGrid>`, `SvGridApi`, `ColumnDef`, features, and the\n full Enterprise surface.\n- **New** [Why headless?](./why-headless.md) explains the layered\n architecture and when to drop down to the headless core.\n- **New** [Tailwind integration](./help/tailwind.md) walks the\n `--sg-*` token surface, dark-mode wiring via `data-theme`, and the\n override hooks for the stable `.sv-grid-*` class names.\n- **Split** [Getting started](./getting-started.md) into six short\n pages (install / first-grid / data-and-columns / features /\n theme-and-density / going-to-production); the old single-page\n version is preserved at\n [getting-started-full.md](./getting-started-full.md).\n- **Cleaned** every code sample against the live library surface.\n Removed phantom APIs: `state={...}`, `rowModels={...}`,\n `initialState={...}`, `manualFiltering`, `manualSorting`,\n `manualPagination`, `onColumnFiltersChange`, the wrapper `getRowId`\n prop, per-column `enableSorting` / `enableColumnFilter` /\n `enableGrouping` flags, the never-shipped\n `@svgrid/grid/themes/default.css` import.\n- **Em-dashes globally swept to hyphens** (`-` → `-`) across all\n source-controlled text. Codified as a rule for new content.\n\n## How we version\n\n| Tier | What it means |\n| ----------------- | -------------------------------------------------------------------------------------------------------------- |\n| **Major** (1.x) | Breaking change to a Stable API. Includes prop / method renames, type-narrowing, default-behaviour changes. |\n| **Minor** | New Stable API. New Experimental API. New demo. Doc rewrites that touch the public-facing claims. |\n| **Patch** | Bug fixes. Type-only fixes. Internal refactors with no public surface change. Doc typo fixes. |\n\nThe [API stability page](./help/api-stability.md) annotates each export\nwith its current tier (`Stable`, `Experimental`, `Internal`). As of 1.0,\n`Stable` APIs follow semver; `Experimental` APIs may still change in a\nminor release.\n"
4392
4392
  },
4393
4393
  {
4394
4394
  "slug": "compliance/audit-log",
@@ -4416,7 +4416,14 @@ export const docs = [
4416
4416
  "path": "docs/compliance/index.md",
4417
4417
  "title": "Compliance",
4418
4418
  "section": "Compliance",
4419
- "markdown": "# Compliance\n\nsv-grid is a client-side UI library - **all data stays in the\nbrowser**, the library never makes a network call of its own, no\ntelemetry phones home. The compliance story is therefore short, but\nbecause enterprise procurement asks the same questions every time,\nthis section answers each one directly.\n\n> If your reviewer wants a one-pager: jump to the\n> [vendor-questionnaire shortlist](#vendor-questionnaire-shortlist)\n> at the bottom.\n\n## Pages\n\n- [SOC 2 posture](./soc2.md) - what the library covers, what your\n hosting / build pipeline must cover\n- [GDPR + data residency](./gdpr.md) - personal-data handling, where\n data physically sits, the user-rights surface\n- [HIPAA posture](./hipaa.md) - PHI handling in the browser, what\n \"no PHI on disk\" requires you to wire\n- [Accessibility Conformance Report (VPAT 2.5Rev)](./vpat.md) - the\n per-criterion WCAG 2.1 / Section 508 / EN 301 549 claim, with the\n evidence behind each one and the gaps stated rather than omitted.\n- [Audit log integration](./audit-log.md) - turn the grid's callbacks\n into an immutable audit trail with one adapter\n\n## Vendor-questionnaire shortlist\n\n| Question | Answer |\n| ------------------------------------------------- | --------------------------------------------------------------- |\n| Does the library transmit any data? | **No.** Zero outbound network calls. Inspect with DevTools. |\n| Does the library write to localStorage? | **Only when you opt in.** [Saved views](../help/saved-views.md) writes when you tell it to. |\n| Does the library evaluate user input as code? | **No.** CSP-compliant; no `eval` / `new Function`. |\n| Does the library include third-party trackers? | **No.** Verify the bundle - ~77 kB gzip, no analytics SDK. |\n| 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). |\n| 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). |\n| Is the library HIPAA-compliant? | Same: HIPAA-neutral. PHI handling is a property of your app, not the grid. See [HIPAA posture](./hipaa.md). |\n| Is the source code auditable? | **Yes.** MIT-licensed; published as readable source (no minified obfuscation). |\n| Where is data stored? | **In your app's memory.** Never on a sv-grid server. There is no sv-grid server. |\n| Is there a security disclosure policy? | Yes - email `support@jqwidgets.com`. Patches typically ship within 7 days for high-severity issues. |\n| Is the library tested for accessibility? | **Yes.** `axe-core` runs against a rendered `<SvGrid>` in CI on every commit, across the plain grid, the filter row, row selection and pagination. Layout-dependent rules (notably colour contrast) are disabled because the suite runs in jsdom, which performs no layout; contrast is covered instead by a computed check over all 20 built-in themes in light and dark. See [accessibility](../help/accessibility.md). |\n| Do you publish a VPAT / ACR? | **Yes.** [VPAT 2.5Rev INT](./vpat.md), covering WCAG 2.1 AA, Revised Section 508 and EN 301 549 in one document. It is a self-assessment, and says so: every \"Supports\" names the test behind it, and the two known gaps (no `aria-invalid` on cell editors, no recorded screen-reader test pass) are stated in the report rather than left out. |\n| Are dependencies vetted? | Yes - one runtime dependency in `@svgrid/grid` (`esm-env`, MIT, itself dependency-free). `@svgrid/enterprise` lazy-loads `jszip` + `pdfmake` as peers. See [security](../help/security.md) for the dep table. |\n| Is there an SBOM? | **Yes.** A CycloneDX 1.6 document per published package lives in [`sbom/`](https://github.com/sv-grid/sv-grid/tree/main/sbom), regenerated with `pnpm sbom`. With one dependency-free runtime dependency in the grid the graph is shallow by construction. See [security](../help/security.md#sbom). |\n\n## See also\n\n- [Security & supply chain](../help/security.md) - the parent posture\n- [Observability](../help/observability.md) - the audit log seam\n- [API stability](../help/api-stability.md) - the deprecation promise\n"
4419
+ "markdown": "# Compliance\n\nsv-grid is a client-side UI library - **all data stays in the\nbrowser**, the library never makes a network call of its own, no\ntelemetry phones home. The compliance story is therefore short, but\nbecause enterprise procurement asks the same questions every time,\nthis section answers each one directly.\n\n> If your reviewer wants a one-pager: jump to the\n> [vendor-questionnaire shortlist](#vendor-questionnaire-shortlist)\n> at the bottom.\n\n## Pages\n\n- [SOC 2 posture](./soc2.md) - what the library covers, what your\n hosting / build pipeline must cover\n- [GDPR + data residency](./gdpr.md) - personal-data handling, where\n data physically sits, the user-rights surface\n- [HIPAA posture](./hipaa.md) - PHI handling in the browser, what\n \"no PHI on disk\" requires you to wire\n- [Accessibility Conformance Report (VPAT 2.5Rev)](./vpat.md) - the\n per-criterion WCAG 2.2 / Section 508 / EN 301 549 claim, with the\n evidence behind each one and the gaps stated rather than omitted.\n- [Security questionnaire answers](./security-questionnaire.md) - data\n handling, supply chain, secure development and vulnerability handling,\n in the order a vendor review asks them\n- [Audit log integration](./audit-log.md) - turn the grid's callbacks\n into an immutable audit trail with one adapter\n\n## Vendor-questionnaire shortlist\n\n| Question | Answer |\n| ------------------------------------------------- | --------------------------------------------------------------- |\n| Does the library transmit any data? | **No.** Zero outbound network calls. Inspect with DevTools. |\n| Does the library write to localStorage? | **Only when you opt in.** [Saved views](../help/saved-views.md) writes when you tell it to. |\n| Does the library evaluate user input as code? | **No.** CSP-compliant; no `eval` / `new Function`. |\n| Does the library include third-party trackers? | **No.** No analytics SDK in the bundle; see [bundle size](../help/bundle-size.md) for what is in it. |\n| 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). |\n| 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). |\n| Is the library HIPAA-compliant? | Same: HIPAA-neutral. PHI handling is a property of your app, not the grid. See [HIPAA posture](./hipaa.md). |\n| Is the source code auditable? | **Yes.** MIT-licensed; published as readable source (no minified obfuscation). |\n| Where is data stored? | **In your app's memory.** Never on a sv-grid server. There is no sv-grid server. |\n| Is there a security disclosure policy? | Yes - [SECURITY.md](https://github.com/sv-grid/sv-grid/blob/main/SECURITY.md): private reporting, acknowledgement within 3 working days, assessment within 10. Enterprise customers get faster response; see [vulnerability handling](../help/security.md#vulnerability-handling). |\n| Is the library tested for accessibility? | **Yes.** `axe-core` runs on every commit twice: in jsdom across several grid configurations, and in Chromium, where the layout rules (contrast, target size) can run. Contrast is also computed for all 20 built-in themes in light and dark. See [accessibility](../help/accessibility.md). |\n| Do you publish a VPAT / ACR? | **Yes.** [VPAT 2.5Rev INT](./vpat.md), report 2.0, covering WCAG 2.2 AA, Revised Section 508 and EN 301 549. It is a self-assessment and says so: every \"Supports\" names the test behind it, and the gaps (drag-only actions, menu focus return, no recorded screen-reader pass) are listed rather than left out. |\n| Are dependencies vetted? | Yes - one runtime dependency in `@svgrid/grid` (`esm-env`, MIT, itself dependency-free). `@svgrid/enterprise` lazy-loads `jszip` + `pdfmake` as optional peers and ships one vendored module (the Smart UI exporter). See [security](../help/security.md) for the table. |\n| Is there an SBOM? | **Yes.** A CycloneDX 1.6 document per published package in [`sbom/`](https://github.com/sv-grid/sv-grid/tree/main/sbom), vendored code included. Each release regenerates and signs them (Sigstore attestation, verify with `gh attestation verify`), and CI fails if one drifts from its manifest. See [security](../help/security.md#sbom). |\n| Will you fill in our security questionnaire? | Yes. Most answers are already written up in [security questionnaire answers](./security-questionnaire.md); send the rest to `support@jqwidgets.com`. |\n\n## See also\n\n- [Security & supply chain](../help/security.md) - the parent posture\n- [Observability](../help/observability.md) - the audit log seam\n- [API stability](../help/api-stability.md) - the deprecation promise\n"
4420
+ },
4421
+ {
4422
+ "slug": "compliance/security-questionnaire",
4423
+ "path": "docs/compliance/security-questionnaire.md",
4424
+ "title": "Security questionnaire answers",
4425
+ "section": "Compliance",
4426
+ "markdown": "# Security questionnaire answers\n\nAnswers to the questions a vendor security review asks about a front-end\ncomponent library, grouped the way most questionnaires (SIG Lite, CAIQ, a\nbuyer's own) group them. Each answer points at the code, file or workflow that\nbacks it, so a reviewer can check it rather than take it on trust.\n\nQuestions about the company rather than the product (insurance, headcount,\nfinancial statements) go to sales@jqwidgets.com.\n\n## Scope: what is being assessed\n\n| Question | Answer |\n| --- | --- |\n| What is the product? | JavaScript packages installed from npm: `@svgrid/grid` (MIT) and `@svgrid/enterprise` (commercial). They run inside your application, in the browser or under Node for SSR. |\n| Is it a hosted service? | **No.** We operate no service your application depends on. Your data never reaches a system of ours. |\n| Do you host anything at all? | The website (svgrid.com), the trial and licensing forms, and an optional remote MCP server (mcp.svgrid.com) for AI coding assistants. None of them is in your application's runtime path. What the MCP server records is listed on the [privacy page](https://svgrid.com/privacy/). |\n| Does a SOC 2 report apply? | SOC 2 examines service organizations, and we run no service in your data path. See [SOC 2 posture](./soc2.md) for how the library fits your own report. |\n\n## Data handling\n\n| Question | Answer |\n| --- | --- |\n| Does the library send data anywhere? | **No.** No telemetry, analytics or update checks. The only network calls are ones you configure: a server data source calls the `fetch` you pass it, and the AI helpers call the `AIProvider` you register. |\n| Does the license check phone home? | **No.** The Enterprise key is validated offline, in the browser. Without a valid key the features still run and show a watermark. |\n| Does it write to storage? | Not unless you opt in (saved views, for example). See [GDPR + data residency](./gdpr.md). |\n| Does it evaluate code? | No `eval` or `new Function` in `@svgrid/grid`; it runs under a strict CSP. See [security](../help/security.md#csp-guidance). |\n| Personal data, PHI | The library processes only what your app renders. See [GDPR](./gdpr.md) and [HIPAA](./hipaa.md). |\n\n## Supply chain\n\n| Question | Answer |\n| --- | --- |\n| Runtime dependencies | `@svgrid/grid`: one, `esm-env` (MIT, no dependencies of its own). `@svgrid/enterprise`: none required; `jszip` and `pdfmake` are optional peers loaded on first XLSX or PDF use. Enterprise also ships one vendored module, the Smart UI exporter (jQWidgets). |\n| SBOM | CycloneDX 1.6, one per package, in [`sbom/`](https://github.com/sv-grid/sv-grid/tree/main/sbom). Regenerated with every release, and CI fails if one drifts from its manifest (`pnpm sbom:check`). Vendored code is listed as a component. |\n| Are releases signed? | npm packages are published from GitHub Actions with `--provenance`, so npm shows the workflow and commit that built them. From the next release on, each SBOM also carries a Sigstore attestation: `gh attestation verify sbom/svgrid-grid.cdx.json --repo sv-grid/sv-grid`. |\n| Can you build from source? | Yes. The npm packages are built from this public repository; there are no private patches. |\n| Licenses of what you ship | MIT for the grid and its dependency; the vendored exporter is jQWidgets' own code under its license. The SBOM records each license. |\n\n## Secure development\n\n| Question | Answer |\n| --- | --- |\n| How is code tested before release? | Every push to `main` runs the Test workflow (`.github/workflows/test.yml`): type checks of every package, lint, the grid and Enterprise unit suites, browser specs in Chromium, bundle-size budgets and SBOM drift. The release workflow (`.github/workflows/publish-npm.yml`) runs when a push to `main` finishes its Test run green, and publishes that commit; there is no scheduled publish. A manual run is the maintainer's override. |\n| Security-relevant tests | HTML sanitization of cell content (`sanitize-html.test.ts`); formula injection in CSV, TSV and chart CSV exports (`csv-injection.test.ts`); crafted .xlsx files that address cells far outside the sheet (`import-xlsx-limits.dom.test.ts`); LIMIT and OFFSET rejected unless they are non-negative integers in the SvelteKit SQL data source (`sql-source.test.ts`); and the accessibility suites. |\n| CSV / formula injection | File exports prefix text that a spreadsheet would run as a formula (`=`, `+`, `-`, `@`, tab, carriage return) with `'`, by default. See [export](../help/export.md). |\n| Can a version change after release? | No. npm does not allow a published version to be overwritten. |\n\n## Vulnerability management\n\n| Question | Answer |\n| --- | --- |\n| How do we report a vulnerability? | Privately, through GitHub's vulnerability reporting or by email, as [SECURITY.md](https://github.com/sv-grid/sv-grid/blob/main/SECURITY.md) describes. |\n| Response times | Acknowledgement within 3 working days and an assessment within 10 (SECURITY.md). Enterprise customers: acknowledgement within one business day, and a fix for High and Critical issues within five business days ([security](../help/security.md#vulnerability-handling)). |\n| How are customers told? | A GitHub security advisory and the release notes. Enterprise customers hear before the advisory is public. |\n| Known vulnerabilities | None published. Check the repository's advisories page for the current list. |\n| EU Cyber Resilience Act | The pieces the CRA asks a manufacturer for are in place: a coordinated disclosure policy (SECURITY.md), a machine-readable SBOM per release, and a published support policy ([API stability](../help/api-stability.md#long-term-support)). |\n\n## Accessibility\n\n| Question | Answer |\n| --- | --- |\n| Do you publish an ACR / VPAT? | Yes: [VPAT 2.5Rev INT against WCAG 2.2 AA](./vpat.md), self-assessed, with every gap listed. |\n\n## See also\n\n- [Compliance overview](./index.md)\n- [Security & supply chain](../help/security.md)\n- [Audit log integration](./audit-log.md)\n"
4420
4427
  },
4421
4428
  {
4422
4429
  "slug": "compliance/soc2",
@@ -4430,7 +4437,7 @@ export const docs = [
4430
4437
  "path": "docs/compliance/vpat.md",
4431
4438
  "title": "Accessibility Conformance Report (VPAT 2.5Rev, INT)",
4432
4439
  "section": "Compliance",
4433
- "markdown": "# Accessibility Conformance Report (VPAT 2.5Rev, INT)\n\n**Product:** SvGrid (`@svgrid/grid`, `@svgrid/enterprise`)\n**Report version:** 1.0\n**Report date:** 2026-08-24\n**Contact:** support@jqwidgets.com\n\nThis report follows the **VPAT 2.5Rev International edition**, which covers the\nRevised Section 508 standards, EN 301 549, and WCAG 2.1 in one document.\n\n> **This is a self-assessment, not a third-party certification.** It records what\n> we test, how we test it, and what we have not tested. Nothing here is a legal\n> certification of conformance. Where a criterion depends on your content or your\n> theme, this report says so rather than claiming credit for it.\n\n## What SvGrid is, for the purposes of this report\n\nSvGrid is a **software component**, not a web page or an application. It renders\na data grid inside a page you control. Several WCAG criteria are therefore\nscoped to the page rather than the component (page title, language of page,\nbypass blocks, consistent navigation) and are marked **Not Applicable** with a\nnote; you remain responsible for them in the page that hosts the grid.\n\nSeveral others are **shared**: the grid supplies correct roles, names and\nkeyboard behaviour, but you supply cell content. A custom cell renderer that\nemits an image without alt text will fail 1.1.1 no matter what the grid does.\nThose are marked *Supports, with author responsibility* and the boundary is\nstated in the remarks.\n\n## Evaluation methods\n\n| Method | What it covers | Where it runs |\n| --- | --- | --- |\n| `axe-core` against a rendered grid | Roles, names, relationships, duplicate ids, nested-interactive violations. Four configurations: plain, filter row + global filter, row selection, pagination | `packages/grid/src/a11y.axe.test.ts`, on every commit in CI |\n| WCAG contrast computation | Text, secondary text, header text, text on zebra / hovered / selected rows, text on accent controls, and the accent as a focus indicator, for **all 20 built-in themes in both light and dark** | `packages/grid/src/themes/contrast.test.ts`, on every commit in CI |\n| ARIA contract unit tests | The role / `aria-*` property builders and the roving-tabindex pattern | `a11y.test.ts`, `a11y.contract.test.ts` |\n| Focus and live-region unit tests | Focus trap, dismissable layers, scroll lock, the `aria-live` announcer | `packages/grid/src/a11y/*.test.ts` |\n| Manual keyboard review | The documented keyboard map | Manual, not automated |\n\n### Known limits of this evidence\n\nStated plainly, because a conformance report that hides its gaps is worse than\nno report:\n\n- **The axe suite runs in jsdom**, which performs no layout or painting. Its own\n `color-contrast` rule is therefore disabled there, and geometry-dependent\n rules (`target-size`, `scrollable-region-focusable`) are not exercised.\n Contrast is covered separately and more thoroughly by computation over the\n theme tokens, but **target size has not been machine-verified**.\n- **No formal screen-reader test pass has been recorded.** The grid implements\n the WAI-ARIA 1.2 grid pattern and is audited structurally, but we do not\n currently publish results from a scripted NVDA / JAWS / VoiceOver run.\n Criteria that depend on assistive-technology behaviour are marked\n *Supports* on the strength of the ARIA implementation and automated audit,\n and that basis is noted per row.\n- **Only the built-in themes are contrast-tested.** A custom theme is yours to\n verify; the method is documented in [accessibility](../help/accessibility.md).\n\nWriting this report was itself an audit, and it found two real defects rather\nthan only describing existing behaviour. Both are fixed and covered by tests:\nthe grid never called its own `announce()`, so the documented status messages\nwere not being made at all; and a cell failing `validate` was marked with a red\nclass and a mouse-only tooltip, giving a screen-reader user no way to know the\nvalue had been rejected.\n\n## WCAG 2.1 Level A\n\n| Criterion | Conformance | Remarks |\n| --- | --- | --- |\n| 1.1.1 Non-text Content | Supports, with author responsibility | Grid chrome (sort, filter, menu, pagination controls) carries text or `aria-label`. Content inside cells is yours; a custom renderer must supply its own text alternatives. |\n| 1.2.x Time-based Media | Not Applicable | The grid renders no audio or video. |\n| 1.3.1 Info and Relationships | Supports | Native `<table>` semantics plus the ARIA grid pattern: `grid`, `rowgroup`, `row`, `columnheader`, `gridcell`, with `aria-rowindex` / `aria-colindex` / `aria-rowcount` / `aria-colcount`. Verified by the axe suite and the ARIA contract tests. |\n| 1.3.2 Meaningful Sequence | Supports | DOM order follows visual order, including with pinned columns. |\n| 1.3.3 Sensory Characteristics | Supports | Sort state is exposed via `aria-sort`, not by icon alone. |\n| 1.4.1 Use of Color | Supports, with author responsibility | Grid state is conveyed by ARIA as well as colour: sort by `aria-sort`, selection by `aria-selected`, focus by the roving tabindex, and a failed `validate` by `aria-invalid` plus its message rather than the red highlight alone. Conditional formatting you configure is yours to make non-colour-dependent. |\n| 1.4.2 Audio Control | Not Applicable | No audio. |\n| 2.1.1 Keyboard | Supports | Full keyboard operation: navigation, selection, sorting, filtering, editing, undo. Column resize handles are keyboard-operable with arrow keys. See the keyboard map in [accessibility](../help/accessibility.md). |\n| 2.1.2 No Keyboard Trap | Supports | Roving tabindex: one cell is tabbable and Tab exits the grid. Popovers (filter menus, editors) use a dismissable-layer stack that restores focus on close. Covered by the focus-trap unit tests. |\n| 2.1.4 Character Key Shortcuts | Supports | Single-character shortcuts act only while focus is inside the grid, and are suppressed while a cell editor is open. |\n| 2.2.1 Timing Adjustable | Not Applicable | No time limits. |\n| 2.2.2 Pause, Stop, Hide | Supports | No auto-updating content originates in the grid. Scroll animation and chevron transitions honour `prefers-reduced-motion: reduce`. |\n| 2.3.1 Three Flashes | Supports | Cell-flash highlighting on value change is a single fade well under three flashes per second. |\n| 2.4.1 Bypass Blocks | Not Applicable | Page-level concern. |\n| 2.4.2 Page Titled | Not Applicable | Page-level concern. |\n| 2.4.3 Focus Order | Supports | Roving tabindex keeps a single predictable stop; popovers return focus to their trigger. |\n| 2.4.4 Link Purpose | Supports, with author responsibility | Links rendered inside cells are yours. |\n| 2.5.1 Pointer Gestures | Supports | No multipoint or path-based gesture is required; drag operations (column reorder, resize, row drag) all have keyboard equivalents. |\n| 2.5.2 Pointer Cancellation | Supports | Actions fire on pointer-up. |\n| 2.5.3 Label in Name | Supports | Accessible names for grid controls begin with their visible text. |\n| 2.5.4 Motion Actuation | Not Applicable | No motion actuation. |\n| 3.1.1 Language of Page | Not Applicable | Page-level concern. |\n| 3.2.1 On Focus | Supports | Focus alone never changes context. |\n| 3.2.2 On Input | Supports | Filtering and editing update the grid in place; no unexpected context change. |\n| 3.3.1 Error Identification | Supports, with author responsibility | A cell failing a column's `validate` hook carries `aria-invalid=\"true\"`, and the message it returns reaches assistive technology as the cell's accessible description or as visually-hidden text read with the cell - not only as the hover tooltip. Deciding *what* is invalid is yours. |\n| 3.3.2 Labels or Instructions | Supports | Editors and filter inputs derive an accessible name from the column header. |\n| 4.1.2 Name, Role, Value | Supports | The core of the grid pattern, and the criterion the axe suite exercises most directly. Interactive chrome exposes role, name and state. |\n| 4.1.3 Status Messages | Supports | The status changes that move no focus are announced through a visually-hidden `aria-live=\"polite\"` region: filter match counts, filter clearing, and bulk selection changes. Changes the accessibility tree already carries (the focused cell, `aria-sort`, a single row's `aria-selected`) are deliberately not repeated there. Covered by `a11y.announce.test.ts` against a rendered grid. |\n\n## WCAG 2.1 Level AA\n\n| Criterion | Conformance | Remarks |\n| --- | --- | --- |\n| 1.4.3 Contrast (Minimum) | Supports for built-in themes; author responsibility for custom themes | Every one of the 20 built-in presets is CI-tested in both light and dark against 4.5:1 for body, secondary, header, zebra, hover, selection and accent-control text. A custom theme is not covered by that test. |\n| 1.4.4 Resize Text | Supports | Layout is token-driven and reflows at 200% zoom. |\n| 1.4.5 Images of Text | Supports | No images of text. |\n| 1.4.10 Reflow | Partially Supports | The grid reflows and its own regions scroll rather than the page. A data table with many columns still requires horizontal scrolling at 320 CSS pixels, which is inherent to tabular data; the `responsive` prop and per-column `hideBelow` let you reduce the column set at narrow widths. |\n| 1.4.11 Non-text Contrast | Supports | The accent used for focus and selection indication is CI-tested at 3:1 against the background for every theme. Note that decorative table gridlines are intentionally not held to 3:1: the grid's structure is conveyed by the accessibility tree, so the rule does not apply to them. |\n| 1.4.12 Text Spacing | Supports | Row height and cell padding are token-driven; no clipping under the required spacing overrides. |\n| 1.4.13 Content on Hover or Focus | Supports | Tooltips and popovers are dismissable with Escape, hoverable, and persist until dismissed. |\n| 2.4.5 Multiple Ways | Not Applicable | Page-level concern. |\n| 2.4.6 Headings and Labels | Supports | Column headers are descriptive `columnheader` elements. |\n| 2.4.7 Focus Visible | Supports | The active cell carries a visible focus ring that uses `currentColor`, so it survives forced-colors mode. |\n| 3.1.2 Language of Parts | Not Applicable | Page-level concern. |\n| 3.2.3 Consistent Navigation | Not Applicable | Page-level concern. |\n| 3.2.4 Consistent Identification | Supports | Grid controls are identified consistently across instances. |\n| 3.3.3 Error Suggestion | Supports, with author responsibility | The string your `validate` hook returns is carried through verbatim, so a correction hint (\"Score must be at least 90\") reaches the user. Writing a useful hint is yours. |\n| 3.3.4 Error Prevention | Not Applicable | No legal, financial or data-deletion transaction originates in the grid. |\n| 4.1.1 Parsing | Supports | Obsolete in WCAG 2.2; no duplicate ids or malformed markup, checked by the axe suite. |\n\n## Revised Section 508\n\nSection 508 incorporates **WCAG 2.0 Level A and AA** by reference. Every WCAG\n2.0 criterion is a subset of the 2.1 tables above, so the conformance claims\ncarry over unchanged.\n\n| Chapter | Conformance | Remarks |\n| --- | --- | --- |\n| 302 Functional Performance Criteria | Supports, with the limits noted above | Operation without vision relies on the ARIA grid pattern; see the screen-reader caveat in *Known limits*. |\n| 501-504 Software | Supports | The grid is authored content within a host application; it exposes platform accessibility services via ARIA in the browser. |\n| 602 Support Documentation | Supports | Accessibility documentation is published at [accessibility](../help/accessibility.md), including the keyboard map and verification guidance. |\n\n## EN 301 549\n\nEN 301 549 v3.2.1, the harmonised European standard, incorporates **WCAG 2.1\nLevel A and AA** for web content. Clauses 9.1 through 9.4 map directly onto the\nWCAG 2.1 tables above; clause 11 (software) is addressed by the same ARIA\nimplementation. No separate claims are made here.\n\n## Reproducing these results\n\n```bash\npnpm --filter @svgrid/grid test:lib # includes the axe and contrast suites\n```\n\nBoth suites fail the build on a regression, so this report is checked by CI\nrather than being a point-in-time snapshot.\n\n## See also\n\n- [Accessibility](../help/accessibility.md) - roles, keyboard map, and how to verify a custom theme\n- [Compliance overview](./index.md) - the wider procurement questions\n"
4440
+ "markdown": "# Accessibility Conformance Report (VPAT 2.5Rev, INT)\n\n**Product:** SvGrid (`@svgrid/grid`, `@svgrid/enterprise`)\n**Report version:** 2.0\n**Report date:** 2026-10-25\n**Standards:** WCAG 2.2 Level A and AA, Revised Section 508, EN 301 549 v3.2.1\n**Contact:** support@jqwidgets.com\n\nThis report follows the **VPAT 2.5Rev International edition**. Version 1.0\n(2026-08-24) covered WCAG 2.1. This version moves to WCAG 2.2, re-checks every\nrow against the code, and corrects four rows that version 1.0 overstated\n(2.1.1, 2.1.2, 2.4.3, 2.4.7). The defects behind 2.1.2 and 2.4.7 were fixed\nwhile this report was written; the rest are listed as gaps below.\n\n> **This is a self-assessment, not a third-party audit.** Every \"Supports\"\n> names the test or the code behind it. Where a criterion depends on your\n> content or your theme, the row says so.\n\n## What SvGrid is, for the purposes of this report\n\nSvGrid is a **software component** that renders a data grid inside a page you\ncontrol. Page-level criteria (page title, language of page, bypass blocks,\nconsistent navigation, consistent help) are **Not Applicable** to the\ncomponent; you remain responsible for them in the host page.\n\nSeveral criteria are **shared**: the grid supplies roles, names and keyboard\nbehaviour, and you supply cell content. A custom cell renderer that emits an\nimage without alt text fails 1.1.1 whatever the grid does. Those rows read\n*Supports, with author responsibility*.\n\n## Evaluation methods\n\n| Method | What it covers | Where it runs |\n| --- | --- | --- |\n| `axe-core` in jsdom | Roles, names, relationships, duplicate ids, nested interactive controls. Plain grid, filter row + global filter, row selection, pagination, an invalid cell, an open cell editor | `packages/grid/src/a11y.axe.test.ts`, every commit |\n| `axe-core` in Chromium | The same plus the layout rules jsdom cannot run (`color-contrast`, `target-size`), tags `wcag2a`, `wcag2aa`, `wcag21a`, `wcag21aa`, `wcag22aa`, on the quick-start demo in the default theme | `tests/e2e/grid-a11y.spec.ts`, every commit |\n| Keyboard and focus in Chromium | Tab leaves the grid at both ends; focus is visible when the keyboard brings it in; the forced-colors indicator | `tests/e2e/grid-a11y.spec.ts` |\n| WCAG contrast computation | Body, secondary, header, zebra, hover, selection and on-accent text at 4.5:1, and the accent at 3:1, for **all 20 built-in themes in light and dark** | `packages/grid/src/themes/contrast.test.ts` |\n| ARIA contract and announcement tests | Role and `aria-*` builders; the live-region messages on a mounted grid | `a11y.test.ts`, `a11y.contract.test.ts`, `a11y.announce.test.ts`, `a11y/*.test.ts` |\n| Code review | Each row below, re-read against the source on 2026-10-25 | This report |\n\n### Known limits of this evidence\n\n- **No scripted screen-reader pass (NVDA, JAWS, VoiceOver) has been\n recorded.** Rows that depend on assistive-technology behaviour rest on the\n ARIA implementation and the axe runs.\n- The browser axe run covers one configuration (the quick-start demo, default\n theme). The jsdom runs cover the others with virtualization off.\n- Only the built-in themes are contrast-tested. A custom theme is yours to\n verify; the method is in [accessibility](../help/accessibility.md).\n\n## WCAG 2.2 Level A\n\n| Criterion | Conformance | Remarks |\n| --- | --- | --- |\n| 1.1.1 Non-text Content | Supports, with author responsibility | Grid controls carry text or `aria-label`. Content you render in cells is yours. |\n| 1.2.1-1.2.3 Time-based Media | Not Applicable | No audio or video. |\n| 1.3.1 Info and Relationships | Partially Supports | Native `<table>` semantics plus `grid` / `treegrid`, `rowgroup`, `row`, `columnheader`, `gridcell`, `aria-rowcount`, `aria-colcount`, and absolute `aria-rowindex` / `aria-colindex` on body cells. Gaps: header rows carry no `aria-rowindex` and header cells no `aria-colindex` (matters under column virtualization); a cell range selection is shown visually but not exposed through `aria-selected`; grouped rows on a plain `grid` carry `aria-level`, which ARIA defines only for `treegrid`. |\n| 1.3.2 Meaningful Sequence | Supports | DOM order follows visual order, pinned columns included. |\n| 1.3.3 Sensory Characteristics | Supports | Sort state is exposed through `aria-sort`, not only by the icon. |\n| 1.4.1 Use of Color | Supports, with author responsibility | Sort, row selection and validation errors are carried by `aria-sort`, `aria-selected` and `aria-invalid` with the message, not by colour alone. Conditional formatting you configure is yours. |\n| 1.4.2 Audio Control | Not Applicable | No audio. |\n| 2.1.1 Keyboard | Partially Supports | Navigation, row selection, sorting, filtering, editing, undo, column and row resize (arrow keys on the focused handle) and tree / group expand all work from the keyboard. Gaps: managed row dragging (`rowDragManaged`) has no keyboard path; moving a column has one only through the tool panel's Move up / Move down; the column menu opens without taking focus and has no arrow-key navigation; a custom header renderer gets `role=\"button\"` with `tabindex=\"-1\"`. |\n| 2.1.2 No Keyboard Trap | Supports | Tab on the last cell and Shift+Tab on the first move focus off the grid (`tests/e2e/grid-a11y.spec.ts`). Before 2026-10-25 every Tab was consumed and no key left the grid. |\n| 2.1.4 Character Key Shortcuts | Supports | Typing a character starts editing only while focus is on the grid (the \"active only on focus\" exception). |\n| 2.2.1 Timing Adjustable | Not Applicable | No time limits. |\n| 2.2.2 Pause, Stop, Hide | Supports, with author responsibility | The grid starts no auto-updating content. A live feed you push into it is yours to make pausable. The cell flash stops under `prefers-reduced-motion`. |\n| 2.3.1 Three Flashes or Below Threshold | Supports | The cell flash is one fade per value change. |\n| 2.4.1 Bypass Blocks | Not Applicable | Page-level. |\n| 2.4.2 Page Titled | Not Applicable | Page-level. |\n| 2.4.3 Focus Order | Partially Supports | The grid is one tab stop, and Tab leaves it at either end. Gap: grid menus (column menu, context menu) do not return focus to the button that opened them when they close. |\n| 2.4.4 Link Purpose (In Context) | Supports, with author responsibility | Links in cells are yours. |\n| 2.5.1 Pointer Gestures | Supports | No multipoint or path-based gesture is required. |\n| 2.5.2 Pointer Cancellation | Supports | A pointer-down on a cell only moves the active cell and starts a selection; buttons, menus, sorting and editing act on click (the up event). |\n| 2.5.3 Label in Name | Supports | Accessible names of grid controls contain their visible text. |\n| 2.5.4 Motion Actuation | Not Applicable | No motion input. |\n| 3.1.1 Language of Page | Not Applicable | Page-level. |\n| 3.2.1 On Focus | Supports | Focus alone never changes context. |\n| 3.2.2 On Input | Supports | Filtering and editing update the grid in place. |\n| 3.2.6 Consistent Help | Not Applicable | Page-level. |\n| 3.3.1 Error Identification | Supports, with author responsibility | A cell failing its column's `validate` gets `aria-invalid=\"true\"`, and the message reaches assistive technology as text read with the cell. What counts as invalid is yours. |\n| 3.3.2 Labels or Instructions | Partially Supports | Cell editors are named after their column (`a11y.axe.test.ts`). Gap: the inline filter-row input has a placeholder and no label. |\n| 3.3.7 Redundant Entry | Not Applicable | The grid runs no multi-step process. |\n| 4.1.2 Name, Role, Value | Partially Supports | Grid structure, selection checkboxes (`aria-checked`, including `mixed`), sort buttons, expanders (`aria-expanded`) and editors expose name, role and state, and both axe runs pass. Gaps: range selection state (see 1.3.1) and custom header renderers (see 2.1.1). |\n| 4.1.3 Status Messages | Supports | Filter match counts, cleared filters and bulk selection changes go to a visually hidden `role=\"status\"` region (`a11y.announce.test.ts`). What the tree already carries (the active cell, `aria-sort`, one row's `aria-selected`) is not repeated there. |\n\nWCAG 2.2 removed 4.1.1 Parsing; it is not listed.\n\n## WCAG 2.2 Level AA\n\n| Criterion | Conformance | Remarks |\n| --- | --- | --- |\n| 1.2.4, 1.2.5 Captions, Audio Description | Not Applicable | No media. |\n| 1.3.4 Orientation | Supports | No orientation lock. |\n| 1.3.5 Identify Input Purpose | Not Applicable | The grid collects no personal data about the user. |\n| 1.4.3 Contrast (Minimum) | Supports for built-in themes; author responsibility for custom themes | All 20 presets pass 4.5:1 in light and dark (`contrast.test.ts`), and axe's `color-contrast` rule passes in Chromium on the default theme. |\n| 1.4.4 Resize Text | Supports | Sizes are CSS pixel tokens that scale with browser zoom. No automated 200% test yet. |\n| 1.4.5 Images of Text | Supports | None. |\n| 1.4.10 Reflow | Partially Supports | A table with many columns scrolls horizontally at 320 CSS px, which tabular data needs. The `responsive` prop and per-column `hideBelow` reduce the column set at narrow widths. |\n| 1.4.11 Non-text Contrast | Supports | The accent used for the focus ring and selection is tested at 3:1 against the background in every theme. Gridlines are decorative and not held to 3:1. |\n| 1.4.12 Text Spacing | Supports | Row height and padding are tokens; no automated text-spacing test yet. |\n| 1.4.13 Content on Hover or Focus | Supports | Tooltips and popovers close with Escape and stay while hovered. |\n| 2.4.5 Multiple Ways | Not Applicable | Page-level. |\n| 2.4.6 Headings and Labels | Supports | Column headers name their columns. |\n| 2.4.7 Focus Visible | Supports | The active cell has an accent ring, shown when the keyboard brings focus to the grid, and a system `Highlight` outline under forced colors (`grid-a11y.spec.ts`). Before 2026-10-25 a grid reached by Tab showed no indicator, and forced colors removed the ring. |\n| 2.4.11 Focus Not Obscured (Minimum) | Partially Supports | Moving the active cell scrolls it into view below the sticky header. Gap: horizontal scrolling does not allow for left-pinned columns, so a cell can end up under one. |\n| 2.5.7 Dragging Movements | Partially Supports | Range selection has Shift+click, the fill handle has double-click, column order has the tool panel buttons. Gaps: managed row dragging and column resize by pointer have no single-pointer alternative. |\n| 2.5.8 Target Size (Minimum) | Supports | axe's `target-size` rule passes in Chromium on the quick-start demo. Several controls are under 24 px (selection checkbox 16 px, tree toggle 14 px, header filter and menu buttons 22 px, resize handle 5 px) and pass on the spacing exception; a body-row checkbox's whole cell is also clickable. |\n| 3.1.2 Language of Parts | Not Applicable | Page-level. |\n| 3.2.3 Consistent Navigation | Not Applicable | Page-level. |\n| 3.2.4 Consistent Identification | Supports | Controls are named the same way across instances. |\n| 3.3.3 Error Suggestion | Supports, with author responsibility | The string `validate` returns reaches the user verbatim. |\n| 3.3.4 Error Prevention (Legal, Financial, Data) | Not Applicable | No such transaction originates in the grid. |\n| 3.3.8 Accessible Authentication (Minimum) | Not Applicable | No authentication. |\n\n## Enterprise components\n\nRows above describe `<SvGrid>`. The Enterprise components add their own\nsurfaces:\n\n| Component | Status |\n| --- | --- |\n| `<SvSheet>` spreadsheet shell | axe in Chromium over 11 demos, light and dark; ribbon and sheet tabs use roving tabindex; dialogs take focus and return it (`tests/e2e/sheet-a11y.spec.ts`). |\n| Export menu, import dialog | `role=\"menu\"` with arrow keys and Escape; `role=\"dialog\"` with focus moved in and restored. |\n| Change review panel | Keyboard decisions (J / K, Enter, A, R), focus kept after a decision, axe-tested (`review/SvReviewPanel.dom.test.ts`). |\n| Grid board (`SvGridBoard`) | Cards and lanes move by keyboard (Space to grab, arrows, Escape) with a polite live region. Announcements are English only. |\n| Scheduler (`SvGridScheduler`) | Arrow keys move the focused event and select ranges; status messages use `role=\"status\"`. Gap: no keyboard resize of an event. |\n| Kanban (`SvBoard`), pivot designer | Gap: cards between lanes, and pivot fields between wells, move by drag only. The pivot designer adds fields by keyboard. |\n\n## Other gaps on record\n\nNot tied to a single criterion, and on the list for remediation:\n\n- Several accessible names are hard-coded English (\"Select row\", \"Select all\n rows\", \"Fill handle\", \"Resize row\", the find bar's buttons) instead of going\n through `localization.text`.\n- No browser test yet for RTL on the plain grid (the sheet has one).\n- No screen-reader pass recorded (see *Known limits*).\n\n## Revised Section 508\n\nSection 508 incorporates **WCAG 2.0 Level A and AA** by reference. Every WCAG\n2.0 criterion appears in the tables above with the same verdict.\n\n| Chapter | Conformance | Remarks |\n| --- | --- | --- |\n| 302 Functional Performance Criteria | Partially Supports | Operation without vision relies on the ARIA grid pattern (no recorded screen-reader pass); operation without fine motor control is limited by the drag-only actions under 2.1.1 and 2.5.7. |\n| 501-504 Software | See WCAG tables | The grid is web content inside a host application and exposes the platform accessibility API through ARIA. |\n| 602 Support Documentation | Supports | [Accessibility](../help/accessibility.md) documents roles, the keyboard map and how to verify a custom theme. |\n\n## EN 301 549\n\nEN 301 549 v3.2.1 incorporates **WCAG 2.1 Level A and AA** for web content\n(clause 9) and software (clause 11). Its criteria are a subset of the WCAG 2.2\ntables above and carry the same verdicts.\n\n## Reproducing these results\n\n```bash\npnpm --filter @svgrid/grid test:lib # jsdom axe, contrast, ARIA contract, announcements\nnpx playwright test tests/e2e/grid-a11y.spec.ts --project=chromium\n```\n\nBoth run in CI on every commit, so a regression in a \"Supports\" row fails the\nbuild.\n\n## See also\n\n- [Accessibility](../help/accessibility.md) - roles, keyboard map, how to verify a custom theme\n- [Compliance overview](./index.md) - the other procurement questions\n"
4434
4441
  },
4435
4442
  {
4436
4443
  "slug": "enterprise/README",
@@ -4787,7 +4794,7 @@ export const docs = [
4787
4794
  "path": "docs/enterprise/support.md",
4788
4795
  "title": "Enterprise support",
4789
4796
  "section": "Enterprise tier",
4790
- "markdown": "# Enterprise support\n\nWhat you get on each tier, what response time to expect, how to\nescalate.\n\n## SLAs\n\n| Tier | Channel | First response | Resolution target | Hours of cover |\n| --------------------- | ------------------------ | -------------- | ----------------- | ---------------- |\n| Community (free) | GitHub issues | best-effort | best-effort | community-driven |\n| Enterprise (Grid) | Email + private Slack | next business day | 5 business days | 9-5 ET, M-F |\n| Enterprise Suite | Email + private Slack | next business day | 5 business days | 9-5 ET, M-F |\n| Enterprise - Custom | Named contact + Slack | 4h business hours, **1h for sev-1** | per contract | 9-7 ET, M-F (+ on-call sev-1) |\n\n\"Sev-1\" = production outage caused by sv-grid; \"sev-2\" = major\nfeature broken; \"sev-3\" = bug; \"sev-4\" = question.\n\n## What's in scope\n\n| In scope | Out of scope |\n| ----------------------------------------- | ------------------------------------------------------ |\n| sv-grid bugs | Bugs in your application code |\n| Type-error questions in sv-grid surface | Generic TypeScript / Svelte questions |\n| Migration help (from another grid) | Full app port (we can recommend partners) |\n| Performance triage on supported browsers | Performance on EOL browsers |\n| Feature-request triage | We promise to evaluate; we don't promise to build |\n| Production-down incident triage | Re-architecture of your data layer |\n\n## How to open a ticket\n\n1. **Reproduce in a minimal repo** - StackBlitz / CodeSandbox / `pnpm\n create svelte` + the smallest grid that shows the issue. We\n support the official `@svgrid/grid` and `@svgrid/enterprise`\n packages.\n2. **Include**:\n - sv-grid version (`pnpm ls @svgrid/grid @svgrid/enterprise`)\n - Svelte version, Vite version, OS\n - Browser + version (we test on the latest 2 majors of Chrome, Firefox, Safari, Edge - see [browser support](../help/browser-support.md))\n - The exact error message + stack trace\n - A 30-second screen recording for visual issues\n3. **Send to** `support@jqwidgets.com` with subject `[sev-N] <one-line summary>`.\n\n## Escalation\n\nFor Enterprise and above, replying to the ticket with `[escalate]` in the\nsubject moves it to the on-call engineer regardless of business hours.\nUse for production outages only.\n\nEnterprise - Custom customers get a Slack Connect channel; ping `@oncall` for\nsev-1.\n\n## Security disclosures\n\nFor security issues, **do not file a public issue**. Email\n`support@jqwidgets.com` (PGP fingerprint at\n[svgrid.com/.well-known/security.txt](https://svgrid.com/.well-known/security.txt)).\nResponse within 24h; patch within 7 days for high-severity.\n\nSee [security & supply chain](../help/security.md) for the full\ndisclosure policy.\n\n## Roadmap visibility\n\n- Community: public roadmap at [svgrid.com/roadmap](https://svgrid.com/roadmap/)\n- Enterprise and Enterprise Suite: quarterly roadmap email + invite to monthly office hours\n- Enterprise - Custom: named PM, monthly roadmap call, ability to sponsor features\n\n## Documentation feedback\n\nFound a doc bug, unclear page, or missing topic? Open an issue at\n[github.com/sv-grid/sv-grid/issues](https://github.com/sv-grid/sv-grid/issues)\nwith the `docs` label, or hit the \"Edit on GitHub\" link on any page.\n\n## See also\n\n- [Enterprise licensing](./licensing.md)\n- [Enterprise evaluation](./evaluation.md)\n- [Security & supply chain](../help/security.md)\n- [API stability](../help/api-stability.md) - the deprecation policy that drives support windows\n"
4797
+ "markdown": "# Enterprise support\n\nWhat you get on each tier, what response time to expect, how to\nescalate.\n\n## SLAs\n\n| Tier | Channel | First response | Resolution target | Hours of cover |\n| --------------------- | ------------------------ | -------------- | ----------------- | ---------------- |\n| Community (free) | GitHub issues | best-effort | best-effort | community-driven |\n| Enterprise (Grid) | Email + private Slack | next business day | 5 business days | 9-5 ET, M-F |\n| Enterprise Suite | Email + private Slack | next business day | 5 business days | 9-5 ET, M-F |\n| Enterprise - Custom | Named contact + Slack | 4h business hours, **1h for sev-1** | per contract | 9-7 ET, M-F (+ on-call sev-1) |\n\n\"Sev-1\" = production outage caused by sv-grid; \"sev-2\" = major\nfeature broken; \"sev-3\" = bug; \"sev-4\" = question.\n\n## What's in scope\n\n| In scope | Out of scope |\n| ----------------------------------------- | ------------------------------------------------------ |\n| sv-grid bugs | Bugs in your application code |\n| Type-error questions in sv-grid surface | Generic TypeScript / Svelte questions |\n| Migration help (from another grid) | Full app port (we can recommend partners) |\n| Performance triage on supported browsers | Performance on EOL browsers |\n| Feature-request triage | We promise to evaluate; we don't promise to build |\n| Production-down incident triage | Re-architecture of your data layer |\n\n## How to open a ticket\n\n1. **Reproduce in a minimal repo** - StackBlitz / CodeSandbox / `pnpm\n create svelte` + the smallest grid that shows the issue. We\n support the official `@svgrid/grid` and `@svgrid/enterprise`\n packages.\n2. **Include**:\n - sv-grid version (`pnpm ls @svgrid/grid @svgrid/enterprise`)\n - Svelte version, Vite version, OS\n - Browser + version (we test on the latest 2 majors of Chrome, Firefox, Safari, Edge - see [browser support](../help/browser-support.md))\n - The exact error message + stack trace\n - A 30-second screen recording for visual issues\n3. **Send to** `support@jqwidgets.com` with subject `[sev-N] <one-line summary>`.\n\n## Escalation\n\nFor Enterprise and above, replying to the ticket with `[escalate]` in the\nsubject moves it to the on-call engineer regardless of business hours.\nUse for production outages only.\n\nEnterprise - Custom customers get a Slack Connect channel; ping `@oncall` for\nsev-1.\n\n## Security disclosures\n\nFor security issues, **do not file a public issue**. Report privately, through\nGitHub's private vulnerability reporting or by email, as\n[SECURITY.md](https://github.com/sv-grid/sv-grid/blob/main/SECURITY.md)\ndescribes; [svgrid.com/.well-known/security.txt](https://svgrid.com/.well-known/security.txt)\npoints to the same place. Enterprise customers get an acknowledgement within one\nbusiness day, and an advisory and patch within five business days for High and\nCritical issues.\n\nSee [security & supply chain](../help/security.md) for the full\ndisclosure policy.\n\n## Roadmap visibility\n\n- Community: public roadmap at [svgrid.com/roadmap](https://svgrid.com/roadmap/)\n- Enterprise and Enterprise Suite: quarterly roadmap email + invite to monthly office hours\n- Enterprise - Custom: named PM, monthly roadmap call, ability to sponsor features\n\n## Documentation feedback\n\nFound a doc bug, unclear page, or missing topic? Open an issue at\n[github.com/sv-grid/sv-grid/issues](https://github.com/sv-grid/sv-grid/issues)\nwith the `docs` label, or hit the \"Edit on GitHub\" link on any page.\n\n## See also\n\n- [Enterprise licensing](./licensing.md)\n- [Enterprise evaluation](./evaluation.md)\n- [Security & supply chain](../help/security.md)\n- [API stability](../help/api-stability.md) - the deprecation policy that drives support windows\n"
4791
4798
  },
4792
4799
  {
4793
4800
  "slug": "getting-started-full",
@@ -4871,7 +4878,7 @@ export const docs = [
4871
4878
  "path": "docs/help/accessibility.md",
4872
4879
  "title": "Accessibility",
4873
4880
  "section": "Help",
4874
- "markdown": "# Accessibility\n\nSvGrid implements the WAI-ARIA 1.2 grid pattern with full keyboard\nnavigation and a screen-reader announcement layer. This page documents\nexactly what the grid does, where the responsibility line sits between\nthe library and your code, and how to verify conformance.\n\n![An ARIA grid whose rows carry aria-rowindex and cells carry aria-colindex, a roving tabindex marking the active cell that arrow keys move, and an aria-live region announcing the new cell to a screen reader.](/docs-media/grid-a11y.svg)\n\nLive demo - high-contrast toggle, `aria-live` log, and a focus-trap\nwalk-through:\n\n<div data-docs-demo=\"17-accessibility\" data-height=\"520\"></div>\n\n## TL;DR\n\n| Standard | Status |\n| ----------------------- | ---------------------------------------------------------------------- |\n| WAI-ARIA 1.2 grid pattern | Implemented (see [Roles & properties](#roles--properties)). |\n| WCAG 2.1 AA | Structure is audited by `axe-core` in CI. Contrast is enforced in CI for **all 20 built-in presets, light and dark**; a custom theme is yours to verify. |\n| Keyboard navigation | Full coverage; see [Keyboard map](#keyboard-map). |\n| Screen-reader announcements | Filter results and bulk selection changes, via a single `aria-live=polite` region. See [What the grid announces](#what-the-grid-announces). |\n| Reduced motion | Honored: scroll animations + chevron transitions disable when `prefers-reduced-motion: reduce`. |\n| Forced colors / high contrast | Supported: borders + focus rings use `currentColor`; no hardcoded `border-color`. |\n\n## Roles & properties\n\n| Element | Role | Notable attributes |\n| ------------------------------ | -------------- | --------------------------------------------------------------------------------------------------- |\n| `<table>` root | `grid` | `aria-rowcount`, `aria-colcount` |\n| `<thead>`, `<tbody>` | `rowgroup` | |\n| Every `<tr>` (header + body) | `row` | `aria-rowindex` (1-based); selected rows get `aria-selected=\"true\"` |\n| Header `<th>` | `columnheader` | `aria-sort` (`\"ascending\"` / `\"descending\"` / `\"none\"`) |\n| Body `<td>` | `gridcell` | `aria-colindex`, `aria-selected`, `aria-readonly` (when the column is non-editable) |\n| Active cell | `gridcell` | `tabindex=\"0\"`; every other cell `tabindex=\"-1\"` (roving tabindex pattern) |\n| Filter popover | `dialog` | `aria-label` derived from the column header |\n| Cell editor input | `textbox` / `combobox` / `checkbox` (depending on `editorType`) | `aria-label` mirrors the column header |\n| Live announcement region | none (uses `aria-live=\"polite\"` on a visually-hidden `<div>`) | |\n\nThe grid never sets `role=\"presentation\"` on table elements - screen\nreaders receive a fully-structured grid.\n\n## Keyboard map\n\nStandard ARIA grid navigation, plus a handful of grid-specific\nshortcuts:\n\n### Navigation\n\n| Key | Action |\n| ------------------- | --------------------------------------------------------------------- |\n| Tab | Move focus *out* of the grid to the next focusable element. |\n| Shift+Tab | Move focus *into* the grid from the previous focusable element. |\n| Arrow Up/Down | Move active cell one row. |\n| Arrow Left/Right | Move active cell one column. |\n| Home | Active cell → first column in the row. |\n| End | Active cell → last column in the row. |\n| Ctrl/Cmd + Home | Active cell → top-left of the grid. |\n| Ctrl/Cmd + End | Active cell → bottom-right. |\n| Ctrl/Cmd + Arrow | Reserved. The grid does not move the active cell; `enableSheet()` in `@svgrid/enterprise` binds it to Excel's jump-to-edge-of-data-region. See [Excel keyboard shortcuts](./cells/keyboard-shortcuts.md). |\n| Page Up / Page Down | Scroll a viewport's worth of rows. |\n\n### Selection (when `rowSelectionFeature` is on)\n\n| Key | Action |\n| ------------------------- | --------------------------------------------------------------- |\n| Space | Toggle the active row's selection. |\n| Ctrl/Cmd + A | Not bound by the grid; the browser's select-all applies. The header checkbox selects every row, and `api.selectCells` selects ranges. |\n| Shift + Arrow Up/Down | Extend the row selection. |\n| Ctrl/Cmd + Click on a row | Toggle that row's selection without affecting others. |\n\n### Sort + filter\n\n| Key | Action |\n| -------------------------------- | -------------------------------------------------------- |\n| Enter (on a header) | Toggle sort: `none → asc → desc → none`. |\n| Shift + Enter (on a header) | Add to multi-sort. |\n| Alt + Down (on a header) | Open the filter menu (when `filterMode='menu'`). |\n| Escape (in a filter menu) | Close the menu. |\n\n### Editing\n\n| Key | Action |\n| --------------------------- | ----------------------------------------------------- |\n| Enter / F2 / double-click | Enter edit mode on the active cell. |\n| Type any character | Start editing with that character as the first input. |\n| Enter / Tab (while editing) | Commit and move to the next cell / row. |\n| Escape (while editing) | Cancel; revert the cell. |\n| Delete / Backspace | Clear the active cell (for cells whose editor supports clearing). |\n\n### Tree rows (when you build them)\n\nThe keyboard handler in [Tree rows](./rows/tree-rows.md) adds:\n\n| Key | Action (active cell in name column) |\n| ------------------- | ----------------------------------- |\n| Arrow Right | Expand a collapsed node. |\n| Arrow Left | Collapse an expanded node. |\n| Enter / Space | Toggle. |\n\nOn a grouped grid, a tree (`getSubRows`) or a\n[server-side row model](./server/server-grouping.md#keyboard-and-accessibility)\nthe grid handles these itself, and **Ctrl+Enter** on any cell of a group\nrow toggles it; on the server model a leaf with a detail panel\n(`renderDetailRow`) opens or closes it with the same key.\n\n## Screen-reader announcements\n\nThe grid shares one visually-hidden `aria-live=\"polite\"` region with the rest of\nthe component library, and is deliberately sparing about what it puts there.\n\n### What the grid announces\n\n| Event | What is said |\n| --- | --- |\n| A filter changes the matching rows | `\"12 of 250 rows match the current filters\"`, or `\"No rows match the current filters\"` |\n| Every filter is cleared | `\"Filters cleared, showing all 250 rows\"` |\n| A bulk selection change | `\"250 rows selected\"` / `\"Selection cleared\"` |\n\nFilter announcements are debounced by 400 ms, so typing in the search box\nannounces the count you stopped on rather than one for every prefix. They are\nalso skipped entirely under `externalFilter`, because there the server decides\nwhat matched and the local count would describe only the page in hand.\n\n### What it deliberately does not announce\n\nThis is the more important half. A live region is not the only way a screen\nreader learns something, and announcing what the accessibility tree already\ncarries makes the grid talk over itself:\n\n- **The cell you moved to.** Focus moves there (roving tabindex), so the reader\n announces the cell, its column header and its row position natively.\n- **Sort state.** Carried by `aria-sort` on the column header, read when focus\n lands on it.\n- **Whether the row you are on is selected.** Carried by `aria-selected`.\n- **Selecting or deselecting a single row.** The focused row is announced with\n its new selected state; adding `\"1 row selected\"` on top would be a second,\n redundant utterance. Only changes of more than one row, which cannot have come\n from a single focus move, are announced.\n\n### Translating them\n\nAnnouncements are full sentences, so unlike the single-word labels elsewhere in\n`localeText` they take `{placeholders}` and you control the word order:\n\nThe examples on this page run against these rows:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns, type SvGridApi } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n department: string\n city: string\n age: number\n salary: number\n }\n\n const people: Person[] = [\n { id: 1, name: 'Ada Lovelace', department: 'Engineering', city: 'London', age: 36, salary: 142000 },\n { id: 2, name: 'Grace Hopper', department: 'Engineering', city: 'New York', age: 45, salary: 168000 },\n { id: 3, name: 'Linus Torvalds', department: 'Platform', city: 'Portland', age: 54, salary: 155000 },\n { id: 4, name: 'Radia Perlman', department: 'Networking', city: 'Seattle', age: 49, salary: 161000 },\n { id: 5, name: 'Barbara Liskov', department: 'Platform', city: 'Boston', age: 52, salary: 172000 },\n ]\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 190 },\n { field: 'department', header: 'Department', width: 150 },\n { field: 'city', header: 'City', width: 130 },\n { field: 'age', header: 'Age', width: 80 },\n { field: 'salary', header: 'Salary', width: 130, format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```svelte\n<SvGrid\n localization={{\n text: {\n announceFilterResults: '{visible} van de {total} rijen komen overeen',\n announceNoMatches: 'Geen rijen komen overeen',\n announceFiltersCleared: 'Filters gewist, alle {total} rijen worden getoond',\n announceRowsSelected: '{count} rijen geselecteerd',\n announceSelectionCleared: 'Selectie gewist',\n },\n }}\n/>\n```\n\nAn unknown placeholder is left in the output rather than blanked, so a typo in\nan override is visible instead of silently eating the number.\n\n## Focus management\n\n- The grid uses a **roving tabindex**: at most one cell at a time has\n `tabindex=\"0\"`, every other has `tabindex=\"-1\"`. This puts the grid\n in the tab order exactly once.\n- The \"active cell\" is the focused cell. It's tracked through every\n navigation, editing, and selection action.\n- Editing transfers focus to the editor `<input>`; committing returns\n focus to the cell.\n- Modals (filter menu, save dialog) use a focus trap that returns\n focus to the originating header/cell on close.\n\n## High-contrast / forced-colors mode\n\nWindows High Contrast mode (`forced-colors: active`) is respected. The\ngrid uses `currentColor` for every border and focus ring, so the\nsystem's color tokens take over without overrides leaking. We test\nagainst the [W3C forced-colors test page](https://web.dev/articles/forced-colors).\n\n## Right to left\n\nSet `dir=\"rtl\"` on the page or any element above the grid and the layout\nmirrors: the row-number gutter and every pinned column stick to the right\nedge and stay there while the cells scroll under them, because the pins\nare logical (`inset-inline-start`, `inset-inline-end`) rather than a\nphysical `left`. Nothing to opt into and no second stylesheet.\n\n## Reduced motion\n\nWhen `prefers-reduced-motion: reduce` matches:\n\n- Smooth-scroll calls become `behavior: 'instant'`.\n- Chevron rotations (used in tree demos) are instant rather than 160 ms\n ease.\n- Sparkline + KPI bar transitions are disabled.\n\nYou don't need to opt in - the grid checks the media query on every\nanimation entry point.\n\n## What you're responsible for\n\nThe grid can't know:\n\n- **Contrast** of your custom CSS variables. Use the [Tailwind\n integration](./tailwind.md) page's contrast notes when picking\n `--sg-fg` / `--sg-bg` pairs.\n- **Labels** for cells whose content is purely visual (e.g. a status\n pill that's just a coloured dot). Set `aria-label` on the cell\n content yourself.\n- **Reading order** of header groups. The grid emits group headers\n with `aria-colspan` correctly, but if your group label is \"Q1\"\n alone, screen readers say \"Q1\" - consider \"Q1 2025\" to give context.\n- **The wording of validation messages.** A cell failing a column's\n `validate` hook is marked `aria-invalid` and the returned string is\n carried to assistive technology, so return a message that says how to\n fix it (\"Score must be at least 90\"), not just that something is\n wrong (\"Invalid\"). Returning `false` marks the cell invalid with no\n message at all, which leaves a screen-reader user without a reason.\n\n## How to verify\n\n1. **Keyboard sweep.** Unplug your mouse. Tab in, navigate every cell,\n sort, filter, edit, undo. If any action is unreachable, file an issue.\n2. **NVDA + VoiceOver.** Each makes different choices about announcement\n verbosity. Test both.\n3. **Lighthouse accessibility audit.** Run it against your own build. Most\n deltas are contrast issues in your theme rather than grid markup, so\n check those first.\n\n > We run `axe-core` against a rendered grid in CI (`a11y.axe.test.ts`),\n > covering the plain grid, the filter row, row selection and pagination.\n > That suite runs in jsdom, which does no layout, so axe's own\n > colour-contrast rule is disabled there.\n >\n > Contrast is covered separately and more thoroughly: `themes/contrast.test.ts`\n > computes WCAG ratios for **every built-in preset in both light and dark**\n > and fails the build below AA. Body text, secondary text, header text, text\n > on zebra / hovered / selected rows, and text on accent-filled controls all\n > have to clear 4.5:1, and the accent has to clear 3:1 where it signals focus\n > or selection. So the presets are checked exhaustively rather than whichever\n > one a browser test happened to load. What is still yours to verify is a\n > **custom** theme.\n4. **axe-core in your e2e suite.**\n ```ts\n import { injectAxe, checkA11y } from 'axe-playwright'\n await injectAxe(page)\n await checkA11y(page, '.sv-grid-shell', { detailedReport: false })\n ```\n\n## Frequently asked questions\n\n### Is SvGrid accessible / WCAG compliant?\n\nSvGrid implements the WAI-ARIA 1.2 grid pattern: `role=\"grid\"` structure, full\nkeyboard navigation (arrows, Home/End, Page Up/Down, Ctrl+Home/End), a focus\nring on the active cell, and an `aria-live` announcement layer. Final WCAG\nconformance also depends on your own cell content and color choices - this page\ndocuments exactly where that line sits.\n\n### Does SvGrid work with screen readers?\n\nYes. The grid exposes proper roles and emits `aria-live` announcements for\nsorting, filtering, and selection changes, so NVDA, JAWS, and VoiceOver can\nread the grid state. Because it renders real DOM (not canvas), the content is\nalso selectable and machine-readable.\n\n### How do I verify accessibility in my app?\n\nRun axe-core against the rendered grid (recipe in the testing guide) and test\nkeyboard-only navigation. Pair it with the high-contrast focus toggle and the\n`--sg-*` contrast tokens to meet your target contrast ratios.\n\n## More examples\n\n### Keyboard shortcuts + a11y\n\nCtrl+K command palette, Ctrl+/ cheat sheet, vim-style gg / G chord nav. Layers on top of the grid's WAI-ARIA grid pattern + roving tabindex.\n\n<div data-docs-demo=\"65-keyboard-shortcuts\" data-height=\"460\"></div>\n\n### High-contrast theme\n\nWCAG 2.2 AAA-grade preset for accessibility procurement. Token block opts a subtree into the high-contrast skin while the rest of the page stays standard. Light + dark.\n\n<div data-docs-demo=\"96-high-contrast-theme\" data-height=\"460\"></div>\n\n## Try the keyboard\n\nEverything below is keyboard-reachable. Tab once to enter the grid, then arrow\nbetween cells - the grid is a single tab stop, not one per cell, which is what\nmakes a 10,000-row table usable without a mouse.\n\n```svelte {runnable}\n<SvGrid data={people} {columns} sortable filterable enableCellSelection editable />\n```\n\nTry: Tab in, arrows to move, Enter to edit, Escape to cancel, Shift+arrows to\nextend a range, Ctrl/Cmd+C to copy it.\n\n## What a screen reader is told\n\nThe grid root carries `role=\"grid\"` with `aria-rowcount` and `aria-colcount`,\nheaders carry `aria-sort`, and rows and cells carry their index. Sort a column\nin the example above and inspect the header: the `aria-sort` attribute flips\nwith it, which is how a screen reader user knows the order changed at all.\n\n```svelte {runnable}\n<script lang=\"ts\">\n let report = $state('(sort a column)')\n\n function inspect() {\n const grid = document.querySelector('[role=\"grid\"], [role=\"treegrid\"]')\n const sorted = document.querySelectorAll('[role=\"columnheader\"][aria-sort]')\n report =\n 'role=' + (grid?.getAttribute('role') ?? 'missing') +\n ' | aria-rowcount=' + (grid?.getAttribute('aria-rowcount') ?? 'missing') +\n ' | headers with aria-sort: ' + sorted.length\n }\n</script>\n\n<SvGrid data={people} {columns} sortable />\n\n<button type=\"button\" onclick={inspect}>Inspect the ARIA</button>\n<p><code>{report}</code></p>\n```\n\n## See also\n\n- [Browser support](./browser-support.md) - the `ResizeObserver` /\n Pointer Events floor every assistive-tech tool relies on.\n- [Tailwind integration](./tailwind.md) - the `--sg-*` tokens that\n control contrast.\n- [Testing your grid](./testing.md) - includes an axe-core recipe.\n"
4881
+ "markdown": "# Accessibility\n\nSvGrid implements the WAI-ARIA 1.2 grid pattern with full keyboard\nnavigation and a screen-reader announcement layer. This page documents\nexactly what the grid does, where the responsibility line sits between\nthe library and your code, and how to verify conformance.\n\n![An ARIA grid whose rows carry aria-rowindex and cells carry aria-colindex, with the active cell that arrow keys move named by aria-activedescendant, and an aria-live region for status messages.](/docs-media/grid-a11y.svg)\n\nLive demo - high-contrast toggle, `aria-live` log, and a focus-trap\nwalk-through:\n\n<div data-docs-demo=\"17-accessibility\" data-height=\"520\"></div>\n\n## TL;DR\n\n| Standard | Status |\n| ----------------------- | ---------------------------------------------------------------------- |\n| WAI-ARIA 1.2 grid pattern | Implemented (see [Roles & properties](#roles--properties)). |\n| WCAG 2.2 AA | Self-assessed, criterion by criterion, in the [Accessibility Conformance Report](../compliance/vpat.md), gaps included. Structure is audited by `axe-core` in CI, in jsdom and in a real browser. Contrast is enforced in CI for **all 20 built-in presets, light and dark**; a custom theme is yours to verify. |\n| Keyboard navigation | Navigation, selection, sorting, filtering and editing; see [Keyboard map](#keyboard-map). Row dragging and moving columns by drag have no keyboard path yet; the ACR lists them. |\n| Screen-reader announcements | Filter results and bulk selection changes, via a single `aria-live=polite` region. See [What the grid announces](#what-the-grid-announces). |\n| Reduced motion | The cell flash and the loading shimmer stop under `prefers-reduced-motion: reduce`. |\n| Forced colors / high contrast | The active cell switches to a system `Highlight` outline (a box-shadow ring would vanish). Tested in a browser with forced colors emulated. |\n\n## Roles & properties\n\n| Element | Role | Notable attributes |\n| ------------------------------ | -------------- | --------------------------------------------------------------------------------------------------- |\n| `<table>` root | `grid` (`treegrid` with `treeData` or server grouping) | `tabindex=\"0\"`, `aria-activedescendant` pointing at the active cell, `aria-rowcount`, `aria-colcount` |\n| `<thead>`, `<tbody>`, `<tfoot>` | `rowgroup` | |\n| Body `<tr>` | `row` | `aria-rowindex` (1-based, absolute, so it holds under virtualization); `aria-level` / `aria-expanded` on tree and group rows |\n| Header `<th>` | `columnheader` | `aria-sort` (`\"ascending\"` / `\"descending\"` / `\"none\"`) on sortable columns |\n| Body `<td>` | `gridcell` | `id`, `aria-colindex`, `aria-rowindex`, `aria-selected` (row selection); `aria-invalid` plus the message when `validate` rejects the value |\n| Selection checkboxes | `checkbox` | `aria-checked`, `\"mixed\"` on the header when some rows are selected |\n| Filter popover | `menu` | |\n| Cell editor input | `textbox` (text, number and multi-line editors) | `aria-label` is the column header |\n| Live announcement region | `status` (`aria-live=\"polite\"` on a visually-hidden `<div>`) | |\n\nHeader rows carry no `aria-rowindex` yet, and a cell range selection (as\nopposed to row selection) is not exposed through `aria-selected`. Both are\nlisted in the [ACR](../compliance/vpat.md).\n\nThe grid never sets `role=\"presentation\"` on table elements - screen\nreaders receive a fully-structured grid.\n\n## Keyboard map\n\nStandard ARIA grid navigation, plus a handful of grid-specific\nshortcuts:\n\n### Navigation\n\n| Key | Action |\n| ------------------- | --------------------------------------------------------------------- |\n| Tab / Shift+Tab | Move the active cell right / left, wrapping at row ends. On the last cell (first, for Shift+Tab) focus leaves the grid for the next (previous) element on the page. Ctrl+End then Tab, or Ctrl+Home then Shift+Tab, leaves from anywhere. |\n| Arrow Up/Down | Move active cell one row. |\n| Arrow Left/Right | Move active cell one column. |\n| Home | Active cell → first column in the row. |\n| End | Active cell → last column in the row. |\n| Ctrl/Cmd + Home | Active cell → top-left of the grid. |\n| Ctrl/Cmd + End | Active cell → bottom-right. |\n| Ctrl/Cmd + Arrow | Reserved. The grid does not move the active cell; `enableSheet()` in `@svgrid/enterprise` binds it to Excel's jump-to-edge-of-data-region. See [Excel keyboard shortcuts](./cells/keyboard-shortcuts.md). |\n| Page Up / Page Down | Scroll a viewport's worth of rows. |\n\n### Selection (when `rowSelectionFeature` is on)\n\n| Key | Action |\n| ------------------------- | --------------------------------------------------------------- |\n| Space | Toggle the active row's selection. |\n| Ctrl/Cmd + A | Not bound by the grid; the browser's select-all applies. The header checkbox selects every row, and `api.selectCells` selects ranges. |\n| Shift + Arrow keys | Extend the cell range from the active cell. |\n| Ctrl/Cmd + Click on a cell | Add a cell range to the selection. |\n\n### Sort + filter\n\n| Key | Action |\n| -------------------------------- | -------------------------------------------------------- |\n| Enter / Space (on a header's sort button) | Toggle sort: `none → asc → desc → none`. |\n| Enter / Space (on a header's filter button) | Open the filter menu. |\n| Escape (in a filter menu) | Close the menu. |\n\nHeader buttons are reached with the mouse or, from outside the grid, with\nTab; they are not part of the cell navigation.\n\n### Editing\n\n| Key | Action |\n| --------------------------- | ----------------------------------------------------- |\n| F2 / double-click | Enter edit mode on the active cell. (Enter moves down, as in a spreadsheet.) |\n| Type any character | Start editing with that character as the first input. |\n| Enter / Tab (while editing) | Commit and move to the next cell / row. |\n| Escape (while editing) | Cancel; revert the cell. |\n| Delete / Backspace | Clear the active cell (for cells whose editor supports clearing). |\n\n### Tree rows (when you build them)\n\nThe keyboard handler in [Tree rows](./rows/tree-rows.md) adds:\n\n| Key | Action (active cell in name column) |\n| ------------------- | ----------------------------------- |\n| Arrow Right | Expand a collapsed node. |\n| Arrow Left | Collapse an expanded node. |\n| Enter / Space | Toggle. |\n\nOn a grouped grid, a tree (`getSubRows`) or a\n[server-side row model](./server/server-grouping.md#keyboard-and-accessibility)\nthe grid handles these itself, and **Ctrl+Enter** on any cell of a group\nrow toggles it; on the server model a leaf with a detail panel\n(`renderDetailRow`) opens or closes it with the same key.\n\n## Screen-reader announcements\n\nThe grid shares one visually-hidden `aria-live=\"polite\"` region with the rest of\nthe component library, and is deliberately sparing about what it puts there.\n\n### What the grid announces\n\n| Event | What is said |\n| --- | --- |\n| A filter changes the matching rows | `\"12 of 250 rows match the current filters\"`, or `\"No rows match the current filters\"` |\n| Every filter is cleared | `\"Filters cleared, showing all 250 rows\"` |\n| A bulk selection change | `\"250 rows selected\"` / `\"Selection cleared\"` |\n\nFilter announcements are debounced by 400 ms, so typing in the search box\nannounces the count you stopped on rather than one for every prefix. They are\nalso skipped entirely under `externalFilter`, because there the server decides\nwhat matched and the local count would describe only the page in hand.\n\n### What it deliberately does not announce\n\nThis is the more important half. A live region is not the only way a screen\nreader learns something, and announcing what the accessibility tree already\ncarries makes the grid talk over itself:\n\n- **The cell you moved to.** `aria-activedescendant` on the grid points at it,\n so the reader announces the cell, its column header and its row position\n natively.\n- **Sort state.** Carried by `aria-sort` on the column header, read when focus\n lands on it.\n- **Whether the row you are on is selected.** Carried by `aria-selected`.\n- **Selecting or deselecting a single row.** The focused row is announced with\n its new selected state; adding `\"1 row selected\"` on top would be a second,\n redundant utterance. Only changes of more than one row, which cannot have come\n from a single focus move, are announced.\n\n### Translating them\n\nAnnouncements are full sentences, so unlike the single-word labels elsewhere in\n`localeText` they take `{placeholders}` and you control the word order:\n\nThe examples on this page run against these rows:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns, type SvGridApi } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n department: string\n city: string\n age: number\n salary: number\n }\n\n const people: Person[] = [\n { id: 1, name: 'Ada Lovelace', department: 'Engineering', city: 'London', age: 36, salary: 142000 },\n { id: 2, name: 'Grace Hopper', department: 'Engineering', city: 'New York', age: 45, salary: 168000 },\n { id: 3, name: 'Linus Torvalds', department: 'Platform', city: 'Portland', age: 54, salary: 155000 },\n { id: 4, name: 'Radia Perlman', department: 'Networking', city: 'Seattle', age: 49, salary: 161000 },\n { id: 5, name: 'Barbara Liskov', department: 'Platform', city: 'Boston', age: 52, salary: 172000 },\n ]\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 190 },\n { field: 'department', header: 'Department', width: 150 },\n { field: 'city', header: 'City', width: 130 },\n { field: 'age', header: 'Age', width: 80 },\n { field: 'salary', header: 'Salary', width: 130, format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```svelte\n<SvGrid\n localization={{\n text: {\n announceFilterResults: '{visible} van de {total} rijen komen overeen',\n announceNoMatches: 'Geen rijen komen overeen',\n announceFiltersCleared: 'Filters gewist, alle {total} rijen worden getoond',\n announceRowsSelected: '{count} rijen geselecteerd',\n announceSelectionCleared: 'Selectie gewist',\n },\n }}\n/>\n```\n\nAn unknown placeholder is left in the output rather than blanked, so a typo in\nan override is visible instead of silently eating the number.\n\n## Focus management\n\n- The `<table>` is the grid's single tab stop. Focus stays on it, and\n `aria-activedescendant` names the active cell; cells themselves carry no\n `tabindex`.\n- The active cell is drawn with an accent ring. It is hidden while the grid\n sits untouched at its seeded first cell, and shown as soon as a click, a\n key or the api activates a cell, or the keyboard brings focus to the grid.\n- Tab moves between cells and leaves the grid at either end (see the\n [keyboard map](#navigation)).\n- Editing transfers focus to the editor `<input>`, which is named after the\n column; committing returns focus to the grid.\n- The filter popover moves focus to its first control when it opens. Grid\n menus do not yet return focus to the button that opened them on close;\n the [ACR](../compliance/vpat.md) lists it under 2.4.3.\n\n## High-contrast / forced-colors mode\n\nUnder Windows High Contrast (`forced-colors: active`) the active cell gets a\n2 px outline in the system `Highlight` colour, because forced colors removes\nthe box-shadow ring the grid draws otherwise. `tests/e2e/grid-a11y.spec.ts`\nchecks it with forced colors emulated in Chromium.\n\n## Right to left\n\nSet `dir=\"rtl\"` on the page or any element above the grid and the layout\nmirrors: the row-number gutter and every pinned column stick to the right\nedge and stay there while the cells scroll under them, because the pins\nare logical (`inset-inline-start`, `inset-inline-end`) rather than a\nphysical `left`. Nothing to opt into and no second stylesheet.\n\n## Reduced motion\n\nWhen `prefers-reduced-motion: reduce` matches:\n\n- The cell flash (`cellFlash`) does not animate.\n- The loading-row shimmer stops.\n\nKeyboard scrolling is always instant, so there is no smooth scroll to turn\noff. Chevron rotations still use a short transition. You don't need to opt\nin; both rules are plain CSS media queries.\n\n## What you're responsible for\n\nThe grid can't know:\n\n- **Contrast** of your custom CSS variables. Use the [Tailwind\n integration](./tailwind.md) page's contrast notes when picking\n `--sg-fg` / `--sg-bg` pairs.\n- **Labels** for cells whose content is purely visual (e.g. a status\n pill that's just a coloured dot). Set `aria-label` on the cell\n content yourself.\n- **Reading order** of header groups. The grid emits group headers\n with `aria-colspan` correctly, but if your group label is \"Q1\"\n alone, screen readers say \"Q1\" - consider \"Q1 2025\" to give context.\n- **The wording of validation messages.** A cell failing a column's\n `validate` hook is marked `aria-invalid` and the returned string is\n carried to assistive technology, so return a message that says how to\n fix it (\"Score must be at least 90\"), not just that something is\n wrong (\"Invalid\"). Returning `false` marks the cell invalid with no\n message at all, which leaves a screen-reader user without a reason.\n\n## How to verify\n\n1. **Keyboard sweep.** Unplug your mouse. Tab in, navigate every cell,\n sort, filter, edit, undo. If any action is unreachable, file an issue.\n2. **NVDA + VoiceOver.** Each makes different choices about announcement\n verbosity. Test both.\n3. **Lighthouse accessibility audit.** Run it against your own build. Most\n deltas are contrast issues in your theme rather than grid markup, so\n check those first.\n\n > We run `axe-core` against a rendered grid in CI (`a11y.axe.test.ts`),\n > covering the plain grid, the filter row, row selection and pagination.\n > That suite runs in jsdom, which does no layout, so axe's own\n > colour-contrast rule is disabled there.\n >\n > Contrast is covered separately and more thoroughly: `themes/contrast.test.ts`\n > computes WCAG ratios for **every built-in preset in both light and dark**\n > and fails the build below AA. Body text, secondary text, header text, text\n > on zebra / hovered / selected rows, and text on accent-filled controls all\n > have to clear 4.5:1, and the accent has to clear 3:1 where it signals focus\n > or selection. So the presets are checked exhaustively rather than whichever\n > one a browser test happened to load. What is still yours to verify is a\n > **custom** theme.\n4. **axe-core in your e2e suite.**\n ```ts\n import AxeBuilder from '@axe-core/playwright'\n const results = await new AxeBuilder({ page })\n .include('.sv-grid-container')\n .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])\n .analyze()\n expect(results.violations).toEqual([])\n ```\n\n## Frequently asked questions\n\n### Is SvGrid accessible / WCAG compliant?\n\nSvGrid implements the WAI-ARIA 1.2 grid pattern: `role=\"grid\"` structure, full\nkeyboard navigation (arrows, Home/End, Page Up/Down, Ctrl+Home/End), a focus\nring on the active cell, and an `aria-live` announcement layer. Final WCAG\nconformance also depends on your own cell content and color choices - this page\ndocuments exactly where that line sits.\n\n### Does SvGrid work with screen readers?\n\nThe grid exposes the ARIA grid roles and states, and emits `aria-live`\nannouncements for filtering and bulk selection changes. Sort state is read\nfrom `aria-sort` on the header rather than announced. No scripted NVDA, JAWS\nor VoiceOver pass has been recorded yet; the\n[ACR](../compliance/vpat.md) says so where it matters. Because it renders real DOM (not canvas), the content is\nalso selectable and machine-readable.\n\n### How do I verify accessibility in my app?\n\nRun axe-core against the rendered grid (recipe in the testing guide) and test\nkeyboard-only navigation. Pair it with the high-contrast focus toggle and the\n`--sg-*` contrast tokens to meet your target contrast ratios.\n\n## More examples\n\n### Keyboard shortcuts + a11y\n\nCtrl+K command palette, Ctrl+/ cheat sheet, vim-style gg / G chord nav. Layers on top of the grid's WAI-ARIA grid pattern.\n\n<div data-docs-demo=\"65-keyboard-shortcuts\" data-height=\"460\"></div>\n\n### High-contrast theme\n\nWCAG 2.2 AAA-grade preset for accessibility procurement. Token block opts a subtree into the high-contrast skin while the rest of the page stays standard. Light + dark.\n\n<div data-docs-demo=\"96-high-contrast-theme\" data-height=\"460\"></div>\n\n## Try the keyboard\n\nEverything below is keyboard-reachable. Tab once to enter the grid, then arrow\nbetween cells - the grid is a single tab stop, not one per cell, which is what\nmakes a 10,000-row table usable without a mouse.\n\n```svelte {runnable}\n<SvGrid data={people} {columns} sortable filterable enableCellSelection editable />\n```\n\nTry: Tab in, arrows to move, Enter to edit, Escape to cancel, Shift+arrows to\nextend a range, Ctrl/Cmd+C to copy it.\n\n## What a screen reader is told\n\nThe grid root carries `role=\"grid\"` with `aria-rowcount` and `aria-colcount`,\nheaders carry `aria-sort`, and rows and cells carry their index. Sort a column\nin the example above and inspect the header: the `aria-sort` attribute flips\nwith it, which is how a screen reader user knows the order changed at all.\n\n```svelte {runnable}\n<script lang=\"ts\">\n let report = $state('(sort a column)')\n\n function inspect() {\n const grid = document.querySelector('[role=\"grid\"], [role=\"treegrid\"]')\n const sorted = document.querySelectorAll('[role=\"columnheader\"][aria-sort]')\n report =\n 'role=' + (grid?.getAttribute('role') ?? 'missing') +\n ' | aria-rowcount=' + (grid?.getAttribute('aria-rowcount') ?? 'missing') +\n ' | headers with aria-sort: ' + sorted.length\n }\n</script>\n\n<SvGrid data={people} {columns} sortable />\n\n<button type=\"button\" onclick={inspect}>Inspect the ARIA</button>\n<p><code>{report}</code></p>\n```\n\n## See also\n\n- [Browser support](./browser-support.md) - the `ResizeObserver` /\n Pointer Events floor every assistive-tech tool relies on.\n- [Tailwind integration](./tailwind.md) - the `--sg-*` tokens that\n control contrast.\n- [Testing your grid](./testing.md) - includes an axe-core recipe.\n"
4875
4882
  },
4876
4883
  {
4877
4884
  "slug": "help/agents",
@@ -5130,7 +5137,7 @@ export const docs = [
5130
5137
  "path": "docs/help/cells/paste-find-structure.md",
5131
5138
  "title": "Paste Special, Find and Replace, and structural edits",
5132
5139
  "section": "Cells",
5133
- "markdown": "# Paste Special, Find and Replace, and structural edits\n\nThe three Excel operations that write more than one cell, plus freeze panes.\n\n```ts\nimport {\n parseClipboard, buildClipboardPayload, planPaste, resolvePasteCell,\n findAll, replaceAll, setFindTarget,\n insertRows, deleteColumns, setStructureTarget,\n splitFrozenRows, freezeAtActiveCell,\n} from '@svgrid/enterprise/sheet'\n```\n\nAll of them run inside `cmd.batch()`, so each is **one** `Ctrl+Z`.\n\n## Paste Special\n\n### Why the clipboard needed an HTML flavour\n\nThe grid's clipboard is TSV only: `writeText` out, `readText` in. Values\nsurvive; formats, formulas and merges do not. Excel writes both `text/plain`\nand `text/html` and reads the HTML back when it is there, so matching that is\nwhat makes a round trip work.\n\n`buildClipboardPayload` produces both:\n\n```ts\nconst { text, html } = buildClipboardPayload(grid, { row: 2, col: 0 })\n\nawait navigator.clipboard.write([\n new ClipboardItem({\n 'text/plain': new Blob([text], { type: 'text/plain' }),\n 'text/html': new Blob([html], { type: 'text/html' }),\n }),\n])\n```\n\nThe HTML is a plain `<table>`. Formats ride on inline styles every app reads,\nwith Excel's own `mso-number-format` beside them so Excel keeps the number\nformat rather than guessing one from the text; the number behind a formatted\ndisplay rides in Excel's `x:num`; the formula travels in a `data-formula`\nattribute they all ignore. So a paste into Excel keeps the look and the\nnumbers, and a paste back into the grid keeps the formula.\n\n`parseClipboardHtml` reads the other direction. Excel's clipboard puts every\ncell's format in a `<style>` block keyed by class, the formula in `x:fmla`\nand the raw number in `x:num`; Google Sheets writes `data-sheets-value`,\n`data-sheets-numberformat` and `data-sheets-formula` (in R1C1). All of\nthem come through: the cell's `text` is the number when the source wrote\none, its `format` carries `numFmt`, bold, italic, colour, fill, font and\nwrap, and `formula` is what the source held. `resolvePasteCell` turns an\nR1C1 formula into A1 for the cell it lands in when you pass the destination\nas its fifth argument. Excel's formulas come as written, since its HTML\nsays nothing about where they were copied from; `anchorForeignFormulas`\nsettles them the way the shell does: a formula whose references all fall\ninside the block, read as if copied from A1, is kept with that origin so\nthe paste moves it, and one that reaches outside the block is replaced by\nits value.\n\nThe second argument records where the copy came from, which is how a pasted\nformula knows how far it moved. Omit it and references paste unshifted, which\nis correct for a paste from another application: it has no position in this\nsheet to have moved from.\n\nReading is symmetric, and falls back to TSV when the HTML holds no table:\n\n```ts\nconst grid = parseClipboard({ text, html })\n```\n\n### The options\n\n```ts\ntype PasteSpecialOptions = {\n what?: 'all' | 'values' | 'formulas' | 'formats'\n operation?: 'none' | 'add' | 'subtract' | 'multiply' | 'divide'\n transpose?: boolean\n skipBlanks?: boolean\n}\n```\n\n`planPaste` says where each source cell lands; `resolvePasteCell` says what it\nbecomes. Both are pure, so the option matrix is testable without a clipboard:\n\n```ts\nfor (const { row, col, source, offset } of planPaste(grid, at, opts, origin)) {\n const decision = resolvePasteCell(source, getValue(row, col), opts, offset)\n switch (decision.kind) {\n case 'skip': break\n case 'value': setRaw(row, col, decision.value); break\n case 'format': store.set([[row, col, row, col]], decision.format ?? {}, lookup); break\n case 'both': /* both of the above */ break\n }\n}\n```\n\nArithmetic operates on values, ignoring formats and formulas, as Excel does. A\nnon-numeric cell or a divide by zero **skips** rather than writing `NaN`.\n\n`Ctrl+Shift+V` calls the handler you register with `setPasteSpecialHandler`.\nThe keyboard layer owns the key; the dialog is yours.\n\n### The grid's clipboard hooks\n\n`@svgrid/grid` has two per-cell hooks, `processCellForClipboard` on the way\nout and `processCellFromClipboard` on the way in, and two whole-clipboard\nones for the HTML flavour:\n\n```svelte\n<SvGrid\n clipboardHtml={({ rects, text }) => buildClipboardPayload(gridOf(rects)).html}\n onPasteClipboard={({ text, html, source }) => {\n const grid = html ? parseClipboardHtml(html) : null\n if (!grid) return // plain text: the grid pastes it as usual\n landBlock(grid)\n return true // handled; the grid writes nothing itself\n }}\n/>\n```\n\nA copy leaves out what the copier cannot see: a collapsed row or column is\nfolded to nothing, and the keyboard already walks past it, so the block that\nreaches the clipboard closes up around it. That is what makes \"filter, copy,\npaste\" in the spreadsheet shell carry the rows that matched, next to each\nother, rather than the hidden ones as well.\n\n`clipboardHtml` runs once per copy, after the text is assembled; return the\nHTML to put beside it, or nothing for a text-only copy. The grid writes both\nthrough the `copy` event (`execCommand`), so it works on plain HTTP too,\nand through `navigator.clipboard.write` where the event is refused.\n\n`onPasteClipboard` runs on Ctrl+V and on a Paste command with the text and,\nwhen the clipboard has one, the HTML. With the hook set the grid leaves the\nkey to the browser, so the native `paste` event delivers the HTML as the\nsource wrote it (`source: 'event'`); where the event does not arrive, the\nasync clipboard is read for both types (`source: 'async'`). Return `true`\nonce you have written the cells; anything else lets the grid paste the text\nthe way it always has. Whatever the hook writes lands in one undo step with\nthe grid's own writes.\n\n`processCellFromClipboard` receives the raw clipboard text and what the grid\nwould have written, and returns the value to write, or `undefined` to leave\nthe cell alone:\n\n```svelte\n<SvGrid\n processCellFromClipboard={({ text, parsedValue }) =>\n text.startsWith('=') ? text : parsedValue}\n/>\n```\n\n### Writes that ask first\n\nEvery command here writes through `cmd.setCellValue`, which trusts its\ncaller. A sheet that refuses some cells (a protected sheet with locked\ncells) says so through `cmd.canEdit(r, c)`, the grid's own editability\nanswer, and the fills, stamps, AutoSum and the copies from above skip a\ncell that says no. The format target can refuse a change too\n(`guard(rects)`, with `refused()` called when it does), and the\nstructure target can refuse an insert or delete (`canApply(edit)`), which\nis how the ribbon knows to grey Bold and Insert on a protected sheet.\n\n## Find and Replace\n\nFinding looks at what the user **sees**. Replacing writes what the user\n**typed**, which for a formula cell is the formula, not its result. Replacing\n`100` inside a cell showing `100` that actually holds `=B2*C2` would either do\nnothing or destroy the formula, depending on which text you reached for. So\n`lookIn` chooses what is searched, and replace always writes through the raw\ntext.\n\n```ts\nsetFindTarget({\n getRaw: (r, c) => raw[r][c],\n getDisplay: (r, c) => displayed[r][c],\n setRaw: (r, c, text) => { raw[r][c] = text },\n isEditable: (r, c) => true,\n})\n\nfindAll(cmd, 'cat', { matchCase: true })\nreplaceAll(cmd, 'cat', 'dog', { lookIn: 'formulas', scope: 'selection' })\n```\n\n| Option | Default | Does |\n| ------ | ------- | ---- |\n| `matchCase` | false | Case sensitive. |\n| `matchEntireCell` | false | The cell must equal the text, not contain it. |\n| `lookIn` | `'values'` | Search displayed values, or formula source. |\n| `scope` | `'sheet'` | Restrict to the current selection. |\n\nThe needle is treated as literal text, not a pattern, so `.` and `$1` mean\nthemselves.\n\n`replaceAll` is the command most likely to overflow a 200-step undo history,\nwhich is why the grouping seam came first. `Ctrl+H` calls\n`setFindReplaceHandler`.\n\n## Insert and delete with reference fixup\n\n`api.addRow` and friends always existed. What was missing is the fixup pass:\ninserting a row above `=SUM(D2:D11)` without widening the range silently\nproduces the wrong total, and deleting a referenced row leaves a formula\npointing at whatever moved in. Neither shows an error, which is why this\nwaited for the engine.\n\n```ts\nsetStructureTarget({\n getRaw, setRaw,\n apply: (edit) => { /* do the structural change to your data */ },\n names, // rewritten too\n format: { store, lookup }, // entries for deleted rows dropped\n})\n\ninsertRows(cmd) // span taken from the selection\ndeleteColumns(cmd, 2, 1)\n```\n\nOrder is fixed: rewrite formulas, drop format entries for what is going, then\napply the change. The first two read the OLD geometry.\n\nNothing needs *shifting* in the format store. It keys on row and column **ids**,\nand an id travels with the thing it names, so an insert moves nothing. A\ndelete drops those ids, which is what `forgetRow` / `forgetColumn` are for.\n\n`Ctrl+Shift+Plus` and `Ctrl+Minus` act on rows when the selection spans every\ncolumn, columns when it spans every row, and **decline** otherwise. Excel opens\na dialog for the ambiguous case; deciding what that looks like is yours, so the\nkey falls through and you can bind your own.\n\n## Freeze panes\n\nColumns freeze properly and for free through column pinning. Rows are the\nhonest part of this module.\n\nThe grid renders `pinnedTopRows` into a **separate** tbody above a virtualized\nbody that still renders every row, so handing it the first three displayed rows\nshows them twice. Excluding them from the body means changing the virtualizer,\nwhich is the path built for a million rows, and freeze is not worth that risk.\n\nSo `applyFreeze` does the column half through the api and reports the state;\n`splitFrozenRows` does the row arithmetic and you apply it:\n\n```svelte\n<script>\n let freeze = $state({ rows: 2, cols: 1 })\n const split = $derived(splitFrozenRows(rows, freeze.rows))\n</script>\n\n<SvGrid data={split.bodyRows} pinnedTopRows={split.pinnedTopRows} {columns} />\n```\n\n`freezeAtActiveCell`, `freezeTopRow`, `freezeFirstColumn` and `unfreeze` are\nthe Excel gestures. Split panes stays declined: a second scroll viewport in the\nhot render path, for something freeze already covers.\n\n## Text to Columns and Remove Duplicates\n\nThe two one-shot transforms an Excel user reaches for on arriving data. Both\nare pure functions rather than commands, because they get run from a button, a\nmenu, a paste handler or a test, and none of those want a keystroke.\n\n```ts\nimport {\n splitText, textToColumns, guessDelimiter,\n findDuplicates, removeDuplicates,\n} from '@svgrid/enterprise/sheet'\n```\n\n### Text to Columns\n\n```ts\nguessDelimiter(['a;b', 'c;d']) // ';'\ntextToColumns(['a,b,c', 'd,e'])\n// { rows: [['a','b','c'], ['d','e','']], width: 3 }\n```\n\nEvery row is padded to the widest. That matters: writing a ragged result into\na grid leaves whatever was already in the cell, so a row that split into two\nfields would keep stale text in the third column.\n\n`splitText` is a scan, not a `String.split`, because a quoted field may contain\nthe delimiter and a doubled quote is an escaped one:\n\n```ts\nsplitText('a,\"b,c\",d') // ['a', 'b,c', 'd']\nsplitText('a b', { delimiters: [' '], collapse: true }) // ['a', 'b']\nsplitText('a:b:c', { delimiters: [':'], limit: 2 }) // ['a', 'b:c']\n```\n\n`guessDelimiter` scores a candidate on appearing in most rows **and** the same\nnumber of times in each, so a comma inside one field does not beat the tab\nthat actually separates the columns.\n\n### Remove Duplicates\n\n`findDuplicates` reports rather than removes, so the caller decides what\nremoval means for its data structure and a UI can say \"3 duplicates found\"\nbefore anything is written:\n\n```ts\nfindDuplicates([['a'], ['b'], ['a']])\n// { keep: [0, 1], remove: [2] }\n\nremoveDuplicates(rows, (r) => [r.email], { matchCase: true })\n// { rows: [...], removed: 3 }\n```\n\nComparison is **case-insensitive** by default, matching Excel. That surprises\npeople, which is exactly why it matches rather than being tidier.\n\n## More examples\n\n### Paste from Excel: formats and formulas survive\n\nExcel puts an HTML document on the clipboard beside the tab-separated text: formats in a style block keyed by class, formulas in x:fmla, raw numbers in x:num. The sheet reads it, so a pasted block arrives bold, filled, with its number formats, and with its formulas moved to where they landed; Google Sheets' data-sheets-formula flavour reads the same. Two buttons put exactly what Excel and Sheets put on the clipboard; click a cell and Ctrl+V.\n\n<div data-docs-demo=\"466-paste-from-excel\" data-height=\"560\"></div>\n\n\n### Paste Special, Find/Replace\n\nThe three Excel operations that write more than one cell: Paste Special (values / formulas / formats / transpose / arithmetic, with a text/html clipboard flavour so formats survive a round trip through Excel), Find and Replace that searches what you SEE but writes what you TYPED so a formula is not destroyed by replacing its result, and insert/delete that rewrites every formula - inserting above =SUM(B1:B4) widens it instead of dropping the new row.\n\n<div data-docs-demo=\"454-paste-find-structure\" data-height=\"560\"></div>\n\n### Data cleanup: Text to Columns, Remove Duplicates\n\nA CRM export landed in column A, semicolon-separated, with the same people in it twice. Data -> Text to Columns opens a wizard that has already guessed the delimiter and previews the split; Data -> Remove Duplicates lets you tick the columns that decide identity, compares case-insensitively like Excel, and reports \"3 duplicate values found and removed; 11 unique values remain\". Each operation is one Ctrl+Z.\n\n<div data-docs-demo=\"458-data-cleanup\" data-height=\"560\"></div>\n\n## See also\n\n- [Excel keyboard shortcuts](./keyboard-shortcuts.md)\n- [Number formats](./number-formats.md)\n- [Spreadsheet formulas](../spreadsheet-formulas.md)\n"
5140
+ "markdown": "\n# Paste Special, Find and Replace, and structural edits\n\nThe three Excel operations that write more than one cell, plus freeze panes.\n\n```ts\nimport {\n parseClipboard, buildClipboardPayload, planPaste, resolvePasteCell,\n findAll, replaceAll, setFindTarget,\n insertRows, deleteColumns, setStructureTarget,\n splitFrozenRows, freezeAtActiveCell,\n} from '@svgrid/enterprise/sheet'\n```\n\nAll of them run inside `cmd.batch()`, so each is **one** `Ctrl+Z`.\n\n## Paste Special\n\n### Why the clipboard needed an HTML flavour\n\nThe grid's clipboard is TSV only: `writeText` out, `readText` in. Values\nsurvive; formats, formulas and merges do not. Excel writes both `text/plain`\nand `text/html` and reads the HTML back when it is there, so matching that is\nwhat makes a round trip work.\n\n`buildClipboardPayload` produces both:\n\n```ts\nconst { text, html } = buildClipboardPayload(grid, { row: 2, col: 0 })\n\nawait navigator.clipboard.write([\n new ClipboardItem({\n 'text/plain': new Blob([text], { type: 'text/plain' }),\n 'text/html': new Blob([html], { type: 'text/html' }),\n }),\n])\n```\n\nThe HTML is a plain `<table>`. Formats ride on inline styles every app reads,\nwith Excel's own `mso-number-format` beside them so Excel keeps the number\nformat rather than guessing one from the text; the number behind a formatted\ndisplay rides in Excel's `x:num`; the formula travels in a `data-formula`\nattribute they all ignore. So a paste into Excel keeps the look and the\nnumbers, and a paste back into the grid keeps the formula.\n\n`parseClipboardHtml` reads the other direction. Excel's clipboard puts every\ncell's format in a `<style>` block keyed by class, the formula in `x:fmla`\nand the raw number in `x:num`; Google Sheets writes `data-sheets-value`,\n`data-sheets-numberformat` and `data-sheets-formula` (in R1C1). All of\nthem come through: the cell's `text` is the number when the source wrote\none, its `format` carries `numFmt`, bold, italic, colour, fill, font and\nwrap, and `formula` is what the source held. `resolvePasteCell` turns an\nR1C1 formula into A1 for the cell it lands in when you pass the destination\nas its fifth argument. Excel's formulas come as written, since its HTML\nsays nothing about where they were copied from; `anchorForeignFormulas`\nsettles them the way the shell does: a formula whose references all fall\ninside the block, read as if copied from A1, is kept with that origin so\nthe paste moves it, and one that reaches outside the block is replaced by\nits value.\n\nThe second argument records where the copy came from, which is how a pasted\nformula knows how far it moved. Omit it and references paste unshifted, which\nis correct for a paste from another application: it has no position in this\nsheet to have moved from.\n\nReading is symmetric, and falls back to TSV when the HTML holds no table:\n\n```ts\nconst grid = parseClipboard({ text, html })\n```\n\n### The options\n\n```ts\ntype PasteSpecialOptions = {\n what?: 'all' | 'values' | 'formulas' | 'formats'\n operation?: 'none' | 'add' | 'subtract' | 'multiply' | 'divide'\n transpose?: boolean\n skipBlanks?: boolean\n}\n```\n\n`planPaste` says where each source cell lands; `resolvePasteCell` says what it\nbecomes. Both are pure, so the option matrix is testable without a clipboard:\n\n```ts\nfor (const { row, col, source, offset } of planPaste(grid, at, opts, origin)) {\n const decision = resolvePasteCell(source, getValue(row, col), opts, offset)\n switch (decision.kind) {\n case 'skip': break\n case 'value': setRaw(row, col, decision.value); break\n case 'format': store.set([[row, col, row, col]], decision.format ?? {}, lookup); break\n case 'both': /* both of the above */ break\n }\n}\n```\n\nArithmetic operates on values, ignoring formats and formulas, as Excel does. A\nnon-numeric cell or a divide by zero **skips** rather than writing `NaN`.\n\n`Ctrl+Shift+V` calls the handler you register with `setPasteSpecialHandler`.\nThe keyboard layer owns the key; the dialog is yours.\n\n### The grid's clipboard hooks\n\n`@svgrid/grid` has two per-cell hooks, `processCellForClipboard` on the way\nout and `processCellFromClipboard` on the way in, and two whole-clipboard\nones for the HTML flavour:\n\n```svelte\n<SvGrid\n clipboardHtml={({ rects, text }) => buildClipboardPayload(gridOf(rects)).html}\n onPasteClipboard={({ text, html, source }) => {\n const grid = html ? parseClipboardHtml(html) : null\n if (!grid) return // plain text: the grid pastes it as usual\n landBlock(grid)\n return true // handled; the grid writes nothing itself\n }}\n/>\n```\n\nA copy leaves out what the copier cannot see: a collapsed row or column is\nfolded to nothing, and the keyboard already walks past it, so the block that\nreaches the clipboard closes up around it. That is what makes \"filter, copy,\npaste\" in the spreadsheet shell carry the rows that matched, next to each\nother, rather than the hidden ones as well.\n\n`clipboardHtml` runs once per copy, after the text is assembled; return the\nHTML to put beside it, or nothing for a text-only copy. The grid writes both\nthrough the `copy` event (`execCommand`), so it works on plain HTTP too,\nand through `navigator.clipboard.write` where the event is refused.\n\n`onPasteClipboard` runs on Ctrl+V and on a Paste command with the text and,\nwhen the clipboard has one, the HTML. With the hook set the grid leaves the\nkey to the browser, so the native `paste` event delivers the HTML as the\nsource wrote it (`source: 'event'`); where the event does not arrive, the\nasync clipboard is read for both types (`source: 'async'`). Return `true`\nonce you have written the cells; anything else lets the grid paste the text\nthe way it always has. Whatever the hook writes lands in one undo step with\nthe grid's own writes.\n\n`processCellFromClipboard` receives the raw clipboard text and what the grid\nwould have written, and returns the value to write, or `undefined` to leave\nthe cell alone:\n\n```svelte\n<SvGrid\n processCellFromClipboard={({ text, parsedValue }) =>\n text.startsWith('=') ? text : parsedValue}\n/>\n```\n\n### Writes that ask first\n\nEvery command here writes through `cmd.setCellValue`, which trusts its\ncaller. A sheet that refuses some cells (a protected sheet with locked\ncells) says so through `cmd.canEdit(r, c)`, the grid's own editability\nanswer, and the fills, stamps, AutoSum and the copies from above skip a\ncell that says no. The format target can refuse a change too\n(`guard(rects)`, with `refused()` called when it does), and the\nstructure target can refuse an insert or delete (`canApply(edit)`), which\nis how the ribbon knows to grey Bold and Insert on a protected sheet.\n\n## Find and Replace\n\nFinding looks at what the user **sees**. Replacing writes what the user\n**typed**, which for a formula cell is the formula, not its result. Replacing\n`100` inside a cell showing `100` that actually holds `=B2*C2` would either do\nnothing or destroy the formula, depending on which text you reached for. So\n`lookIn` chooses what is searched, and replace always writes through the raw\ntext.\n\n```ts\nsetFindTarget({\n getRaw: (r, c) => raw[r][c],\n getDisplay: (r, c) => displayed[r][c],\n setRaw: (r, c, text) => { raw[r][c] = text },\n isEditable: (r, c) => true,\n})\n\nfindAll(cmd, 'cat', { matchCase: true })\nreplaceAll(cmd, 'cat', 'dog', { lookIn: 'formulas', scope: 'selection' })\n```\n\n| Option | Default | Does |\n| ------ | ------- | ---- |\n| `matchCase` | false | Case sensitive. |\n| `matchEntireCell` | false | The cell must equal the text, not contain it. |\n| `lookIn` | `'values'` | Search displayed values, or formula source. |\n| `scope` | `'sheet'` | Restrict to the current selection. |\n\nThe needle is treated as literal text, not a pattern, so `.` and `$1` mean\nthemselves.\n\n`replaceAll` is the command most likely to overflow a 200-step undo history,\nwhich is why the grouping seam came first. `Ctrl+H` calls\n`setFindReplaceHandler`.\n\n## Insert and delete with reference fixup\n\n`api.addRow` and friends always existed. What was missing is the fixup pass:\ninserting a row above `=SUM(D2:D11)` without widening the range silently\nproduces the wrong total, and deleting a referenced row leaves a formula\npointing at whatever moved in. Neither shows an error, which is why this\nwaited for the engine.\n\n```ts\nsetStructureTarget({\n getRaw, setRaw,\n apply: (edit) => { /* do the structural change to your data */ },\n names, // rewritten too\n format: { store, lookup }, // entries for deleted rows dropped\n})\n\ninsertRows(cmd) // span taken from the selection\ndeleteColumns(cmd, 2, 1)\n```\n\nOrder is fixed: rewrite formulas, drop format entries for what is going, then\napply the change. The first two read the OLD geometry.\n\nNothing needs *shifting* in the format store. It keys on row and column **ids**,\nand an id travels with the thing it names, so an insert moves nothing. A\ndelete drops those ids, which is what `forgetRow` / `forgetColumn` are for.\n\n`Ctrl+Shift+Plus` and `Ctrl+Minus` act on rows when the selection spans every\ncolumn, columns when it spans every row, and **decline** otherwise. Excel opens\na dialog for the ambiguous case; deciding what that looks like is yours, so the\nkey falls through and you can bind your own.\n\n## Freeze panes\n\nColumns freeze properly and for free through column pinning. Rows are the\nhonest part of this module.\n\nThe grid renders `pinnedTopRows` into a **separate** tbody above a virtualized\nbody that still renders every row, so handing it the first three displayed rows\nshows them twice. Excluding them from the body means changing the virtualizer,\nwhich is the path built for a million rows, and freeze is not worth that risk.\n\nSo `applyFreeze` does the column half through the api and reports the state;\n`splitFrozenRows` does the row arithmetic and you apply it:\n\n```svelte\n<script>\n let freeze = $state({ rows: 2, cols: 1 })\n const split = $derived(splitFrozenRows(rows, freeze.rows))\n</script>\n\n<SvGrid data={split.bodyRows} pinnedTopRows={split.pinnedTopRows} {columns} />\n```\n\n`freezeAtActiveCell`, `freezeTopRow`, `freezeFirstColumn` and `unfreeze` are\nthe Excel gestures. Split panes stays declined: a second scroll viewport in the\nhot render path, for something freeze already covers.\n\n## Text to Columns and Remove Duplicates\n\nThe two one-shot transforms an Excel user reaches for on arriving data. Both\nare pure functions rather than commands, because they get run from a button, a\nmenu, a paste handler or a test, and none of those want a keystroke.\n\n```ts\nimport {\n splitText, textToColumns, guessDelimiter,\n findDuplicates, removeDuplicates,\n} from '@svgrid/enterprise/sheet'\n```\n\n### Text to Columns\n\n```ts\nguessDelimiter(['a;b', 'c;d']) // ';'\ntextToColumns(['a,b,c', 'd,e'])\n// { rows: [['a','b','c'], ['d','e','']], width: 3 }\n```\n\nEvery row is padded to the widest. That matters: writing a ragged result into\na grid leaves whatever was already in the cell, so a row that split into two\nfields would keep stale text in the third column.\n\n`splitText` is a scan, not a `String.split`, because a quoted field may contain\nthe delimiter and a doubled quote is an escaped one:\n\n```ts\nsplitText('a,\"b,c\",d') // ['a', 'b,c', 'd']\nsplitText('a b', { delimiters: [' '], collapse: true }) // ['a', 'b']\nsplitText('a:b:c', { delimiters: [':'], limit: 2 }) // ['a', 'b:c']\n```\n\n`guessDelimiter` scores a candidate on appearing in most rows **and** the same\nnumber of times in each, so a comma inside one field does not beat the tab\nthat actually separates the columns.\n\n### Remove Duplicates\n\n`findDuplicates` reports rather than removes, so the caller decides what\nremoval means for its data structure and a UI can say \"3 duplicates found\"\nbefore anything is written:\n\n```ts\nfindDuplicates([['a'], ['b'], ['a']])\n// { keep: [0, 1], remove: [2] }\n\nremoveDuplicates(rows, (r) => [r.email], { matchCase: true })\n// { rows: [...], removed: 3 }\n```\n\nComparison is **case-insensitive** by default, matching Excel. That surprises\npeople, which is exactly why it matches rather than being tidier.\n\n## More examples\n\n### Paste from Excel: formats and formulas survive\n\nExcel puts an HTML document on the clipboard beside the tab-separated text: formats in a style block keyed by class, formulas in x:fmla, raw numbers in x:num. The sheet reads it, so a pasted block arrives bold, filled, with its number formats, and with its formulas moved to where they landed; Google Sheets' data-sheets-formula flavour reads the same. Two buttons put exactly what Excel and Sheets put on the clipboard; click a cell and Ctrl+V.\n\n<div data-docs-demo=\"466-paste-from-excel\" data-height=\"560\"></div>\n\n\n### Paste Special, Find/Replace\n\nThe three Excel operations that write more than one cell: Paste Special (values / formulas / formats / transpose / arithmetic, with a text/html clipboard flavour so formats survive a round trip through Excel), Find and Replace that searches what you SEE but writes what you TYPED so a formula is not destroyed by replacing its result, and insert/delete that rewrites every formula - inserting above =SUM(B1:B4) widens it instead of dropping the new row.\n\n<div data-docs-demo=\"454-paste-find-structure\" data-height=\"560\"></div>\n\n### Data cleanup: Text to Columns, Remove Duplicates\n\nA CRM export landed in column A, semicolon-separated, with the same people in it twice. Data -> Text to Columns opens a wizard that has already guessed the delimiter and previews the split; Data -> Remove Duplicates lets you tick the columns that decide identity, compares case-insensitively like Excel, and reports \"3 duplicate values found and removed; 11 unique values remain\". Each operation is one Ctrl+Z.\n\n<div data-docs-demo=\"458-data-cleanup\" data-height=\"560\"></div>\n\n## See also\n\n- [Excel keyboard shortcuts](./keyboard-shortcuts.md)\n- [Number formats](./number-formats.md)\n- [Spreadsheet formulas](../spreadsheet-formulas.md)\n"
5134
5141
  },
5135
5142
  {
5136
5143
  "slug": "help/cells/rich-text-cells",
@@ -5466,7 +5473,7 @@ export const docs = [
5466
5473
  "path": "docs/help/export.md",
5467
5474
  "title": "Data export and printing",
5468
5475
  "section": "Import & export",
5469
- "markdown": "# Data export and printing\n\n**CSV / TSV / JSON export and copy-to-clipboard are free** in the community\n**[@svgrid/grid](https://www.npmjs.com/package/@svgrid/grid)** - the commodity\n\"data out\" every grid needs. The richer formats - **Excel (xlsx)**, **legacy\nExcel (xls)**, **PDF**, styled **HTML**, **XML**, **Markdown**, multi-sheet\nworkbooks, password protection, conditional-format export, and the drop-in\nexport menu - ship in the paid\n**[@svgrid/enterprise](https://www.npmjs.com/package/@svgrid/enterprise)** add-on,\nwhich reuses the exact same serializers so the two tiers feel like one product.\n\nFor the report built step by step, with a live grid under most steps, see [Export: a report to Excel and PDF](./export/report.md); this page is the reference.\n\n![Pick a row scope, then serialize the grid to Excel, CSV, TSV, HTML, PDF, or Print.](/docs-media/grid-export.svg)\n\n| Capability | Package |\n| ---------- | ------- |\n| CSV / TSV / JSON export, copy-to-clipboard (TSV / CSV / Markdown) | **Free** (`@svgrid/grid`) |\n| Excel `.xlsx` (typed cells, styles, conditional formatting, tables, multi-sheet) | Enterprise |\n| PDF, styled HTML, XML, legacy `.xls`, password-protected export | Enterprise |\n| `exportValue` hook, conditional-format export, `SvExportMenu`, `print()` | Enterprise |\n\n## Free: CSV / TSV / JSON + clipboard\n\nThe community grid's `SvGridApi` carries four zero-dependency methods - no\nlicense, no peer deps:\n\nThe examples on this page run against these rows:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns, tableFeatures, rowSortingFeature, columnFilteringFeature } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n email: string\n department: string\n age: number\n salary: number\n city: string\n startDate: string\n active: boolean\n }\n\n type Order = {\n id: string\n customer: string\n product: string\n quantity: number\n total: number\n status: 'pending' | 'shipped' | 'delivered'\n orderedAt: string\n }\n\n type Row = Person\n\n const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })\n\n const people: Person[] = [\n { id: 1, name: 'Ada Lovelace', email: 'ada@example.com', department: 'Engineering', age: 36, salary: 142000, city: 'London', startDate: '2021-03-01', active: true },\n { id: 2, name: 'Grace Hopper', email: 'grace@example.com', department: 'Engineering', age: 45, salary: 168000, city: 'New York', startDate: '2019-07-15', active: true },\n { id: 3, name: 'Linus Torvalds', email: 'linus@example.com', department: 'Platform', age: 54, salary: 155000, city: 'Portland', startDate: '2020-01-20', active: false },\n { id: 4, name: 'Radia Perlman', email: 'radia@example.com', department: 'Networking', age: 49, salary: 161000, city: 'Seattle', startDate: '2022-09-05', active: true },\n { id: 5, name: 'Barbara Liskov', email: 'barbara@example.com', department: 'Platform', age: 52, salary: 172000, city: 'Boston', startDate: '2018-11-11', active: true },\n ]\n\n let rows = $state<Person[]>(people)\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 200 },\n { field: 'department', header: 'Department', width: 150 },\n { field: 'city', header: 'City', width: 140 },\n { field: 'age', header: 'Age', width: 90 },\n { field: 'salary', header: 'Salary', width: 130, format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```ts\nawait api.exportCsv({ filename: 'orders' }) // orders.csv (BOM + Excel-friendly)\nawait api.exportTsv() // grid.tsv\nawait api.exportJson({ rows: 'selected' }) // grid.json, checked rows only\nawait api.copyToClipboard({ format: 'tsv' }) // paste straight into Excel / Sheets\n```\n\nEvery method:\n\n- defaults to the **current view** (`rows: 'selected' | 'all'` to change),\n- formats values **as shown on screen** (currency, dates) - pass\n `rawValues: true` for the underlying values,\n- accepts a `columns: string[]` field subset (in that order),\n- runs on a chunked, cancelable loop (`signal`, `onProgress`) so a 100k-row\n export never freezes the tab,\n- returns the serialized text; pass `download: false` to skip the download\n and just get the string.\n\n```svelte {runnable}\n<script lang=\"ts\">\n import { SvGrid, tableFeatures, type SvGridApi } from '@svgrid/grid'\n let api = $state<SvGridApi<any, Row> | null>(null)\n</script>\n\n<button onclick={() => api?.exportCsv({ filename: 'orders' })}>Export CSV</button>\n<button onclick={() => api?.copyToClipboard()}>Copy for Excel</button>\n<SvGrid data={rows} columns={columns} features={features} onApiReady={(a) => (api = a)} />\n```\n\nThe rest of this page covers the **Enterprise** formats.\n\nTry the export bar below - downloads run in your browser; the bundled\nlicense key removes the unlicensed watermark:\n\n<div data-docs-demo=\"21-export-and-print\" data-height=\"500\"></div>\n\n\n## What it is\n\n`@svgrid/enterprise` augments the `SvGridApi` you already get from\n`<SvGrid onApiReady>` with two methods:\n\n- `api.exportData({ format, filename?, columns?, rows?, pageOrientation? })`\n- `api.print({ title?, columns?, rows?, orientation? })`\n\nBoth methods default to **the currently displayed rows** - sort, filter,\nor paginate the grid, and the export reflects that view automatically.\n\n## When to use it\n\n- Reporting flows where users want to take the grid offline (spreadsheets,\n emailed PDFs).\n- Compliance / audit trails that require a printable artifact.\n- Quick CSV/TSV pulls for downstream pipelines.\n\nIf you only need machine-readable data, prefer CSV / TSV - they have no\npeer dependencies and produce the smallest files. Use xlsx / PDF only\nwhen the recipient expects formatted documents.\n\n## Minimal example\n\n```svelte {runnable}\n<script lang=\"ts\">\n import { SvGrid, tableFeatures, rowSortingFeature, type SvGridApi, type ColumnDef } from '@svgrid/grid'\n import { installEnterprise, type EnterpriseGridApi } from '@svgrid/enterprise'\n\n // Without a key, the feature still works but the grid shows an\n // \"unlicensed\" watermark and the console emits a one-time nudge directing\n // users to the pricing page. After you buy, call setLicenseKey(yourKey)\n // once at startup.\n\n const features = tableFeatures({ rowSortingFeature })\n\n type Order = { company: string; product: string; price: number }\n const rows: Order[] = [\n { company: 'ACME', product: 'Widget', price: 19.95 },\n { company: 'Globex', product: 'Gadget', price: 49.00 },\n ]\n const columns: ColumnDef<typeof features, Order>[] = [\n { field: 'company', header: 'Company' },\n { field: 'product', header: 'Product' },\n { field: 'price', header: 'Price', format: { type: 'currency', currency: 'USD' } },\n ]\n\n let api = $state<EnterpriseGridApi<typeof features, Order> | null>(null)\n\n function onReady(next: SvGridApi<typeof features, Order>) {\n api = installEnterprise(next)\n }\n</script>\n\n<button onclick={() => api?.exportData({ format: 'xlsx', filename: 'orders' })}>\n Export Excel\n</button>\n<button onclick={() => api?.exportData({ format: 'pdf', filename: 'orders', pageOrientation: 'landscape' })}>\n Export PDF\n</button>\n<button onclick={() => api?.print({ title: 'Orders' })}>\n Print\n</button>\n\n<SvGrid data={rows} columns={columns} features={features} onApiReady={onReady} />\n```\n\n## Install\n\n```bash\npnpm add @svgrid/enterprise\n# Optional - install only the peers you actually use:\npnpm add jszip # required for xlsx\npnpm add pdfmake # required for pdf\n```\n\nCSV, TSV, HTML, and Print have **no extra dependencies**. The peer\ndependencies are lazy-loaded only when you call the format that needs\nthem.\n\n## Licensing\n\n`@svgrid/enterprise` has a tiered license gate:\n\n| Key state | Behavior |\n| ------------------------------------------ | -------- |\n| No key set (`setLicenseKey()` not called) | Feature works. Grid shows an unlicensed watermark linking to svgrid.com/pricing; console.log emits a one-time nudge. |\n| A key that is not your license key | Same as no key: the feature works, with the watermark and a one-time console warning. |\n| Your license key | Works silently. |\n\nBuy a production key at <https://svgrid.com/pricing/> ($599 / developer /\nyear). To evaluate, you need no key at all: everything runs with a watermark.\n\n## Reference\n\n### `setLicenseKey(key: string): void`\n\nStores the key in module state. Call once at app startup (e.g. in\n`main.ts`). Subsequent calls overwrite.\n\n### `clearLicenseKey(): void` · `hasValidLicense(): boolean` · `dismissUnlicensedNudge(): void`\n\nProgrammatic helpers. `hasValidLicense()` is useful when you want UI to\nbranch on license status. `dismissUnlicensedNudge()` removes the\nwatermark and stops the MutationObserver - call it after setting a\nvalid key if you loaded the module without one during testing.\n\n### `installEnterprise(api): EnterpriseGridApi`\n\nMutates the given `SvGridApi` to add `exportData` and `print`. Returns\nthe same object with the augmented type, so existing references keep\nworking.\n\n### `api.exportData(opts)` - `Promise<void>`\n\n| Option | Type | Default | Notes |\n| ----------------- | ----------------------------------------------------- | -------------------- | ----- |\n| `format` | `'xlsx' \\| 'xls' \\| 'pdf' \\| 'csv' \\| 'tsv' \\| 'html' \\| 'json' \\| 'xml' \\| 'md'` | required | `xlsx` needs `jszip`, `pdf` needs `pdfmake`. `xls` / CSV / TSV / HTML / JSON / XML / Markdown are dependency-free. |\n| `pdf` | `PdfExportOptions` | - | PDF layout: page size, margins, title / subtitle / logo, theme colors, column widths, repeated header, page numbers. See \"PDF options\". |\n| `conditionalFormats` | `ConditionalFormat[]` | - | Same array as `<SvGrid conditionalFormats>`; carried into pdf / xlsx / html. See \"Conditional formatting in exports\". |\n| `freezeHeader` | `boolean` | `true` | Freeze the header row (xlsx / xls). |\n| `freezeColumns` | `number` | pinned cols | Freeze this many leading columns (xlsx / xls). Defaults to the grid's left-pinned columns. |\n| `autoFitColumns` | `boolean` | `true` | Size columns to content (xlsx / xls); a column's explicit `width` wins. |\n| `precisionSafe` | `boolean` | `false` | Export long integer IDs (> 15 digits) as text so Excel's float precision doesn't round them (xlsx / xls). |\n| `excelTable` | `boolean \\| { totalsRow?; style? }` | - | Wrap single-sheet xlsx in a native Excel Table (filter dropdowns, banded rows; `{ totalsRow: true }` adds SUM formulas). |\n| `download` | `boolean` | `true` | When false, return the {@link ExportResult} without downloading. |\n| `filename` | `string` | `\"grid\"` | Extension is appended if missing. |\n| `columns` | `{ field; header?; format?; align?; exportValue? }[]` | grid's own columns | Drives column selection + header labels. Auto-derived from the grid (with each column's `format`) when omitted. See `exportValue` below. |\n| `rows` | `ReadonlyArray<TData> \\| 'displayed' \\| 'selected' \\| 'all'` | `'displayed'` | `'displayed'` = current filtered/sorted/paged view, `'selected'` = checked rows, `'all'` = full dataset, or pass an explicit array. |\n| `rawValues` | `boolean` | `false` | By default the exporter writes the **formatted display value** (what you see). Set `true` to write raw underlying values (numbers stay numeric in xlsx). |\n| `autoGroup` | `boolean` | `true` | Carry the grid's active row grouping into xlsx outline rows. Pass your own `groupBy` to override, or `false` to ignore. |\n| `csv` | `{ delimiter?; eol?; bom? }` | `{ ',', '\\r\\n', BOM }` | CSV / TSV tuning. UTF-8 BOM is on by default so Excel opens it without mojibake. |\n| `onProgress` | `(p) => void` | - | Progress for large exports: `{ phase, ratio, row?, total? }`, `phase` = `'project' \\| 'serialize' \\| 'write'`. |\n| `signal` | `AbortSignal` | - | Cancel an in-flight export (checked between chunks). Rejects with `AbortError`. |\n| `pageOrientation` | `'portrait' \\| 'landscape'` | `\"portrait\"` | PDF only. |\n| `merges` | `{ row; col; rowSpan?; colSpan? }[]` | `[]` | Merged cells (xlsx / pdf). Zero-based **body** row/col (header excluded). Single-sheet only; mutually exclusive with `groupBy` / `hierarchical`. |\n\n### Faithful values (what you see is what you export)\n\nBy default the export renders each cell the way the grid does on screen: a\ncolumn with `format: { type: 'currency', currency: 'USD' }` exports `$19.95`,\na date column exports its formatted date, a percent column exports `42%`. This\nholds for **every** format (csv / tsv / html / pdf / xlsx). Pass\n`rawValues: true` to write the underlying values instead (e.g. feeding a data\npipeline that wants the numeric `19.95`).\n\nFor columns whose on-screen value comes from a **custom cell renderer**, a\n`fieldFn`, or a lookup, give the column an `exportValue` hook - it takes\nprecedence over `format` and the raw field:\n\n```ts\nawait api.exportData({\n format: 'xlsx',\n columns: [\n { field: 'company', header: 'Company' },\n // a column rendered with a custom snippet on screen:\n { field: 'status', header: 'Status', exportValue: (row) => STATUS_LABELS[row.status] },\n ],\n})\n```\n\n### Export only what's selected\n\n```ts\n// current view (default)\nawait api.exportData({ format: 'xlsx' })\n// only the checked rows\nawait api.exportData({ format: 'xlsx', rows: 'selected' })\n// the entire underlying dataset, ignoring filters/paging\nawait api.exportData({ format: 'csv', rows: 'all' })\n```\n\n### Large exports: progress + cancel\n\nCSV / TSV / HTML are serialized natively (no peer dependency) and stream in\nchunks, yielding to the event loop so a big export doesn't freeze the tab:\n\n```ts\nconst controller = new AbortController()\nawait api.exportData({\n format: 'csv',\n rows: 'all',\n signal: controller.signal,\n onProgress: ({ ratio }) => updateProgressBar(ratio),\n})\n// controller.abort() rejects the export with an AbortError\n```\n\n### Excel-native numbers (xlsx)\n\nA single-sheet `xlsx` export writes numeric, currency, percent, and date\ncolumns as **real typed cells** with an Excel number format - so Excel can sum\nand sort them, and they still display formatted (currency symbol, thousands,\n`%`, date pattern) - via SvGrid's own OOXML writer. Set `rawValues: true` for\nunformatted raw values. The grouped-outline, multi-sheet, image, and merged-cell\npaths use the bundled writer (formatted-string cells). The legacy `xls` format\nis always typed.\n\n### Excel fidelity: freeze, auto-fit, hyperlinks\n\n`xlsx` and `xls` exports polish the spreadsheet automatically:\n\n- **Freeze header** - the header row stays visible when scrolling. On by\n default; `freezeHeader: false` to disable, `freezeColumns: n` to also freeze\n leading columns.\n- **Auto-fit column widths** - columns are sized to their content. On by\n default (`autoFitColumns: false` to disable); a column's explicit `width`\n (pixels) always wins.\n- **Hyperlinks** - give a column a `link(row)` hook to render clickable links.\n Works in `xlsx`, `xls`, `html`, `pdf`, and `print`.\n\nSingle-sheet `xlsx` is written by SvGrid's own OOXML writer, so numbers/dates\nstay typed with number formats, conditional-format colors are **real per-cell\nfills**, and freeze/widths/hyperlinks all apply. (Grouped/outline, multi-sheet,\nembedded-image, and merged-cell exports use the bundled writer.)\n\n```ts\nawait api.exportData({\n format: 'xlsx',\n freezeHeader: true, // default\n columns: [\n { field: 'name', header: 'Company', width: 220,\n link: (row) => `https://crm.example.com/accounts/${row.id}` },\n { field: 'revenue', header: 'Revenue', format: { type: 'currency', currency: 'USD' } },\n ],\n})\n```\n\nConditional-format colors (data bars / color scales) already render as real\ncell fills in `xlsx`, which is higher fidelity than the writer's built-in\nrule-only conditional formatting - so we keep the per-cell approach.\n\n### Get the file instead of downloading (`download: false`)\n\n`exportData` returns an **`ExportResult`** for the dependency-free paths\n(csv/tsv/html/json/xml/md, xls, pdf, single-sheet xlsx) so you can preview,\nupload, email, or attach the file. With `download: false` it builds and returns\nthe file **without** triggering a browser download:\n\n```ts\nconst res = await api.exportData({ format: 'xlsx', download: false })\n// res: { blob, filename, mime, rowCount, byteSize }\nawait uploadToStorage(res.blob, res.filename)\n```\n\nThe grouped / multi-sheet / image / blanket-styled xlsx paths use the vendored\nwriter, which downloads directly and returns `undefined` (and throws on\n`download: false`).\n\n### Excel Table (filter dropdowns + totals row)\n\nWrap a single-sheet xlsx in a native **Excel Table** - the user gets column\nfilter dropdowns, banded rows, structured references, and (optionally) a totals\nrow with live `SUM()` formulas:\n\n```ts\nawait api.exportData({ format: 'xlsx', excelTable: { totalsRow: true } })\n// or just `excelTable: true` for the table without a totals row\n```\n\nColumn widths auto-fit and leading **pinned columns are frozen automatically**\n(override with `freezeColumns`). For long IDs, `precisionSafe: true` writes them\nas text so Excel's 15-digit float limit doesn't silently round `1002000300040005`.\n\n### JSON / XML / Markdown\n\n```ts\nawait api.exportData({ format: 'json' }) // array of { field: value } - defaults to raw values\nawait api.exportData({ format: 'xml' }) // <rows><row><field>value</field>…\nawait api.exportData({ format: 'md' }) // GitHub-flavored Markdown table (great for docs / LLMs)\n```\n\nJSON defaults to **raw** values (real numbers/dates) since it's a data format;\npass `rawValues: false` for formatted strings. XML and Markdown use the\nformatted display values.\n\n### Copy to clipboard\n\n`api.copyExport(opts)` serializes to the clipboard instead of downloading a\nfile - handy for \"copy these rows into a spreadsheet or an email\":\n\n```ts\nawait api.copyExport({ format: 'tsv' }) // pastes into Excel / Sheets as columns (default)\nawait api.copyExport({ format: 'md', rows: 'selected' }) // Markdown table of the checked rows\nawait api.copyExport({ format: 'html' }) // rich text/html - keeps the table when pasted\n```\n\nSupported formats: `csv`, `tsv`, `html`, `json`, `xml`, `md`. `html` writes\nboth `text/html` (rich paste) and a `text/plain` fallback. Needs a secure\ncontext and a user gesture (call it from a click).\n\n### Conditional formatting in exports\n\nPass the same `conditionalFormats` array you give `<SvGrid>` to carry the grid's\ncolor scales, data bars, icon sets, and predicate rules into the **styled**\nformats - PDF, xlsx, and HTML (and `print()`):\n\n```ts\nconst conditionalFormats = [\n { type: 'colorScale', columns: ['score'], min: '#dcfce7', max: '#fee2e2' },\n { type: 'rule', columns: ['status'], when: ({ value }) => value === 'Overdue', background: '#fecaca' },\n]\n\nawait api.exportData({ format: 'pdf', conditionalFormats })\nawait api.exportData({ format: 'xlsx', conditionalFormats }) // real cell fills in Excel\nawait api.print({ conditionalFormats })\n```\n\nCell background, text color, and bold carry through as **real cell fills** in\n`xlsx` (single-sheet), `xls`, `html`, and `pdf`; icon sets prepend their glyph\nto the cell text.\n\nIn **xlsx**, **data bars** and **color scales** become **native Excel\nconditional formatting** (`<conditionalFormatting>` rules) - Excel draws and\nrecomputes them itself, so they're interactive, not a static snapshot.\nPredicate `rule` formats stay as computed per-cell fills. In the other styled\nformats (`xls` / `html` / `pdf`) a data bar degrades to a light fill of the bar\ncolor (cells can't hold a partial-width bar). The data formats (csv / tsv /\njson / xml / md) are unstyled, so conditional formatting is ignored there.\nGrouped PDF exports skip conditional formatting (the group/subtotal rows own the\nlayout).\n\n### PDF options\n\nThe PDF is built from a full pdfmake document you control via `pdf`:\n\n```ts\nawait api.exportData({\n format: 'pdf',\n filename: 'orders',\n pdf: {\n pageSize: 'A4', // 'A4' | 'A3' | 'A5' | 'LETTER' | 'LEGAL'\n pageOrientation: 'landscape',\n title: 'Q3 Orders',\n subtitle: 'Generated by Ops',\n logo: logoDataUrl, // top-left image (data URL)\n headerColor: '#334155', // header row fill\n zebra: true, // striped rows\n columnWidths: '*', // '*' fill, 'auto', or a per-column pt array\n // repeatHeader (default true), showPageNumbers (default true) also available\n },\n})\n```\n\nThe header row repeats on every page, each page gets a `Page X of Y` +\ndate footer, per-column alignment is honored, and wide grids auto-switch to\nlandscape (override with `pdf.pageOrientation`).\n\nThe PDF looks like the grid it came from. With `pdf.matchTheme` (default\ntrue) the exporter reads the mounted grid's computed colours - header fill\nand text, body text, the zebra stripe, the lines, a group row's fill - so a\ngrid on the Ember theme or a Theme Builder palette prints in those colours\nrather than the slate defaults. A dark theme lends only its header: the\npage is white, so its body text and stripes would not read. The order of\nprecedence is explicit `pdf` colours (`headerColor`, `headerTextColor`,\n`textColor`, `zebraColor`, `borderColor`, `groupColor`, ...), then\n`styles`, then the theme, then the defaults. `styles.headerRow` /\n`styles.rows` / `styles.rowAlternate` / `styles.cells` (A1 references, row\n1 being the header) apply to the PDF table the way they do to xlsx and\nhtml, `header` / `footer` lines print above and below the table, and\n`merges` span data cells.\n\nWhen the grid is grouped, the PDF carries the grouping: a bold **group header**\nper cluster (nested for multi-level grouping) and a **subtotal row** summing the\nnumber / currency columns - matching the xlsx outline export. It's on by\ndefault (`autoGroup`); pass `groupBy` to override or `autoGroup: false` to get a\nflat table.\n\n#### Charts and a KPI strip\n\nA report is rarely just the table. `pdf.charts` prints charts with it: hand\nover the rendered chart's element (the `SvChart` wrapper or its `<svg>`) and\nthe export rasterises it at 2x through the chart's own PNG path, so the page\ngets the picture on screen, theme and all; or pass an image data URL you\nalready have. Each takes a `title`, a `caption` and a `width` in pt\n(default: the content width). `pdf.kpis` prints a strip of headline numbers\nabove the table, each with a label, the value and an optional `delta` line\nin its own colour:\n\n```svelte\n<div bind:this={chartEl}><SvChart {spec} /></div>\n\n<button onclick={() => api.exportData({\n format: 'pdf',\n filename: 'q3-report',\n pdf: {\n title: 'Q3 Orders',\n kpis: [\n { label: 'Revenue', value: '$1.24M', delta: '+4.2% vs Q2', color: '#16a34a' },\n { label: 'Orders', value: '842' },\n { label: 'Avg order', value: '$1,473', delta: '-1.1%', color: '#ef4444' },\n ],\n charts: [{ element: chartEl, title: 'Revenue by region', caption: 'Displayed rows, grouped by region' }],\n chartsPosition: 'above', // or 'below' the table\n },\n})}>Export report</button>\n```\n\nA chart block never splits across a page break. `resolvePdfCharts` and\n`buildPdfDocDefinition` are exported for a document you assemble yourself.\n\n#### Merged cells\n\nPass `merges` to write real merged regions into the sheet. Row / column\nindices are zero-based over the exported **body** (the header row is not\ncounted), and the shape lines up with the grid's own `MergeSpec`:\n\n```ts\n// Merge the first two data rows of column 0, and span a 3-column banner\nawait api.exportData({\n format: 'xlsx',\n merges: [\n { row: 0, col: 0, rowSpan: 2 }, // vertical merge (e.g. a repeated group key)\n { row: 5, col: 0, colSpan: 3 }, // horizontal merge (a section banner)\n ],\n})\n```\n\nTo export the merges you already show in the grid, take your `MergeSpec[]`\n(`{ rowIndex, columnId, rowspan, colspan }`) and map `columnId` to its column\nindex: `{ row: m.rowIndex, col: colIndex(m.columnId), rowSpan: m.rowspan, colSpan: m.colspan }`.\n\nThrows on missing peer (`jszip` / `pdfmake`), revoked / malformed\nlicense, or empty result set. With no license set, it runs but the\ngrid is watermarked.\n\n### `api.print(opts?)` - `Promise<void>`\n\nOpens a new window with a paginated, printable rendering of the grid and\ntriggers the browser print dialog. This is the **zero-dependency \"Save as PDF\"**\nroute: it uses the browser's own engine, so it has excellent font + CSS\nfidelity (including CJK / RTL) and needs no `pdfmake`. The header row repeats on\nevery page, values print **formatted** (matching the grid), and columns keep\ntheir alignment.\n\n| Option | Type | Default |\n| ------------- | -------------------------------------- | ----------- |\n| `title` | `string` | `\"Grid\"` |\n| `subtitle` | `string` | - |\n| `logo` | `string` (data URL) | - |\n| `columns` | `{ field; header?; format?; align? }[]`| grid's own columns |\n| `rows` | `ReadonlyArray<TData> \\| 'displayed' \\| 'selected' \\| 'all'` | `'displayed'` |\n| `rawValues` | `boolean` | `false` |\n| `orientation` | `'portrait' \\| 'landscape'` | `\"portrait\"` |\n| `pageSize` | `string` (e.g. `'A4'`, `'Letter'`) | browser default |\n| `margin` | `string` (e.g. `'14mm'`) | `'14mm'` |\n| `zebra` | `boolean` | `true` |\n| `headerColor` | `string` | `'#f1f5f9'` |\n\nBrowsers may block the popup unless `print()` is called from a user\ngesture (a click handler is fine - automatic on-load print is not). Page\nnumbers come from the browser's own print header/footer.\n\n**`exportData({ format: 'pdf' })` vs `print()`** - use PDF export for a\nprogrammatic, silent file download with full layout control (see \"PDF\noptions\"); use `print()` when you want best-fidelity output and the user to\npick print or \"Save as PDF\" from the dialog.\n\n## Drop-in Export menu (`SvExportMenu`)\n\nRather than wiring your own toolbar, drop in the bundled `SvExportMenu`\ncomponent. It renders an \"Export\" button with a format picker, a row-scope\ntoggle (current view / selected / all), and a built-in progress bar + Cancel\nfor large exports:\n\n```svelte\n<script lang=\"ts\">\n import { SvGrid, type SvGridApi } from '@svgrid/grid'\n import { installEnterprise, SvExportMenu, type EnterpriseGridApi } from '@svgrid/enterprise'\n\n let api = $state<EnterpriseGridApi<typeof features, Order> | null>(null)\n</script>\n\n<div class=\"toolbar\">\n <SvExportMenu {api} filename=\"orders\" />\n</div>\n\n<SvGrid data={rows} columns={columns} features={features}\n onApiReady={(a) => (api = installEnterprise(a))} />\n```\n\n| Prop | Type | Default | Notes |\n| ------------ | ------------------------------------------------ | --------------------------- | ----- |\n| `api` | `EnterpriseGridApi \\| null` | required | Button is disabled until the api is ready. |\n| `filename` | `string` | `'grid'` | Base name, no extension. |\n| `formats` | `ExportFormat[]` | xlsx/xls/pdf/csv/tsv/html | Which formats to offer, in order. |\n| `allowScope` | `boolean` | `true` | Show the current-view / selected / all toggle. |\n| `allowColumns` | `boolean` | `true` | Show per-column include checkboxes (choose which columns to export). |\n| `allowCopy` | `boolean` | `true` | Show \"Copy for Excel\" (tsv) + \"Copy Markdown\" clipboard actions. |\n| `allowPrint` | `boolean` | `false` | Show a \"Print…\" action (`api.print`). |\n| `scope` | `'displayed' \\| 'selected' \\| 'all'` | `'displayed'` | Initial row scope. |\n| `label` | `string` | `'Export'` | Button text. |\n| `conditionalFormats` | `ConditionalFormat[]` | - | Carried into pdf / xlsx / html exports. |\n\nThe menu is sectioned into **Rows** (scope), **Columns** (a picker), and\n**Download** (each format shown with an icon + one-line description), plus\n**copy-to-clipboard** and optional **print** actions. It's **keyboard\naccessible** (arrow keys move between items, Tab is trapped inside, Esc closes\nand returns focus to the button, with `role=\"menu\"` / `menuitem`), handles\nerrors inline (missing peer dependency, empty grid), and wires `onProgress` +\nan `AbortController` for you.\n\nFor large exports, the single-sheet xlsx writer builds in **chunks that yield to\nthe event loop** (and zips asynchronously), so the tab stays responsive and\n`onProgress` ticks; pass a `signal` to cancel.\n\n## Gotchas\n\n- **Empty grids** - both `exportData` and `print` throw if there are no\n displayed rows. Catch the error and show a notice in the UI.\n- **Column ordering** - if you don't pass `columns`, the export uses\n `Object.keys(rows[0])` order. Pass `columns` explicitly when the row\n shape doesn't match the column order you want.\n- **Cell formatters** - column-level format hints (date, number, currency,\n percent) are applied to the exported value by default, so the file matches\n the grid. Custom snippet renderers are **not** auto-serialized - give those\n columns an `exportValue` hook (see \"Faithful values\" above), or set\n `rawValues: true` if you want the raw underlying values.\n- **Print popup blocked** - `print()` resolves but the browser silently\n blocks the new window. Always trigger from a user click, and surface\n the thrown error.\n- **Bundle size** - the vendored exporter is ~50 KB minified. It is\n loaded lazily on first call so it does not bloat the initial bundle\n for users who never export.\n\n## Frequently asked questions\n\n### How do I export a Svelte data grid to Excel?\n\nInstall `@svgrid/enterprise`, call `installEnterprise(api)`, then call the export helper with\n`format: 'xlsx'`. The exporter writes a real OOXML workbook in the browser - no\nserver round-trip. CSV, TSV, PDF, and HTML use the same call with a different\nformat.\n\n### What's the difference between `xls` and `xlsx`?\n\n`xlsx` is the modern OOXML workbook (Excel 2007+); it needs the `jszip` peer\ndependency and supports the richest output (styles, images, multi-sheet,\nformulas). `xls` is the **legacy Excel 2003 XML Spreadsheet** format: pick it\nfor maximum compatibility with old Excel installs or systems that only accept\n`.xls`. It has **no peer dependency**, streams in the browser, and keeps\nnumbers and dates typed (so sums and sorting still work in Excel) with number\nformats applied. It's single-sheet - use `xlsx` for multi-tab workbooks.\n\n```ts\nawait api.exportData({ format: 'xls', filename: 'orders' })\n```\n\n### Is export part of the free Community package?\n\nNo. Export and printing ship in the paid `@svgrid/enterprise` add-on. The free\n`@svgrid/grid` package covers the full grid (sorting, filtering, grouping,\nediting, virtualization) but not export/print/pivot/import.\n\n### Does exporting bloat my bundle?\n\nNo. The ~50 KB exporter is lazy-loaded on the first export call, so users who\nnever export never download it.\n\n## More examples\n\n### Password-protected export\n\nPBKDF2 (100k iters) + AES-GCM 256 client-side. Strength meter, encrypt + download, in-page decrypt tool to verify the round-trip. Enterprise pack maps to ECMA-376 Agile encryption.\n\n<div data-docs-demo=\"93-password-protected-export\" data-height=\"460\"></div>\n\n### Formulas preserved in xlsx\n\nBuilds a real OOXML workbook in the browser via JSZip; computed columns export as <f>...</f> formula cells. Open in Excel and the math recomputes when you edit a number.\n\n<div data-docs-demo=\"101-formulas-in-xlsx\" data-height=\"460\"></div>\n\n### Export grouped grid to Excel\n\nA flat sales grid (Region → Country) exported via api.exportData({ format: \"xlsx\", groupBy }) which uses Smart's NATIVE Excel row outline grouping. Opens in Excel with +/- buttons in the row header gutter for every group level.\n\n<div data-docs-demo=\"126-export-grouped-grid\" data-height=\"460\"></div>\n\n### Export pivot grid to Excel\n\ncreatePivotModel leaves projected into an xlsx via api.exportData with groupBy: [\"region\"] - each region becomes an Excel outline group. Engine column ids (\"pv__Q1__m0\") translate to readable headers (\"Q1 · Revenue\").\n\n<div data-docs-demo=\"127-export-pivot-grid\" data-height=\"460\"></div>\n\n### Export - Formatting, scope + XLS\n\nFaithful export: currency / date / percent render as shown (toggle raw values), pick a row scope (view / selected / all), legacy .xls (Excel 2003 XML, no jszip), an exportValue hook, and the drop-in SvExportMenu.\n\n<div data-docs-demo=\"201-export-formatting-and-xls\" data-height=\"460\"></div>\n\n### Export - Grouped PDF + Print\n\nGroup the grid and export: the PDF + xlsx carry bold group headers and per-cluster subtotal rows (auto-carried from grouping state). Polished Print is the zero-dependency \"Save as PDF\" route with a repeated header and title.\n\n<div data-docs-demo=\"202-export-pdf-grouped-and-print\" data-height=\"460\"></div>\n\n## Try the export API\n\nEvery exporter is on the grid api and takes the same\n`GridExportOptions`. `rows: 'displayed'` is the default and is almost always\nwhat a user means by \"export this\" - it follows their filter and sort.\n\n```svelte\n<script lang=\"ts\">\n let api = $state<SvGridApi<{}, Person> | null>(null)\n</script>\n\n<div>\n <button type=\"button\" onclick={() => api?.exportCsv({ filename: 'people' })}>CSV</button>\n <button type=\"button\" onclick={() => api?.exportTsv({ filename: 'people' })}>TSV</button>\n <button type=\"button\" onclick={() => api?.exportJson({ filename: 'people' })}>JSON</button>\n <button type=\"button\" onclick={() => api?.print()}>Print</button>\n</div>\n\n<SvGrid data={people} {columns} sortable filterable onApiReady={(next) => (api = next)} />\n```\n\nSort or filter first, then export: the file follows the view.\n\n## Exporting a subset\n\n`columns` restricts the fields and fixes their order, and `rawValues` decides\nwhether the file carries what the screen shows or what the row holds. The\nsalary column is the one to watch - formatted it is `$142,000`, raw it is\n`142000`, and a spreadsheet can only do arithmetic on the second.\n\n```svelte\n<script lang=\"ts\">\n let api = $state<SvGridApi<{}, Person> | null>(null)\n</script>\n\n<div>\n <button type=\"button\" onclick={() => api?.exportCsv({ filename: 'formatted', columns: ['name', 'salary'] })}>\n Name + salary, as displayed\n </button>\n <button type=\"button\" onclick={() => api?.exportCsv({ filename: 'raw', columns: ['name', 'salary'], rawValues: true })}>\n Name + salary, raw values\n </button>\n</div>\n\n<SvGrid data={people} {columns} onApiReady={(next) => (api = next)} />\n```\n"
5476
+ "markdown": "# Data export and printing\n\n**CSV / TSV / JSON export and copy-to-clipboard are free** in the community\n**[@svgrid/grid](https://www.npmjs.com/package/@svgrid/grid)** - the commodity\n\"data out\" every grid needs. The richer formats - **Excel (xlsx)**, **legacy\nExcel (xls)**, **PDF**, styled **HTML**, **XML**, **Markdown**, multi-sheet\nworkbooks, password protection, conditional-format export, and the drop-in\nexport menu - ship in the paid\n**[@svgrid/enterprise](https://www.npmjs.com/package/@svgrid/enterprise)** add-on,\nwhich reuses the exact same serializers so the two tiers feel like one product.\n\nFor the report built step by step, with a live grid under most steps, see [Export: a report to Excel and PDF](./export/report.md); this page is the reference.\n\n![Pick a row scope, then serialize the grid to Excel, CSV, TSV, HTML, PDF, or Print.](/docs-media/grid-export.svg)\n\n| Capability | Package |\n| ---------- | ------- |\n| CSV / TSV / JSON export, copy-to-clipboard (TSV / CSV / Markdown) | **Free** (`@svgrid/grid`) |\n| Excel `.xlsx` (typed cells, styles, conditional formatting, tables, multi-sheet) | Enterprise |\n| PDF, styled HTML, XML, legacy `.xls`, password-protected export | Enterprise |\n| `exportValue` hook, conditional-format export, `SvExportMenu`, `print()` | Enterprise |\n\n## Free: CSV / TSV / JSON + clipboard\n\nThe community grid's `SvGridApi` carries four zero-dependency methods - no\nlicense, no peer deps:\n\nThe examples on this page run against these rows:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns, tableFeatures, rowSortingFeature, columnFilteringFeature } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n email: string\n department: string\n age: number\n salary: number\n city: string\n startDate: string\n active: boolean\n }\n\n type Order = {\n id: string\n customer: string\n product: string\n quantity: number\n total: number\n status: 'pending' | 'shipped' | 'delivered'\n orderedAt: string\n }\n\n type Row = Person\n\n const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })\n\n const people: Person[] = [\n { id: 1, name: 'Ada Lovelace', email: 'ada@example.com', department: 'Engineering', age: 36, salary: 142000, city: 'London', startDate: '2021-03-01', active: true },\n { id: 2, name: 'Grace Hopper', email: 'grace@example.com', department: 'Engineering', age: 45, salary: 168000, city: 'New York', startDate: '2019-07-15', active: true },\n { id: 3, name: 'Linus Torvalds', email: 'linus@example.com', department: 'Platform', age: 54, salary: 155000, city: 'Portland', startDate: '2020-01-20', active: false },\n { id: 4, name: 'Radia Perlman', email: 'radia@example.com', department: 'Networking', age: 49, salary: 161000, city: 'Seattle', startDate: '2022-09-05', active: true },\n { id: 5, name: 'Barbara Liskov', email: 'barbara@example.com', department: 'Platform', age: 52, salary: 172000, city: 'Boston', startDate: '2018-11-11', active: true },\n ]\n\n let rows = $state<Person[]>(people)\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 200 },\n { field: 'department', header: 'Department', width: 150 },\n { field: 'city', header: 'City', width: 140 },\n { field: 'age', header: 'Age', width: 90 },\n { field: 'salary', header: 'Salary', width: 130, format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```ts\nawait api.exportCsv({ filename: 'orders' }) // orders.csv (BOM + Excel-friendly)\nawait api.exportTsv() // grid.tsv\nawait api.exportJson({ rows: 'selected' }) // grid.json, checked rows only\nawait api.copyToClipboard({ format: 'tsv' }) // paste straight into Excel / Sheets\n```\n\nEvery method:\n\n- defaults to the **current view** (`rows: 'selected' | 'all'` to change),\n- formats values **as shown on screen** (currency, dates) - pass\n `rawValues: true` for the underlying values,\n- accepts a `columns: string[]` field subset (in that order),\n- runs on a chunked, cancelable loop (`signal`, `onProgress`) so a 100k-row\n export never freezes the tab,\n- returns the serialized text; pass `download: false` to skip the download\n and just get the string.\n\n**Formula injection.** A text cell that starts with `=`, `+`, `-`, `@`, a tab\nor a carriage return would run as a formula in the spreadsheet that opens the\nfile, so `exportCsv` and `exportTsv` (and Enterprise's `exportData` for csv and\ntsv) write it with a leading `'`: `=HYPERLINK(...)` comes out as\n`'=HYPERLINK(...)`. Numbers are never touched, and neither is a signed number\nin text form such as `-12.50`. Pass `escapeFormulas: false` when the file feeds\nanother program rather than a spreadsheet. `copyToClipboard` leaves text as\ntyped unless you pass `escapeFormulas: true`, because a copy is pasted by the\nperson who made it.\n\n```svelte {runnable}\n<script lang=\"ts\">\n import { SvGrid, tableFeatures, type SvGridApi } from '@svgrid/grid'\n let api = $state<SvGridApi<any, Row> | null>(null)\n</script>\n\n<button onclick={() => api?.exportCsv({ filename: 'orders' })}>Export CSV</button>\n<button onclick={() => api?.copyToClipboard()}>Copy for Excel</button>\n<SvGrid data={rows} columns={columns} features={features} onApiReady={(a) => (api = a)} />\n```\n\nThe rest of this page covers the **Enterprise** formats.\n\nTry the export bar below - downloads run in your browser; the bundled\nlicense key removes the unlicensed watermark:\n\n<div data-docs-demo=\"21-export-and-print\" data-height=\"500\"></div>\n\n\n## What it is\n\n`@svgrid/enterprise` augments the `SvGridApi` you already get from\n`<SvGrid onApiReady>` with two methods:\n\n- `api.exportData({ format, filename?, columns?, rows?, pageOrientation? })`\n- `api.print({ title?, columns?, rows?, orientation? })`\n\nBoth methods default to **the currently displayed rows** - sort, filter,\nor paginate the grid, and the export reflects that view automatically.\n\n## When to use it\n\n- Reporting flows where users want to take the grid offline (spreadsheets,\n emailed PDFs).\n- Compliance / audit trails that require a printable artifact.\n- Quick CSV/TSV pulls for downstream pipelines.\n\nIf you only need machine-readable data, prefer CSV / TSV - they have no\npeer dependencies and produce the smallest files. Use xlsx / PDF only\nwhen the recipient expects formatted documents.\n\n## Minimal example\n\n```svelte {runnable}\n<script lang=\"ts\">\n import { SvGrid, tableFeatures, rowSortingFeature, type SvGridApi, type ColumnDef } from '@svgrid/grid'\n import { installEnterprise, type EnterpriseGridApi } from '@svgrid/enterprise'\n\n // Without a key, the feature still works but the grid shows an\n // \"unlicensed\" watermark and the console emits a one-time nudge directing\n // users to the pricing page. After you buy, call setLicenseKey(yourKey)\n // once at startup.\n\n const features = tableFeatures({ rowSortingFeature })\n\n type Order = { company: string; product: string; price: number }\n const rows: Order[] = [\n { company: 'ACME', product: 'Widget', price: 19.95 },\n { company: 'Globex', product: 'Gadget', price: 49.00 },\n ]\n const columns: ColumnDef<typeof features, Order>[] = [\n { field: 'company', header: 'Company' },\n { field: 'product', header: 'Product' },\n { field: 'price', header: 'Price', format: { type: 'currency', currency: 'USD' } },\n ]\n\n let api = $state<EnterpriseGridApi<typeof features, Order> | null>(null)\n\n function onReady(next: SvGridApi<typeof features, Order>) {\n api = installEnterprise(next)\n }\n</script>\n\n<button onclick={() => api?.exportData({ format: 'xlsx', filename: 'orders' })}>\n Export Excel\n</button>\n<button onclick={() => api?.exportData({ format: 'pdf', filename: 'orders', pageOrientation: 'landscape' })}>\n Export PDF\n</button>\n<button onclick={() => api?.print({ title: 'Orders' })}>\n Print\n</button>\n\n<SvGrid data={rows} columns={columns} features={features} onApiReady={onReady} />\n```\n\n## Install\n\n```bash\npnpm add @svgrid/enterprise\n# Optional - install only the peers you actually use:\npnpm add jszip # required for xlsx\npnpm add pdfmake # required for pdf\n```\n\nCSV, TSV, HTML, and Print have **no extra dependencies**. The peer\ndependencies are lazy-loaded only when you call the format that needs\nthem.\n\n## Licensing\n\n`@svgrid/enterprise` has a tiered license gate:\n\n| Key state | Behavior |\n| ------------------------------------------ | -------- |\n| No key set (`setLicenseKey()` not called) | Feature works. Grid shows an unlicensed watermark linking to svgrid.com/pricing; console.log emits a one-time nudge. |\n| A key that is not your license key | Same as no key: the feature works, with the watermark and a one-time console warning. |\n| Your license key | Works silently. |\n\nBuy a production key at <https://svgrid.com/pricing/> ($599 / developer /\nyear). To evaluate, you need no key at all: everything runs with a watermark.\n\n## Reference\n\n### `setLicenseKey(key: string): void`\n\nStores the key in module state. Call once at app startup (e.g. in\n`main.ts`). Subsequent calls overwrite.\n\n### `clearLicenseKey(): void` · `hasValidLicense(): boolean` · `dismissUnlicensedNudge(): void`\n\nProgrammatic helpers. `hasValidLicense()` is useful when you want UI to\nbranch on license status. `dismissUnlicensedNudge()` removes the\nwatermark and stops the MutationObserver - call it after setting a\nvalid key if you loaded the module without one during testing.\n\n### `installEnterprise(api): EnterpriseGridApi`\n\nMutates the given `SvGridApi` to add `exportData` and `print`. Returns\nthe same object with the augmented type, so existing references keep\nworking.\n\n### `api.exportData(opts)` - `Promise<void>`\n\n| Option | Type | Default | Notes |\n| ----------------- | ----------------------------------------------------- | -------------------- | ----- |\n| `format` | `'xlsx' \\| 'xls' \\| 'pdf' \\| 'csv' \\| 'tsv' \\| 'html' \\| 'json' \\| 'xml' \\| 'md'` | required | `xlsx` needs `jszip`, `pdf` needs `pdfmake`. `xls` / CSV / TSV / HTML / JSON / XML / Markdown are dependency-free. |\n| `pdf` | `PdfExportOptions` | - | PDF layout: page size, margins, title / subtitle / logo, theme colors, column widths, repeated header, page numbers. See \"PDF options\". |\n| `conditionalFormats` | `ConditionalFormat[]` | - | Same array as `<SvGrid conditionalFormats>`; carried into pdf / xlsx / html. See \"Conditional formatting in exports\". |\n| `freezeHeader` | `boolean` | `true` | Freeze the header row (xlsx / xls). |\n| `freezeColumns` | `number` | pinned cols | Freeze this many leading columns (xlsx / xls). Defaults to the grid's left-pinned columns. |\n| `autoFitColumns` | `boolean` | `true` | Size columns to content (xlsx / xls); a column's explicit `width` wins. |\n| `precisionSafe` | `boolean` | `false` | Export long integer IDs (> 15 digits) as text so Excel's float precision doesn't round them (xlsx / xls). |\n| `excelTable` | `boolean \\| { totalsRow?; style? }` | - | Wrap single-sheet xlsx in a native Excel Table (filter dropdowns, banded rows; `{ totalsRow: true }` adds SUM formulas). |\n| `download` | `boolean` | `true` | When false, return the {@link ExportResult} without downloading. |\n| `filename` | `string` | `\"grid\"` | Extension is appended if missing. |\n| `columns` | `{ field; header?; format?; align?; exportValue? }[]` | grid's own columns | Drives column selection + header labels. Auto-derived from the grid (with each column's `format`) when omitted. See `exportValue` below. |\n| `rows` | `ReadonlyArray<TData> \\| 'displayed' \\| 'selected' \\| 'all'` | `'displayed'` | `'displayed'` = current filtered/sorted/paged view, `'selected'` = checked rows, `'all'` = full dataset, or pass an explicit array. |\n| `rawValues` | `boolean` | `false` | By default the exporter writes the **formatted display value** (what you see). Set `true` to write raw underlying values (numbers stay numeric in xlsx). |\n| `autoGroup` | `boolean` | `true` | Carry the grid's active row grouping into xlsx outline rows. Pass your own `groupBy` to override, or `false` to ignore. |\n| `csv` | `{ delimiter?; eol?; bom?; escapeFormulas? }` | `{ ',', '\\r\\n', BOM, escapeFormulas: true }` | CSV / TSV tuning. UTF-8 BOM is on by default so Excel opens it without mojibake. `escapeFormulas` prefixes formula-like text with `'` (see above). |\n| `onProgress` | `(p) => void` | - | Progress for large exports: `{ phase, ratio, row?, total? }`, `phase` = `'project' \\| 'serialize' \\| 'write'`. |\n| `signal` | `AbortSignal` | - | Cancel an in-flight export (checked between chunks). Rejects with `AbortError`. |\n| `pageOrientation` | `'portrait' \\| 'landscape'` | `\"portrait\"` | PDF only. |\n| `merges` | `{ row; col; rowSpan?; colSpan? }[]` | `[]` | Merged cells (xlsx / pdf). Zero-based **body** row/col (header excluded). Single-sheet only; mutually exclusive with `groupBy` / `hierarchical`. |\n\n### Faithful values (what you see is what you export)\n\nBy default the export renders each cell the way the grid does on screen: a\ncolumn with `format: { type: 'currency', currency: 'USD' }` exports `$19.95`,\na date column exports its formatted date, a percent column exports `42%`. This\nholds for **every** format (csv / tsv / html / pdf / xlsx). Pass\n`rawValues: true` to write the underlying values instead (e.g. feeding a data\npipeline that wants the numeric `19.95`).\n\nFor columns whose on-screen value comes from a **custom cell renderer**, a\n`fieldFn`, or a lookup, give the column an `exportValue` hook - it takes\nprecedence over `format` and the raw field:\n\n```ts\nawait api.exportData({\n format: 'xlsx',\n columns: [\n { field: 'company', header: 'Company' },\n // a column rendered with a custom snippet on screen:\n { field: 'status', header: 'Status', exportValue: (row) => STATUS_LABELS[row.status] },\n ],\n})\n```\n\n### Export only what's selected\n\n```ts\n// current view (default)\nawait api.exportData({ format: 'xlsx' })\n// only the checked rows\nawait api.exportData({ format: 'xlsx', rows: 'selected' })\n// the entire underlying dataset, ignoring filters/paging\nawait api.exportData({ format: 'csv', rows: 'all' })\n```\n\n### Large exports: progress + cancel\n\nCSV / TSV / HTML are serialized natively (no peer dependency) and stream in\nchunks, yielding to the event loop so a big export doesn't freeze the tab:\n\n```ts\nconst controller = new AbortController()\nawait api.exportData({\n format: 'csv',\n rows: 'all',\n signal: controller.signal,\n onProgress: ({ ratio }) => updateProgressBar(ratio),\n})\n// controller.abort() rejects the export with an AbortError\n```\n\n### Excel-native numbers (xlsx)\n\nA single-sheet `xlsx` export writes numeric, currency, percent, and date\ncolumns as **real typed cells** with an Excel number format - so Excel can sum\nand sort them, and they still display formatted (currency symbol, thousands,\n`%`, date pattern) - via SvGrid's own OOXML writer. Set `rawValues: true` for\nunformatted raw values. The grouped-outline, multi-sheet, image, and merged-cell\npaths use the bundled writer (formatted-string cells). The legacy `xls` format\nis always typed.\n\n### Excel fidelity: freeze, auto-fit, hyperlinks\n\n`xlsx` and `xls` exports polish the spreadsheet automatically:\n\n- **Freeze header** - the header row stays visible when scrolling. On by\n default; `freezeHeader: false` to disable, `freezeColumns: n` to also freeze\n leading columns.\n- **Auto-fit column widths** - columns are sized to their content. On by\n default (`autoFitColumns: false` to disable); a column's explicit `width`\n (pixels) always wins.\n- **Hyperlinks** - give a column a `link(row)` hook to render clickable links.\n Works in `xlsx`, `xls`, `html`, `pdf`, and `print`.\n\nSingle-sheet `xlsx` is written by SvGrid's own OOXML writer, so numbers/dates\nstay typed with number formats, conditional-format colors are **real per-cell\nfills**, and freeze/widths/hyperlinks all apply. (Grouped/outline, multi-sheet,\nembedded-image, and merged-cell exports use the bundled writer.)\n\n```ts\nawait api.exportData({\n format: 'xlsx',\n freezeHeader: true, // default\n columns: [\n { field: 'name', header: 'Company', width: 220,\n link: (row) => `https://crm.example.com/accounts/${row.id}` },\n { field: 'revenue', header: 'Revenue', format: { type: 'currency', currency: 'USD' } },\n ],\n})\n```\n\nConditional-format colors (data bars / color scales) already render as real\ncell fills in `xlsx`, which is higher fidelity than the writer's built-in\nrule-only conditional formatting - so we keep the per-cell approach.\n\n### Get the file instead of downloading (`download: false`)\n\n`exportData` returns an **`ExportResult`** for the dependency-free paths\n(csv/tsv/html/json/xml/md, xls, pdf, single-sheet xlsx) so you can preview,\nupload, email, or attach the file. With `download: false` it builds and returns\nthe file **without** triggering a browser download:\n\n```ts\nconst res = await api.exportData({ format: 'xlsx', download: false })\n// res: { blob, filename, mime, rowCount, byteSize }\nawait uploadToStorage(res.blob, res.filename)\n```\n\nThe grouped / multi-sheet / image / blanket-styled xlsx paths use the vendored\nwriter, which downloads directly and returns `undefined` (and throws on\n`download: false`).\n\n### Excel Table (filter dropdowns + totals row)\n\nWrap a single-sheet xlsx in a native **Excel Table** - the user gets column\nfilter dropdowns, banded rows, structured references, and (optionally) a totals\nrow with live `SUM()` formulas:\n\n```ts\nawait api.exportData({ format: 'xlsx', excelTable: { totalsRow: true } })\n// or just `excelTable: true` for the table without a totals row\n```\n\nColumn widths auto-fit and leading **pinned columns are frozen automatically**\n(override with `freezeColumns`). For long IDs, `precisionSafe: true` writes them\nas text so Excel's 15-digit float limit doesn't silently round `1002000300040005`.\n\n### JSON / XML / Markdown\n\n```ts\nawait api.exportData({ format: 'json' }) // array of { field: value } - defaults to raw values\nawait api.exportData({ format: 'xml' }) // <rows><row><field>value</field>…\nawait api.exportData({ format: 'md' }) // GitHub-flavored Markdown table (great for docs / LLMs)\n```\n\nJSON defaults to **raw** values (real numbers/dates) since it's a data format;\npass `rawValues: false` for formatted strings. XML and Markdown use the\nformatted display values.\n\n### Copy to clipboard\n\n`api.copyExport(opts)` serializes to the clipboard instead of downloading a\nfile - handy for \"copy these rows into a spreadsheet or an email\":\n\n```ts\nawait api.copyExport({ format: 'tsv' }) // pastes into Excel / Sheets as columns (default)\nawait api.copyExport({ format: 'md', rows: 'selected' }) // Markdown table of the checked rows\nawait api.copyExport({ format: 'html' }) // rich text/html - keeps the table when pasted\n```\n\nSupported formats: `csv`, `tsv`, `html`, `json`, `xml`, `md`. `html` writes\nboth `text/html` (rich paste) and a `text/plain` fallback. Needs a secure\ncontext and a user gesture (call it from a click).\n\n### Conditional formatting in exports\n\nPass the same `conditionalFormats` array you give `<SvGrid>` to carry the grid's\ncolor scales, data bars, icon sets, and predicate rules into the **styled**\nformats - PDF, xlsx, and HTML (and `print()`):\n\n```ts\nconst conditionalFormats = [\n { type: 'colorScale', columns: ['score'], min: '#dcfce7', max: '#fee2e2' },\n { type: 'rule', columns: ['status'], when: ({ value }) => value === 'Overdue', background: '#fecaca' },\n]\n\nawait api.exportData({ format: 'pdf', conditionalFormats })\nawait api.exportData({ format: 'xlsx', conditionalFormats }) // real cell fills in Excel\nawait api.print({ conditionalFormats })\n```\n\nCell background, text color, and bold carry through as **real cell fills** in\n`xlsx` (single-sheet), `xls`, `html`, and `pdf`; icon sets prepend their glyph\nto the cell text.\n\nIn **xlsx**, **data bars** and **color scales** become **native Excel\nconditional formatting** (`<conditionalFormatting>` rules) - Excel draws and\nrecomputes them itself, so they're interactive, not a static snapshot.\nPredicate `rule` formats stay as computed per-cell fills. In the other styled\nformats (`xls` / `html` / `pdf`) a data bar degrades to a light fill of the bar\ncolor (cells can't hold a partial-width bar). The data formats (csv / tsv /\njson / xml / md) are unstyled, so conditional formatting is ignored there.\nGrouped PDF exports skip conditional formatting (the group/subtotal rows own the\nlayout).\n\n### PDF options\n\nThe PDF is built from a full pdfmake document you control via `pdf`:\n\n```ts\nawait api.exportData({\n format: 'pdf',\n filename: 'orders',\n pdf: {\n pageSize: 'A4', // 'A4' | 'A3' | 'A5' | 'LETTER' | 'LEGAL'\n pageOrientation: 'landscape',\n title: 'Q3 Orders',\n subtitle: 'Generated by Ops',\n logo: logoDataUrl, // top-left image (data URL)\n headerColor: '#334155', // header row fill\n zebra: true, // striped rows\n columnWidths: '*', // '*' fill, 'auto', or a per-column pt array\n // repeatHeader (default true), showPageNumbers (default true) also available\n },\n})\n```\n\nThe header row repeats on every page, each page gets a `Page X of Y` +\ndate footer, per-column alignment is honored, and wide grids auto-switch to\nlandscape (override with `pdf.pageOrientation`).\n\nThe PDF looks like the grid it came from. With `pdf.matchTheme` (default\ntrue) the exporter reads the mounted grid's computed colours - header fill\nand text, body text, the zebra stripe, the lines, a group row's fill - so a\ngrid on the Ember theme or a Theme Builder palette prints in those colours\nrather than the slate defaults. A dark theme lends only its header: the\npage is white, so its body text and stripes would not read. The order of\nprecedence is explicit `pdf` colours (`headerColor`, `headerTextColor`,\n`textColor`, `zebraColor`, `borderColor`, `groupColor`, ...), then\n`styles`, then the theme, then the defaults. `styles.headerRow` /\n`styles.rows` / `styles.rowAlternate` / `styles.cells` (A1 references, row\n1 being the header) apply to the PDF table the way they do to xlsx and\nhtml, `header` / `footer` lines print above and below the table, and\n`merges` span data cells.\n\nWhen the grid is grouped, the PDF carries the grouping: a bold **group header**\nper cluster (nested for multi-level grouping) and a **subtotal row** summing the\nnumber / currency columns - matching the xlsx outline export. It's on by\ndefault (`autoGroup`); pass `groupBy` to override or `autoGroup: false` to get a\nflat table.\n\n#### Charts and a KPI strip\n\nA report is rarely just the table. `pdf.charts` prints charts with it: hand\nover the rendered chart's element (the `SvChart` wrapper or its `<svg>`) and\nthe export rasterises it at 2x through the chart's own PNG path, so the page\ngets the picture on screen, theme and all; or pass an image data URL you\nalready have. Each takes a `title`, a `caption` and a `width` in pt\n(default: the content width). `pdf.kpis` prints a strip of headline numbers\nabove the table, each with a label, the value and an optional `delta` line\nin its own colour:\n\n```svelte\n<div bind:this={chartEl}><SvChart {spec} /></div>\n\n<button onclick={() => api.exportData({\n format: 'pdf',\n filename: 'q3-report',\n pdf: {\n title: 'Q3 Orders',\n kpis: [\n { label: 'Revenue', value: '$1.24M', delta: '+4.2% vs Q2', color: '#16a34a' },\n { label: 'Orders', value: '842' },\n { label: 'Avg order', value: '$1,473', delta: '-1.1%', color: '#ef4444' },\n ],\n charts: [{ element: chartEl, title: 'Revenue by region', caption: 'Displayed rows, grouped by region' }],\n chartsPosition: 'above', // or 'below' the table\n },\n})}>Export report</button>\n```\n\nA chart block never splits across a page break. `resolvePdfCharts` and\n`buildPdfDocDefinition` are exported for a document you assemble yourself.\n\n#### Merged cells\n\nPass `merges` to write real merged regions into the sheet. Row / column\nindices are zero-based over the exported **body** (the header row is not\ncounted), and the shape lines up with the grid's own `MergeSpec`:\n\n```ts\n// Merge the first two data rows of column 0, and span a 3-column banner\nawait api.exportData({\n format: 'xlsx',\n merges: [\n { row: 0, col: 0, rowSpan: 2 }, // vertical merge (e.g. a repeated group key)\n { row: 5, col: 0, colSpan: 3 }, // horizontal merge (a section banner)\n ],\n})\n```\n\nTo export the merges you already show in the grid, take your `MergeSpec[]`\n(`{ rowIndex, columnId, rowspan, colspan }`) and map `columnId` to its column\nindex: `{ row: m.rowIndex, col: colIndex(m.columnId), rowSpan: m.rowspan, colSpan: m.colspan }`.\n\nThrows on missing peer (`jszip` / `pdfmake`), revoked / malformed\nlicense, or empty result set. With no license set, it runs but the\ngrid is watermarked.\n\n### `api.print(opts?)` - `Promise<void>`\n\nOpens a new window with a paginated, printable rendering of the grid and\ntriggers the browser print dialog. This is the **zero-dependency \"Save as PDF\"**\nroute: it uses the browser's own engine, so it has excellent font + CSS\nfidelity (including CJK / RTL) and needs no `pdfmake`. The header row repeats on\nevery page, values print **formatted** (matching the grid), and columns keep\ntheir alignment.\n\n| Option | Type | Default |\n| ------------- | -------------------------------------- | ----------- |\n| `title` | `string` | `\"Grid\"` |\n| `subtitle` | `string` | - |\n| `logo` | `string` (data URL) | - |\n| `columns` | `{ field; header?; format?; align? }[]`| grid's own columns |\n| `rows` | `ReadonlyArray<TData> \\| 'displayed' \\| 'selected' \\| 'all'` | `'displayed'` |\n| `rawValues` | `boolean` | `false` |\n| `orientation` | `'portrait' \\| 'landscape'` | `\"portrait\"` |\n| `pageSize` | `string` (e.g. `'A4'`, `'Letter'`) | browser default |\n| `margin` | `string` (e.g. `'14mm'`) | `'14mm'` |\n| `zebra` | `boolean` | `true` |\n| `headerColor` | `string` | `'#f1f5f9'` |\n\nBrowsers may block the popup unless `print()` is called from a user\ngesture (a click handler is fine - automatic on-load print is not). Page\nnumbers come from the browser's own print header/footer.\n\n**`exportData({ format: 'pdf' })` vs `print()`** - use PDF export for a\nprogrammatic, silent file download with full layout control (see \"PDF\noptions\"); use `print()` when you want best-fidelity output and the user to\npick print or \"Save as PDF\" from the dialog.\n\n## Drop-in Export menu (`SvExportMenu`)\n\nRather than wiring your own toolbar, drop in the bundled `SvExportMenu`\ncomponent. It renders an \"Export\" button with a format picker, a row-scope\ntoggle (current view / selected / all), and a built-in progress bar + Cancel\nfor large exports:\n\n```svelte\n<script lang=\"ts\">\n import { SvGrid, type SvGridApi } from '@svgrid/grid'\n import { installEnterprise, SvExportMenu, type EnterpriseGridApi } from '@svgrid/enterprise'\n\n let api = $state<EnterpriseGridApi<typeof features, Order> | null>(null)\n</script>\n\n<div class=\"toolbar\">\n <SvExportMenu {api} filename=\"orders\" />\n</div>\n\n<SvGrid data={rows} columns={columns} features={features}\n onApiReady={(a) => (api = installEnterprise(a))} />\n```\n\n| Prop | Type | Default | Notes |\n| ------------ | ------------------------------------------------ | --------------------------- | ----- |\n| `api` | `EnterpriseGridApi \\| null` | required | Button is disabled until the api is ready. |\n| `filename` | `string` | `'grid'` | Base name, no extension. |\n| `formats` | `ExportFormat[]` | xlsx/xls/pdf/csv/tsv/html | Which formats to offer, in order. |\n| `allowScope` | `boolean` | `true` | Show the current-view / selected / all toggle. |\n| `allowColumns` | `boolean` | `true` | Show per-column include checkboxes (choose which columns to export). |\n| `allowCopy` | `boolean` | `true` | Show \"Copy for Excel\" (tsv) + \"Copy Markdown\" clipboard actions. |\n| `allowPrint` | `boolean` | `false` | Show a \"Print…\" action (`api.print`). |\n| `scope` | `'displayed' \\| 'selected' \\| 'all'` | `'displayed'` | Initial row scope. |\n| `label` | `string` | `'Export'` | Button text. |\n| `conditionalFormats` | `ConditionalFormat[]` | - | Carried into pdf / xlsx / html exports. |\n\nThe menu is sectioned into **Rows** (scope), **Columns** (a picker), and\n**Download** (each format shown with an icon + one-line description), plus\n**copy-to-clipboard** and optional **print** actions. It's **keyboard\naccessible** (arrow keys move between items, Tab is trapped inside, Esc closes\nand returns focus to the button, with `role=\"menu\"` / `menuitem`), handles\nerrors inline (missing peer dependency, empty grid), and wires `onProgress` +\nan `AbortController` for you.\n\nFor large exports, the single-sheet xlsx writer builds in **chunks that yield to\nthe event loop** (and zips asynchronously), so the tab stays responsive and\n`onProgress` ticks; pass a `signal` to cancel.\n\n## Gotchas\n\n- **Empty grids** - both `exportData` and `print` throw if there are no\n displayed rows. Catch the error and show a notice in the UI.\n- **Column ordering** - if you don't pass `columns`, the export uses\n `Object.keys(rows[0])` order. Pass `columns` explicitly when the row\n shape doesn't match the column order you want.\n- **Cell formatters** - column-level format hints (date, number, currency,\n percent) are applied to the exported value by default, so the file matches\n the grid. Custom snippet renderers are **not** auto-serialized - give those\n columns an `exportValue` hook (see \"Faithful values\" above), or set\n `rawValues: true` if you want the raw underlying values.\n- **Print popup blocked** - `print()` resolves but the browser silently\n blocks the new window. Always trigger from a user click, and surface\n the thrown error.\n- **Bundle size** - the vendored exporter is ~50 KB minified. It is\n loaded lazily on first call so it does not bloat the initial bundle\n for users who never export.\n\n## Frequently asked questions\n\n### How do I export a Svelte data grid to Excel?\n\nInstall `@svgrid/enterprise`, call `installEnterprise(api)`, then call the export helper with\n`format: 'xlsx'`. The exporter writes a real OOXML workbook in the browser - no\nserver round-trip. CSV, TSV, PDF, and HTML use the same call with a different\nformat.\n\n### What's the difference between `xls` and `xlsx`?\n\n`xlsx` is the modern OOXML workbook (Excel 2007+); it needs the `jszip` peer\ndependency and supports the richest output (styles, images, multi-sheet,\nformulas). `xls` is the **legacy Excel 2003 XML Spreadsheet** format: pick it\nfor maximum compatibility with old Excel installs or systems that only accept\n`.xls`. It has **no peer dependency**, streams in the browser, and keeps\nnumbers and dates typed (so sums and sorting still work in Excel) with number\nformats applied. It's single-sheet - use `xlsx` for multi-tab workbooks.\n\n```ts\nawait api.exportData({ format: 'xls', filename: 'orders' })\n```\n\n### Is export part of the free Community package?\n\nNo. Export and printing ship in the paid `@svgrid/enterprise` add-on. The free\n`@svgrid/grid` package covers the full grid (sorting, filtering, grouping,\nediting, virtualization) but not export/print/pivot/import.\n\n### Does exporting bloat my bundle?\n\nNo. The ~50 KB exporter is lazy-loaded on the first export call, so users who\nnever export never download it.\n\n## More examples\n\n### Password-protected export\n\nPBKDF2 (100k iters) + AES-GCM 256 client-side. Strength meter, encrypt + download, in-page decrypt tool to verify the round-trip. Enterprise pack maps to ECMA-376 Agile encryption.\n\n<div data-docs-demo=\"93-password-protected-export\" data-height=\"460\"></div>\n\n### Formulas preserved in xlsx\n\nBuilds a real OOXML workbook in the browser via JSZip; computed columns export as <f>...</f> formula cells. Open in Excel and the math recomputes when you edit a number.\n\n<div data-docs-demo=\"101-formulas-in-xlsx\" data-height=\"460\"></div>\n\n### Export grouped grid to Excel\n\nA flat sales grid (Region → Country) exported via api.exportData({ format: \"xlsx\", groupBy }) which uses Smart's NATIVE Excel row outline grouping. Opens in Excel with +/- buttons in the row header gutter for every group level.\n\n<div data-docs-demo=\"126-export-grouped-grid\" data-height=\"460\"></div>\n\n### Export pivot grid to Excel\n\ncreatePivotModel leaves projected into an xlsx via api.exportData with groupBy: [\"region\"] - each region becomes an Excel outline group. Engine column ids (\"pv__Q1__m0\") translate to readable headers (\"Q1 · Revenue\").\n\n<div data-docs-demo=\"127-export-pivot-grid\" data-height=\"460\"></div>\n\n### Export - Formatting, scope + XLS\n\nFaithful export: currency / date / percent render as shown (toggle raw values), pick a row scope (view / selected / all), legacy .xls (Excel 2003 XML, no jszip), an exportValue hook, and the drop-in SvExportMenu.\n\n<div data-docs-demo=\"201-export-formatting-and-xls\" data-height=\"460\"></div>\n\n### Export - Grouped PDF + Print\n\nGroup the grid and export: the PDF + xlsx carry bold group headers and per-cluster subtotal rows (auto-carried from grouping state). Polished Print is the zero-dependency \"Save as PDF\" route with a repeated header and title.\n\n<div data-docs-demo=\"202-export-pdf-grouped-and-print\" data-height=\"460\"></div>\n\n## Try the export API\n\nEvery exporter is on the grid api and takes the same\n`GridExportOptions`. `rows: 'displayed'` is the default and is almost always\nwhat a user means by \"export this\" - it follows their filter and sort.\n\n```svelte\n<script lang=\"ts\">\n let api = $state<SvGridApi<{}, Person> | null>(null)\n</script>\n\n<div>\n <button type=\"button\" onclick={() => api?.exportCsv({ filename: 'people' })}>CSV</button>\n <button type=\"button\" onclick={() => api?.exportTsv({ filename: 'people' })}>TSV</button>\n <button type=\"button\" onclick={() => api?.exportJson({ filename: 'people' })}>JSON</button>\n <button type=\"button\" onclick={() => api?.print()}>Print</button>\n</div>\n\n<SvGrid data={people} {columns} sortable filterable onApiReady={(next) => (api = next)} />\n```\n\nSort or filter first, then export: the file follows the view.\n\n## Exporting a subset\n\n`columns` restricts the fields and fixes their order, and `rawValues` decides\nwhether the file carries what the screen shows or what the row holds. The\nsalary column is the one to watch - formatted it is `$142,000`, raw it is\n`142000`, and a spreadsheet can only do arithmetic on the second.\n\n```svelte\n<script lang=\"ts\">\n let api = $state<SvGridApi<{}, Person> | null>(null)\n</script>\n\n<div>\n <button type=\"button\" onclick={() => api?.exportCsv({ filename: 'formatted', columns: ['name', 'salary'] })}>\n Name + salary, as displayed\n </button>\n <button type=\"button\" onclick={() => api?.exportCsv({ filename: 'raw', columns: ['name', 'salary'], rawValues: true })}>\n Name + salary, raw values\n </button>\n</div>\n\n<SvGrid data={people} {columns} onApiReady={(next) => (api = next)} />\n```\n"
5470
5477
  },
5471
5478
  {
5472
5479
  "slug": "help/export/import-spreadsheet",
@@ -5704,7 +5711,7 @@ export const docs = [
5704
5711
  "path": "docs/help/migrating-from-ag-grid.md",
5705
5712
  "title": "Migrating from AG Grid to SvGrid",
5706
5713
  "section": "Help",
5707
- "markdown": "# Migrating from AG Grid to SvGrid\n\nIf you tried AG Grid on a Svelte 5 project - via `ag-grid-svelte`, the\nold `ag-grid-community/svelte`, or a hand-rolled wrapper - you probably\nhit the same friction everyone hits: the bridge between AG Grid's\nReact/Angular-first API and Svelte 5 runes is brittle, the bundle is\nheavy, and the Enterprise pricing only makes sense at scale.\n\n<!-- facts:start ag-grid -->\n> **Facts, checked 12 Sep 2026.** `ag-grid-community` 36.1.0, MIT, last published 5 Aug 2026, 12,400,000 npm downloads in the 30 days to 10 Sep 2026. `@svgrid/grid` 3.0.3, MIT, last published 11 Sep 2026, 16,900 npm downloads in the same window. Bundle, minified and gzipped, each package built alone with Svelte external: SvGrid 3.0.4 97.6 KB JS + 10.5 KB CSS (measured 22 Sep 2026); `ag-grid-community` 36.1.0 317.5 KB JS, no separate stylesheet (measured 12 Sep 2026). AG Grid pricing, as its site states it: AG Grid Community is free under MIT. AG Grid Enterprise is listed at $999 USD per developer with one year of updates and Zendesk support; the Enterprise Bundle with AG Charts Enterprise is $1,498 USD per developer (https://www.ag-grid.com/license-pricing/, read 12 Sep 2026). SvGrid: MIT core; @svgrid/enterprise from $299 per developer per year (Indie, under $1M revenue), $599 for Enterprise. Side by side, with sources: [SvGrid vs AG Grid (community + enterprise)](https://svgrid.com/compare/ag-grid/).\n<!-- facts:end -->\n\nThis page is a 30-minute migration recipe from AG Grid to SvGrid. It\ncovers what maps 1:1, what's different by design, and what you'll lose.\nWe tell you when **not** to switch at the bottom.\n\n## TL;DR\n\n| | AG Grid Community | AG Grid Enterprise | SvGrid Community | @svgrid/enterprise |\n| --- | --- | --- | --- | --- |\n| **Licence** | MIT | Commercial, per developer (the price is in the facts box above) | **MIT** | $599/dev/yr (grid) or $999/dev/yr (grid + spreadsheet + Studio) |\n| **Svelte 5 native** | No (community-built integration) | No (community-built integration) | Yes | Yes |\n| **Bundle (gzipped)** | measured, in the facts box above | not measured (licence) | measured, in the facts box above | lazy-loaded subpaths |\n| **Sorting / filtering** | Yes | Yes | Yes | (in Community) |\n| **Row grouping + aggregation** | No (Enterprise) | Yes | Yes (free) | (in Community) |\n| **Master/detail, tree, range select** | No (Enterprise) | Yes | Yes (free) | (in Community) |\n| **Set filter / Excel-style filter menu** | No (Enterprise) | Yes | Yes (free) | (in Community) |\n| **Server-side data, flat (infinite row model)** | Yes | Yes | Yes (free) | (in Community) |\n| **Server-side row model (grouping, tree, pivot, transactions, selection)** | No (Enterprise) | Yes | No | Yes |\n| **Integrated charts** | No (Enterprise) | Yes, AG Charts | Yes (free) | (in Community) |\n| **CSV export** | Yes (API) | Yes | Yes, with TSV and JSON | (in Community) |\n| **Excel export** | No | Yes | No | Yes |\n| **PDF / styled-HTML export, print** | No | No | No | Yes |\n| **Pivot tables** | No | Yes | No | Yes |\n| **MCP server for AI assistants** | Yes, `ag-mcp` | Yes | Yes, `@svgrid/mcp` | (in Community) |\n| **In-grid AI helpers** | No | No | Yes (bring your own model) | (in Community) |\n\n**SvGrid Community gives you most of what AG Grid sells as Enterprise for\nfree**, and `@svgrid/enterprise` adds Excel, PDF and print output, import,\npivot tables and the server-side row model per developer per year. Compare what each paid tier adds\nbefore comparing prices; both are in the facts box. The trade-offs are\nSvelte-only and a much smaller ecosystem. Every AG Grid cell above follows\nag-grid.com's own pages; the dated list is on the\n[SvGrid vs AG Grid](https://svgrid.com/compare/ag-grid/) page.\n\n## Mental model - what changes\n\nAG Grid is one big object you configure declaratively. SvGrid is a\n**headless engine** (`createSvGrid`) with an optional **render\ncomponent** (`<SvGrid>`) on top - the same split TanStack Table made\npopular. You can use either layer; most projects use the render\ncomponent.\n\nEvery example below runs against this setup:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature, type ColumnDef } from '@svgrid/grid'\n\n type Row = { id: number; make: string; model: string; price: number }\n\n const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })\n\n let rows = $state<Row[]>([\n { id: 1, make: 'Toyota', model: 'Celica', price: 35000 },\n { id: 2, make: 'Ford', model: 'Mondeo', price: 32000 },\n { id: 3, make: 'Porsche', model: 'Boxster', price: 72000 },\n ])\n const data = rows\n\n const columns: ColumnDef<typeof features, Row>[] = [\n { field: 'make', header: 'Make' },\n { field: 'model', header: 'Model' },\n { field: 'price', header: 'Price', format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```svelte\n<!-- AG Grid (via a Svelte wrapper) -->\n<AgGridSvelte\n gridOptions={{\n rowData: rows,\n columnDefs: columns,\n onGridReady: (params) => (gridApi = params.api),\n }}\n/>\n\n<!-- SvGrid -->\n<SvGrid\n data={rows}\n columns={columns}\n features={features}\n onApiReady={(api) => (gridApi = api)}\n/>\n```\n\nThree things to note:\n\n1. **No giant `gridOptions` blob.** Each capability is a top-level prop.\n2. **Features are opt-in.** You pass a `features` object built with\n `tableFeatures({...})` - only the features you list ship JS.\n3. **`onApiReady`** gives you a typed `SvGridApi` that is roughly the\n AG Grid `gridApi` equivalent (see the API-mapping table below).\n\n## Column definitions - direct translation\n\nThe shapes are similar enough that you can usually translate by hand\nwithout thinking too hard.\n\n```ts\n// AG Grid\nconst columnDefs: ColDef[] = [\n { field: 'name', headerName: 'Name', sortable: true, filter: true, width: 200 },\n { field: 'price', headerName: 'Price', type: 'numericColumn',\n valueFormatter: ({ value }) => `$${value.toFixed(2)}` },\n { field: 'date', headerName: 'Date',\n valueGetter: ({ data }) => new Date(data.date).toISOString().slice(0, 10) },\n { field: 'status', headerName: 'Status',\n cellRenderer: StatusCellRenderer,\n cellRendererParams: { onChange: handleStatusChange } },\n]\n```\n\n```ts\n// SvGrid\nimport { renderComponent, type ColumnDef } from '@svgrid/grid'\nimport StatusCell from './StatusCell.svelte'\n\nconst columns: ColumnDef<typeof features, Row>[] = [\n { field: 'name', header: 'Name', width: 200 }, // sortable + filterable by default\n { field: 'price', header: 'Price',\n format: { type: 'currency', currency: 'USD' } },\n { field: 'date', header: 'Date',\n format: { type: 'date', pattern: 'y-m-d' } },\n { field: 'status', header: 'Status',\n cell: renderComponent(StatusCell, (ctx) => ({\n value: ctx.getValue(),\n onChange: handleStatusChange,\n })),\n },\n]\n```\n\n### Property mapping\n\n| AG Grid | SvGrid | Notes |\n| --- | --- | --- |\n| `field` | `field` | Same. |\n| `headerName` | `header` | Accepts a string or a snippet/component. |\n| `width` | `width` | Same. |\n| `minWidth` / `maxWidth` | `minWidth` / `maxWidth` | Same. |\n| `sortable: true` | (default) | Sorting is on when `rowSortingFeature` is registered. |\n| `filter: true` | (default) | Filtering is on when `columnFilteringFeature` is registered. |\n| `valueFormatter` | `format: { ... }` | Built-in types: `number`, `currency`, `percent`, `date`. For custom, use `cell`. |\n| `valueGetter` | `fieldFn` | Returns the value for sorting/filtering. |\n| `cellRenderer` + `cellRendererParams` | `cell: renderComponent(C, ctx => props)` | One call, type-checked. |\n| `cellEditor: 'agTextCellEditor'` | `editorType: 'text'` | Built-in: `text`, `number`, `checkbox`, `date`. |\n| `editable: true` | `enableInlineEditing` prop on `<SvGrid>` | Per-grid, not per-column. (Per-column control on the roadmap.) |\n| `pinned: 'left'` / `'right'` | Right-click column menu → Pin | Set programmatically via the api. |\n| `rowGroup: true` | Via `setGroupBy([colId])` | See Grouping below. |\n| `aggFunc: 'sum'` | `aggregate: 'sum'` | Built-in: `sum`, `avg`, `min`, `max`, `count`. |\n\n## Feature registration - the one new thing\n\nAG Grid auto-enables most features; you turn them off. SvGrid is the\nopposite - features are opt-in. The result is a smaller bundle.\n\n```ts\nimport {\n tableFeatures,\n rowSortingFeature,\n columnFilteringFeature,\n columnGroupingFeature,\n rowExpandingFeature,\n rowPaginationFeature,\n rowSelectionFeature,\n} from '@svgrid/grid'\n\nconst features = tableFeatures({\n rowSortingFeature,\n columnFilteringFeature,\n rowSelectionFeature,\n // omit any you don't need - their code won't ship\n})\n```\n\nPass `features` to `<SvGrid>` once. From then on the grid behaves like\nAG Grid's `enableSorting`, `enableFilter`, `rowSelection`, etc. are all\non for the registered features.\n\n## API mapping (`gridApi` → `SvGridApi`)\n\nYou get the SvGrid API from `onApiReady` (equivalent to AG Grid's\n`onGridReady`).\n\n| AG Grid `gridApi.X()` | SvGrid `api.X()` |\n| --- | --- |\n| `setRowData(rows)` | (declarative - just update `data` prop) |\n| `addRow(row)` / `applyTransaction({ add: [row] })` | `api.addRow(row)` / `api.addRows(rows)` |\n| `applyTransaction({ remove: [row] })` | `api.removeRow(rowIndex)` |\n| `getValue(colId, rowNode)` | `api.getCellValue(rowIndex, columnId)` |\n| `setValue(...)` | `api.setCellValue(rowIndex, columnId, value)` |\n| `setColumnVisible(colId, visible)` | `api.setColumnVisible(columnId, visible)` |\n| `getSortModel()` / `setSortModel()` | `api.setSort(columnId, 'asc'\\|'desc'\\|null)` |\n| `setFilterModel({...})` | `api.setFilter(columnId, { operator, value })` |\n| `getDisplayedRowAtIndex(i)` / `forEachNodeAfterFilterAndSort(...)` | `api.getDisplayedRows()` |\n| `getModel()` (raw rows) | `api.getData()` |\n\n## Common patterns\n\n### Sorting + filtering + pagination (the 80% case)\n\n```svelte\n<script lang=\"ts\">\n import {\n SvGrid,\n tableFeatures,\n rowSortingFeature,\n columnFilteringFeature,\n rowPaginationFeature,\n } from '@svgrid/grid'\n\n const features = tableFeatures({\n rowSortingFeature,\n columnFilteringFeature,\n rowPaginationFeature,\n })\n</script>\n\n<SvGrid\n data={rows}\n columns={columns}\n features={features}\n showPagination\n showColumnFilters\n/>\n```\n\nAG Grid equivalent: `gridOptions: { defaultColDef: { sortable: true, filter: true }, pagination: true }`.\n\n### Cell editing with persistence\n\n```svelte\n<script lang=\"ts\">\n function onCellValueChange(e: { rowIndex: number; columnId: string; value: unknown }) {\n // Persist however you like (fetch to backend, optimistic local update, etc.)\n console.log('cell changed', e)\n }\n</script>\n\n<SvGrid\n data={rows}\n columns={columns}\n features={features}\n enableInlineEditing\n onCellValueChange={onCellValueChange}\n/>\n```\n\nAG Grid equivalent: `onCellValueChanged: ({ data, colDef, newValue, oldValue }) => ...`.\nSvGrid's event payload is column-id + row-index based rather than node-based; the row data is yours\nto mutate (or not) on the `rows` array you passed in.\n\n### Grouping + aggregation\n\n```svelte\n<script lang=\"ts\">\n import {\n SvGrid,\n tableFeatures,\n columnGroupingFeature,\n rowSortingFeature,\n rowExpandingFeature,\n } from '@svgrid/grid'\n\n const features = tableFeatures({\n rowSortingFeature,\n columnGroupingFeature,\n rowExpandingFeature,\n })\n\n const columns = [\n { field: 'department', header: 'Department' },\n { field: 'team', header: 'Team' },\n { field: 'salary', header: 'Salary', aggregate: 'sum',\n format: { type: 'currency', currency: 'USD' } },\n ]\n\n function setGroup(api) {\n api.setGroupBy(['department', 'team'])\n }\n</script>\n\n<SvGrid\n data={rows}\n columns={columns}\n features={features}\n showGroupingControls\n onApiReady={setGroup}\n/>\n```\n\nAG Grid Enterprise's `rowGroupPanelShow: 'always'` + `aggFunc: 'sum'` translates 1:1.\n\n### Master / detail\n\nAG Grid Enterprise feature; **free in SvGrid Community**. See\n[demo 08](https://svgrid.com/demos/08-tree-and-master-detail/) for the exact pattern.\n\n### Server-side data\n\nAG Grid's Infinite Row Model (Community) and Server-Side Row Model\n(Enterprise) both take an `IServerSideDatasource` with a `getRows(params)`\nthat answers through `params.success({ rowData, rowCount })`. SvGrid has one\n`ServerDataSource` whose `getRows(request)` returns `{ rows, rowCount }`,\nand two controllers over it: `createServerDataSource` (free: paging or\ninfinite block scroll, sort, filter, CRUD) and `createServerRowModel`\n(Enterprise: lazy grouping, tree, pivot, transactions, selection). Both\nmount through one prop, `<SvGrid rowModel={ctl} />`.\n\nAn existing datasource written for AG Grid keeps working behind one call:\n\n```ts\nimport { adaptCallbackDatasource, createServerRowModel } from '@svgrid/enterprise'\n\nconst ctl = createServerRowModel(adaptCallbackDatasource(myServerSideDatasource), {\n groupBy: ['country'],\n aggregations: [{ col: 'amount', fn: 'sum' }],\n})\n```\n\n`adaptCallbackDatasource` maps the request both ways (`rowGroupCols` ->\n`groupBy`, `valueCols` -> `aggregations`, `pivotCols` -> `pivotBy`, the\nsort and filter models, `context`, `parentNode`) and turns `success` /\n`fail` into a resolved or rejected promise.\n\nMore often the datasource is a thin `fetch` and the real investment is the\nendpoint behind it - a Java or Node service that parses AG Grid's\n`IServerSideGetRowsRequest` JSON. That endpoint stays as it is: post\n`toCallbackRequest(request)` and read the answer back.\n\n```ts\nimport { toCallbackRequest } from '@svgrid/enterprise'\n\nconst source = {\n async getRows(request) {\n const res = await fetch('/api/sales', {\n method: 'POST',\n headers: { 'content-type': 'application/json' },\n body: JSON.stringify(toCallbackRequest(request)),\n })\n const { rowData, rowCount, pivotResultFields } = await res.json()\n return { rows: rowData, rowCount: rowCount ?? -1, pivotResultFields }\n },\n}\n```\n\n`fromCallbackRequest` is the other direction, for a SvelteKit endpoint that\nhas to keep serving an AG Grid client during the switch. A saved selection\nor a bulk endpoint written against `getServerSideSelectionState()` keeps\nits shape the same way: `toCallbackSelectionState(ctl.getSelectionState())`\nproduces `{ selectAll, toggledNodes }` (or the `nodeId` /\n`selectAllChildren` / `toggledNodes` tree), `ctl.setSelectionState` takes\nthat shape as it is when your group node ids are the group keys, and\n`fromCallbackSelectionState(state, { groupKey, isGroup })` maps them when\na `getRowId` gave group rows ids of their own. Option by option:\n\n| AG Grid | SvGrid |\n| --- | --- |\n| `rowModelType: 'infinite'` + `datasource` | `createServerDataSource(source, { mode: 'infinite' })` + `rowModel={ctl}` |\n| `rowModelType: 'serverSide'` + `serverSideDatasource` | `createServerRowModel(source, options)` + `rowModel={ctl}` |\n| `getRows(params)` + `params.success({ rowData, rowCount })` / `params.fail()` | `getRows(request)` returning `{ rows, rowCount }` / throwing |\n| `cacheBlockSize`, `maxBlocksInCache`, `maxConcurrentDatasourceRequests`, `blockLoadDebounceMillis` | `blockSize`, `maxBlocksInCache`, `maxConcurrentRequests`, `blockLoadDebounceMs` |\n| `infiniteInitialRowCount` / `serverSideInitialRowCount` | `initialRowCount` |\n| `rowCount: -1` (unknown) | `rowCount: -1` |\n| `refreshInfiniteCache()` / `purgeInfiniteCache()` | `ctl.refresh()` / `ctl.purge()` |\n| `request.rowGroupCols`, `groupKeys`, `valueCols`, `pivotCols`, `pivotMode` | `request.groupBy`, `groupKeys`, `aggregations`, `pivotBy`, `pivotMode` |\n| `getChildCount(data)` | `childCount: (row) => row.childCount` |\n| `isServerSideGroupOpenByDefault` | `isGroupOpenByDefault(route, row)` |\n| `getServerSideGroupLevelParams` | `levelParams(level, route)` |\n| `isServerSideGroup` / `getServerSideGroupKey` (tree) | `treeData: true` + `hasChildren` / `getRowId` |\n| `grandTotalRow` / `groupTotalRow` | `grandTotalRow` / `groupFooters` |\n| `refreshServerSide({ route, purge })` / `retryServerSideLoads()` | `ctl.refresh({ route, purge })` / `ctl.retryLoads()` |\n| `applyServerSideTransaction` / `applyServerSideTransactionAsync` / `flushServerSideAsyncTransactions` | `ctl.applyTransaction` / `applyTransactionAsync` / `flushAsyncTransactions` |\n| `applyServerSideRowData` | `ctl.applyRowData` |\n| `serverSideSortAllLevels`, `serverSideEnableClientSideSort`, `serverSideOnlyRefreshFilteredGroups` | `sortAllLevels`, `clientSideSort`, `onlyRefreshFilteredGroups` |\n| `getServerSideSelectionState` / `setServerSideSelectionState` | `ctl.getSelectionState()` / `setSelectionState()` (the `toggledNodes` shape is accepted; `toCallbackSelectionState` / `fromCallbackSelectionState` convert) |\n| `ServerSideTransactionResult.status`: `Applied`, `StoreNotFound`, `StoreLoading`, `StoreWaitingToLoad`, `StoreLoadingFailed`, `Cancelled` | `ServerTransactionResult.status`: the same six, lower camel case (`applied`, `storeNotFound`, ...) - a `switch` on the old spelling falls through silently |\n| `groupSelects: 'descendants'` | `selection: { groupSelects: 'descendants' }` |\n| `pivotResultFields` in `success`, `setPivotResultColumns`, `processPivotResultColDef` | `pivotResultFields` / `pivotResultColumns` in the result, `pivotResultColumn(field, def)` |\n| `pagination` + `paginateChildRows` | `pagination: { pageSize, paginateChildRows }` |\n| `getCacheBlockState()` / `getServerSideGroupLevelState()` | `ctl.getCacheState()` / `ctl.levelStates()` |\n| `serverSideDatasource.destroy()` | `source.destroy()` |\n\nTwo differences worth knowing before you start: SvGrid sends the global\nsearch box to the server as `filterModel.global` (AG Grid's quick filter is\nclient-side only and unsupported under its infinite and server-side models),\nand SvGrid has no viewport row model. See\n[Server grouping](./server/server-grouping.md) and\n[demo 467](https://svgrid.com/demos/467-server-row-model-1m/).\n\n### Excel / PDF export\n\nAG Grid: `gridApi.exportDataAsExcel({...})` (Enterprise-only).\nSvGrid: install `@svgrid/enterprise`, call `api.exportData({ format: 'xlsx', ... })`. See [Data export and printing](./export.md).\n\n```ts\nimport { installEnterprise, setLicenseKey } from '@svgrid/enterprise'\nsetLicenseKey('YOUR-LICENSE-KEY') // your Enterprise key\n\n// inside onApiReady:\nconst pro = installEnterprise(api)\nawait pro.exportData({ format: 'xlsx', filename: 'orders' })\n```\n\n## Gotchas - things that don't translate directly\n\n### 1. Per-column `editable: true`\nEditing is switched on at the grid level (`enableInlineEditing`) and\nnarrowed per column with `editable: boolean | (ctx) => boolean` on the\ncolumn definition, so AG Grid's per-column flag and its callback form both\nmap directly. What does not map is AG Grid's `editable` on a column\ngroup: set it on each child column.\n\n### 2. Column drag-to-reorder\nHeader drag is `enableColumnReorder` on `<SvGrid>`; `setColumnOrder`\non the API does the same from code. See\n[column moving](./columns/column-moving.md) for the events.\n\n### 3. AG Grid `valueGetter` chains\nAG Grid's `valueGetter` can read other column values via the API. In\nSvGrid, `fieldFn` only receives the row; if you need cross-column\ncomputed values, do it in the cell renderer with `ctx.row.original` or\ncompute the derived value upstream and store it in the row.\n\n### 4. `cellClass` / `rowClass` callbacks\nOn the roadmap. For now, render a wrapper element in your `cell` snippet\nwith the conditional class.\n\n### 5. The Status Bar / Side Bar / Tool Panels\nAG Grid's chrome (status bar with row count, side bar with filters and\ncolumns panels) doesn't exist in SvGrid - build it as plain Svelte\nmarkup around the grid. Most teams build their own anyway because\nAG Grid's defaults rarely match a polished design system.\n\n### 6. Set filter (the Excel-style funnel popup)\nSvGrid ships an Excel-style filter menu (free in Community). API surface\nis similar but not identical - see [Set filter](./filtering/set-filter.md).\n\n## When NOT to migrate\n\nBe honest. Stay on AG Grid if you:\n\n- **Use multiple frameworks** - AG Grid has React, Angular, Vue, Solid, Qwik, vanilla adapters. SvGrid is Svelte-only.\n- **Need a push-based viewport row model** - SvGrid's server-side row model covers grouping, tree, pivot, transactions and select-all across unloaded rows, and its real-time page merges deltas into loaded rows, but the server cannot push the visible window over a socket the way the viewport model does.\n- **Need custom tool panels** - SvGrid's tool panel is a fixed Columns + Filters pair. (Custom filter components are covered: a column's `customFilter` renders your own control in the filter menu, the floating filter row and the Filters tab.)\n- **Are mid-project and shipping in <2 weeks** - the migration is a few hours per grid, but only do it when you have buffer.\n- **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.)\n\nIf none of those apply: switching drops a per-developer Enterprise licence\nfor features that are in SvGrid's MIT core, cuts the bundle by the\ndifference in the facts box above, and gives you a Svelte-native API that\nplays well with runes.\n\n## Step-by-step migration\n\nA typical migration of a single grid takes 1-3 hours:\n\n1. **Install** - `pnpm add @svgrid/grid` (and `@svgrid/enterprise` if you need export).\n2. **Translate columnDefs** - use the mapping table above. Most columns are 1:1.\n3. **Wrap features** - figure out which AG Grid features you actually use; register only those in `tableFeatures({...})`.\n4. **Swap the component** - `<AgGridSvelte gridOptions={...}>` → `<SvGrid data={rows} columns={columns} features={features}>`.\n5. **Move event handlers** - AG Grid `onCellValueChanged` → SvGrid `onCellValueChange` (signature differs slightly, see above).\n6. **Move API calls** - AG Grid `gridApi.X()` → SvGrid `api.X()` per the API table.\n7. **Test interactions** - sort, filter, edit, select. Most \"just works.\"\n8. **Remove `ag-grid-*` packages** - `pnpm remove ag-grid-community ag-grid-svelte` etc. Inspect your bundle to confirm the drop; the facts box above has both measured sizes.\n\n## Need help migrating?\n\nEnterprise customers get **migration help included** with the support plan\n(architecture review, port one grid for you as a reference). Email\n`support@jqwidgets.com` after purchase, or `sales@jqwidgets.com` for\npre-sales questions.\n\n## Frequently asked questions\n\n### Is SvGrid a drop-in replacement for AG Grid in Svelte?\n\nNot a literal drop-in - there is no `ag-grid-svelte` shim to swap. But the\nconcepts map closely: column definitions, row models, sorting, filtering,\ngrouping, and an imperative API all have direct SvGrid equivalents, so most\nteams port a grid in 30 minutes to a day. It is a configuration translation,\nnot a rewrite.\n\n### What is the SvGrid equivalent of AG Grid Enterprise?\n\n`@svgrid/enterprise`. It adds Excel/PDF/styled-HTML export (CSV, TSV and JSON export are already free in the grid), a printable view, pivot\ntables and data import. The in-grid AI helpers are free in `@svgrid/grid`.\nIt is licensed per developer ($599 for the grid, $999 with the spreadsheet\nand Studio, both covering unlimited apps), and the\nCommunity package is MIT-licensed and free for commercial use.\n\n### Does SvGrid use Svelte 5 runes, or is it a wrapper?\n\nIt is Svelte-5-native. State is `$state` / `$derived` / `$effect` and cells\nrender through Svelte snippets - there is no React or Angular core underneath\nand no framework bridge to keep in sync.\n\n### Will my AG Grid bundle size shrink?\n\nAlmost always. The facts box at the top of this page has both packages\nmeasured the same way on the same date: the full SvGrid render component\nwith its stylesheet against `createGrid` with every AG Grid Community\nmodule registered. You add `@svgrid/enterprise` features only where you\nimport them, and the headless core on its own is a small fraction of the\nrender component.\n\n## More examples\n\n### AG Grid ↔ sv-grid side-by-side\n\nTwo real grids over the same dataset: the installed AG Grid Community on the left, sv-grid on the right. Same global filter drives both. Source code panels for either side.\n\n<div data-docs-demo=\"139-migration-from-ag-grid\" data-height=\"460\"></div>\n\n## See also\n\n- [Getting started](../getting-started.md) - full SvGrid walkthrough\n- [Why headless?](../why-headless.md) - the headless / render-component split\n- [Data export and printing](./export.md) - the `@svgrid/enterprise` feature pack\n- [Comparison: SvGrid vs AG Grid vs TanStack Table](./comparison.md) - the\n measured benchmark and the feature matrix\n- [SvGrid vs AG Grid comparison page](https://svgrid.com/compare/ag-grid/) -\n every claim with its source and date\n"
5714
+ "markdown": "\n# Migrating from AG Grid to SvGrid\n\nIf you tried AG Grid on a Svelte 5 project - via `ag-grid-svelte`, the\nold `ag-grid-community/svelte`, or a hand-rolled wrapper - you probably\nhit the same friction everyone hits: the bridge between AG Grid's\nReact/Angular-first API and Svelte 5 runes is brittle, the bundle is\nheavy, and the Enterprise pricing only makes sense at scale.\n\n<!-- facts:start ag-grid -->\n> **Facts, checked 12 Sep 2026.** `ag-grid-community` 36.1.0, MIT, last published 5 Aug 2026, 12,400,000 npm downloads in the 30 days to 10 Sep 2026. `@svgrid/grid` 3.0.3, MIT, last published 11 Sep 2026, 16,900 npm downloads in the same window. Bundle, minified and gzipped, each package built alone with Svelte external: SvGrid 3.0.4 97.6 KB JS + 10.5 KB CSS (measured 22 Sep 2026); `ag-grid-community` 36.1.0 317.5 KB JS, no separate stylesheet (measured 12 Sep 2026). AG Grid pricing, as its site states it: AG Grid Community is free under MIT. AG Grid Enterprise is listed at $999 USD per developer with one year of updates and Zendesk support; the Enterprise Bundle with AG Charts Enterprise is $1,498 USD per developer (https://www.ag-grid.com/license-pricing/, read 12 Sep 2026). SvGrid: MIT core; @svgrid/enterprise from $299 per developer per year (Indie, under $1M revenue), $599 for Enterprise. Side by side, with sources: [SvGrid vs AG Grid (community + enterprise)](https://svgrid.com/compare/ag-grid/).\n<!-- facts:end -->\n\nThis page is a 30-minute migration recipe from AG Grid to SvGrid. It\ncovers what maps 1:1, what's different by design, and what you'll lose.\nWe tell you when **not** to switch at the bottom.\n\n## TL;DR\n\n| | AG Grid Community | AG Grid Enterprise | SvGrid Community | @svgrid/enterprise |\n| --- | --- | --- | --- | --- |\n| **Licence** | MIT | Commercial, per developer (the price is in the facts box above) | **MIT** | $599/dev/yr (grid) or $999/dev/yr (grid + spreadsheet + Studio) |\n| **Svelte 5 native** | No (community-built integration) | No (community-built integration) | Yes | Yes |\n| **Bundle (gzipped)** | measured, in the facts box above | not measured (licence) | measured, in the facts box above | lazy-loaded subpaths |\n| **Sorting / filtering** | Yes | Yes | Yes | (in Community) |\n| **Row grouping + aggregation** | No (Enterprise) | Yes | Yes (free) | (in Community) |\n| **Master/detail, tree, range select** | No (Enterprise) | Yes | Yes (free) | (in Community) |\n| **Set filter / Excel-style filter menu** | No (Enterprise) | Yes | Yes (free) | (in Community) |\n| **Server-side data, flat (infinite row model)** | Yes | Yes | Yes (free) | (in Community) |\n| **Server-side row model (grouping, tree, pivot, transactions, selection)** | No (Enterprise) | Yes | No | Yes |\n| **Integrated charts** | No (Enterprise) | Yes, AG Charts | Yes (free) | (in Community) |\n| **CSV export** | Yes (API) | Yes | Yes, with TSV and JSON | (in Community) |\n| **Excel export** | No | Yes | No | Yes |\n| **PDF / styled-HTML export, print** | No | No | No | Yes |\n| **Pivot tables** | No | Yes | No | Yes |\n| **MCP server for AI assistants** | Yes, `ag-mcp` | Yes | Yes, `@svgrid/mcp` | (in Community) |\n| **In-grid AI helpers** | No | No | Yes (bring your own model) | (in Community) |\n\n**SvGrid Community gives you most of what AG Grid sells as Enterprise for\nfree**, and `@svgrid/enterprise` adds Excel, PDF and print output, import,\npivot tables and the server-side row model per developer per year. Compare what each paid tier adds\nbefore comparing prices; both are in the facts box. The trade-offs are\nSvelte-only and a much smaller ecosystem. Every AG Grid cell above follows\nag-grid.com's own pages; the dated list is on the\n[SvGrid vs AG Grid](https://svgrid.com/compare/ag-grid/) page.\n\n## Mental model - what changes\n\nAG Grid is one big object you configure declaratively. SvGrid is a\n**headless engine** (`createSvGrid`) with an optional **render\ncomponent** (`<SvGrid>`) on top - the same split TanStack Table made\npopular. You can use either layer; most projects use the render\ncomponent.\n\nEvery example below runs against this setup:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature, type ColumnDef } from '@svgrid/grid'\n\n type Row = { id: number; make: string; model: string; price: number }\n\n const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })\n\n let rows = $state<Row[]>([\n { id: 1, make: 'Toyota', model: 'Celica', price: 35000 },\n { id: 2, make: 'Ford', model: 'Mondeo', price: 32000 },\n { id: 3, make: 'Porsche', model: 'Boxster', price: 72000 },\n ])\n const data = rows\n\n const columns: ColumnDef<typeof features, Row>[] = [\n { field: 'make', header: 'Make' },\n { field: 'model', header: 'Model' },\n { field: 'price', header: 'Price', format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```svelte\n<!-- AG Grid (via a Svelte wrapper) -->\n<AgGridSvelte\n gridOptions={{\n rowData: rows,\n columnDefs: columns,\n onGridReady: (params) => (gridApi = params.api),\n }}\n/>\n\n<!-- SvGrid -->\n<SvGrid\n data={rows}\n columns={columns}\n features={features}\n onApiReady={(api) => (gridApi = api)}\n/>\n```\n\nThree things to note:\n\n1. **No giant `gridOptions` blob.** Each capability is a top-level prop.\n2. **Features are opt-in.** You pass a `features` object built with\n `tableFeatures({...})` - only the features you list ship JS.\n3. **`onApiReady`** gives you a typed `SvGridApi` that is roughly the\n AG Grid `gridApi` equivalent (see the API-mapping table below).\n\n## Column definitions - direct translation\n\nThe shapes are similar enough that you can usually translate by hand\nwithout thinking too hard.\n\n```ts\n// AG Grid\nconst columnDefs: ColDef[] = [\n { field: 'name', headerName: 'Name', sortable: true, filter: true, width: 200 },\n { field: 'price', headerName: 'Price', type: 'numericColumn',\n valueFormatter: ({ value }) => `$${value.toFixed(2)}` },\n { field: 'date', headerName: 'Date',\n valueGetter: ({ data }) => new Date(data.date).toISOString().slice(0, 10) },\n { field: 'status', headerName: 'Status',\n cellRenderer: StatusCellRenderer,\n cellRendererParams: { onChange: handleStatusChange } },\n]\n```\n\n```ts\n// SvGrid\nimport { renderComponent, type ColumnDef } from '@svgrid/grid'\nimport StatusCell from './StatusCell.svelte'\n\nconst columns: ColumnDef<typeof features, Row>[] = [\n { field: 'name', header: 'Name', width: 200 }, // sortable + filterable by default\n { field: 'price', header: 'Price',\n format: { type: 'currency', currency: 'USD' } },\n { field: 'date', header: 'Date',\n format: { type: 'date', pattern: 'y-m-d' } },\n { field: 'status', header: 'Status',\n cell: renderComponent(StatusCell, (ctx) => ({\n value: ctx.getValue(),\n onChange: handleStatusChange,\n })),\n },\n]\n```\n\n### Property mapping\n\n| AG Grid | SvGrid | Notes |\n| --- | --- | --- |\n| `field` | `field` | Same. |\n| `headerName` | `header` | Accepts a string or a snippet/component. |\n| `width` | `width` | Same. |\n| `minWidth` / `maxWidth` | `minWidth` / `maxWidth` | Same. |\n| `sortable: true` | (default) | Sorting is on when `rowSortingFeature` is registered. |\n| `filter: true` | (default) | Filtering is on when `columnFilteringFeature` is registered. |\n| `valueFormatter` | `format: { ... }` | Built-in types: `number`, `currency`, `percent`, `date`. For custom, use `cell`. |\n| `valueGetter` | `fieldFn` | Returns the value for sorting/filtering. |\n| `cellRenderer` + `cellRendererParams` | `cell: renderComponent(C, ctx => props)` | One call, type-checked. |\n| `cellEditor: 'agTextCellEditor'` | `editorType: 'text'` | Built-in: `text`, `number`, `checkbox`, `date`. |\n| `editable: true` | `enableInlineEditing` prop on `<SvGrid>` | Per-grid, not per-column. (Per-column control on the roadmap.) |\n| `pinned: 'left'` / `'right'` | Right-click column menu → Pin | Set programmatically via the api. |\n| `rowGroup: true` | Via `setGroupBy([colId])` | See Grouping below. |\n| `aggFunc: 'sum'` | `aggregate: 'sum'` | Built-in: `sum`, `avg`, `min`, `max`, `count`. |\n\n## Feature registration - the one new thing\n\nAG Grid auto-enables most features; you turn them off. SvGrid is the\nopposite - features are opt-in. The result is a smaller bundle.\n\n```ts\nimport {\n tableFeatures,\n rowSortingFeature,\n columnFilteringFeature,\n columnGroupingFeature,\n rowExpandingFeature,\n rowPaginationFeature,\n rowSelectionFeature,\n} from '@svgrid/grid'\n\nconst features = tableFeatures({\n rowSortingFeature,\n columnFilteringFeature,\n rowSelectionFeature,\n // omit any you don't need - their code won't ship\n})\n```\n\nPass `features` to `<SvGrid>` once. From then on the grid behaves like\nAG Grid's `enableSorting`, `enableFilter`, `rowSelection`, etc. are all\non for the registered features.\n\n## API mapping (`gridApi` → `SvGridApi`)\n\nYou get the SvGrid API from `onApiReady` (equivalent to AG Grid's\n`onGridReady`).\n\n| AG Grid `gridApi.X()` | SvGrid `api.X()` |\n| --- | --- |\n| `setRowData(rows)` | (declarative - just update `data` prop) |\n| `addRow(row)` / `applyTransaction({ add: [row] })` | `api.addRow(row)` / `api.addRows(rows)` |\n| `applyTransaction({ remove: [row] })` | `api.removeRow(rowIndex)` |\n| `getValue(colId, rowNode)` | `api.getCellValue(rowIndex, columnId)` |\n| `setValue(...)` | `api.setCellValue(rowIndex, columnId, value)` |\n| `setColumnVisible(colId, visible)` | `api.setColumnVisible(columnId, visible)` |\n| `getSortModel()` / `setSortModel()` | `api.setSort(columnId, 'asc'\\|'desc'\\|null)` |\n| `setFilterModel({...})` | `api.setFilter(columnId, { operator, value })` |\n| `getDisplayedRowAtIndex(i)` / `forEachNodeAfterFilterAndSort(...)` | `api.getDisplayedRows()` |\n| `getModel()` (raw rows) | `api.getData()` |\n\n## Common patterns\n\n### Sorting + filtering + pagination (the 80% case)\n\n```svelte\n<script lang=\"ts\">\n import {\n SvGrid,\n tableFeatures,\n rowSortingFeature,\n columnFilteringFeature,\n rowPaginationFeature,\n } from '@svgrid/grid'\n\n const features = tableFeatures({\n rowSortingFeature,\n columnFilteringFeature,\n rowPaginationFeature,\n })\n</script>\n\n<SvGrid\n data={rows}\n columns={columns}\n features={features}\n showPagination\n showColumnFilters\n/>\n```\n\nAG Grid equivalent: `gridOptions: { defaultColDef: { sortable: true, filter: true }, pagination: true }`.\n\n### Cell editing with persistence\n\n```svelte\n<script lang=\"ts\">\n function onCellValueChange(e: { rowIndex: number; columnId: string; value: unknown }) {\n // Persist however you like (fetch to backend, optimistic local update, etc.)\n console.log('cell changed', e)\n }\n</script>\n\n<SvGrid\n data={rows}\n columns={columns}\n features={features}\n enableInlineEditing\n onCellValueChange={onCellValueChange}\n/>\n```\n\nAG Grid equivalent: `onCellValueChanged: ({ data, colDef, newValue, oldValue }) => ...`.\nSvGrid's event payload is column-id + row-index based rather than node-based; the row data is yours\nto mutate (or not) on the `rows` array you passed in.\n\n### Grouping + aggregation\n\n```svelte\n<script lang=\"ts\">\n import {\n SvGrid,\n tableFeatures,\n columnGroupingFeature,\n rowSortingFeature,\n rowExpandingFeature,\n } from '@svgrid/grid'\n\n const features = tableFeatures({\n rowSortingFeature,\n columnGroupingFeature,\n rowExpandingFeature,\n })\n\n const columns = [\n { field: 'department', header: 'Department' },\n { field: 'team', header: 'Team' },\n { field: 'salary', header: 'Salary', aggregate: 'sum',\n format: { type: 'currency', currency: 'USD' } },\n ]\n\n function setGroup(api) {\n api.setGroupBy(['department', 'team'])\n }\n</script>\n\n<SvGrid\n data={rows}\n columns={columns}\n features={features}\n showGroupingControls\n onApiReady={setGroup}\n/>\n```\n\nAG Grid Enterprise's `rowGroupPanelShow: 'always'` + `aggFunc: 'sum'` translates 1:1.\n\n### Master / detail\n\nAG Grid Enterprise feature; **free in SvGrid Community**. See\n[demo 08](https://svgrid.com/demos/08-tree-and-master-detail/) for the exact pattern.\n\n### Server-side data\n\nAG Grid's Infinite Row Model (Community) and Server-Side Row Model\n(Enterprise) both take an `IServerSideDatasource` with a `getRows(params)`\nthat answers through `params.success({ rowData, rowCount })`. SvGrid has one\n`ServerDataSource` whose `getRows(request)` returns `{ rows, rowCount }`,\nand two controllers over it: `createServerDataSource` (free: paging or\ninfinite block scroll, sort, filter, CRUD) and `createServerRowModel`\n(Enterprise: lazy grouping, tree, pivot, transactions, selection). Both\nmount through one prop, `<SvGrid rowModel={ctl} />`.\n\nAn existing datasource written for AG Grid keeps working behind one call:\n\n```ts\nimport { adaptCallbackDatasource, createServerRowModel } from '@svgrid/enterprise'\n\nconst ctl = createServerRowModel(adaptCallbackDatasource(myServerSideDatasource), {\n groupBy: ['country'],\n aggregations: [{ col: 'amount', fn: 'sum' }],\n})\n```\n\n`adaptCallbackDatasource` maps the request both ways (`rowGroupCols` ->\n`groupBy`, `valueCols` -> `aggregations`, `pivotCols` -> `pivotBy`, the\nsort and filter models, `context`, `parentNode`) and turns `success` /\n`fail` into a resolved or rejected promise.\n\nMore often the datasource is a thin `fetch` and the real investment is the\nendpoint behind it - a Java or Node service that parses AG Grid's\n`IServerSideGetRowsRequest` JSON. That endpoint stays as it is: post\n`toCallbackRequest(request)` and read the answer back.\n\n```ts\nimport { toCallbackRequest } from '@svgrid/enterprise'\n\nconst source = {\n async getRows(request) {\n const res = await fetch('/api/sales', {\n method: 'POST',\n headers: { 'content-type': 'application/json' },\n body: JSON.stringify(toCallbackRequest(request)),\n })\n const { rowData, rowCount, pivotResultFields } = await res.json()\n return { rows: rowData, rowCount: rowCount ?? -1, pivotResultFields }\n },\n}\n```\n\n`fromCallbackRequest` is the other direction, for a SvelteKit endpoint that\nhas to keep serving an AG Grid client during the switch. A saved selection\nor a bulk endpoint written against `getServerSideSelectionState()` keeps\nits shape the same way: `toCallbackSelectionState(ctl.getSelectionState())`\nproduces `{ selectAll, toggledNodes }` (or the `nodeId` /\n`selectAllChildren` / `toggledNodes` tree), `ctl.setSelectionState` takes\nthat shape as it is when your group node ids are the group keys, and\n`fromCallbackSelectionState(state, { groupKey, isGroup })` maps them when\na `getRowId` gave group rows ids of their own. Option by option:\n\n| AG Grid | SvGrid |\n| --- | --- |\n| `rowModelType: 'infinite'` + `datasource` | `createServerDataSource(source, { mode: 'infinite' })` + `rowModel={ctl}` |\n| `rowModelType: 'serverSide'` + `serverSideDatasource` | `createServerRowModel(source, options)` + `rowModel={ctl}` |\n| `getRows(params)` + `params.success({ rowData, rowCount })` / `params.fail()` | `getRows(request)` returning `{ rows, rowCount }` / throwing |\n| `cacheBlockSize`, `maxBlocksInCache`, `maxConcurrentDatasourceRequests`, `blockLoadDebounceMillis` | `blockSize`, `maxBlocksInCache`, `maxConcurrentRequests`, `blockLoadDebounceMs` |\n| `infiniteInitialRowCount` / `serverSideInitialRowCount` | `initialRowCount` |\n| `rowCount: -1` (unknown) | `rowCount: -1` |\n| `refreshInfiniteCache()` / `purgeInfiniteCache()` | `ctl.refresh()` / `ctl.purge()` |\n| `request.rowGroupCols`, `groupKeys`, `valueCols`, `pivotCols`, `pivotMode` | `request.groupBy`, `groupKeys`, `aggregations`, `pivotBy`, `pivotMode` |\n| `getChildCount(data)` | `childCount: (row) => row.childCount` |\n| `isServerSideGroupOpenByDefault` | `isGroupOpenByDefault(route, row)` |\n| `getServerSideGroupLevelParams` | `levelParams(level, route)` |\n| `isServerSideGroup` / `getServerSideGroupKey` (tree) | `treeData: true` + `hasChildren` / `getRowId` |\n| `grandTotalRow` / `groupTotalRow` | `grandTotalRow` / `groupFooters` |\n| `refreshServerSide({ route, purge })` / `retryServerSideLoads()` | `ctl.refresh({ route, purge })` / `ctl.retryLoads()` |\n| `applyServerSideTransaction` / `applyServerSideTransactionAsync` / `flushServerSideAsyncTransactions` | `ctl.applyTransaction` / `applyTransactionAsync` / `flushAsyncTransactions` |\n| `applyServerSideRowData` | `ctl.applyRowData` |\n| `serverSideSortAllLevels`, `serverSideEnableClientSideSort`, `serverSideOnlyRefreshFilteredGroups` | `sortAllLevels`, `clientSideSort`, `onlyRefreshFilteredGroups` |\n| `getServerSideSelectionState` / `setServerSideSelectionState` | `ctl.getSelectionState()` / `setSelectionState()` (the `toggledNodes` shape is accepted; `toCallbackSelectionState` / `fromCallbackSelectionState` convert) |\n| `ServerSideTransactionResult.status`: `Applied`, `StoreNotFound`, `StoreLoading`, `StoreWaitingToLoad`, `StoreLoadingFailed`, `Cancelled` | `ServerTransactionResult.status`: the same six, lower camel case (`applied`, `storeNotFound`, ...) - a `switch` on the old spelling falls through silently |\n| `groupSelects: 'descendants'` | `selection: { groupSelects: 'descendants' }` |\n| `pivotResultFields` in `success`, `setPivotResultColumns`, `processPivotResultColDef` | `pivotResultFields` / `pivotResultColumns` in the result, `pivotResultColumn(field, def)` |\n| `pagination` + `paginateChildRows` | `pagination: { pageSize, paginateChildRows }` |\n| `getCacheBlockState()` / `getServerSideGroupLevelState()` | `ctl.getCacheState()` / `ctl.levelStates()` |\n| `serverSideDatasource.destroy()` | `source.destroy()` |\n\nTwo differences worth knowing before you start: SvGrid sends the global\nsearch box to the server as `filterModel.global` (AG Grid's quick filter is\nclient-side only and unsupported under its infinite and server-side models),\nand SvGrid has no viewport row model. See\n[Server grouping](./server/server-grouping.md) and\n[demo 467](https://svgrid.com/demos/467-server-row-model-1m/).\n\n### Excel / PDF export\n\nAG Grid: `gridApi.exportDataAsExcel({...})` (Enterprise-only).\nSvGrid: install `@svgrid/enterprise`, call `api.exportData({ format: 'xlsx', ... })`. See [Data export and printing](./export.md).\n\n```ts\nimport { installEnterprise, setLicenseKey } from '@svgrid/enterprise'\nsetLicenseKey('YOUR-LICENSE-KEY') // your Enterprise key\n\n// inside onApiReady:\nconst pro = installEnterprise(api)\nawait pro.exportData({ format: 'xlsx', filename: 'orders' })\n```\n\n## Gotchas - things that don't translate directly\n\n### 1. Per-column `editable: true`\nEditing is switched on at the grid level (`enableInlineEditing`) and\nnarrowed per column with `editable: boolean | (ctx) => boolean` on the\ncolumn definition, so AG Grid's per-column flag and its callback form both\nmap directly. What does not map is AG Grid's `editable` on a column\ngroup: set it on each child column.\n\n### 2. Column drag-to-reorder\nHeader drag is `enableColumnReorder` on `<SvGrid>`; `setColumnOrder`\non the API does the same from code. See\n[column moving](./columns/column-moving.md) for the events.\n\n### 3. AG Grid `valueGetter` chains\nAG Grid's `valueGetter` can read other column values via the API. In\nSvGrid, `fieldFn` only receives the row; if you need cross-column\ncomputed values, do it in the cell renderer with `ctx.row.original` or\ncompute the derived value upstream and store it in the row.\n\n### 4. `cellClass` / `rowClass` callbacks\nOn the roadmap. For now, render a wrapper element in your `cell` snippet\nwith the conditional class.\n\n### 5. The Status Bar / Side Bar / Tool Panels\nAG Grid's chrome (status bar with row count, side bar with filters and\ncolumns panels) doesn't exist in SvGrid - build it as plain Svelte\nmarkup around the grid. Most teams build their own anyway because\nAG Grid's defaults rarely match a polished design system.\n\n### 6. Set filter (the Excel-style funnel popup)\nSvGrid ships an Excel-style filter menu (free in Community). API surface\nis similar but not identical - see [Set filter](./filtering/set-filter.md).\n\n## When NOT to migrate\n\nBe honest. Stay on AG Grid if you:\n\n- **Use multiple frameworks** - AG Grid has React, Angular, Vue, Solid, Qwik, vanilla adapters. SvGrid is Svelte-only.\n- **Need a push-based viewport row model** - SvGrid's server-side row model covers grouping, tree, pivot, transactions and select-all across unloaded rows, and its real-time page merges deltas into loaded rows, but the server cannot push the visible window over a socket the way the viewport model does.\n- **Need custom tool panels** - SvGrid's tool panel is a fixed Columns + Filters pair. (Custom filter components are covered: a column's `customFilter` renders your own control in the filter menu, the floating filter row and the Filters tab.)\n- **Are mid-project and shipping in <2 weeks** - the migration is a few hours per grid, but only do it when you have buffer.\n- **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.)\n\nIf none of those apply: switching drops a per-developer Enterprise licence\nfor features that are in SvGrid's MIT core, cuts the bundle by the\ndifference in the facts box above, and gives you a Svelte-native API that\nplays well with runes.\n\n## Step-by-step migration\n\nA typical migration of a single grid takes 1-3 hours:\n\n1. **Install** - `pnpm add @svgrid/grid` (and `@svgrid/enterprise` if you need export).\n2. **Translate columnDefs** - use the mapping table above. Most columns are 1:1.\n3. **Wrap features** - figure out which AG Grid features you actually use; register only those in `tableFeatures({...})`.\n4. **Swap the component** - `<AgGridSvelte gridOptions={...}>` → `<SvGrid data={rows} columns={columns} features={features}>`.\n5. **Move event handlers** - AG Grid `onCellValueChanged` → SvGrid `onCellValueChange` (signature differs slightly, see above).\n6. **Move API calls** - AG Grid `gridApi.X()` → SvGrid `api.X()` per the API table.\n7. **Test interactions** - sort, filter, edit, select. Most \"just works.\"\n8. **Remove `ag-grid-*` packages** - `pnpm remove ag-grid-community ag-grid-svelte` etc. Inspect your bundle to confirm the drop; the facts box above has both measured sizes.\n\n## Need help migrating?\n\nEnterprise customers get **migration help included** with the support plan\n(architecture review, port one grid for you as a reference). Email\n`support@jqwidgets.com` after purchase, or `sales@jqwidgets.com` for\npre-sales questions.\n\n## Frequently asked questions\n\n### Is SvGrid a drop-in replacement for AG Grid in Svelte?\n\nNot a literal drop-in - there is no `ag-grid-svelte` shim to swap. But the\nconcepts map closely: column definitions, row models, sorting, filtering,\ngrouping, and an imperative API all have direct SvGrid equivalents, so most\nteams port a grid in 30 minutes to a day. It is a configuration translation,\nnot a rewrite.\n\n### What is the SvGrid equivalent of AG Grid Enterprise?\n\n`@svgrid/enterprise`. It adds Excel/PDF/styled-HTML export (CSV, TSV and JSON export are already free in the grid), a printable view, pivot\ntables and data import. The in-grid AI helpers are free in `@svgrid/grid`.\nIt is licensed per developer ($599 for the grid, $999 with the spreadsheet\nand Studio, both covering unlimited apps), and the\nCommunity package is MIT-licensed and free for commercial use.\n\n### Does SvGrid use Svelte 5 runes, or is it a wrapper?\n\nIt is Svelte-5-native. State is `$state` / `$derived` / `$effect` and cells\nrender through Svelte snippets - there is no React or Angular core underneath\nand no framework bridge to keep in sync.\n\n### Will my AG Grid bundle size shrink?\n\nAlmost always. The facts box at the top of this page has both packages\nmeasured the same way on the same date: the full SvGrid render component\nwith its stylesheet against `createGrid` with every AG Grid Community\nmodule registered. You add `@svgrid/enterprise` features only where you\nimport them, and the headless core on its own is a small fraction of the\nrender component.\n\n## More examples\n\n### AG Grid ↔ sv-grid side-by-side\n\nTwo real grids over the same dataset: the installed AG Grid Community on the left, sv-grid on the right. Same global filter drives both. Source code panels for either side.\n\n<div data-docs-demo=\"139-migration-from-ag-grid\" data-height=\"460\"></div>\n\n## See also\n\n- [Getting started](../getting-started.md) - full SvGrid walkthrough\n- [Why headless?](../why-headless.md) - the headless / render-component split\n- [Data export and printing](./export.md) - the `@svgrid/enterprise` feature pack\n- [Comparison: SvGrid vs AG Grid vs TanStack Table](./comparison.md) - the\n measured benchmark and the feature matrix\n- [SvGrid vs AG Grid comparison page](https://svgrid.com/compare/ag-grid/) -\n every claim with its source and date\n"
5708
5715
  },
5709
5716
  {
5710
5717
  "slug": "help/migrating-from-airtable",
@@ -5781,7 +5788,7 @@ export const docs = [
5781
5788
  "path": "docs/help/migrating-from-primevue-datatable.md",
5782
5789
  "title": "Migrating from PrimeVue / PrimeNG / PrimeReact DataTable",
5783
5790
  "section": "Help",
5784
- "markdown": "# Migrating from PrimeVue / PrimeNG / PrimeReact DataTable\n\nThe Prime DataTable is the grid in the Prime UI suites for Vue, Angular,\nand React. Its columns are declared as `<Column>` children with `field`\n/ `header` props - a shape that maps cleanly onto SvGrid's `ColumnDef`\narray. The port is mostly translating columns and events into a Svelte 5\ncomponent. Since PrimeVue 5 the package ships under the PrimeUI licence\nrather than MIT: free for individuals and small organisations under the\nlimits in its licence file, per developer with a licence key otherwise.\nThe facts box below quotes the terms as read on the date shown.\n\n> Estimated effort: **2-4 hours** per grid.\n\n<!-- facts:start primevue-datatable -->\n> **Facts, checked 12 Sep 2026.** `primevue` 5.0.1, Commercial (see licence file), last published 13 Aug 2026, 3,010,000 npm downloads in the 30 days to 10 Sep 2026. `@svgrid/grid` 3.0.3, MIT, last published 11 Sep 2026, 16,900 npm downloads in the same window. Bundle, minified and gzipped, each package built alone with Svelte external: SvGrid 3.0.4 97.6 KB JS + 10.5 KB CSS (measured 22 Sep 2026). PrimeVue / PrimeNG / PrimeReact DataTable pricing, as its site states it: primeui.dev lists the Commercial Suite at a launch price of $599 per developer (standard $799) as a perpetual licence with one year of updates, renewable at $399 per developer per year; the Community License is free for individuals, non-profits and organisations under $1M revenue, fewer than five developers, fewer than ten employees and under $3M in venture funding (https://primeui.dev/pricing, read 12 Sep 2026). SvGrid: MIT core; @svgrid/enterprise from $299 per developer per year (Indie, under $1M revenue), $599 for Enterprise. Side by side, with sources: [SvGrid vs PrimeVue / PrimeNG / PrimeReact DataTable](https://svgrid.com/compare/primevue-datatable/).\n<!-- facts:end -->\n\n## Vocabulary cheat sheet\n\n| Prime DataTable | sv-grid |\n| ---------------------------------------- | ----------------------------------------- |\n| `<DataTable :value=\"rows\">` | `<SvGrid data={rows}>` |\n| `<Column field=\"name\" header=\"Name\" />` | `{ field: 'name', header: 'Name' }` |\n| `sortable` | `rowSortingFeature` |\n| `:filters` / filter display | `columnFilteringFeature` |\n| `<template #body>` cell slot | `cell: (c) => renderSnippet(...)` |\n| `editMode` + cell editor template | `editorType` (+ custom `cellEditor`) |\n| `:expandedRows` / row expansion | `rowExpandingFeature` |\n| `lazy` + `@page` / `@sort` / `@filter` | `externalSort` / `externalFilter` + events |\n| `paginator` + `:rows` | `showPagination` (+ page size) |\n\n## Before / after\n\nThe example at the end of this page runs against these rows:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n department: string\n city: string\n age: number\n salary: number\n }\n\n const people: Person[] = [\n { id: 1, name: 'Ada Lovelace', department: 'Engineering', city: 'London', age: 36, salary: 142000 },\n { id: 2, name: 'Grace Hopper', department: 'Engineering', city: 'New York', age: 45, salary: 168000 },\n { id: 3, name: 'Linus Torvalds', department: 'Platform', city: 'Portland', age: 54, salary: 155000 },\n { id: 4, name: 'Radia Perlman', department: 'Networking', city: 'Seattle', age: 49, salary: 161000 },\n { id: 5, name: 'Barbara Liskov', department: 'Platform', city: 'Boston', age: 52, salary: 172000 },\n ]\n\n let rows = $state<Person[]>(people)\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 200, editorType: 'text' },\n { field: 'department', header: 'Department', width: 150, editorType: 'text' },\n { field: 'city', header: 'City', width: 140, editorType: 'text' },\n { field: 'age', header: 'Age', width: 90, editorType: 'number' },\n { field: 'salary', header: 'Salary', width: 130, editorType: 'number', format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```diff\n- <DataTable :value=\"rows\" paginator :rows=\"25\" sortMode=\"multiple\">\n- <Column field=\"name\" header=\"Name\" sortable />\n- <Column field=\"amount\" header=\"Amount\" sortable>\n- <template #body=\"{ data }\">{{ fmt(data.amount) }}</template>\n- </Column>\n- </DataTable>\n\n+ <script lang=\"ts\">\n+ import {\n+ SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,\n+ type ColumnDef,\n+ } from '@svgrid/grid'\n+ const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })\n+ const columns: ColumnDef<typeof features, Row>[] = [\n+ { field: 'name', header: 'Name' },\n+ { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },\n+ ]\n+ </script>\n+\n+ <SvGrid data={rows} columns={columns} features={features} showPagination />\n```\n\n## What changes\n\n- **`<Column>` children → a `ColumnDef[]` array.**\n- **`#body` slots → `cell` snippets** via `renderSnippet`.\n- **Prime theming → `--sg-*` tokens / Tailwind** - no Prime theme\n dependency.\n- **`lazy` → `externalSort` / `externalFilter`** with refetch on events.\n\n## Frequently asked questions\n\n### How do Prime `<Column>` definitions map to SvGrid?\n\nEach `<Column field header />` becomes a `{ field, header }` object in SvGrid's\n`columns` array, and `#body` templates become `renderSnippet` cells. Sorting and\nfiltering move from per-column props to the `rowSortingFeature` /\n`columnFilteringFeature` registration.\n\n### Is SvGrid open-source like the Prime grid core?\n\n`@svgrid/grid` is MIT with no licence key or eligibility conditions. The\nPrime cores were MIT through PrimeVue 4; from PrimeVue 5 the npm package\ncarries the PrimeUI licence, whose free Community License depends on your\nrevenue, developer count, headcount and funding, and whose Commercial\nLicense is per developer with a key. The other difference is framework:\nSvGrid is Svelte 5, not Vue / Angular / React.\n\n### Do I lose Prime theming?\n\nYou re-create the look with `--sg-*` tokens (optionally driven by your Tailwind\ntheme), so the grid matches your design system without a Prime theme dependency.\n\n## What you end up with\n\nSorting, filtering, pagination and row selection in one pass.\n\n```svelte {runnable}\n<SvGrid data={rows} {columns} sortable filterable pageable pageSize={3} selectable />\n```\n\n## See also\n\n- [SvGrid vs Prime DataTable](https://svgrid.com/compare/primevue-datatable/) - the side-by-side comparison\n- [Tailwind integration](./tailwind.md) - match your design system\n- [Cell components](./cells/cell-components.md) - snippet cells + editors\n"
5791
+ "markdown": "\n# Migrating from PrimeVue / PrimeNG / PrimeReact DataTable\n\nThe Prime DataTable is the grid in the Prime UI suites for Vue, Angular,\nand React. Its columns are declared as `<Column>` children with `field`\n/ `header` props - a shape that maps cleanly onto SvGrid's `ColumnDef`\narray. The port is mostly translating columns and events into a Svelte 5\ncomponent. Since PrimeVue 5 the package ships under the PrimeUI licence\nrather than MIT: free for individuals and small organisations under the\nlimits in its licence file, per developer with a licence key otherwise.\nThe facts box below quotes the terms as read on the date shown.\n\n> Estimated effort: **2-4 hours** per grid.\n\n<!-- facts:start primevue-datatable -->\n> **Facts, checked 12 Sep 2026.** `primevue` 5.0.1, Commercial (see licence file), last published 13 Aug 2026, 3,010,000 npm downloads in the 30 days to 10 Sep 2026. `@svgrid/grid` 3.0.3, MIT, last published 11 Sep 2026, 16,900 npm downloads in the same window. Bundle, minified and gzipped, each package built alone with Svelte external: SvGrid 3.0.4 97.6 KB JS + 10.5 KB CSS (measured 22 Sep 2026). PrimeVue / PrimeNG / PrimeReact DataTable pricing, as its site states it: primeui.dev lists the Commercial Suite at a launch price of $599 per developer (standard $799) as a perpetual licence with one year of updates, renewable at $399 per developer per year; the Community License is free for individuals, non-profits and organisations under $1M revenue, fewer than five developers, fewer than ten employees and under $3M in venture funding (https://primeui.dev/pricing, read 12 Sep 2026). SvGrid: MIT core; @svgrid/enterprise from $299 per developer per year (Indie, under $1M revenue), $599 for Enterprise. Side by side, with sources: [SvGrid vs PrimeVue / PrimeNG / PrimeReact DataTable](https://svgrid.com/compare/primevue-datatable/).\n<!-- facts:end -->\n\n## Vocabulary cheat sheet\n\n| Prime DataTable | sv-grid |\n| ---------------------------------------- | ----------------------------------------- |\n| `<DataTable :value=\"rows\">` | `<SvGrid data={rows}>` |\n| `<Column field=\"name\" header=\"Name\" />` | `{ field: 'name', header: 'Name' }` |\n| `sortable` | `rowSortingFeature` |\n| `:filters` / filter display | `columnFilteringFeature` |\n| `<template #body>` cell slot | `cell: (c) => renderSnippet(...)` |\n| `editMode` + cell editor template | `editorType` (+ custom `cellEditor`) |\n| `:expandedRows` / row expansion | `rowExpandingFeature` |\n| `lazy` + `@page` / `@sort` / `@filter` | `externalSort` / `externalFilter` + events |\n| `paginator` + `:rows` | `showPagination` (+ page size) |\n\n## Before / after\n\nThe example at the end of this page runs against these rows:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n department: string\n city: string\n age: number\n salary: number\n }\n\n const people: Person[] = [\n { id: 1, name: 'Ada Lovelace', department: 'Engineering', city: 'London', age: 36, salary: 142000 },\n { id: 2, name: 'Grace Hopper', department: 'Engineering', city: 'New York', age: 45, salary: 168000 },\n { id: 3, name: 'Linus Torvalds', department: 'Platform', city: 'Portland', age: 54, salary: 155000 },\n { id: 4, name: 'Radia Perlman', department: 'Networking', city: 'Seattle', age: 49, salary: 161000 },\n { id: 5, name: 'Barbara Liskov', department: 'Platform', city: 'Boston', age: 52, salary: 172000 },\n ]\n\n let rows = $state<Person[]>(people)\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 200, editorType: 'text' },\n { field: 'department', header: 'Department', width: 150, editorType: 'text' },\n { field: 'city', header: 'City', width: 140, editorType: 'text' },\n { field: 'age', header: 'Age', width: 90, editorType: 'number' },\n { field: 'salary', header: 'Salary', width: 130, editorType: 'number', format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```diff\n- <DataTable :value=\"rows\" paginator :rows=\"25\" sortMode=\"multiple\">\n- <Column field=\"name\" header=\"Name\" sortable />\n- <Column field=\"amount\" header=\"Amount\" sortable>\n- <template #body=\"{ data }\">{{ fmt(data.amount) }}</template>\n- </Column>\n- </DataTable>\n\n+ <script lang=\"ts\">\n+ import {\n+ SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,\n+ type ColumnDef,\n+ } from '@svgrid/grid'\n+ const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })\n+ const columns: ColumnDef<typeof features, Row>[] = [\n+ { field: 'name', header: 'Name' },\n+ { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },\n+ ]\n+ </script>\n+\n+ <SvGrid data={rows} columns={columns} features={features} showPagination />\n```\n\n## What changes\n\n- **`<Column>` children → a `ColumnDef[]` array.**\n- **`#body` slots → `cell` snippets** via `renderSnippet`.\n- **Prime theming → `--sg-*` tokens / Tailwind** - no Prime theme\n dependency.\n- **`lazy` → `externalSort` / `externalFilter`** with refetch on events.\n\n## Frequently asked questions\n\n### How do Prime `<Column>` definitions map to SvGrid?\n\nEach `<Column field header />` becomes a `{ field, header }` object in SvGrid's\n`columns` array, and `#body` templates become `renderSnippet` cells. Sorting and\nfiltering move from per-column props to the `rowSortingFeature` /\n`columnFilteringFeature` registration.\n\n### Is SvGrid open-source like the Prime grid core?\n\n`@svgrid/grid` is MIT with no licence key or eligibility conditions. The\nPrime cores were MIT through PrimeVue 4; from PrimeVue 5 the npm package\ncarries the PrimeUI licence, whose free Community License depends on your\nrevenue, developer count, headcount and funding, and whose Commercial\nLicense is per developer with a key. The other difference is framework:\nSvGrid is Svelte 5, not Vue / Angular / React.\n\n### Do I lose Prime theming?\n\nYou re-create the look with `--sg-*` tokens (optionally driven by your Tailwind\ntheme), so the grid matches your design system without a Prime theme dependency.\n\n## What you end up with\n\nSorting, filtering, pagination and row selection in one pass.\n\n```svelte {runnable}\n<SvGrid data={rows} {columns} sortable filterable pageable pageSize={3} selectable />\n```\n\n## See also\n\n- [SvGrid vs Prime DataTable](https://svgrid.com/compare/primevue-datatable/) - the side-by-side comparison\n- [Tailwind integration](./tailwind.md) - match your design system\n- [Cell components](./cells/cell-components.md) - snippet cells + editors\n"
5785
5792
  },
5786
5793
  {
5787
5794
  "slug": "help/migrating-from-react-data-grid",
@@ -5802,7 +5809,7 @@ export const docs = [
5802
5809
  "path": "docs/help/migrating-from-smart-grid.md",
5803
5810
  "title": "Migrating from Smart.Grid (Smart Web Components)",
5804
5811
  "section": "Help",
5805
- "markdown": "# Migrating from Smart.Grid (Smart Web Components)\n\nSmart.Grid (htmlelements.com) and SvGrid come from the **same team**.\nSmart.Grid is a framework-agnostic custom element - it even works inside\nSvelte today - while SvGrid is the reactive, Svelte-5-native option. If\nyou are standardising a Svelte app on idiomatic components, this guide\nmaps a Smart.Grid setup onto SvGrid.\n\n> Estimated effort: **2-4 hours** per grid. The main shift is from a\n> custom element bound through properties / attributes to a reactive\n> Svelte component.\n\n<!-- facts:start smart-grid -->\n> **Facts, checked 12 Sep 2026.** `smart-webcomponents` 27.0.1, ISC, last published 13 Aug 2026, 6,620 npm downloads in the 30 days to 10 Sep 2026. `@svgrid/grid` 3.0.3, MIT, last published 11 Sep 2026, 16,900 npm downloads in the same window. Bundle, minified and gzipped, each package built alone with Svelte external: SvGrid 3.0.4 97.6 KB JS + 10.5 KB CSS (measured 22 Sep 2026). Smart.Grid pricing, as its site states it: htmlelements.com lists the Developer License at $499 (on sale at $399) per developer, perpetual, or $39 per month, and the Team License at $1,499 per five developers; the free Community License covers the core components but not the Grid (https://www.htmlelements.com/license/, read 12 Sep 2026). SvGrid: MIT core; @svgrid/enterprise from $299 per developer per year (Indie, under $1M revenue), $599 for Enterprise. Side by side, with sources: [SvGrid vs Smart.Grid (Smart Web Components)](https://svgrid.com/compare/smart-grid/).\n<!-- facts:end -->\n\n## Vocabulary cheat sheet\n\n| Smart.Grid (web component) | sv-grid |\n| ---------------------------------------- | ----------------------------------------- |\n| `<smart-grid>` element | `<SvGrid ... />` |\n| `grid.dataSource = new Smart.DataAdapter`| `data` array (or `externalSort/Filter`) |\n| `{ label: 'Name', dataField: 'name' }` | `{ header: 'Name', field: 'name' }` |\n| `template` / cell template | `cell: (c) => renderSnippet(...)` |\n| `editing` + editor | `enableInlineEditing` + `editorType` |\n| `sorting` / `filtering` | `rowSortingFeature` / `columnFilteringFeature` |\n| `grouping` | `columnGroupingFeature` + `api.setGroupBy()` |\n| `paging` + `pager` | `showPagination` |\n| element events (`change`, ...) | `onCellValueChange`, `onApiReady` |\n| `theme` attribute | `--sg-*` tokens / Tailwind |\n\n## Before / after\n\nThe example at the end of this page runs against these rows:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n department: string\n city: string\n age: number\n salary: number\n }\n\n const people: Person[] = [\n { id: 1, name: 'Ada Lovelace', department: 'Engineering', city: 'London', age: 36, salary: 142000 },\n { id: 2, name: 'Grace Hopper', department: 'Engineering', city: 'New York', age: 45, salary: 168000 },\n { id: 3, name: 'Linus Torvalds', department: 'Platform', city: 'Portland', age: 54, salary: 155000 },\n { id: 4, name: 'Radia Perlman', department: 'Networking', city: 'Seattle', age: 49, salary: 161000 },\n { id: 5, name: 'Barbara Liskov', department: 'Platform', city: 'Boston', age: 52, salary: 172000 },\n ]\n\n let rows = $state<Person[]>(people)\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 200, editorType: 'text' },\n { field: 'department', header: 'Department', width: 150, editorType: 'text' },\n { field: 'city', header: 'City', width: 140, editorType: 'text' },\n { field: 'age', header: 'Age', width: 90, editorType: 'number' },\n { field: 'salary', header: 'Salary', width: 130, editorType: 'number', format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```diff\n- <smart-grid id=\"grid\" sorting filtering paging></smart-grid>\n- <script>\n- const grid = document.querySelector('#grid')\n- grid.dataSource = new Smart.DataAdapter({ dataSource: rows, dataFields: [...] })\n- grid.columns = [\n- { label: 'Name', dataField: 'name' },\n- { label: 'Amount', dataField: 'amount' },\n- ]\n- </script>\n\n+ <script lang=\"ts\">\n+ import {\n+ SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,\n+ type ColumnDef,\n+ } from '@svgrid/grid'\n+ const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })\n+ const columns: ColumnDef<typeof features, Row>[] = [\n+ { field: 'name', header: 'Name' },\n+ { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },\n+ ]\n+ </script>\n+\n+ <SvGrid data={rows} columns={columns} features={features} showPagination />\n```\n\n## What changes\n\n- **Custom element + DataAdapter → reactive `$state`.** Data binding is a\n prop, not an assigned `dataSource`.\n- **Element templates → Svelte snippets** via `renderSnippet`.\n- **`theme` attribute → `--sg-*` tokens.**\n\n## A note on family\n\nSmart.Grid is a genuinely good framework-agnostic grid from the same\nteam, and it runs in Svelte as a web component. The reason to pick SvGrid\nis *idiomatic* Svelte: runes, snippets, and an MIT core. If you need one\ngrid across Angular, React, Vue, Svelte, and vanilla, Smart.Grid is the\nright call.\n\n## Frequently asked questions\n\n### Is SvGrid from the same team as Smart.Grid?\n\nYes. Smart Web Components (htmlelements.com) and SvGrid are built by the same\nteam. SvGrid is the Svelte-5-native option with an MIT community core.\n\n### Can I keep using Smart.Grid in Svelte instead?\n\nYes - Smart.Grid is a web component and works inside Svelte. Choose SvGrid when\nyou want an idiomatic Svelte component (runes + snippets) rather than a custom\nelement bound through properties.\n\n### How do Smart.Grid columns map to SvGrid?\n\n`label` becomes `header`, `dataField` becomes `field`, and element templates\nbecome `renderSnippet` cells. Sorting / filtering / grouping move to registered\nfeatures.\n\n## More examples\n\n### Smart.Chart integration\n\nMounts a <smart-chart> web component (htmlelements.com) and pipes the grid's displayed rows into its dataSource. Re-aggregates on every filter / sort.\n\n<div data-docs-demo=\"77-smart-chart\" data-height=\"460\"></div>\n\n## What you end up with\n\nSorting, filtering and editing with a footer summary.\n\n```svelte {runnable}\n<SvGrid data={rows} {columns} sortable filterable editable summary />\n```\n\n## The ported grid, running\n\nSorting, filtering, editing and a totals row - the working set a Smart grid\nusually carries, as props.\n\n```svelte {runnable}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n city: string\n age: number\n salary: number\n }\n\n const seed: Person[] = [\n { id: 1, name: 'Ada Lovelace', city: 'London', age: 36, salary: 142000 },\n { id: 2, name: 'Grace Hopper', city: 'New York', age: 45, salary: 168000 },\n { id: 3, name: 'Linus Torvalds', city: 'Portland', age: 54, salary: 155000 },\n ]\n\n let rows = $state<Person[]>(seed.map((p) => ({ ...p })))\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 180, editorType: 'text' },\n { field: 'city', header: 'City', width: 150, editorType: 'text' },\n { field: 'salary', header: 'Salary', width: 150, editorType: 'number', summary: 'sum',\n format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n\n<SvGrid data={rows} {columns} sortable filterable editable summary />\n```\n\n## See also\n\n- [SvGrid vs Smart.Grid](https://svgrid.com/compare/smart-grid/) - the side-by-side comparison\n- [About SvGrid](https://svgrid.com/about/) - built by jQWidgets / htmlelements.com\n- [Cell components](./cells/cell-components.md) - snippet-based custom cells\n"
5812
+ "markdown": "\n# Migrating from Smart.Grid (Smart Web Components)\n\nSmart.Grid (htmlelements.com) and SvGrid come from the **same team**.\nSmart.Grid is a framework-agnostic custom element - it even works inside\nSvelte today - while SvGrid is the reactive, Svelte-5-native option. If\nyou are standardising a Svelte app on idiomatic components, this guide\nmaps a Smart.Grid setup onto SvGrid.\n\n> Estimated effort: **2-4 hours** per grid. The main shift is from a\n> custom element bound through properties / attributes to a reactive\n> Svelte component.\n\n<!-- facts:start smart-grid -->\n> **Facts, checked 12 Sep 2026.** `smart-webcomponents` 27.0.1, ISC, last published 13 Aug 2026, 6,620 npm downloads in the 30 days to 10 Sep 2026. `@svgrid/grid` 3.0.3, MIT, last published 11 Sep 2026, 16,900 npm downloads in the same window. Bundle, minified and gzipped, each package built alone with Svelte external: SvGrid 3.0.4 97.6 KB JS + 10.5 KB CSS (measured 22 Sep 2026). Smart.Grid pricing, as its site states it: htmlelements.com lists the Developer License at $499 (on sale at $399) per developer, perpetual, or $39 per month, and the Team License at $1,499 per five developers; the free Community License covers the core components but not the Grid (https://www.htmlelements.com/license/, read 12 Sep 2026). SvGrid: MIT core; @svgrid/enterprise from $299 per developer per year (Indie, under $1M revenue), $599 for Enterprise. Side by side, with sources: [SvGrid vs Smart.Grid (Smart Web Components)](https://svgrid.com/compare/smart-grid/).\n<!-- facts:end -->\n\n## Vocabulary cheat sheet\n\n| Smart.Grid (web component) | sv-grid |\n| ---------------------------------------- | ----------------------------------------- |\n| `<smart-grid>` element | `<SvGrid ... />` |\n| `grid.dataSource = new Smart.DataAdapter`| `data` array (or `externalSort/Filter`) |\n| `{ label: 'Name', dataField: 'name' }` | `{ header: 'Name', field: 'name' }` |\n| `template` / cell template | `cell: (c) => renderSnippet(...)` |\n| `editing` + editor | `enableInlineEditing` + `editorType` |\n| `sorting` / `filtering` | `rowSortingFeature` / `columnFilteringFeature` |\n| `grouping` | `columnGroupingFeature` + `api.setGroupBy()` |\n| `paging` + `pager` | `showPagination` |\n| element events (`change`, ...) | `onCellValueChange`, `onApiReady` |\n| `theme` attribute | `--sg-*` tokens / Tailwind |\n\n## Before / after\n\nThe example at the end of this page runs against these rows:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n department: string\n city: string\n age: number\n salary: number\n }\n\n const people: Person[] = [\n { id: 1, name: 'Ada Lovelace', department: 'Engineering', city: 'London', age: 36, salary: 142000 },\n { id: 2, name: 'Grace Hopper', department: 'Engineering', city: 'New York', age: 45, salary: 168000 },\n { id: 3, name: 'Linus Torvalds', department: 'Platform', city: 'Portland', age: 54, salary: 155000 },\n { id: 4, name: 'Radia Perlman', department: 'Networking', city: 'Seattle', age: 49, salary: 161000 },\n { id: 5, name: 'Barbara Liskov', department: 'Platform', city: 'Boston', age: 52, salary: 172000 },\n ]\n\n let rows = $state<Person[]>(people)\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 200, editorType: 'text' },\n { field: 'department', header: 'Department', width: 150, editorType: 'text' },\n { field: 'city', header: 'City', width: 140, editorType: 'text' },\n { field: 'age', header: 'Age', width: 90, editorType: 'number' },\n { field: 'salary', header: 'Salary', width: 130, editorType: 'number', format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```diff\n- <smart-grid id=\"grid\" sorting filtering paging></smart-grid>\n- <script>\n- const grid = document.querySelector('#grid')\n- grid.dataSource = new Smart.DataAdapter({ dataSource: rows, dataFields: [...] })\n- grid.columns = [\n- { label: 'Name', dataField: 'name' },\n- { label: 'Amount', dataField: 'amount' },\n- ]\n- </script>\n\n+ <script lang=\"ts\">\n+ import {\n+ SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,\n+ type ColumnDef,\n+ } from '@svgrid/grid'\n+ const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })\n+ const columns: ColumnDef<typeof features, Row>[] = [\n+ { field: 'name', header: 'Name' },\n+ { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },\n+ ]\n+ </script>\n+\n+ <SvGrid data={rows} columns={columns} features={features} showPagination />\n```\n\n## What changes\n\n- **Custom element + DataAdapter → reactive `$state`.** Data binding is a\n prop, not an assigned `dataSource`.\n- **Element templates → Svelte snippets** via `renderSnippet`.\n- **`theme` attribute → `--sg-*` tokens.**\n\n## A note on family\n\nSmart.Grid is a genuinely good framework-agnostic grid from the same\nteam, and it runs in Svelte as a web component. The reason to pick SvGrid\nis *idiomatic* Svelte: runes, snippets, and an MIT core. If you need one\ngrid across Angular, React, Vue, Svelte, and vanilla, Smart.Grid is the\nright call.\n\n## Frequently asked questions\n\n### Is SvGrid from the same team as Smart.Grid?\n\nYes. Smart Web Components (htmlelements.com) and SvGrid are built by the same\nteam. SvGrid is the Svelte-5-native option with an MIT community core.\n\n### Can I keep using Smart.Grid in Svelte instead?\n\nYes - Smart.Grid is a web component and works inside Svelte. Choose SvGrid when\nyou want an idiomatic Svelte component (runes + snippets) rather than a custom\nelement bound through properties.\n\n### How do Smart.Grid columns map to SvGrid?\n\n`label` becomes `header`, `dataField` becomes `field`, and element templates\nbecome `renderSnippet` cells. Sorting / filtering / grouping move to registered\nfeatures.\n\n## More examples\n\n### Smart.Chart integration\n\nMounts a <smart-chart> web component (htmlelements.com) and pipes the grid's displayed rows into its dataSource. Re-aggregates on every filter / sort.\n\n<div data-docs-demo=\"77-smart-chart\" data-height=\"460\"></div>\n\n## What you end up with\n\nSorting, filtering and editing with a footer summary.\n\n```svelte {runnable}\n<SvGrid data={rows} {columns} sortable filterable editable summary />\n```\n\n## The ported grid, running\n\nSorting, filtering, editing and a totals row - the working set a Smart grid\nusually carries, as props.\n\n```svelte {runnable}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n city: string\n age: number\n salary: number\n }\n\n const seed: Person[] = [\n { id: 1, name: 'Ada Lovelace', city: 'London', age: 36, salary: 142000 },\n { id: 2, name: 'Grace Hopper', city: 'New York', age: 45, salary: 168000 },\n { id: 3, name: 'Linus Torvalds', city: 'Portland', age: 54, salary: 155000 },\n ]\n\n let rows = $state<Person[]>(seed.map((p) => ({ ...p })))\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 180, editorType: 'text' },\n { field: 'city', header: 'City', width: 150, editorType: 'text' },\n { field: 'salary', header: 'Salary', width: 150, editorType: 'number', summary: 'sum',\n format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n\n<SvGrid data={rows} {columns} sortable filterable editable summary />\n```\n\n## See also\n\n- [SvGrid vs Smart.Grid](https://svgrid.com/compare/smart-grid/) - the side-by-side comparison\n- [About SvGrid](https://svgrid.com/about/) - built by jQWidgets / htmlelements.com\n- [Cell components](./cells/cell-components.md) - snippet-based custom cells\n"
5806
5813
  },
5807
5814
  {
5808
5815
  "slug": "help/migrating-from-svar-svelte-datagrid",
@@ -5816,7 +5823,7 @@ export const docs = [
5816
5823
  "path": "docs/help/migrating-from-svelte-headless-table.md",
5817
5824
  "title": "Migrating from svelte-headless-table",
5818
5825
  "section": "Help",
5819
- "markdown": "# Migrating from svelte-headless-table\n\nsvelte-headless-table popularised the headless-table pattern in the\nSvelte ecosystem. It is built on Svelte 4 stores and plugins\n(`addSortBy`, `addColumnFilters`, `addPagination`, ...), and it leaves\nthe markup to you. SvGrid keeps the same headless idea but runs on\nSvelte 5 runes and ships a render component, so the port mostly\n*removes* the table you used to hand-author.\n\n> Estimated effort: **1-3 hours** per grid. Most of the time is deleting\n> the `<table>` markup and `Subscribe` blocks you no longer need.\n\n<!-- facts:start svelte-headless-table pkg:@humanspeak/svelte-headless-table -->\n> **Facts, checked 12 Sep 2026.** `svelte-headless-table` 0.18.3, MIT, last published 28 Oct 2024, 90,100 npm downloads in the 30 days to 10 Sep 2026. `@humanspeak/svelte-headless-table` 6.2.0, MIT, last published 27 Aug 2026, 8,640 npm downloads in the same window. `@svgrid/grid` 3.0.3, MIT, last published 11 Sep 2026, 16,900 npm downloads in the same window. Bundle, minified and gzipped, each package built alone with Svelte external: SvGrid 3.0.4 97.6 KB JS + 10.5 KB CSS (measured 22 Sep 2026); `svelte-headless-table` 0.18.3 5.7 KB JS, no separate stylesheet, svelte external (measured 12 Sep 2026). svelte-headless-table pricing, as its site states it: svelte-headless-table is MIT and free; no paid licence or support is offered, and the author states there are no plans for a Svelte 5 port (https://github.com/bryanmylee/svelte-headless-table, read 12 Sep 2026). SvGrid: MIT core; @svgrid/enterprise from $299 per developer per year (Indie, under $1M revenue), $599 for Enterprise. Side by side, with sources: [SvGrid vs svelte-headless-table](https://svgrid.com/compare/svelte-headless-table/).\n<!-- facts:end -->\n\n## Know your options first\n\nThe original package's last release and its Svelte 4 peer range are in the\nfacts box above, and its README states there are no current plans for a\nSvelte 5 port, so a Svelte 5 upgrade forces a decision. There are three\nhonest answers and you should know all of them:\n\n1. **`@humanspeak/svelte-headless-table`** - a maintained fork on Svelte 5 with\n the same API; its version, publish date and downloads are in the facts box\n too. Changing one package name is the cheapest path by a wide margin. If\n your table works and you only need Svelte 5, do that.\n2. **TanStack Table v9** - its Svelte adapter declares a Svelte 5 peer range.\n Still headless-only, so you keep writing and maintaining the markup.\n3. **SvGrid** - this page. A different trade: you delete the markup and take a\n renderer instead.\n\nPick SvGrid when the markup is the part you are tired of. Note that the blocker\nis not the syntax and not really the install either: `svelte-headless-table@0.18.3`\ndeclares `svelte@^4`, which npm 11 overrides with a warning (older npm needed\n`--legacy-peer-deps`), and the untouched component then type-checks clean in\nlegacy mode. Slots and `let:` still work in Svelte 5 - they are deprecated in\nfavour of snippets, not removed - so the `Subscribe` blocks below keep\nrendering. The trouble starts when that component moves to runes: the library\ntakes a store, your data is a rune, and the bridge between them is yours to\nwrite and maintain. We ran the whole upgrade and captured every line of it in\n[Upgrading a Svelte 4 table to Svelte 5](./svelte-5-upgrade-data-tables.md).\n\n## Run the codemod\n\nThe example at the end of this page runs against these rows:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n department: string\n city: string\n age: number\n salary: number\n }\n\n const people: Person[] = [\n { id: 1, name: 'Ada Lovelace', department: 'Engineering', city: 'London', age: 36, salary: 142000 },\n { id: 2, name: 'Grace Hopper', department: 'Engineering', city: 'New York', age: 45, salary: 168000 },\n { id: 3, name: 'Linus Torvalds', department: 'Platform', city: 'Portland', age: 54, salary: 155000 },\n { id: 4, name: 'Radia Perlman', department: 'Networking', city: 'Seattle', age: 49, salary: 161000 },\n { id: 5, name: 'Barbara Liskov', department: 'Platform', city: 'Boston', age: 52, salary: 172000 },\n ]\n\n let rows = $state<Person[]>(people)\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 200, editorType: 'text' },\n { field: 'department', header: 'Department', width: 150, editorType: 'text' },\n { field: 'city', header: 'City', width: 140, editorType: 'text' },\n { field: 'age', header: 'Age', width: 90, editorType: 'number' },\n { field: 'salary', header: 'Salary', width: 130, editorType: 'number', format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```bash\nnpx @svgrid/migrate # preview the result\nnpx @svgrid/migrate src --write # apply it\n```\n\nIt translates column definitions and plugin config, deletes the\n`Subscribe`/`Render` scaffolding, and reports anything it cannot map rather than\ndropping it silently. It previews by default. See\n[`@svgrid/migrate`](https://www.npmjs.com/package/@svgrid/migrate) for the full\nmapping and its limits.\n\n## Vocabulary cheat sheet\n\n| svelte-headless-table | sv-grid |\n| ----------------------------------------- | ----------------------------------------- |\n| `createTable(data, plugins)` | `createSvGrid({...})` or `<SvGrid>` |\n| `table.createColumns((t) => [...])` | `columns: ColumnDef[]` |\n| `t.column({ accessor: 'x', header })` | `{ field: 'x', header }` |\n| `t.column({ accessor: (r) => ... })` | `{ id, fieldFn: (r) => ... }` |\n| `t.group({ header, columns })` | `{ header, columns: [...] }` (column group) |\n| `addSortBy()` | `rowSortingFeature` |\n| `addColumnFilters()` / `addTableFilter()` | `columnFilteringFeature` |\n| `addPagination()` | Built in; toggle `showPagination` |\n| `addExpandedRows()` / `addSubRows()` | `rowExpandingFeature` |\n| `addGroupBy()` | `columnGroupingFeature` + `api.setGroupBy()` |\n| `addSelectedRows()` | `rowSelectionFeature` |\n| `addDataExport()` | `@svgrid/enterprise` export pack |\n| `createViewModel(columns)` + `Subscribe` | `<SvGrid>` (no view model to wire) |\n| `pluginStates.sort.sortKeys` | `api.setSort(id, dir)` / `onSortingChange` |\n\n### The shortcut form\n\nThat table maps plugins onto the headless *features*, which is what you want if\nyou keep driving the engine yourself. If you are moving to the `<SvGrid>`\ncomponent, every capability also has a boolean prop, and that is what the\ncodemod emits:\n\n| Plugin | `<SvGrid>` prop |\n| --- | --- |\n| `addSortBy()` | `sortable` |\n| `addTableFilter()` | `filterable showGlobalFilter` |\n| `addColumnFilters()` | `filterable showColumnFilters` |\n| `addPagination({ initialPageSize: 25 })` | `pageable pageSize={25}` |\n| `addSelectedRows()` | `showRowSelection` |\n| `addGroupBy()` | `groupable` |\n| `addSubRows()` | `treeData` |\n| `addColumnOrder()` | `enableColumnReorder` |\n| `addResizedColumns()` | nothing - resizing is built in |\n| `addHiddenColumns()` | `visible: false` on the column |\n| `addExpandedRows()` | `treeData`, or `isDetailRow` + `renderDetailRow` |\n| `addGridLayout()` | nothing - SvGrid owns its layout |\n\nEvery capability is off by default and turned on by its prop; there is no\nplugin registration step.\n\n## Before / after\n\n```diff\n- <script>\n- import { createTable } from 'svelte-headless-table'\n- import { addSortBy, addColumnFilters, addPagination } from 'svelte-headless-table/plugins'\n- import { readable } from 'svelte/store'\n-\n- const table = createTable(readable(data), {\n- sort: addSortBy(), filter: addColumnFilters(), page: addPagination(),\n- })\n- const columns = table.createColumns((t) => [\n- t.column({ accessor: 'name', header: 'Name' }),\n- t.column({ accessor: 'amount', header: 'Amount' }),\n- ])\n- const { headerRows, rows, tableAttrs, tableBodyAttrs } = table.createViewModel(columns)\n- </script>\n-\n- <table {...$tableAttrs}>\n- <thead> ...Subscribe over headerRows... </thead>\n- <tbody {...$tableBodyAttrs}> ...Subscribe over rows... </tbody>\n- </table>\n\n+ <script lang=\"ts\">\n+ import {\n+ SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,\n+ type ColumnDef,\n+ } from '@svgrid/grid'\n+\n+ const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })\n+ const columns: ColumnDef<typeof features, Row>[] = [\n+ { field: 'name', header: 'Name' },\n+ { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },\n+ ]\n+ </script>\n+\n+ <SvGrid data={rows} columns={columns} features={features} showPagination />\n```\n\nType the column array against your row type. `GridColumns<(typeof data)[number]>`\nis the shortest form; a bare `GridColumns` widens the row to\n`Record<string, unknown>` and stops checking `field` against your real keys.\n\n## What you get for free\n\n- **The renderer.** No `createViewModel`, no `Subscribe`, no hand-built\n `<table>`. SvGrid ships virtualization, sticky headers, column\n resize, keyboard nav, and ARIA.\n- **Excel-style filter menu** and **cell-range selection + TSV copy**,\n which are BYO in svelte-headless-table.\n- **Inline editing** with typed editors and validation hooks.\n- **In-grid AI helpers** - natural-language filter, smart fill, summarise -\n free in `@svgrid/grid` against a model you register.\n- **Enterprise features** - Excel and PDF export, print, import and pivot -\n in one paid add-on; CSV, TSV and JSON export are free.\n\nIf you would rather keep driving your own `<table>`, the headless demo\nbelow does exactly that on `createSvGrid`, plugins replaced by features:\n\n<div data-docs-demo=\"186-headless-table\" data-height=\"520\"></div>\n\n## What changes\n\n- **Stores → runes.** Reactive data is `$state` / a plain array, not a\n Svelte store you pass to `createTable`. If your rows came from a `derived`\n store, read it with `$` at the call site or move it to `$derived`.\n- **Plugins → features.** Register `rowSortingFeature` etc. in\n `tableFeatures({...})` instead of `addSortBy()` in the plugin bag.\n- **View model → component.** You stop owning the markup; style through\n `--sg-*` tokens (and Tailwind) instead of `tableAttrs`.\n\n## What does not come across\n\n- **Custom `cell` renderers.** `createRender(MyComponent, props)` has no direct\n equivalent; SvGrid uses a `cell` snippet. The codemod preserves yours as a\n `// TODO port:` comment.\n- **Your own plugins.** There is no plugin system to port them into.\n- **`tableAttrs` / `attrs()` spreading.** The component owns its attributes.\n\n## When not to migrate\n\n- You need control of the exact DOM. Use the fork, or SvGrid's\n [headless core](../why-headless.md) at `@svgrid/grid/core`.\n- Your table is a handful of rows with no interaction. A plain `{#each}` is\n less code than either library.\n- You depend on custom plugins. That is a rewrite, not a migration.\n- You only need Svelte 5 support. Use the fork.\n\n## Frequently asked questions\n\n### How hard is it to move from svelte-headless-table to SvGrid?\n\nUsually 1-3 hours per grid, and `npx @svgrid/migrate` does the mechanical part.\nThe plugin-to-feature mapping is almost one-to-one; most of the work is deleting\nthe `createViewModel` + `Subscribe` + `<table>` markup, because SvGrid renders\nthat for you.\n\n### Does SvGrid use Svelte 5 runes instead of stores?\n\nYes. svelte-headless-table is built on Svelte 4 stores; SvGrid is Svelte-5\nnative (`$state` / `$derived` / `$effect`) with snippets for custom cells.\n\n### Is SvGrid still headless like svelte-headless-table?\n\nYes - `createSvGrid` plus the row-model factories is a headless engine you can\ndrive with your own markup, importable on its own from `@svgrid/grid/core`. The\ndifference is that SvGrid *also* ships a batteries-included `<SvGrid>` component\nso you usually do not have to.\n\n### Is svelte-headless-table still maintained?\n\nThe original's last publish date and Svelte 4 peer range are in the facts box\nat the top of the page, read from npm on the date shown, and its README says\nthere are no current plans for a Svelte 5 port. A community fork,\n`@humanspeak/svelte-headless-table`, is maintained and runs on Svelte 5 with\nthe same API; the facts box has its release line too. The fork is the\nlowest-effort option if you are happy with the library and only need Svelte 5.\n\n## What you end up with\n\nSorting, filtering and selection, on a library that still ships for Svelte 5.\n\n```svelte {runnable}\n<SvGrid data={rows} {columns} sortable filterable selectable />\n```\n\n## See also\n\n- [Upgrading a Svelte 4 table to Svelte 5](./svelte-5-upgrade-data-tables.md) - the whole upgrade run and captured, step by step\n- [SvGrid vs svelte-headless-table](https://svgrid.com/compare/svelte-headless-table/) - the side-by-side comparison, with a source and date for every claim\n- [Headless: build a table](./headless/build-a-table.md) - the demo above, step by step\n- [Migrating from TanStack Table](./migrating-from-tanstack-table.md) - sibling headless guide\n- [Why headless?](../why-headless.md) - the design rationale\n- [Architecture](./architecture.md) - the engine + render-component split\n"
5826
+ "markdown": "\n# Migrating from svelte-headless-table\n\nsvelte-headless-table popularised the headless-table pattern in the\nSvelte ecosystem. It is built on Svelte 4 stores and plugins\n(`addSortBy`, `addColumnFilters`, `addPagination`, ...), and it leaves\nthe markup to you. SvGrid keeps the same headless idea but runs on\nSvelte 5 runes and ships a render component, so the port mostly\n*removes* the table you used to hand-author.\n\n> Estimated effort: **1-3 hours** per grid. Most of the time is deleting\n> the `<table>` markup and `Subscribe` blocks you no longer need.\n\n<!-- facts:start svelte-headless-table pkg:@humanspeak/svelte-headless-table -->\n> **Facts, checked 12 Sep 2026.** `svelte-headless-table` 0.18.3, MIT, last published 28 Oct 2024, 90,100 npm downloads in the 30 days to 10 Sep 2026. `@humanspeak/svelte-headless-table` 6.2.0, MIT, last published 27 Aug 2026, 8,640 npm downloads in the same window. `@svgrid/grid` 3.0.3, MIT, last published 11 Sep 2026, 16,900 npm downloads in the same window. Bundle, minified and gzipped, each package built alone with Svelte external: SvGrid 3.0.4 97.6 KB JS + 10.5 KB CSS (measured 22 Sep 2026); `svelte-headless-table` 0.18.3 5.7 KB JS, no separate stylesheet, svelte external (measured 12 Sep 2026). svelte-headless-table pricing, as its site states it: svelte-headless-table is MIT and free; no paid licence or support is offered, and the author states there are no plans for a Svelte 5 port (https://github.com/bryanmylee/svelte-headless-table, read 12 Sep 2026). SvGrid: MIT core; @svgrid/enterprise from $299 per developer per year (Indie, under $1M revenue), $599 for Enterprise. Side by side, with sources: [SvGrid vs svelte-headless-table](https://svgrid.com/compare/svelte-headless-table/).\n<!-- facts:end -->\n\n## Know your options first\n\nThe original package's last release and its Svelte 4 peer range are in the\nfacts box above, and its README states there are no current plans for a\nSvelte 5 port, so a Svelte 5 upgrade forces a decision. There are three\nhonest answers and you should know all of them:\n\n1. **`@humanspeak/svelte-headless-table`** - a maintained fork on Svelte 5 with\n the same API; its version, publish date and downloads are in the facts box\n too. Changing one package name is the cheapest path by a wide margin. If\n your table works and you only need Svelte 5, do that.\n2. **TanStack Table v9** - its Svelte adapter declares a Svelte 5 peer range.\n Still headless-only, so you keep writing and maintaining the markup.\n3. **SvGrid** - this page. A different trade: you delete the markup and take a\n renderer instead.\n\nPick SvGrid when the markup is the part you are tired of. Note that the blocker\nis not the syntax and not really the install either: `svelte-headless-table@0.18.3`\ndeclares `svelte@^4`, which npm 11 overrides with a warning (older npm needed\n`--legacy-peer-deps`), and the untouched component then type-checks clean in\nlegacy mode. Slots and `let:` still work in Svelte 5 - they are deprecated in\nfavour of snippets, not removed - so the `Subscribe` blocks below keep\nrendering. The trouble starts when that component moves to runes: the library\ntakes a store, your data is a rune, and the bridge between them is yours to\nwrite and maintain. We ran the whole upgrade and captured every line of it in\n[Upgrading a Svelte 4 table to Svelte 5](./svelte-5-upgrade-data-tables.md).\n\n## Run the codemod\n\nThe example at the end of this page runs against these rows:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n department: string\n city: string\n age: number\n salary: number\n }\n\n const people: Person[] = [\n { id: 1, name: 'Ada Lovelace', department: 'Engineering', city: 'London', age: 36, salary: 142000 },\n { id: 2, name: 'Grace Hopper', department: 'Engineering', city: 'New York', age: 45, salary: 168000 },\n { id: 3, name: 'Linus Torvalds', department: 'Platform', city: 'Portland', age: 54, salary: 155000 },\n { id: 4, name: 'Radia Perlman', department: 'Networking', city: 'Seattle', age: 49, salary: 161000 },\n { id: 5, name: 'Barbara Liskov', department: 'Platform', city: 'Boston', age: 52, salary: 172000 },\n ]\n\n let rows = $state<Person[]>(people)\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 200, editorType: 'text' },\n { field: 'department', header: 'Department', width: 150, editorType: 'text' },\n { field: 'city', header: 'City', width: 140, editorType: 'text' },\n { field: 'age', header: 'Age', width: 90, editorType: 'number' },\n { field: 'salary', header: 'Salary', width: 130, editorType: 'number', format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```bash\nnpx @svgrid/migrate # preview the result\nnpx @svgrid/migrate src --write # apply it\n```\n\nIt translates column definitions and plugin config, deletes the\n`Subscribe`/`Render` scaffolding, and reports anything it cannot map rather than\ndropping it silently. It previews by default. See\n[`@svgrid/migrate`](https://www.npmjs.com/package/@svgrid/migrate) for the full\nmapping and its limits.\n\n## Vocabulary cheat sheet\n\n| svelte-headless-table | sv-grid |\n| ----------------------------------------- | ----------------------------------------- |\n| `createTable(data, plugins)` | `createSvGrid({...})` or `<SvGrid>` |\n| `table.createColumns((t) => [...])` | `columns: ColumnDef[]` |\n| `t.column({ accessor: 'x', header })` | `{ field: 'x', header }` |\n| `t.column({ accessor: (r) => ... })` | `{ id, fieldFn: (r) => ... }` |\n| `t.group({ header, columns })` | `{ header, columns: [...] }` (column group) |\n| `addSortBy()` | `rowSortingFeature` |\n| `addColumnFilters()` / `addTableFilter()` | `columnFilteringFeature` |\n| `addPagination()` | Built in; toggle `showPagination` |\n| `addExpandedRows()` / `addSubRows()` | `rowExpandingFeature` |\n| `addGroupBy()` | `columnGroupingFeature` + `api.setGroupBy()` |\n| `addSelectedRows()` | `rowSelectionFeature` |\n| `addDataExport()` | `@svgrid/enterprise` export pack |\n| `createViewModel(columns)` + `Subscribe` | `<SvGrid>` (no view model to wire) |\n| `pluginStates.sort.sortKeys` | `api.setSort(id, dir)` / `onSortingChange` |\n\n### The shortcut form\n\nThat table maps plugins onto the headless *features*, which is what you want if\nyou keep driving the engine yourself. If you are moving to the `<SvGrid>`\ncomponent, every capability also has a boolean prop, and that is what the\ncodemod emits:\n\n| Plugin | `<SvGrid>` prop |\n| --- | --- |\n| `addSortBy()` | `sortable` |\n| `addTableFilter()` | `filterable showGlobalFilter` |\n| `addColumnFilters()` | `filterable showColumnFilters` |\n| `addPagination({ initialPageSize: 25 })` | `pageable pageSize={25}` |\n| `addSelectedRows()` | `showRowSelection` |\n| `addGroupBy()` | `groupable` |\n| `addSubRows()` | `treeData` |\n| `addColumnOrder()` | `enableColumnReorder` |\n| `addResizedColumns()` | nothing - resizing is built in |\n| `addHiddenColumns()` | `visible: false` on the column |\n| `addExpandedRows()` | `treeData`, or `isDetailRow` + `renderDetailRow` |\n| `addGridLayout()` | nothing - SvGrid owns its layout |\n\nEvery capability is off by default and turned on by its prop; there is no\nplugin registration step.\n\n## Before / after\n\n```diff\n- <script>\n- import { createTable } from 'svelte-headless-table'\n- import { addSortBy, addColumnFilters, addPagination } from 'svelte-headless-table/plugins'\n- import { readable } from 'svelte/store'\n-\n- const table = createTable(readable(data), {\n- sort: addSortBy(), filter: addColumnFilters(), page: addPagination(),\n- })\n- const columns = table.createColumns((t) => [\n- t.column({ accessor: 'name', header: 'Name' }),\n- t.column({ accessor: 'amount', header: 'Amount' }),\n- ])\n- const { headerRows, rows, tableAttrs, tableBodyAttrs } = table.createViewModel(columns)\n- </script>\n-\n- <table {...$tableAttrs}>\n- <thead> ...Subscribe over headerRows... </thead>\n- <tbody {...$tableBodyAttrs}> ...Subscribe over rows... </tbody>\n- </table>\n\n+ <script lang=\"ts\">\n+ import {\n+ SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,\n+ type ColumnDef,\n+ } from '@svgrid/grid'\n+\n+ const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })\n+ const columns: ColumnDef<typeof features, Row>[] = [\n+ { field: 'name', header: 'Name' },\n+ { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },\n+ ]\n+ </script>\n+\n+ <SvGrid data={rows} columns={columns} features={features} showPagination />\n```\n\nType the column array against your row type. `GridColumns<(typeof data)[number]>`\nis the shortest form; a bare `GridColumns` widens the row to\n`Record<string, unknown>` and stops checking `field` against your real keys.\n\n## What you get for free\n\n- **The renderer.** No `createViewModel`, no `Subscribe`, no hand-built\n `<table>`. SvGrid ships virtualization, sticky headers, column\n resize, keyboard nav, and ARIA.\n- **Excel-style filter menu** and **cell-range selection + TSV copy**,\n which are BYO in svelte-headless-table.\n- **Inline editing** with typed editors and validation hooks.\n- **In-grid AI helpers** - natural-language filter, smart fill, summarise -\n free in `@svgrid/grid` against a model you register.\n- **Enterprise features** - Excel and PDF export, print, import and pivot -\n in one paid add-on; CSV, TSV and JSON export are free.\n\nIf you would rather keep driving your own `<table>`, the headless demo\nbelow does exactly that on `createSvGrid`, plugins replaced by features:\n\n<div data-docs-demo=\"186-headless-table\" data-height=\"520\"></div>\n\n## What changes\n\n- **Stores → runes.** Reactive data is `$state` / a plain array, not a\n Svelte store you pass to `createTable`. If your rows came from a `derived`\n store, read it with `$` at the call site or move it to `$derived`.\n- **Plugins → features.** Register `rowSortingFeature` etc. in\n `tableFeatures({...})` instead of `addSortBy()` in the plugin bag.\n- **View model → component.** You stop owning the markup; style through\n `--sg-*` tokens (and Tailwind) instead of `tableAttrs`.\n\n## What does not come across\n\n- **Custom `cell` renderers.** `createRender(MyComponent, props)` has no direct\n equivalent; SvGrid uses a `cell` snippet. The codemod preserves yours as a\n `// TODO port:` comment.\n- **Your own plugins.** There is no plugin system to port them into.\n- **`tableAttrs` / `attrs()` spreading.** The component owns its attributes.\n\n## When not to migrate\n\n- You need control of the exact DOM. Use the fork, or SvGrid's\n [headless core](../why-headless.md) at `@svgrid/grid/core`.\n- Your table is a handful of rows with no interaction. A plain `{#each}` is\n less code than either library.\n- You depend on custom plugins. That is a rewrite, not a migration.\n- You only need Svelte 5 support. Use the fork.\n\n## Frequently asked questions\n\n### How hard is it to move from svelte-headless-table to SvGrid?\n\nUsually 1-3 hours per grid, and `npx @svgrid/migrate` does the mechanical part.\nThe plugin-to-feature mapping is almost one-to-one; most of the work is deleting\nthe `createViewModel` + `Subscribe` + `<table>` markup, because SvGrid renders\nthat for you.\n\n### Does SvGrid use Svelte 5 runes instead of stores?\n\nYes. svelte-headless-table is built on Svelte 4 stores; SvGrid is Svelte-5\nnative (`$state` / `$derived` / `$effect`) with snippets for custom cells.\n\n### Is SvGrid still headless like svelte-headless-table?\n\nYes - `createSvGrid` plus the row-model factories is a headless engine you can\ndrive with your own markup, importable on its own from `@svgrid/grid/core`. The\ndifference is that SvGrid *also* ships a batteries-included `<SvGrid>` component\nso you usually do not have to.\n\n### Is svelte-headless-table still maintained?\n\nThe original's last publish date and Svelte 4 peer range are in the facts box\nat the top of the page, read from npm on the date shown, and its README says\nthere are no current plans for a Svelte 5 port. A community fork,\n`@humanspeak/svelte-headless-table`, is maintained and runs on Svelte 5 with\nthe same API; the facts box has its release line too. The fork is the\nlowest-effort option if you are happy with the library and only need Svelte 5.\n\n## What you end up with\n\nSorting, filtering and selection, on a library that still ships for Svelte 5.\n\n```svelte {runnable}\n<SvGrid data={rows} {columns} sortable filterable selectable />\n```\n\n## See also\n\n- [Upgrading a Svelte 4 table to Svelte 5](./svelte-5-upgrade-data-tables.md) - the whole upgrade run and captured, step by step\n- [SvGrid vs svelte-headless-table](https://svgrid.com/compare/svelte-headless-table/) - the side-by-side comparison, with a source and date for every claim\n- [Headless: build a table](./headless/build-a-table.md) - the demo above, step by step\n- [Migrating from TanStack Table](./migrating-from-tanstack-table.md) - sibling headless guide\n- [Why headless?](../why-headless.md) - the design rationale\n- [Architecture](./architecture.md) - the engine + render-component split\n"
5820
5827
  },
5821
5828
  {
5822
5829
  "slug": "help/migrating-from-syncfusion",
@@ -5844,7 +5851,7 @@ export const docs = [
5844
5851
  "path": "docs/help/migrating-from-ui-kit-tables.md",
5845
5852
  "title": "Migrating from a UI-kit table (Flowbite / Skeleton / shadcn-svelte)",
5846
5853
  "section": "Help",
5847
- "markdown": "# Migrating from a UI-kit table (Flowbite / Skeleton / shadcn-svelte)\n\nFlowbite-Svelte, Skeleton, and shadcn-svelte all ship a styled `<Table>`\ncomponent. They are presentation components: they render the rows you\npass and match your design tokens, but sorting, filtering,\nvirtualization, and editing are yours to write by hand. Moving to SvGrid\nreplaces that hand-rolled logic with built-in features - while still\nletting you match the design system.\n\n> **Not the shadcn-svelte data table.** That one is a separate recipe\n> built on TanStack Table v9, and it already does sorting, filtering,\n> pagination, and row selection. If that is what you have, read\n> [Migrating from the shadcn-svelte data table](./migrating-from-shadcn-data-table.md)\n> instead - the port is different, and smaller.\n\n<!-- facts:start svelte-ui-kit-tables -->\n> **Facts, checked 12 Sep 2026.** `@svgrid/grid` 3.0.3, MIT, last published 11 Sep 2026, 16,900 npm downloads in the 30 days to 10 Sep 2026. Bundle, minified and gzipped, each package built alone with Svelte external: SvGrid 3.0.4 97.6 KB JS + 10.5 KB CSS (measured 22 Sep 2026). Flowbite / Skeleton / shadcn-svelte tables pricing, as its site states it: Flowbite Svelte, Skeleton and shadcn-svelte are MIT component libraries; their table components are free and no grid licence is sold (https://github.com/themesberg/flowbite-svelte, read 12 Sep 2026). SvGrid: MIT core; @svgrid/enterprise from $299 per developer per year (Indie, under $1M revenue), $599 for Enterprise. Side by side, with sources: [SvGrid vs Flowbite / Skeleton / shadcn-svelte tables](https://svgrid.com/compare/svelte-ui-kit-tables/).\n<!-- facts:end -->\n\n> Estimated effort: **30 min - 1 hour** per table. You are mostly\n> deleting `{#each}` markup and the sort / filter state you wrote\n> yourself.\n\n## When this guide applies\n\nYou have a table that started simple and has grown:\n\n- You added a click-to-sort handler and a sort-state variable.\n- You added a search box and an array `.filter(...)`.\n- The list got long and now you want virtualization or pagination.\n- You started editing cells inline and it got messy.\n\nThat is the moment a styled `<Table>` stops paying for itself.\n\n## Before / after\n\nThe example at the end of this page runs against these rows:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n department: string\n city: string\n age: number\n salary: number\n }\n\n const people: Person[] = [\n { id: 1, name: 'Ada Lovelace', department: 'Engineering', city: 'London', age: 36, salary: 142000 },\n { id: 2, name: 'Grace Hopper', department: 'Engineering', city: 'New York', age: 45, salary: 168000 },\n { id: 3, name: 'Linus Torvalds', department: 'Platform', city: 'Portland', age: 54, salary: 155000 },\n { id: 4, name: 'Radia Perlman', department: 'Networking', city: 'Seattle', age: 49, salary: 161000 },\n { id: 5, name: 'Barbara Liskov', department: 'Platform', city: 'Boston', age: 52, salary: 172000 },\n ]\n\n let rows = $state<Person[]>(people)\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 200, editorType: 'text' },\n { field: 'department', header: 'Department', width: 150, editorType: 'text' },\n { field: 'city', header: 'City', width: 140, editorType: 'text' },\n { field: 'age', header: 'Age', width: 90, editorType: 'number' },\n { field: 'salary', header: 'Salary', width: 130, editorType: 'number', format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```diff\n- <script>\n- import { Table, TableHead, TableHeadCell, TableBody, TableBodyRow, TableBodyCell } from 'flowbite-svelte'\n- let sortKey = 'name', asc = true\n- $: sorted = [...rows].sort((a, b) => (a[sortKey] > b[sortKey] ? 1 : -1) * (asc ? 1 : -1))\n- </script>\n-\n- <Table>\n- <TableHead>\n- <TableHeadCell on:click={() => (sortKey = 'name')}>Name</TableHeadCell>\n- <TableHeadCell on:click={() => (sortKey = 'amount')}>Amount</TableHeadCell>\n- </TableHead>\n- <TableBody>\n- {#each sorted as row}\n- <TableBodyRow>\n- <TableBodyCell>{row.name}</TableBodyCell>\n- <TableBodyCell>{row.amount}</TableBodyCell>\n- </TableBodyRow>\n- {/each}\n- </TableBody>\n- </Table>\n\n+ <script lang=\"ts\">\n+ import {\n+ SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,\n+ type ColumnDef,\n+ } from '@svgrid/grid'\n+\n+ const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })\n+ const columns: ColumnDef<typeof features, Row>[] = [\n+ { field: 'name', header: 'Name' },\n+ { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },\n+ ]\n+ </script>\n+\n+ <SvGrid data={rows} columns={columns} features={features} showPagination />\n```\n\nThe sort handler, the `sorted` derivation, and the `{#each}` all go\naway. Sorting is a click on the header; filtering is the column menu.\n\n## Keep your design system\n\nSvGrid is unstyled-by-token, so it can match Flowbite / Skeleton /\nshadcn:\n\n- Re-theme through the `--sg-*` CSS custom properties (borders, header\n background, zebra rows, hover, selection, density).\n- Or drive those tokens from your Tailwind theme - see the\n [Tailwind integration](./tailwind.md) guide.\n\n## What you get for free\n\n- **Sorting, filtering, and pagination** without writing handlers.\n- **Row + column virtualization** so thousands of rows stay smooth.\n- **Inline editing**, **cell-range selection + copy**, grouping, tree,\n and master/detail when you need them.\n- **Accessibility** - WAI-ARIA grid roles and keyboard navigation built\n in, instead of a plain `<table>`.\n\n## What you give up\n\n- The **tiny footprint** of a styled `<table>` for a truly static list.\n- A **pixel-perfect**, zero-config match with the rest of the kit - you\n re-create the look with tokens instead (a one-time setup).\n\n## Frequently asked questions\n\n### When should I replace a Flowbite / Skeleton / shadcn table with a data grid?\n\nWhen the table needs sorting, filtering, virtualization, inline editing, or\nlarge datasets. These styled `<Table>` components are presentation only;\nonce you are hand-writing table behaviour, a data grid like SvGrid removes\nthat code. (shadcn-svelte also ships a separate TanStack-based data table -\nsee [that migration guide](./migrating-from-shadcn-data-table.md).)\n\n### Can SvGrid match my existing UI-kit styling?\n\nYes. SvGrid themes through `--sg-*` CSS variables, which you can wire to your\nTailwind / design-system tokens so it matches Flowbite, Skeleton, or\nshadcn-svelte.\n\n### Is it overkill for a small static table?\n\nFor a small, static table that never sorts or filters, a styled `<table>` is\nlighter and fine. Switch when the behaviour - not just the styling - becomes the\nwork.\n\n## What you end up with\n\nEverything the presentational table could not do: sort, filter, page, edit.\n\n```svelte {runnable}\n<SvGrid data={rows} {columns} sortable filterable pageable pageSize={3} editable />\n```\n\n## See also\n\n- [SvGrid vs UI-kit tables](https://svgrid.com/compare/svelte-ui-kit-tables/) - the side-by-side comparison\n- [Tailwind integration](./tailwind.md) - match your design system\n- [Getting started](../getting-started.md) - a working grid in ~15 lines\n"
5854
+ "markdown": "\n# Migrating from a UI-kit table (Flowbite / Skeleton / shadcn-svelte)\n\nFlowbite-Svelte, Skeleton, and shadcn-svelte all ship a styled `<Table>`\ncomponent. They are presentation components: they render the rows you\npass and match your design tokens, but sorting, filtering,\nvirtualization, and editing are yours to write by hand. Moving to SvGrid\nreplaces that hand-rolled logic with built-in features - while still\nletting you match the design system.\n\n> **Not the shadcn-svelte data table.** That one is a separate recipe\n> built on TanStack Table v9, and it already does sorting, filtering,\n> pagination, and row selection. If that is what you have, read\n> [Migrating from the shadcn-svelte data table](./migrating-from-shadcn-data-table.md)\n> instead - the port is different, and smaller.\n\n<!-- facts:start svelte-ui-kit-tables -->\n> **Facts, checked 12 Sep 2026.** `@svgrid/grid` 3.0.3, MIT, last published 11 Sep 2026, 16,900 npm downloads in the 30 days to 10 Sep 2026. Bundle, minified and gzipped, each package built alone with Svelte external: SvGrid 3.0.4 97.6 KB JS + 10.5 KB CSS (measured 22 Sep 2026). Flowbite / Skeleton / shadcn-svelte tables pricing, as its site states it: Flowbite Svelte, Skeleton and shadcn-svelte are MIT component libraries; their table components are free and no grid licence is sold (https://github.com/themesberg/flowbite-svelte, read 12 Sep 2026). SvGrid: MIT core; @svgrid/enterprise from $299 per developer per year (Indie, under $1M revenue), $599 for Enterprise. Side by side, with sources: [SvGrid vs Flowbite / Skeleton / shadcn-svelte tables](https://svgrid.com/compare/svelte-ui-kit-tables/).\n<!-- facts:end -->\n\n> Estimated effort: **30 min - 1 hour** per table. You are mostly\n> deleting `{#each}` markup and the sort / filter state you wrote\n> yourself.\n\n## When this guide applies\n\nYou have a table that started simple and has grown:\n\n- You added a click-to-sort handler and a sort-state variable.\n- You added a search box and an array `.filter(...)`.\n- The list got long and now you want virtualization or pagination.\n- You started editing cells inline and it got messy.\n\nThat is the moment a styled `<Table>` stops paying for itself.\n\n## Before / after\n\nThe example at the end of this page runs against these rows:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n department: string\n city: string\n age: number\n salary: number\n }\n\n const people: Person[] = [\n { id: 1, name: 'Ada Lovelace', department: 'Engineering', city: 'London', age: 36, salary: 142000 },\n { id: 2, name: 'Grace Hopper', department: 'Engineering', city: 'New York', age: 45, salary: 168000 },\n { id: 3, name: 'Linus Torvalds', department: 'Platform', city: 'Portland', age: 54, salary: 155000 },\n { id: 4, name: 'Radia Perlman', department: 'Networking', city: 'Seattle', age: 49, salary: 161000 },\n { id: 5, name: 'Barbara Liskov', department: 'Platform', city: 'Boston', age: 52, salary: 172000 },\n ]\n\n let rows = $state<Person[]>(people)\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 200, editorType: 'text' },\n { field: 'department', header: 'Department', width: 150, editorType: 'text' },\n { field: 'city', header: 'City', width: 140, editorType: 'text' },\n { field: 'age', header: 'Age', width: 90, editorType: 'number' },\n { field: 'salary', header: 'Salary', width: 130, editorType: 'number', format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```diff\n- <script>\n- import { Table, TableHead, TableHeadCell, TableBody, TableBodyRow, TableBodyCell } from 'flowbite-svelte'\n- let sortKey = 'name', asc = true\n- $: sorted = [...rows].sort((a, b) => (a[sortKey] > b[sortKey] ? 1 : -1) * (asc ? 1 : -1))\n- </script>\n-\n- <Table>\n- <TableHead>\n- <TableHeadCell on:click={() => (sortKey = 'name')}>Name</TableHeadCell>\n- <TableHeadCell on:click={() => (sortKey = 'amount')}>Amount</TableHeadCell>\n- </TableHead>\n- <TableBody>\n- {#each sorted as row}\n- <TableBodyRow>\n- <TableBodyCell>{row.name}</TableBodyCell>\n- <TableBodyCell>{row.amount}</TableBodyCell>\n- </TableBodyRow>\n- {/each}\n- </TableBody>\n- </Table>\n\n+ <script lang=\"ts\">\n+ import {\n+ SvGrid, tableFeatures, rowSortingFeature, columnFilteringFeature,\n+ type ColumnDef,\n+ } from '@svgrid/grid'\n+\n+ const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })\n+ const columns: ColumnDef<typeof features, Row>[] = [\n+ { field: 'name', header: 'Name' },\n+ { field: 'amount', header: 'Amount', format: { type: 'currency', currency: 'USD' } },\n+ ]\n+ </script>\n+\n+ <SvGrid data={rows} columns={columns} features={features} showPagination />\n```\n\nThe sort handler, the `sorted` derivation, and the `{#each}` all go\naway. Sorting is a click on the header; filtering is the column menu.\n\n## Keep your design system\n\nSvGrid is unstyled-by-token, so it can match Flowbite / Skeleton /\nshadcn:\n\n- Re-theme through the `--sg-*` CSS custom properties (borders, header\n background, zebra rows, hover, selection, density).\n- Or drive those tokens from your Tailwind theme - see the\n [Tailwind integration](./tailwind.md) guide.\n\n## What you get for free\n\n- **Sorting, filtering, and pagination** without writing handlers.\n- **Row + column virtualization** so thousands of rows stay smooth.\n- **Inline editing**, **cell-range selection + copy**, grouping, tree,\n and master/detail when you need them.\n- **Accessibility** - WAI-ARIA grid roles and keyboard navigation built\n in, instead of a plain `<table>`.\n\n## What you give up\n\n- The **tiny footprint** of a styled `<table>` for a truly static list.\n- A **pixel-perfect**, zero-config match with the rest of the kit - you\n re-create the look with tokens instead (a one-time setup).\n\n## Frequently asked questions\n\n### When should I replace a Flowbite / Skeleton / shadcn table with a data grid?\n\nWhen the table needs sorting, filtering, virtualization, inline editing, or\nlarge datasets. These styled `<Table>` components are presentation only;\nonce you are hand-writing table behaviour, a data grid like SvGrid removes\nthat code. (shadcn-svelte also ships a separate TanStack-based data table -\nsee [that migration guide](./migrating-from-shadcn-data-table.md).)\n\n### Can SvGrid match my existing UI-kit styling?\n\nYes. SvGrid themes through `--sg-*` CSS variables, which you can wire to your\nTailwind / design-system tokens so it matches Flowbite, Skeleton, or\nshadcn-svelte.\n\n### Is it overkill for a small static table?\n\nFor a small, static table that never sorts or filters, a styled `<table>` is\nlighter and fine. Switch when the behaviour - not just the styling - becomes the\nwork.\n\n## What you end up with\n\nEverything the presentational table could not do: sort, filter, page, edit.\n\n```svelte {runnable}\n<SvGrid data={rows} {columns} sortable filterable pageable pageSize={3} editable />\n```\n\n## See also\n\n- [SvGrid vs UI-kit tables](https://svgrid.com/compare/svelte-ui-kit-tables/) - the side-by-side comparison\n- [Tailwind integration](./tailwind.md) - match your design system\n- [Getting started](../getting-started.md) - a working grid in ~15 lines\n"
5848
5855
  },
5849
5856
  {
5850
5857
  "slug": "help/migrating-from-vincjo-datatables",
@@ -5949,7 +5956,7 @@ export const docs = [
5949
5956
  "path": "docs/help/rows/kanban-board.md",
5950
5957
  "title": "Kanban board mode",
5951
5958
  "section": "Kanban",
5952
- "markdown": "# Kanban board mode\n\nSet one `board` prop and the grid renders its rows as **cards in horizontal\nlanes** instead of a table. It is the same `<SvGrid>`, the same `data` and\n`columns` - only the presentation changes. Lanes are bucketed by a field;\ndragging a card to another lane tells you to reassign that field on your own\ndata.\n\nFor a board built up option by option, see [Build a sprint board](../kanban/sprint-board.md); this page is the reference for everything the `board` prop can say.\n\n![The same grid rows bucketed into lanes by a groupBy field, each row a card, with a drag reassigning the field.](/docs-media/grid-kanban.svg)\n\n<div data-docs-demo=\"343-kanban-board\" data-height=\"620\"></div>\n\n<!-- tutorial:kanban-board-drag -->\n<figure class=\"docs-tutorial\" id=\"tutorial-kanban-board-drag\" data-docs-tutorial=\"kanban-board-drag\">\n<video class=\"docs-tutorial-video\" src=\"/tutorials/kanban-board-drag.mp4\" poster=\"/tutorials/kanban-board-drag.poster.webp\" width=\"960\" height=\"540\" muted loop playsinline preload=\"none\" aria-label=\"Kanban board mode in SvGrid, 31 second tutorial\"><track kind=\"captions\" srclang=\"en\" label=\"English\" src=\"/tutorials/kanban-board-drag.vtt\" default>Your browser does not play embedded video. <a href=\"/tutorials/kanban-board-drag.mp4\">Download the MP4</a>.</video>\n<figcaption><strong>Kanban board mode in SvGrid</strong> (31 s, silent).</figcaption>\n<details class=\"docs-tutorial-transcript\"><summary>Transcript</summary>\n<p>One board prop turns the grid into a Kanban board. Lanes come from the status field, and every card is a row.</p>\n<p>Drag a card from Backlog into Review.</p>\n<p>The drop writes the new status back to the row, so the data and the board never disagree. In progress carries a WIP limit and refuses a card past it.</p>\n<p>Switch to Table, and the same rows show as a grid, with the card you moved already in Review.</p>\n</details>\n</figure>\n<!-- /tutorial:kanban-board-drag -->\n\nEvery example below runs against this setup. The board *renderer* ships in\n`@svgrid/enterprise`, so `enableBoardView()` is what lights the view up - the\n`board` prop itself is part of the free grid.\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, SvAvatar, SvChip, type GridColumns } from '@svgrid/grid'\n import { enableBoardView } from '@svgrid/enterprise'\n\n enableBoardView()\n\n // Wider than the minimum on purpose: the later examples reach for swimlanes,\n // facets, flags and cover images, and one shared row type keeps every block\n // on this page runnable against the same data.\n type Task = {\n id: number\n title: string\n status: 'backlog' | 'in_progress' | 'review' | 'done'\n assignee: string\n priority: 'Low' | 'Medium' | 'High'\n points: number\n tags: string[]\n labels: string[]\n blocked: boolean\n comments: number\n attachments: number\n due: string\n created: string\n cover?: string\n stories?: Task[]\n assignees: string[]\n }\n\n const task = (\n id: number,\n title: string,\n status: Task['status'],\n assignee: string,\n priority: Task['priority'],\n points: number,\n extra: Partial<Task> = {},\n ): Task => ({\n id, title, status, assignee, priority, points,\n tags: [], labels: [], blocked: false, comments: 0, attachments: 0, assignees: [assignee],\n due: '2026-07-01', created: '2026-06-01',\n ...extra,\n })\n\n let data = $state<Task[]>([\n task(1, 'API auth flow', 'backlog', 'Sam', 'High', 5, { tags: ['api'] }),\n task(2, 'Board drag-and-drop', 'in_progress', 'Lee', 'High', 8, { comments: 3, blocked: true }),\n task(3, 'Empty states', 'in_progress', 'Sam', 'Low', 2, { tags: ['ui'] }),\n task(4, 'Dark theme audit', 'review', 'Ada', 'Medium', 3, { attachments: 2 }),\n task(5, 'Release 1.3.0', 'done', 'Ada', 'High', 5),\n ])\n\n // Referenced by the selection example.\n let count = $state(0)\n\n const columns: GridColumns<Task> = [\n { field: 'title', header: 'Task', width: 240 },\n { field: 'assignee', header: 'Assignee', width: 140 },\n { field: 'priority', header: 'Priority', width: 110 },\n { field: 'points', header: 'Points', width: 90 },\n { field: 'status', header: 'Status', width: 130 },\n ]\n\n let nextId = 100\n const uid = () => ++nextId\n const addRow = (laneId: Task[\"status\"]) => {\n data = [...data, task(uid(), \"New task\", laneId, \"Sam\", \"Low\", 1)]\n }\n const remove = (row: Task) => {\n data = data.filter((r) => r !== row)\n }\n const clearLane = (laneId: Task[\"status\"]) => {\n data = data.filter((r) => r.status !== laneId)\n }\n const save = (row: Task) => console.log(\"save\", row.id)\n const row = data[0]!\n\n const lanes = [\n { id: 'backlog', title: 'Backlog' },\n { id: 'in_progress', title: 'In progress', color: '#f59e0b', wipLimit: 3 },\n { id: 'review', title: 'Review', color: '#8b5cf6' },\n { id: 'done', title: 'Done', color: '#22c55e' },\n ]\n</script>\n```\n\n## The minimum\n\nPoint `board.groupBy` at the field that decides the lane. With nothing else,\nlanes are derived from the distinct values found in the data (first-seen\norder), and each row renders as a default card built from your columns.\n\n```svelte {runnable}\n<SvGrid {data} {columns} board={{ groupBy: 'status' }} />\n```\n\n## Ordered lanes, titles, colors, WIP limits\n\nPass an explicit `lanes` array to fix the order, give friendly titles, and add\nan accent color or a work-in-progress limit. A lane id equals the `groupBy`\nfield value of the cards it holds; a lane with no cards shows a placeholder.\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{\n groupBy: 'status',\n lanes: [\n { id: 'backlog', title: 'Backlog' },\n { id: 'in_progress', title: 'In progress', color: '#f59e0b', wipLimit: 3 },\n { id: 'review', title: 'Review', color: '#8b5cf6' },\n { id: 'done', title: 'Done', color: '#22c55e' },\n ],\n }} />\n```\n\nThe lane header always shows its card count; when the count exceeds `wipLimit`\nit is flagged (shown as `count/limit`). Set **`enforceWip`** to make the limit\nhard - a drag or keyboard move that would push a lane past its limit is\nrejected and the card snaps back (announced to screen readers).\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', enforceWip: true, lanes }} />\n```\n\n## Lane summaries (roll-ups)\n\nPass `laneSummary` to show a per-lane total in the header - story points, a\ndollar sum, anything. It receives the lane's cards (the current swimlane's when\n`swimlaneBy` is set) and returns a short string. `swimlaneSummary` does the same\nfor a whole swimlane band.\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{\n groupBy: 'status',\n laneSummary: (rows) => `${rows.reduce((s, r) => s + r.points, 0)} pts`,\n swimlaneSummary: (rows) => `${rows.reduce((s, r) => s + r.points, 0)} pts`,\n }} />\n```\n\n## Search, filter and sort\n\nThe board renders the grid's **filtered and sorted** row model, not the raw\ndata - so column filters, the grid's sort, and the built-in search box all flow\nthrough to the lanes. A search box shows above the board by default; set\n`searchable: false` to hide it, or `searchPlaceholder` to change its text.\n\n```svelte {runnable}\n<SvGrid {data} {columns} sortable\n board={{ groupBy: 'status', searchPlaceholder: 'Find a task...' }} />\n```\n\n## Swimlanes\n\nSet `swimlaneBy` to split the board into horizontal **swimlane bands** by a\nsecond field. Each band shows the full lane set with only its own cards.\nDragging a card into a lane under a different band reassigns the swimlane field\ntoo - `onCardMove` then carries `fromSwimlane` / `toSwimlane`. Add\n`collapsibleSwimlanes` to let users fold a whole band via its header chevron.\n\n```svelte\n<SvGrid {data} {columns}\n board={{\n groupBy: 'status',\n swimlaneBy: 'assignee',\n onCardMove: (e) => {\n e.row.status = e.toLane\n if (e.toSwimlane != null) e.row.assignee = e.toSwimlane\n },\n }} />\n```\n\n## Collapsible lanes\n\nSet `collapsibleLanes` and each lane header gets a chevron that collapses the\nlane to a slim strip - handy for wide boards.\n\n```svelte {runnable}\n<SvGrid {data} {columns} board={{ groupBy: 'status', collapsibleLanes: true }} />\n```\n\n## Card context menu\n\nProvide `cardMenu` and right-clicking (or long-pressing) a card opens a context\nmenu. Return the items for that card; the `ctx` argument gives board-native\nhelpers - `moveTo(laneId)` and `edit()` - plus the lane list, so a \"Move to\"\nsubmenu is a one-liner. Items use the same `MenuItem` shape as `SvContextMenu`\n(label / icon / shortcut / `children` submenus / `separator` / `onSelect`).\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{\n groupBy: 'status',\n cardMenu: (row, ctx) => [\n { label: 'Edit', onSelect: ctx.edit },\n { label: 'Move to', children: ctx.lanes\n .filter((l) => l.id !== row.status)\n .map((l) => ({ label: l.title, onSelect: () => ctx.moveTo(l.id) })) },\n { separator: true },\n { label: 'Delete', onSelect: () => remove(row) },\n ],\n }} />\n```\n\n## Lane context menu\n\nAlongside `cardMenu`, `laneMenu` puts a menu on a **lane header** right-click.\nIts `ctx` gives lane-native helpers - `addCard(title?)`, `toggleCollapse()`,\nplus the lane's `cards` and `collapsed` state.\n\n```svelte\n<SvGrid {data} {columns}\n board={{ groupBy: 'status',\n laneMenu: (laneId, ctx) => [\n { label: 'Add card', onSelect: () => ctx.addCard() },\n { label: `Clear (${ctx.cards.length})`, onSelect: () => clearLane(laneId) },\n ] }} />\n```\n\n## Facet filters, multi-select, flags & age\n\nA cluster of \"power\" options, all on the built-in default card:\n\n- **`facets`** - a filter bar of chips (one per distinct value) for the listed\n fields; selecting chips filters the visible cards. Works with array fields\n (tags) too.\n- **`selectable`** - click to select a card, Ctrl/Cmd-click to toggle, and\n dragging a selected card moves the **whole selection**. `onSelectionChange`\n reports the selected rows.\n- **`flagField`** - a truthy field paints a red **blocked** corner.\n- **`ageField`** - a created/started date renders a relative **age** badge (`3d`).\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{\n groupBy: 'status',\n facets: ['tags', 'assignee'],\n selectable: true,\n onSelectionChange: (rows) => (count = rows.length),\n flagField: 'blocked',\n ageField: 'created',\n }} />\n```\n\n## Hierarchical cards (epics -> stories)\n\nPoint `childrenField` at a row's child rows and each card gains a children\ncount that **expands to show its sub-cards** inline, each with its own title\nand `groupBy` value - the epic -> stories shape.\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', childrenField: 'stories' }} />\n```\n\n## Reorderable lanes & runtime group-by\n\nSet `reorderableLanes` to let users **drag lane headers** to reorder the\ncolumns; the order is tracked (and saved with `persistKey`), and\n`onLaneReorder(orderedIds)` fires. Because `groupBy` is reactive, you can also\nswitch the **lane axis at runtime** just by changing it - the board re-buckets\nand resets card positions to the new field automatically. Set `onLaneRename`\nand users can **double-click a lane title** to rename it inline.\n\n```svelte\n<script>\n let groupBy = $state('status') // bind to a Status / Assignee / Priority selector\n</script>\n\n<SvGrid {data} {columns}\n board={{ groupBy, reorderableLanes: true, onCardMove: (e) => (row[groupBy] = e.toLane) }} />\n```\n\n## Saving the board layout\n\nPass `persistKey` and the board saves its layout - card positions, order,\nper-card edits, and collapsed lanes - to `localStorage` under that key, and\nrestores it on load. It needs `getRowId` so the saved keys line up with the\nright rows after a reload.\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n getRowId={(r) => String(r.id)}\n board={{ groupBy: 'status', persistKey: 'my-board' }} />\n```\n\nThe layout is an overlay on top of your data, so if you also persist the data\nitself (e.g. mirroring `onCardMove` to your store), the two stay in sync. To\npersist somewhere other than `localStorage`, use `onLayoutChange(layout)` and\nwrite it yourself; feed it back by seeding your data before mount. To reset,\nclear the key and remount the board (e.g. Svelte's `{#key}`).\n\n## Virtualized lanes (large boards)\n\nFor boards with thousands of cards in a lane, set `virtualized` so each lane\nonly keeps the cards in view in the DOM. Windowing is fixed-height, so set\n`cardHeight` to match your cards (default `76`). Drag-and-drop, keyboard move,\nand search all keep working - keyboard focus scrolls an off-screen card into\nview before landing on it.\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', virtualized: true, cardHeight: 72 }} />\n```\n\nBecause windowing assumes a uniform card height, keep your cards a consistent\nsize (or close to it) when virtualizing; leave `virtualized` off for boards\nwith a few hundred cards, where it isn't needed.\n\n## Moving cards\n\nMoving cards is **built in** - you write no move code. Cards are draggable\nbetween lanes and within a lane (with a live insertion marker), and the board\napplies the move itself: it reassigns the lane and reorders, tracked as an\noverlay keyed by row id, without mutating your data.\n\n`onCardMove` is an optional **notification** - it fires after each move so you\ncan persist to a backend, or mirror the new lane onto your own row if another\nview (a table, a count) reads the same data:\n\n```svelte\n<script>\n // Optional. The board already moved the card; this just syncs your store.\n function onCardMove(e) {\n // e = { row, fromLane, toLane, toIndex }\n e.row.status = e.toLane\n }\n</script>\n\n<SvGrid {data} {columns}\n getRowId={(r) => String(r.id)}\n board={{ groupBy: 'status', onCardMove }} />\n```\n\nPass `getRowId` so the move overlay stays pinned to the right row across data\nchanges (adds/removes/re-sorts). Without it the board falls back to per-object\nidentity, which is fine until you replace the row objects wholesale.\n\n## Keyboard drag-and-drop\n\nThe board is fully keyboard operable, so drag-and-drop is not mouse-only. Focus\na card and:\n\n- **Space** / **Enter** - grab it (press again to drop).\n- **Arrow Left / Right** - move it to the previous / next lane.\n- **Arrow Up / Down** - reorder it within its lane.\n- **Escape** - cancel and restore its original position.\n\nEvery step is announced through an ARIA live region for screen-reader users.\n\n## Editing cards\n\nSet `editable` and the board gets a **built-in card editor**: double-click a\ncard (or press **F2** while it is focused) to edit its fields inline. The\nfields come from the columns that declare an `editorType` (or all fields if\nnone do), rendered as the matching input (text / number / date / checkbox).\nSave writes to the board's edit overlay - the card updates immediately - and\nfires `onCardCommit` with the changed fields, so you can persist:\n\n```svelte\n<script>\n function onCardCommit(e) {\n // e = { row, changes, values } - the board already applied it\n Object.assign(e.row, e.values) // mirror onto your data / persist\n }\n</script>\n\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', editable: true, onCardCommit }} />\n```\n\n### Detail drawer\n\nFor a fuller editor, set `drawer` and opening a card shows a built-in\n**`SvDrawer` + `SvForm`** rendered from your columns with the UI-kit editors\n(text / date / select / number / colour / checkbox, chosen from each column's\n`editorType`). `true` shows **all** fields; pass a config to pick a subset or\ncustomize the drawer:\n\n```svelte\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', drawer: true, onCardCommit: (e) => save(e) }} />\n\n<!-- only some fields, custom title / side -->\n<SvGrid {data} {columns}\n board={{ groupBy: 'status',\n drawer: { fields: ['title', 'due', 'assignee'], title: (row) => row.title, side: 'right' } }} />\n```\n\nSaving applies the edit and fires `onCardCommit`. The drawer does **not** close\non an outside click (so opening a select or picker inside it, or a stray click,\nnever loses your edits) - close it with Save, Escape, or the × button. If\n`commentsField` is set, the drawer also shows the **comments thread** (read /\nwrite / delete) below the form.\n\nPrecedence: `onCardEdit` > `drawer` > the inline `editable` editor - so pass\n`onCardEdit` if you'd rather open your own editor or route to a detail screen.\n\n## Custom cards\n\nOmit `card` for the default card (title from the first column, then a few\nmeta rows). Pass a `card` snippet to render whatever you like - it receives the\nrow, so you can drop in avatars, chips, progress, or actions from the UI kit.\n\n```svelte\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', card: taskCard }} />\n\n{#snippet taskCard(task)}\n <div class=\"font-semibold\">{task.title}</div>\n <div class=\"row\">\n <SvAvatar name={task.assignee} size={20} />\n <SvChip variant={task.priority === 'High' ? 'danger' : 'neutral'}>\n {task.priority}\n </SvChip>\n </div>\n{/snippet}\n```\n\nYou can also set `titleField` and `cardFields` to steer the default card\nwithout writing a snippet.\n\n## Adding cards\n\nProvide `onCardAdd` and each lane header gains a `+` button; it fires with the\nlane id so you can append a new row in that lane. Add `composer` for a nicer\n**type-a-title** box at the bottom of each lane - Enter calls\n`onCardAdd(laneId, title)`.\n\n```svelte\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', composer: true, onCardAdd: (lane, title) => addRow(lane, title) }} />\n```\n\n## Card badges, tags, comments & cover\n\nThe default card can show a rich badge row without a custom snippet - point the\nboard at your fields:\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{\n groupBy: 'status',\n labelsField: 'labels', // tags: string[] or { text, color }[] (coloured chips)\n dueField: 'due', // Date | ISO string; red when overdue\n assigneesField: 'assignees', // string | string[] -> avatar initials\n commentsField: 'comments', // array (length) or number -> comment-count badge\n attachmentsField: 'attachments', // array or number -> attachment-count badge\n coverField: 'cover', // a CSS colour -> strip across the card top\n }} />\n```\n\n`labelsField` is your **tags** - pass `{ text, color }[]` for coloured chips.\nThese badges render on the default card **and** below a custom `card` snippet.\n\n**Comments** are interactive: the comment badge expands an inline thread, and\nthe same thread appears in the **detail drawer** (a more discoverable place to\nmanage them). Pass `commentsField` (a `BoardComment[]` = `{ id, text, author?,\nat? }`) plus `onCommentAdd` / `onCommentDelete` to let users **write and delete**\ncomments - update your data in the callbacks.\n\n```svelte\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', commentsField: 'comments',\n onCommentAdd: (row, text) => row.comments.push({ id: uid(), text, author: 'You' }),\n onCommentDelete: (row, id) => (row.comments = row.comments.filter((c) => c.id !== id)) }} />\n```\n\nA **blocked** card (one that can't move forward - waiting on a dependency) is\nmarked with `flagField`: a truthy value shows a red corner + a \"Blocked\" badge,\nand a string value is used as the reason (badge tooltip). A blocked card is\n**locked from moving** (drag + keyboard) until it is unblocked - so blocking\nactually does something. Set `flagBlocksMoves: false` if you want a purely\nvisual flag that still allows moves.\n\n## Sub-tasks (checklists)\n\nPoint `subtasks` at a field holding `BoardSubtask[]` (`{ id, title, done }`) and\neach card gets a progress chip + bar; expand it to tick items or add more. The\nboard tracks toggles/adds in its own overlay (your data is never mutated) and\nfires `onSubtaskToggle` / `onSubtaskAdd` as notifications. Sub-task state is\nincluded in `persistKey` so it survives a reload.\n\n```svelte\n<SvGrid {data} {columns}\n getRowId={(r) => String(r.id)}\n board={{ groupBy: 'status', subtasks: 'items',\n onSubtaskToggle: (row, id, done) => …, onSubtaskAdd: (row, title) => … }} />\n```\n\nFor a full-detail editor, wire `onCardEdit` to open an `SvDrawer` with the rest\nof a card's fields (see demo 349).\n\n## `BoardConfig`\n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `groupBy` | `string` | **Required.** Field whose value buckets each row into a lane. |\n| `lanes` | `BoardLane[]` | Explicit, ordered lanes. Omit to derive from distinct values. |\n| `card` | `Snippet<[row]>` | Custom card body. Omit for the default card. |\n| `onCardMove` | `(e) => void` | Optional notification after a built-in move: `{ row, fromLane, toLane, toIndex }`. Persist / mirror here. |\n| `onCardAdd` | `(laneId, title?) => void` | Add-card affordance (header `+`, or composer title). |\n| `composer` | `boolean` | Type-a-title quick-add box at the bottom of each lane. |\n| `subtasks` | `string` | Field of `BoardSubtask[]`; renders a checklist + progress on the card. |\n| `onSubtaskToggle` | `(row, id, done) => void` | Notified when a sub-task is toggled. |\n| `onSubtaskAdd` | `(row, title) => void` | Notified when a sub-task is added on the card. |\n| `labelsField` | `string` | Field of label strings / `{text,color}` -> chips on the card. |\n| `dueField` | `string` | Field of a due date -> badge (red when overdue). |\n| `assigneesField` | `string` | Field of assignee name(s) -> avatar(s) on the card. |\n| `editable` | `boolean` | Enables the built-in inline card editor (double-click / F2). |\n| `onCardEdit` | `(row) => void` | Open your own editor instead of the built-in one. |\n| `drawer` | `boolean \\| BoardDrawerConfig` | Built-in `SvDrawer` + `SvForm` detail editor; `true` = all fields, or `{ fields, title, side, size }`. |\n| `cardMenu` | `(row, ctx) => MenuItem[]` | Card right-click menu; `ctx` = `{ lanes, moveTo, edit }`. |\n| `laneMenu` | `(laneId, ctx) => MenuItem[]` | Lane-header right-click menu; `ctx` = `{ cards, collapsed, toggleCollapse, addCard }`. |\n| `facets` | `string[]` | Fields shown as a facet filter-chip bar above the board. |\n| `selectable` | `boolean` | Card multi-select; dragging a selected card moves the whole selection. |\n| `onSelectionChange` | `(rows) => void` | Fires with the selected rows. |\n| `flagField` | `string` | Truthy -> \"Blocked\" badge + red corner (string = reason); locks the card from moving. |\n| `flagBlocksMoves` | `boolean` | Whether a blocked card is locked from moving. Defaults to `true`. |\n| `ageField` | `string` | A date -> a relative age badge (`3d`). |\n| `childrenField` | `string` | Child rows -> an expandable count of nested mini-cards. |\n| `onCardCommit` | `(e) => void` | Fires when the built-in editor saves: `{ row, changes, values }`. |\n| `laneSummary` | `(rows, laneId) => string` | Per-lane header roll-up (points / $ total / count). |\n| `swimlaneSummary` | `(rows, swimId) => string` | Per-swimlane band roll-up. |\n| `onLaneRename` | `(laneId, title) => void` | Enable double-click inline lane rename. |\n| `swimlaneBy` | `string` | Second axis: split the board into swimlane bands by this field. |\n| `collapsibleSwimlanes` | `boolean` | Let users collapse a swimlane band via its header chevron. |\n| `commentsField` | `string` | `BoardComment[]` -> a comment badge that expands to a thread. |\n| `onCommentAdd` | `(row, text) => void` | Let users write comments (append to your data). |\n| `onCommentDelete` | `(row, commentId) => void` | Let users delete comments. |\n| `attachmentsField` | `string` | Array or number -> attachment-count badge. |\n| `coverField` | `string` | A CSS colour -> a strip across the card top. |\n| `enforceWip` | `boolean` | Reject moves that would push a lane past its `wipLimit`. |\n| `collapsibleLanes` | `boolean` | Let users collapse a lane to a strip via its header chevron. |\n| `reorderableLanes` | `boolean` | Let users drag lane headers to reorder columns (persisted). |\n| `onLaneReorder` | `(orderedIds) => void` | Fires after a lane drag-reorder. |\n| `searchable` | `boolean` | Show the built-in search box (default `true`). |\n| `searchPlaceholder` | `string` | Placeholder for the search box. |\n| `virtualized` | `boolean` | Window each lane (only in-view cards in the DOM) for very large boards. |\n| `cardHeight` | `number` | Estimated card height for `virtualized` windowing (default `76`). |\n| `persistKey` | `string` | Save/restore the board layout to `localStorage` (needs `getRowId`). |\n| `onLayoutChange` | `(layout) => void` | Fires with the serializable layout on any change. |\n| `titleField` | `string` | Title on the default card (defaults to first column). |\n| `cardFields` | `string[]` | Meta rows on the default card (max 4). |\n\n`BoardLane` = `{ id, title?, color?, wipLimit? }`.\n\n## Notes\n\n- The board themes purely from the grid's `--sg-*` tokens - pick any preset and\n it follows. Set `--sg-board-lane-w` to change lane width.\n- Board mode replaces the table render, so table-only chrome (column headers,\n the pagination footer, the filter row) does not apply while `board` is set.\n- Moving a card is tracked as an overlay on top of your data - the board never\n mutates your rows. Mirror via `onCardMove` if other views must agree.\n\n## More examples\n\n### Sprint board (swimlanes + WIP)\n\nAn agile sprint board: status lanes crossed with a swimlane per assignee, an enforced WIP limit on In progress, and a story-point roll-up in every lane header via board.laneSummary. Drag across a band to reassign the owner; double-click to edit. Collapsible lanes.\n\n<div data-docs-demo=\"344-kanban-sprint\" data-height=\"560\"></div>\n\n### Sales pipeline (deal board)\n\nA CRM deal board: stages as lanes with a live total-value roll-up per stage (board.laneSummary). Rich deal cards; drag to advance a deal, double-click to edit. Moves and edits persist to localStorage via onCardMove / onCardCommit, so a reload restores the board.\n\n<div data-docs-demo=\"345-kanban-pipeline\" data-height=\"560\"></div>\n\n### Large board (virtualized)\n\nThousands of cards per lane kept smooth with board.virtualized - only the cards in view are in the DOM. A slider scales the board from 1k to 50k cards; drag-and-drop and keyboard move still work across the whole window.\n\n<div data-docs-demo=\"346-kanban-virtualized\" data-height=\"560\"></div>\n\n### Support triage board\n\nA helpdesk triage board: status lanes crossed with a priority swimlane, a search box front-and-center, and an SLA colour bar on each card driven by ticket age. Drag across a band to re-triage a ticket priority.\n\n<div data-docs-demo=\"347-kanban-support\" data-height=\"560\"></div>\n\n### Content calendar\n\nAn editorial pipeline: stage lanes crossed with a swimlane per channel. Rich cards carry a cover glyph, author and target date. Drag a piece down the pipeline, or across a band to move it to another channel; double-click to edit.\n\n<div data-docs-demo=\"348-kanban-content\" data-height=\"560\"></div>\n\n### Cards with sub-tasks & badges\n\nThe default board card made rich by config alone: label / due / assignee badges, a sub-task checklist with a progress bar (expand to tick items or add more), and a quick-add composer at the bottom of each lane. Double-click a card for the BUILT-IN detail drawer (board.drawer -> SvDrawer + SvForm with the UI-kit editors); toggle all fields vs a customized subset. Board / Table switcher.\n\n<div data-docs-demo=\"349-kanban-subtasks\" data-height=\"560\"></div>\n\n### Group-by switch + reorderable lanes\n\nBoard structure, live: switch the lane axis at runtime (Status / Assignee / Priority) and the board re-buckets, and drag a lane header to reorder the columns. Both built-in - the group-by switch resets card positions to the new field; lane order is tracked and persists with persistKey. Board / Table switcher.\n\n<div data-docs-demo=\"350-kanban-structure\" data-height=\"560\"></div>\n\n### Board power tools (filters, multi-select, menus)\n\nA facet filter bar (by tag + assignee), card multi-select with bulk move (click / Ctrl-click then drag the group), a blocked flag, a card-age badge, and both card + lane right-click menus - all from board config on the built-in default card. Board / Table switcher.\n\n<div data-docs-demo=\"351-kanban-power\" data-height=\"560\"></div>\n\n### Epics -> stories (hierarchical cards)\n\nPoint board.childrenField at a row child rows and each card gains a children count that expands to show its sub-cards inline (Jira epic -> stories). Each child shows its own title + status. Board / Table switcher.\n\n<div data-docs-demo=\"352-kanban-epics\" data-height=\"560\"></div>\n\n## See also\n\n- [Row dragging](./row-dragging.md) - reorder rows and move them between grids.\n- [Mobile card view](../mobile-card-view.md) - the responsive grid/card pivot.\n- [Grouping & aggregation](../grouping-aggregation.md) - the row-bucketing model board lanes reuse.\n- [Scheduler / calendar mode](./scheduler.md) - the same rows as bookings on a calendar.\n- [Gantt chart mode](./gantt.md) - the same rows as a project plan: in progress, due 1 November 2026.\n"
5959
+ "markdown": "# Kanban board mode\n\nSet one `board` prop and the grid renders its rows as **cards in horizontal\nlanes** instead of a table. It is the same `<SvGrid>`, the same `data` and\n`columns` - only the presentation changes. Lanes are bucketed by a field;\ndragging a card to another lane tells you to reassign that field on your own\ndata.\n\nFor a board built up option by option, see [Build a sprint board](../kanban/sprint-board.md); for the overview, see [Svelte Kanban board](https://svgrid.com/svelte/kanban-board/). This page is the reference for everything the `board` prop can say.\n\n![The same grid rows bucketed into lanes by a groupBy field, each row a card, with a drag reassigning the field.](/docs-media/grid-kanban.svg)\n\n<div data-docs-demo=\"343-kanban-board\" data-height=\"620\"></div>\n\n<!-- tutorial:kanban-board-drag -->\n<figure class=\"docs-tutorial\" id=\"tutorial-kanban-board-drag\" data-docs-tutorial=\"kanban-board-drag\">\n<video class=\"docs-tutorial-video\" src=\"/tutorials/kanban-board-drag.mp4\" poster=\"/tutorials/kanban-board-drag.poster.webp\" width=\"960\" height=\"540\" muted loop playsinline preload=\"none\" aria-label=\"Kanban board mode in SvGrid, 31 second tutorial\"><track kind=\"captions\" srclang=\"en\" label=\"English\" src=\"/tutorials/kanban-board-drag.vtt\" default>Your browser does not play embedded video. <a href=\"/tutorials/kanban-board-drag.mp4\">Download the MP4</a>.</video>\n<figcaption><strong>Kanban board mode in SvGrid</strong> (31 s, silent).</figcaption>\n<details class=\"docs-tutorial-transcript\"><summary>Transcript</summary>\n<p>One board prop turns the grid into a Kanban board. Lanes come from the status field, and every card is a row.</p>\n<p>Drag a card from Backlog into Review.</p>\n<p>The drop writes the new status back to the row, so the data and the board never disagree. In progress carries a WIP limit and refuses a card past it.</p>\n<p>Switch to Table, and the same rows show as a grid, with the card you moved already in Review.</p>\n</details>\n</figure>\n<!-- /tutorial:kanban-board-drag -->\n\nEvery example below runs against this setup. The board *renderer* ships in\n`@svgrid/enterprise`, so `enableBoardView()` is what lights the view up - the\n`board` prop itself is part of the free grid.\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, SvAvatar, SvChip, type GridColumns } from '@svgrid/grid'\n import { enableBoardView } from '@svgrid/enterprise'\n\n enableBoardView()\n\n // Wider than the minimum on purpose: the later examples reach for swimlanes,\n // facets, flags and cover images, and one shared row type keeps every block\n // on this page runnable against the same data.\n type Task = {\n id: number\n title: string\n status: 'backlog' | 'in_progress' | 'review' | 'done'\n assignee: string\n priority: 'Low' | 'Medium' | 'High'\n points: number\n tags: string[]\n labels: string[]\n blocked: boolean\n comments: number\n attachments: number\n due: string\n created: string\n cover?: string\n stories?: Task[]\n assignees: string[]\n }\n\n const task = (\n id: number,\n title: string,\n status: Task['status'],\n assignee: string,\n priority: Task['priority'],\n points: number,\n extra: Partial<Task> = {},\n ): Task => ({\n id, title, status, assignee, priority, points,\n tags: [], labels: [], blocked: false, comments: 0, attachments: 0, assignees: [assignee],\n due: '2026-07-01', created: '2026-06-01',\n ...extra,\n })\n\n let data = $state<Task[]>([\n task(1, 'API auth flow', 'backlog', 'Sam', 'High', 5, { tags: ['api'] }),\n task(2, 'Board drag-and-drop', 'in_progress', 'Lee', 'High', 8, { comments: 3, blocked: true }),\n task(3, 'Empty states', 'in_progress', 'Sam', 'Low', 2, { tags: ['ui'] }),\n task(4, 'Dark theme audit', 'review', 'Ada', 'Medium', 3, { attachments: 2 }),\n task(5, 'Release 1.3.0', 'done', 'Ada', 'High', 5),\n ])\n\n // Referenced by the selection example.\n let count = $state(0)\n\n const columns: GridColumns<Task> = [\n { field: 'title', header: 'Task', width: 240 },\n { field: 'assignee', header: 'Assignee', width: 140 },\n { field: 'priority', header: 'Priority', width: 110 },\n { field: 'points', header: 'Points', width: 90 },\n { field: 'status', header: 'Status', width: 130 },\n ]\n\n let nextId = 100\n const uid = () => ++nextId\n const addRow = (laneId: Task[\"status\"]) => {\n data = [...data, task(uid(), \"New task\", laneId, \"Sam\", \"Low\", 1)]\n }\n const remove = (row: Task) => {\n data = data.filter((r) => r !== row)\n }\n const clearLane = (laneId: Task[\"status\"]) => {\n data = data.filter((r) => r.status !== laneId)\n }\n const save = (row: Task) => console.log(\"save\", row.id)\n const row = data[0]!\n\n const lanes = [\n { id: 'backlog', title: 'Backlog' },\n { id: 'in_progress', title: 'In progress', color: '#f59e0b', wipLimit: 3 },\n { id: 'review', title: 'Review', color: '#8b5cf6' },\n { id: 'done', title: 'Done', color: '#22c55e' },\n ]\n</script>\n```\n\n## The minimum\n\nPoint `board.groupBy` at the field that decides the lane. With nothing else,\nlanes are derived from the distinct values found in the data (first-seen\norder), and each row renders as a default card built from your columns.\n\n```svelte {runnable}\n<SvGrid {data} {columns} board={{ groupBy: 'status' }} />\n```\n\n## Ordered lanes, titles, colors, WIP limits\n\nPass an explicit `lanes` array to fix the order, give friendly titles, and add\nan accent color or a work-in-progress limit. A lane id equals the `groupBy`\nfield value of the cards it holds; a lane with no cards shows a placeholder.\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{\n groupBy: 'status',\n lanes: [\n { id: 'backlog', title: 'Backlog' },\n { id: 'in_progress', title: 'In progress', color: '#f59e0b', wipLimit: 3 },\n { id: 'review', title: 'Review', color: '#8b5cf6' },\n { id: 'done', title: 'Done', color: '#22c55e' },\n ],\n }} />\n```\n\nThe lane header always shows its card count; when the count exceeds `wipLimit`\nit is flagged (shown as `count/limit`). Set **`enforceWip`** to make the limit\nhard - a drag or keyboard move that would push a lane past its limit is\nrejected and the card snaps back (announced to screen readers).\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', enforceWip: true, lanes }} />\n```\n\n## Lane summaries (roll-ups)\n\nPass `laneSummary` to show a per-lane total in the header - story points, a\ndollar sum, anything. It receives the lane's cards (the current swimlane's when\n`swimlaneBy` is set) and returns a short string. `swimlaneSummary` does the same\nfor a whole swimlane band.\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{\n groupBy: 'status',\n laneSummary: (rows) => `${rows.reduce((s, r) => s + r.points, 0)} pts`,\n swimlaneSummary: (rows) => `${rows.reduce((s, r) => s + r.points, 0)} pts`,\n }} />\n```\n\n## Search, filter and sort\n\nThe board renders the grid's **filtered and sorted** row model, not the raw\ndata - so column filters, the grid's sort, and the built-in search box all flow\nthrough to the lanes. A search box shows above the board by default; set\n`searchable: false` to hide it, or `searchPlaceholder` to change its text.\n\n```svelte {runnable}\n<SvGrid {data} {columns} sortable\n board={{ groupBy: 'status', searchPlaceholder: 'Find a task...' }} />\n```\n\n## Swimlanes\n\nSet `swimlaneBy` to split the board into horizontal **swimlane bands** by a\nsecond field. Each band shows the full lane set with only its own cards.\nDragging a card into a lane under a different band reassigns the swimlane field\ntoo - `onCardMove` then carries `fromSwimlane` / `toSwimlane`. Add\n`collapsibleSwimlanes` to let users fold a whole band via its header chevron.\n\n```svelte\n<SvGrid {data} {columns}\n board={{\n groupBy: 'status',\n swimlaneBy: 'assignee',\n onCardMove: (e) => {\n e.row.status = e.toLane\n if (e.toSwimlane != null) e.row.assignee = e.toSwimlane\n },\n }} />\n```\n\n## Collapsible lanes\n\nSet `collapsibleLanes` and each lane header gets a chevron that collapses the\nlane to a slim strip - handy for wide boards.\n\n```svelte {runnable}\n<SvGrid {data} {columns} board={{ groupBy: 'status', collapsibleLanes: true }} />\n```\n\n## Card context menu\n\nProvide `cardMenu` and right-clicking (or long-pressing) a card opens a context\nmenu. Return the items for that card; the `ctx` argument gives board-native\nhelpers - `moveTo(laneId)` and `edit()` - plus the lane list, so a \"Move to\"\nsubmenu is a one-liner. Items use the same `MenuItem` shape as `SvContextMenu`\n(label / icon / shortcut / `children` submenus / `separator` / `onSelect`).\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{\n groupBy: 'status',\n cardMenu: (row, ctx) => [\n { label: 'Edit', onSelect: ctx.edit },\n { label: 'Move to', children: ctx.lanes\n .filter((l) => l.id !== row.status)\n .map((l) => ({ label: l.title, onSelect: () => ctx.moveTo(l.id) })) },\n { separator: true },\n { label: 'Delete', onSelect: () => remove(row) },\n ],\n }} />\n```\n\n## Lane context menu\n\nAlongside `cardMenu`, `laneMenu` puts a menu on a **lane header** right-click.\nIts `ctx` gives lane-native helpers - `addCard(title?)`, `toggleCollapse()`,\nplus the lane's `cards` and `collapsed` state.\n\n```svelte\n<SvGrid {data} {columns}\n board={{ groupBy: 'status',\n laneMenu: (laneId, ctx) => [\n { label: 'Add card', onSelect: () => ctx.addCard() },\n { label: `Clear (${ctx.cards.length})`, onSelect: () => clearLane(laneId) },\n ] }} />\n```\n\n## Facet filters, multi-select, flags & age\n\nA cluster of \"power\" options, all on the built-in default card:\n\n- **`facets`** - a filter bar of chips (one per distinct value) for the listed\n fields; selecting chips filters the visible cards. Works with array fields\n (tags) too.\n- **`selectable`** - click to select a card, Ctrl/Cmd-click to toggle, and\n dragging a selected card moves the **whole selection**. `onSelectionChange`\n reports the selected rows.\n- **`flagField`** - a truthy field paints a red **blocked** corner.\n- **`ageField`** - a created/started date renders a relative **age** badge (`3d`).\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{\n groupBy: 'status',\n facets: ['tags', 'assignee'],\n selectable: true,\n onSelectionChange: (rows) => (count = rows.length),\n flagField: 'blocked',\n ageField: 'created',\n }} />\n```\n\n## Hierarchical cards (epics -> stories)\n\nPoint `childrenField` at a row's child rows and each card gains a children\ncount that **expands to show its sub-cards** inline, each with its own title\nand `groupBy` value - the epic -> stories shape.\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', childrenField: 'stories' }} />\n```\n\n## Reorderable lanes & runtime group-by\n\nSet `reorderableLanes` to let users **drag lane headers** to reorder the\ncolumns; the order is tracked (and saved with `persistKey`), and\n`onLaneReorder(orderedIds)` fires. Because `groupBy` is reactive, you can also\nswitch the **lane axis at runtime** just by changing it - the board re-buckets\nand resets card positions to the new field automatically. Set `onLaneRename`\nand users can **double-click a lane title** to rename it inline.\n\n```svelte\n<script>\n let groupBy = $state('status') // bind to a Status / Assignee / Priority selector\n</script>\n\n<SvGrid {data} {columns}\n board={{ groupBy, reorderableLanes: true, onCardMove: (e) => (row[groupBy] = e.toLane) }} />\n```\n\n## Saving the board layout\n\nPass `persistKey` and the board saves its layout - card positions, order,\nper-card edits, and collapsed lanes - to `localStorage` under that key, and\nrestores it on load. It needs `getRowId` so the saved keys line up with the\nright rows after a reload.\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n getRowId={(r) => String(r.id)}\n board={{ groupBy: 'status', persistKey: 'my-board' }} />\n```\n\nThe layout is an overlay on top of your data, so if you also persist the data\nitself (e.g. mirroring `onCardMove` to your store), the two stay in sync. To\npersist somewhere other than `localStorage`, use `onLayoutChange(layout)` and\nwrite it yourself; feed it back by seeding your data before mount. To reset,\nclear the key and remount the board (e.g. Svelte's `{#key}`).\n\n## Virtualized lanes (large boards)\n\nFor boards with thousands of cards in a lane, set `virtualized` so each lane\nonly keeps the cards in view in the DOM. Windowing is fixed-height, so set\n`cardHeight` to match your cards (default `76`). Drag-and-drop, keyboard move,\nand search all keep working - keyboard focus scrolls an off-screen card into\nview before landing on it.\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', virtualized: true, cardHeight: 72 }} />\n```\n\nBecause windowing assumes a uniform card height, keep your cards a consistent\nsize (or close to it) when virtualizing; leave `virtualized` off for boards\nwith a few hundred cards, where it isn't needed.\n\n## Moving cards\n\nMoving cards is **built in** - you write no move code. Cards are draggable\nbetween lanes and within a lane (with a live insertion marker), and the board\napplies the move itself: it reassigns the lane and reorders, tracked as an\noverlay keyed by row id, without mutating your data.\n\n`onCardMove` is an optional **notification** - it fires after each move so you\ncan persist to a backend, or mirror the new lane onto your own row if another\nview (a table, a count) reads the same data:\n\n```svelte\n<script>\n // Optional. The board already moved the card; this just syncs your store.\n function onCardMove(e) {\n // e = { row, fromLane, toLane, toIndex }\n e.row.status = e.toLane\n }\n</script>\n\n<SvGrid {data} {columns}\n getRowId={(r) => String(r.id)}\n board={{ groupBy: 'status', onCardMove }} />\n```\n\nPass `getRowId` so the move overlay stays pinned to the right row across data\nchanges (adds/removes/re-sorts). Without it the board falls back to per-object\nidentity, which is fine until you replace the row objects wholesale.\n\n## Keyboard drag-and-drop\n\nThe board is fully keyboard operable, so drag-and-drop is not mouse-only. Focus\na card and:\n\n- **Space** / **Enter** - grab it (press again to drop).\n- **Arrow Left / Right** - move it to the previous / next lane.\n- **Arrow Up / Down** - reorder it within its lane.\n- **Escape** - cancel and restore its original position.\n\nEvery step is announced through an ARIA live region for screen-reader users.\n\n## Editing cards\n\nSet `editable` and the board gets a **built-in card editor**: double-click a\ncard (or press **F2** while it is focused) to edit its fields inline. The\nfields come from the columns that declare an `editorType` (or all fields if\nnone do), rendered as the matching input (text / number / date / checkbox).\nSave writes to the board's edit overlay - the card updates immediately - and\nfires `onCardCommit` with the changed fields, so you can persist:\n\n```svelte\n<script>\n function onCardCommit(e) {\n // e = { row, changes, values } - the board already applied it\n Object.assign(e.row, e.values) // mirror onto your data / persist\n }\n</script>\n\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', editable: true, onCardCommit }} />\n```\n\n### Detail drawer\n\nFor a fuller editor, set `drawer` and opening a card shows a built-in\n**`SvDrawer` + `SvForm`** rendered from your columns with the UI-kit editors\n(text / date / select / number / colour / checkbox, chosen from each column's\n`editorType`). `true` shows **all** fields; pass a config to pick a subset or\ncustomize the drawer:\n\n```svelte\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', drawer: true, onCardCommit: (e) => save(e) }} />\n\n<!-- only some fields, custom title / side -->\n<SvGrid {data} {columns}\n board={{ groupBy: 'status',\n drawer: { fields: ['title', 'due', 'assignee'], title: (row) => row.title, side: 'right' } }} />\n```\n\nSaving applies the edit and fires `onCardCommit`. The drawer does **not** close\non an outside click (so opening a select or picker inside it, or a stray click,\nnever loses your edits) - close it with Save, Escape, or the × button. If\n`commentsField` is set, the drawer also shows the **comments thread** (read /\nwrite / delete) below the form.\n\nPrecedence: `onCardEdit` > `drawer` > the inline `editable` editor - so pass\n`onCardEdit` if you'd rather open your own editor or route to a detail screen.\n\n## Custom cards\n\nOmit `card` for the default card (title from the first column, then a few\nmeta rows). Pass a `card` snippet to render whatever you like - it receives the\nrow, so you can drop in avatars, chips, progress, or actions from the UI kit.\n\n```svelte\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', card: taskCard }} />\n\n{#snippet taskCard(task)}\n <div class=\"font-semibold\">{task.title}</div>\n <div class=\"row\">\n <SvAvatar name={task.assignee} size={20} />\n <SvChip variant={task.priority === 'High' ? 'danger' : 'neutral'}>\n {task.priority}\n </SvChip>\n </div>\n{/snippet}\n```\n\nYou can also set `titleField` and `cardFields` to steer the default card\nwithout writing a snippet.\n\n## Adding cards\n\nProvide `onCardAdd` and each lane header gains a `+` button; it fires with the\nlane id so you can append a new row in that lane. Add `composer` for a nicer\n**type-a-title** box at the bottom of each lane - Enter calls\n`onCardAdd(laneId, title)`.\n\n```svelte\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', composer: true, onCardAdd: (lane, title) => addRow(lane, title) }} />\n```\n\n## Card badges, tags, comments & cover\n\nThe default card can show a rich badge row without a custom snippet - point the\nboard at your fields:\n\n```svelte {runnable}\n<SvGrid {data} {columns}\n board={{\n groupBy: 'status',\n labelsField: 'labels', // tags: string[] or { text, color }[] (coloured chips)\n dueField: 'due', // Date | ISO string; red when overdue\n assigneesField: 'assignees', // string | string[] -> avatar initials\n commentsField: 'comments', // array (length) or number -> comment-count badge\n attachmentsField: 'attachments', // array or number -> attachment-count badge\n coverField: 'cover', // a CSS colour -> strip across the card top\n }} />\n```\n\n`labelsField` is your **tags** - pass `{ text, color }[]` for coloured chips.\nThese badges render on the default card **and** below a custom `card` snippet.\n\n**Comments** are interactive: the comment badge expands an inline thread, and\nthe same thread appears in the **detail drawer** (a more discoverable place to\nmanage them). Pass `commentsField` (a `BoardComment[]` = `{ id, text, author?,\nat? }`) plus `onCommentAdd` / `onCommentDelete` to let users **write and delete**\ncomments - update your data in the callbacks.\n\n```svelte\n<SvGrid {data} {columns}\n board={{ groupBy: 'status', commentsField: 'comments',\n onCommentAdd: (row, text) => row.comments.push({ id: uid(), text, author: 'You' }),\n onCommentDelete: (row, id) => (row.comments = row.comments.filter((c) => c.id !== id)) }} />\n```\n\nA **blocked** card (one that can't move forward - waiting on a dependency) is\nmarked with `flagField`: a truthy value shows a red corner + a \"Blocked\" badge,\nand a string value is used as the reason (badge tooltip). A blocked card is\n**locked from moving** (drag + keyboard) until it is unblocked - so blocking\nactually does something. Set `flagBlocksMoves: false` if you want a purely\nvisual flag that still allows moves.\n\n## Sub-tasks (checklists)\n\nPoint `subtasks` at a field holding `BoardSubtask[]` (`{ id, title, done }`) and\neach card gets a progress chip + bar; expand it to tick items or add more. The\nboard tracks toggles/adds in its own overlay (your data is never mutated) and\nfires `onSubtaskToggle` / `onSubtaskAdd` as notifications. Sub-task state is\nincluded in `persistKey` so it survives a reload.\n\n```svelte\n<SvGrid {data} {columns}\n getRowId={(r) => String(r.id)}\n board={{ groupBy: 'status', subtasks: 'items',\n onSubtaskToggle: (row, id, done) => …, onSubtaskAdd: (row, title) => … }} />\n```\n\nFor a full-detail editor, wire `onCardEdit` to open an `SvDrawer` with the rest\nof a card's fields (see demo 349).\n\n## `BoardConfig`\n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `groupBy` | `string` | **Required.** Field whose value buckets each row into a lane. |\n| `lanes` | `BoardLane[]` | Explicit, ordered lanes. Omit to derive from distinct values. |\n| `card` | `Snippet<[row]>` | Custom card body. Omit for the default card. |\n| `onCardMove` | `(e) => void` | Optional notification after a built-in move: `{ row, fromLane, toLane, toIndex }`. Persist / mirror here. |\n| `onCardAdd` | `(laneId, title?) => void` | Add-card affordance (header `+`, or composer title). |\n| `composer` | `boolean` | Type-a-title quick-add box at the bottom of each lane. |\n| `subtasks` | `string` | Field of `BoardSubtask[]`; renders a checklist + progress on the card. |\n| `onSubtaskToggle` | `(row, id, done) => void` | Notified when a sub-task is toggled. |\n| `onSubtaskAdd` | `(row, title) => void` | Notified when a sub-task is added on the card. |\n| `labelsField` | `string` | Field of label strings / `{text,color}` -> chips on the card. |\n| `dueField` | `string` | Field of a due date -> badge (red when overdue). |\n| `assigneesField` | `string` | Field of assignee name(s) -> avatar(s) on the card. |\n| `editable` | `boolean` | Enables the built-in inline card editor (double-click / F2). |\n| `onCardEdit` | `(row) => void` | Open your own editor instead of the built-in one. |\n| `drawer` | `boolean \\| BoardDrawerConfig` | Built-in `SvDrawer` + `SvForm` detail editor; `true` = all fields, or `{ fields, title, side, size }`. |\n| `cardMenu` | `(row, ctx) => MenuItem[]` | Card right-click menu; `ctx` = `{ lanes, moveTo, edit }`. |\n| `laneMenu` | `(laneId, ctx) => MenuItem[]` | Lane-header right-click menu; `ctx` = `{ cards, collapsed, toggleCollapse, addCard }`. |\n| `facets` | `string[]` | Fields shown as a facet filter-chip bar above the board. |\n| `selectable` | `boolean` | Card multi-select; dragging a selected card moves the whole selection. |\n| `onSelectionChange` | `(rows) => void` | Fires with the selected rows. |\n| `flagField` | `string` | Truthy -> \"Blocked\" badge + red corner (string = reason); locks the card from moving. |\n| `flagBlocksMoves` | `boolean` | Whether a blocked card is locked from moving. Defaults to `true`. |\n| `ageField` | `string` | A date -> a relative age badge (`3d`). |\n| `childrenField` | `string` | Child rows -> an expandable count of nested mini-cards. |\n| `onCardCommit` | `(e) => void` | Fires when the built-in editor saves: `{ row, changes, values }`. |\n| `laneSummary` | `(rows, laneId) => string` | Per-lane header roll-up (points / $ total / count). |\n| `swimlaneSummary` | `(rows, swimId) => string` | Per-swimlane band roll-up. |\n| `onLaneRename` | `(laneId, title) => void` | Enable double-click inline lane rename. |\n| `swimlaneBy` | `string` | Second axis: split the board into swimlane bands by this field. |\n| `collapsibleSwimlanes` | `boolean` | Let users collapse a swimlane band via its header chevron. |\n| `commentsField` | `string` | `BoardComment[]` -> a comment badge that expands to a thread. |\n| `onCommentAdd` | `(row, text) => void` | Let users write comments (append to your data). |\n| `onCommentDelete` | `(row, commentId) => void` | Let users delete comments. |\n| `attachmentsField` | `string` | Array or number -> attachment-count badge. |\n| `coverField` | `string` | A CSS colour -> a strip across the card top. |\n| `enforceWip` | `boolean` | Reject moves that would push a lane past its `wipLimit`. |\n| `collapsibleLanes` | `boolean` | Let users collapse a lane to a strip via its header chevron. |\n| `reorderableLanes` | `boolean` | Let users drag lane headers to reorder columns (persisted). |\n| `onLaneReorder` | `(orderedIds) => void` | Fires after a lane drag-reorder. |\n| `searchable` | `boolean` | Show the built-in search box (default `true`). |\n| `searchPlaceholder` | `string` | Placeholder for the search box. |\n| `virtualized` | `boolean` | Window each lane (only in-view cards in the DOM) for very large boards. |\n| `cardHeight` | `number` | Estimated card height for `virtualized` windowing (default `76`). |\n| `persistKey` | `string` | Save/restore the board layout to `localStorage` (needs `getRowId`). |\n| `onLayoutChange` | `(layout) => void` | Fires with the serializable layout on any change. |\n| `titleField` | `string` | Title on the default card (defaults to first column). |\n| `cardFields` | `string[]` | Meta rows on the default card (max 4). |\n\n`BoardLane` = `{ id, title?, color?, wipLimit? }`.\n\n## Notes\n\n- The board themes purely from the grid's `--sg-*` tokens - pick any preset and\n it follows. Set `--sg-board-lane-w` to change lane width.\n- Board mode replaces the table render, so table-only chrome (column headers,\n the pagination footer, the filter row) does not apply while `board` is set.\n- Moving a card is tracked as an overlay on top of your data - the board never\n mutates your rows. Mirror via `onCardMove` if other views must agree.\n\n## More examples\n\n### Sprint board (swimlanes + WIP)\n\nAn agile sprint board: status lanes crossed with a swimlane per assignee, an enforced WIP limit on In progress, and a story-point roll-up in every lane header via board.laneSummary. Drag across a band to reassign the owner; double-click to edit. Collapsible lanes.\n\n<div data-docs-demo=\"344-kanban-sprint\" data-height=\"560\"></div>\n\n### Sales pipeline (deal board)\n\nA CRM deal board: stages as lanes with a live total-value roll-up per stage (board.laneSummary). Rich deal cards; drag to advance a deal, double-click to edit. Moves and edits persist to localStorage via onCardMove / onCardCommit, so a reload restores the board.\n\n<div data-docs-demo=\"345-kanban-pipeline\" data-height=\"560\"></div>\n\n### Large board (virtualized)\n\nThousands of cards per lane kept smooth with board.virtualized - only the cards in view are in the DOM. A slider scales the board from 1k to 50k cards; drag-and-drop and keyboard move still work across the whole window.\n\n<div data-docs-demo=\"346-kanban-virtualized\" data-height=\"560\"></div>\n\n### Support triage board\n\nA helpdesk triage board: status lanes crossed with a priority swimlane, a search box front-and-center, and an SLA colour bar on each card driven by ticket age. Drag across a band to re-triage a ticket priority.\n\n<div data-docs-demo=\"347-kanban-support\" data-height=\"560\"></div>\n\n### Content calendar\n\nAn editorial pipeline: stage lanes crossed with a swimlane per channel. Rich cards carry a cover glyph, author and target date. Drag a piece down the pipeline, or across a band to move it to another channel; double-click to edit.\n\n<div data-docs-demo=\"348-kanban-content\" data-height=\"560\"></div>\n\n### Cards with sub-tasks & badges\n\nThe default board card made rich by config alone: label / due / assignee badges, a sub-task checklist with a progress bar (expand to tick items or add more), and a quick-add composer at the bottom of each lane. Double-click a card for the BUILT-IN detail drawer (board.drawer -> SvDrawer + SvForm with the UI-kit editors); toggle all fields vs a customized subset. Board / Table switcher.\n\n<div data-docs-demo=\"349-kanban-subtasks\" data-height=\"560\"></div>\n\n### Group-by switch + reorderable lanes\n\nBoard structure, live: switch the lane axis at runtime (Status / Assignee / Priority) and the board re-buckets, and drag a lane header to reorder the columns. Both built-in - the group-by switch resets card positions to the new field; lane order is tracked and persists with persistKey. Board / Table switcher.\n\n<div data-docs-demo=\"350-kanban-structure\" data-height=\"560\"></div>\n\n### Board power tools (filters, multi-select, menus)\n\nA facet filter bar (by tag + assignee), card multi-select with bulk move (click / Ctrl-click then drag the group), a blocked flag, a card-age badge, and both card + lane right-click menus - all from board config on the built-in default card. Board / Table switcher.\n\n<div data-docs-demo=\"351-kanban-power\" data-height=\"560\"></div>\n\n### Epics -> stories (hierarchical cards)\n\nPoint board.childrenField at a row child rows and each card gains a children count that expands to show its sub-cards inline (Jira epic -> stories). Each child shows its own title + status. Board / Table switcher.\n\n<div data-docs-demo=\"352-kanban-epics\" data-height=\"560\"></div>\n\n## See also\n\n- [Row dragging](./row-dragging.md) - reorder rows and move them between grids.\n- [Mobile card view](../mobile-card-view.md) - the responsive grid/card pivot.\n- [Grouping & aggregation](../grouping-aggregation.md) - the row-bucketing model board lanes reuse.\n- [Scheduler / calendar mode](./scheduler.md) - the same rows as bookings on a calendar.\n- [Gantt chart mode](./gantt.md) - the same rows as a project plan: in progress, due 1 November 2026.\n"
5953
5960
  },
5954
5961
  {
5955
5962
  "slug": "help/rows/master-detail",
@@ -5984,7 +5991,7 @@ export const docs = [
5984
5991
  "path": "docs/help/rows/row-pagination.md",
5985
5992
  "title": "Row pagination",
5986
5993
  "section": "Rows",
5987
- "markdown": "# Row pagination\n\nPagination is opt-in: `pageable` turns it on (the longer `showPagination`\ndoes the same) and `pageSize` sets the slice. `<SvGrid>` pages its rows\nitself, so there is nothing else to register. `rowPaginationFeature` and\n`createPaginatedRowModel` are for the headless engine, where the row model\ngoes in `_rowModels.paginatedRowModel` of `createSvGridCore` (see\n[Row models](../headless/row-models.md)); `<SvGrid>` has no `options` prop\nto pass them through.\n<div data-docs-demo=\"02-sort-filter-paginate\" data-height=\"540\"></div>\n\nThe examples on this page run against these rows:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n email: string\n department: string\n age: number\n salary: number\n city: string\n startDate: string\n active: boolean\n }\n\n const people: Person[] = [\n { id: 1, name: 'Ada Lovelace', email: 'ada@example.com', department: 'Engineering', age: 36, salary: 142000, city: 'London', startDate: '2021-03-01', active: true },\n { id: 2, name: 'Grace Hopper', email: 'grace@example.com', department: 'Engineering', age: 45, salary: 168000, city: 'New York', startDate: '2019-07-15', active: true },\n { id: 3, name: 'Linus Torvalds', email: 'linus@example.com', department: 'Platform', age: 54, salary: 155000, city: 'Portland', startDate: '2020-01-20', active: false },\n { id: 4, name: 'Radia Perlman', email: 'radia@example.com', department: 'Networking', age: 49, salary: 161000, city: 'Seattle', startDate: '2022-09-05', active: true },\n { id: 5, name: 'Barbara Liskov', email: 'barbara@example.com', department: 'Platform', age: 52, salary: 172000, city: 'Boston', startDate: '2018-11-11', active: true },\n ]\n\n const data = people\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 200 },\n { field: 'department', header: 'Department', width: 150 },\n { field: 'city', header: 'City', width: 140 },\n { field: 'age', header: 'Age', width: 90 },\n { field: 'salary', header: 'Salary', width: 130, format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```svelte {runnable}\n<SvGrid {data} {columns} pageable />\n```\n\nThe wrapper renders a footer with page nav and a page-size selector.\n\n## Set the initial page size\n\n```svelte\n<SvGrid\n data={rows}\n columns={columns}\n features={features}\n showPagination={true}\n pageSize={25}\n/>\n```\n\nThe wrapper's footer renders 10 / 25 / 50 / 100 in the size selector\nand lets the user change it at runtime. Jumping to a page from outside\nis best done by hiding the built-in footer (`showPagination={false}`)\nand rendering your own controls - see the\n[`09-server-side` demo](../../../examples/src/demos/09-server-side.svelte)\nfor the canonical pattern. A server-side fetcher keeps the footer: hand\n`createServerDataSource` to the grid as `rowModel` and the pager reads the\nserver's count and drives the controller's `setPage` - see\n[Server paging](../server/server-paging.md).\n\n## Page size\n\nThe default is 10 unless you pass `pageSize`. The footer's size\nselector picks 10 / 25 / 50 / 100; pass a different `pageSize` to seed\na different initial value.\n\n## Pagination + virtualization\n\nThese two **work together** but they solve different problems. Use\nvirtualization when the page itself is large (>200 rows); use pagination\nwhen you want explicit pages, when the user prints/exports, or when\nserver-side fetch returns pages.\n\nFor 100k-row + virtualized examples, pagination is off and the whole\nfiltered set is scrollable - see\n[demos/06-large-dataset.svelte](../../../examples/src/demos/06-large-dataset.svelte).\n\n## Try it\n\n`pageable` turns the footer on and `pageSize` sets the slice. Sorting and\nfiltering run before pagination, so page 1 is always the first rows of the\nresult rather than the first rows of your array.\n\n```svelte {runnable}\n<SvGrid data={people} {columns} pageable pageSize={2} sortable filterable />\n```\n\n## See also\n\n- [Server-side guide](../../getting-started.md#11-server-side-data)\n- [Accessing rows](./accessing-rows.md)\n"
5994
+ "markdown": "# Row pagination\n\nPagination is opt-in: `pageable` turns it on (the longer `showPagination`\ndoes the same) and `pageSize` sets the slice. `<SvGrid>` pages its rows\nitself, so there is nothing else to register. `rowPaginationFeature` and\n`createPaginatedRowModel` are for the headless engine, where the row model\ngoes in `_rowModels.paginatedRowModel` of `createSvGridCore` (see\n[Row models](../headless/row-models.md)); `<SvGrid>` has no `options` prop\nto pass them through.\n<div data-docs-demo=\"02-sort-filter-paginate\" data-height=\"540\"></div>\n\nThe examples on this page run against these rows:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvGrid, type GridColumns } from '@svgrid/grid'\n\n type Person = {\n id: number\n name: string\n email: string\n department: string\n age: number\n salary: number\n city: string\n startDate: string\n active: boolean\n }\n\n const people: Person[] = [\n { id: 1, name: 'Ada Lovelace', email: 'ada@example.com', department: 'Engineering', age: 36, salary: 142000, city: 'London', startDate: '2021-03-01', active: true },\n { id: 2, name: 'Grace Hopper', email: 'grace@example.com', department: 'Engineering', age: 45, salary: 168000, city: 'New York', startDate: '2019-07-15', active: true },\n { id: 3, name: 'Linus Torvalds', email: 'linus@example.com', department: 'Platform', age: 54, salary: 155000, city: 'Portland', startDate: '2020-01-20', active: false },\n { id: 4, name: 'Radia Perlman', email: 'radia@example.com', department: 'Networking', age: 49, salary: 161000, city: 'Seattle', startDate: '2022-09-05', active: true },\n { id: 5, name: 'Barbara Liskov', email: 'barbara@example.com', department: 'Platform', age: 52, salary: 172000, city: 'Boston', startDate: '2018-11-11', active: true },\n ]\n\n const data = people\n\n const columns: GridColumns<Person> = [\n { field: 'name', header: 'Name', width: 200 },\n { field: 'department', header: 'Department', width: 150 },\n { field: 'city', header: 'City', width: 140 },\n { field: 'age', header: 'Age', width: 90 },\n { field: 'salary', header: 'Salary', width: 130, format: { type: 'currency', currency: 'USD' } },\n ]\n</script>\n```\n\n```svelte {runnable}\n<SvGrid {data} {columns} pageable />\n```\n\nThe wrapper renders a footer with page nav and a page-size selector.\n\n## Set the initial page size\n\n```svelte\n<SvGrid\n data={rows}\n columns={columns}\n features={features}\n showPagination={true}\n pageSize={25}\n/>\n```\n\nThe wrapper's footer renders 10 / 25 / 50 / 100 in the size selector\nand lets the user change it at runtime. Jumping to a page from outside\nis best done by hiding the built-in footer (`showPagination={false}`)\nand rendering your own controls - see the\n[`09-server-side` demo](../../../examples/src/demos/09-server-side.svelte)\nfor the canonical pattern. A server-side fetcher keeps the footer: hand\n`createServerDataSource` to the grid as `rowModel` and the pager reads the\nserver's count and drives the controller's `setPage` - see\n[Server paging](../server/server-paging.md).\n\n## Page size\n\nThe default is 10 unless you pass `pageSize`. The footer's size\nselector picks 10 / 25 / 50 / 100; pass a different `pageSize` to seed\na different initial value.\n\n## Pagination + virtualization\n\nThese two **work together** but they solve different problems. Use\nvirtualization when the page itself is large (>200 rows); use pagination\nwhen you want explicit pages, when the user prints/exports, or when\nserver-side fetch returns pages.\n\nFor 100k-row + virtualized examples, pagination is off and the whole\nfiltered set is scrollable - see\n[demos/06-large-dataset.svelte](../../../examples/src/demos/06-large-dataset.svelte).\n\n## Try it\n\n`pageable` turns the footer on and `pageSize` sets the slice. Sorting and\nfiltering run before pagination, so page 1 is always the first rows of the\nresult rather than the first rows of your array.\n\n```svelte {runnable}\n<SvGrid data={people} {columns} pageable pageSize={2} sortable filterable />\n```\n\n## Go to the page a row is on\n\n`api.getRowPosition(id)` is where a row sits in the filtered, sorted rows\nacross every page, or `null` when a filter hides it. Divide by the page size\nand `api.setPage` turns to that page, whatever order the user has sorted\ninto. The id is the one `getRowId` returns. With grouping, pages are counted\nin groups and the division does not hold.\n\n```svelte {runnable}\n<script lang=\"ts\">\n import { SvGrid, type SvGridApi } from '@svgrid/grid'\n\n let api = $state<SvGridApi<{}, Person> | null>(null)\n\n function showRow(id: string) {\n const position = api?.getRowPosition(id)\n if (api && position != null) api.setPage(Math.floor(position / api.getPageInfo().pageSize))\n }\n</script>\n\n<button onclick={() => showRow('4')}>Show Radia Perlman</button>\n<SvGrid data={people} {columns} pageable pageSize={2} sortable getRowId={(r) => String(r.id)} onApiReady={(next) => (api = next)} />\n```\n\n`api.getPageInfo()` also returns `pageIndex` and `pageCount`, and\n`api.setPageSize(n)` changes the slice from code.\n\n## See also\n\n- [Server-side guide](../../getting-started.md#11-server-side-data)\n- [Accessing rows](./accessing-rows.md)\n"
5988
5995
  },
5989
5996
  {
5990
5997
  "slug": "help/rows/row-pinning",
@@ -6075,7 +6082,7 @@ export const docs = [
6075
6082
  "path": "docs/help/security.md",
6076
6083
  "title": "Security & supply chain",
6077
6084
  "section": "Help",
6078
- "markdown": "# Security & supply chain\n\nSvGrid is built for shipping into regulated environments where every\ndependency, every runtime call, and every network egress has to be\njustified before procurement signs. This page is the answer to \"what\ndoes this package do, what does it depend on, and what would I tell\nour InfoSec team?\".\n\n![The SvGrid library renders and holds state inside the browser and opens no connection of its own - no fetch, no telemetry; only your app code crosses the boundary to the network to fetch rows and persist changes.](/docs-media/grid-security.svg)\n\n<div data-docs-demo=\"16-csp-compliant\" data-height=\"540\"></div>\n\n## TL;DR\n\n| Property | Status |\n| --------------------------------- | ---------------------------------------------------------------------- |\n| Network egress at runtime | **None.** Zero analytics, zero phone-home, no automatic update checks. |\n| Telemetry | **Zero.** No `fetch`, no `navigator.sendBeacon`, no console identifiers. |\n| `eval` / `new Function` / dynamic code | **None in `@svgrid/grid`.** See [CSP-compliant grid](https://svgrid.com/demos/16-csp-compliant/) demo + runtime self-check. |\n| Cookies / localStorage | None set by the library itself. (Your app's saved-views helpers may opt in.) |\n| Outbound dependencies | **Community:** one runtime dep, `esm-env` (MIT, no dependencies of its own). **Enterprise:** two optional peer deps (`jszip`, `pdfmake`), see below. |\n| AI calls | The user's own `AIProvider` adapter calls whichever endpoint *they* configured. The package never embeds a model client. |\n| License | Community: MIT. Enterprise: commercial (see [LICENSE](../../packages/enterprise/LICENSE)). |\n| npm provenance + signing | Published with `npm publish --provenance` from GitHub Actions; integrity hashes in the npm registry. |\n| Source | 100% open source. `pnpm patch` works; everything in this monorepo is the same code that ships to npm. |\n\n## Runtime dependencies\n\n`@svgrid/grid` has **one runtime dependency**, [`esm-env`](https://www.npmjs.com/package/esm-env)\n(MIT), which has no dependencies of its own and only reports the build's\nbrowser / dev / SSR conditions. Beyond that the user's build pulls in\n`svelte` itself (peer). Verify with `npm view @svgrid/grid dependencies`.\n\n`@svgrid/enterprise` adds two **optional** peer dependencies, both lazy-loaded\non first use:\n\n| Peer | When loaded | License | Why optional |\n| --------------- | -------------------------------------------- | -------------- | ---------------------------------------------------------------- |\n| `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. |\n| `pdfmake` ^0.2 | `api.exportData({ format: 'pdf' })` | MIT | If you don't export to PDF, you don't install this peer. |\n\nNeither is bundled. Both are dynamically `import()`-ed at first call. If\nthe consumer hasn't installed the peer, the call throws a typed error\nnaming the missing module and the install command - the rest of the\nlibrary keeps working.\n\nCSV, TSV, HTML, JSON import/export, print, the AI assistant, and the\npivot helpers have **no extra peer dependencies** at all.\n\n## What the package does at runtime\n\nEvery observable side effect, mapped:\n\n| Surface | Side effect |\n| ------------------------------------ | -------------------------------------------------------------------------- |\n| `<SvGrid>` mount | Sets up `requestAnimationFrame`, `ResizeObserver`, and DOM event listeners on the grid container. |\n| Inline editing | Reads + writes `document` selection; commits via your `onCellValueChange`. |\n| Export to xlsx / pdf / csv / tsv / html | Creates a `Blob` and triggers a download via a synthetic `<a download>`. No network. |\n| Import from xlsx / csv / tsv / json | Reads the user-provided `File` via `arrayBuffer()` / `text()`. No network. |\n| Print | Opens a sandbox popup window with an isolated HTML document and calls its `print()`. |\n| AI helpers | Build a prompt locally and call the consumer-registered `AIProvider`. The grid itself never opens a connection. |\n| License key check | A 4-line string-prefix check against an in-memory revoked-key set. No network. |\n| Unlicensed watermark | Renders a small DOM badge linking to the pricing page. No network. |\n| Unlicensed upgrade prompt | On first unlicensed Enterprise feature call, appends a one-time DOM card linking to a trial. No network, no storage; one in-memory flag. |\n\n## CSP guidance\n\nThe community grid is CSP-friendly. A strict policy that works:\n\n```\ndefault-src 'self';\nscript-src 'self';\nstyle-src 'self' 'unsafe-inline';\nimg-src 'self' data:;\nconnect-src 'self';\n```\n\nNotes:\n\n- `'unsafe-inline'` on `style-src` is needed because Svelte 5 emits\n scoped style attributes inline. You can drop it if you switch to\n `unsafe-hashes` with a CSP nonce-aware build of Svelte.\n- `connect-src 'self'` is enough - the grid never opens a connection to\n a third-party origin.\n- `script-src` does NOT need `'unsafe-eval'` for community. (Enterprise pulls\n in `pdfmake` which historically used `eval`; check the pdfmake version\n if your CSP is strict.)\n- 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.\n\n## Source provenance\n\n- Source repository: `github.com/sv-grid/sv-grid` - all releases tagged.\n- Build pipeline: GitHub Actions. The release workflow signs and\n publishes to npm with `--provenance`. You can verify the signature\n via `npm audit signatures` (npm 9+) or by inspecting the\n package metadata on the registry.\n- No private patches. The code on npm is the code in the public\n monorepo at the tagged commit.\n\n## Vulnerability handling\n\n- Reports: open a draft security advisory on the GitHub repository, or\n email `support@jqwidgets.com`. PGP key on the repository's SECURITY.md.\n- Response SLA (paid customers): acknowledgement within one business\n day, advisory + patch within five business days for severity High +\n Critical.\n- Community: best-effort but every report is triaged.\n- Public advisories for Enterprise customers go out via the support Slack +\n email **before** the GitHub advisory page goes public.\n\n## SBOM\n\nWe publish a **CycloneDX 1.6** document per package in\n[`sbom/`](https://github.com/sv-grid/sv-grid/tree/main/sbom), covering runtime\nand peer dependencies to full declared depth. Fetch the one you need straight\nfrom the repo, or regenerate from a clone:\n\n```bash\npnpm sbom # write sbom/*.cdx.json\npnpm sbom:check # non-zero exit if they have drifted from the manifests\n```\n\nIf your process prefers a scanner-produced document, or you want SPDX instead,\ngenerate one against your own installed tree:\n\n```bash\nnpx @cyclonedx/cdxgen -t npm -o sbom.json\n```\n\nFor Enterprise, the SBOM lists `jszip` and `pdfmake` as optional peers - flag\nto your scanner if you don't use those formats.\n\n## Data residency\n\nThe library processes data **in the browser**. Nothing leaves the user's\nmachine via the package itself.\n\nIf you wire `setAIProvider(fn)` to a remote endpoint, the prompt + row\nsample the helpers build (a column schema + at most ~25 sampled rows)\nis what goes through your adapter. The package gives you the prompt\nverbatim before sending - you decide whether to redact, route to an\non-prem model, or hash sensitive fields.\n\n## Audit-friendly defaults\n\n- **No global state** beyond a few module-scoped variables for the\n license + AI provider registration. No singletons that survive HMR.\n- **Pure-function helpers** for filtering / sorting / aggregation -\n every callable you import is testable in isolation (vitest suite\n proves this for 1000+ assertions).\n- **No prototype pollution surface.** Every helper uses\n `Object.create(null)` or own-property maps; no untyped object\n merging.\n- **No reflection-driven config.** Column definitions are plain\n objects; the grid never reads metadata via `eval` or `with`.\n\n## Frequently asked questions\n\n### Is SvGrid safe to use in a regulated or enterprise environment?\n\nYes. SvGrid is a client-side library: it makes no network calls of its own,\nsends no telemetry, and runs CSP-clean (no `eval`, no `new Function`, no inline\nscripts). All data stays in the browser, so it does not change your app's data\negress posture.\n\n### Does SvGrid send any telemetry or phone home?\n\nNo. There is zero outbound traffic from the library. Any network calls in your\napp are ones you write.\n\n### What is SvGrid's supply-chain footprint?\n\nThe Community core has a minimal dependency surface; Enterprise export/import features\nlazy-load their dependencies only when used. See this page for the full\ndependency and runtime-call accounting procurement asks for.\n\n## See also\n\n- [Browser support](./browser-support.md) - tested target matrix.\n- [Testing and quality](./testing-and-quality.md) - the test suite that\n underwrites this page's claims.\n- [API stability](./api-stability.md) - semver policy, deprecation\n lifecycle.\n"
6085
+ "markdown": "# Security & supply chain\n\nSvGrid is built for shipping into regulated environments where every\ndependency, every runtime call, and every network egress has to be\njustified before procurement signs. This page is the answer to \"what\ndoes this package do, what does it depend on, and what would I tell\nour InfoSec team?\".\n\n![The SvGrid library renders and holds state inside the browser and opens no connection of its own - no fetch, no telemetry; only your app code crosses the boundary to the network to fetch rows and persist changes.](/docs-media/grid-security.svg)\n\n<div data-docs-demo=\"16-csp-compliant\" data-height=\"540\"></div>\n\n## TL;DR\n\n| Property | Status |\n| --------------------------------- | ---------------------------------------------------------------------- |\n| Network egress at runtime | **None.** Zero analytics, zero phone-home, no automatic update checks. |\n| Telemetry | **Zero.** No `fetch`, no `navigator.sendBeacon`, no console identifiers. |\n| `eval` / `new Function` / dynamic code | **None in `@svgrid/grid`.** See [CSP-compliant grid](https://svgrid.com/demos/16-csp-compliant/) demo + runtime self-check. |\n| Cookies / localStorage | None set by the library itself. (Your app's saved-views helpers may opt in.) |\n| Outbound dependencies | **Community:** one runtime dep, `esm-env` (MIT, no dependencies of its own). **Enterprise:** two optional peer deps (`jszip`, `pdfmake`), see below. |\n| AI calls | The user's own `AIProvider` adapter calls whichever endpoint *they* configured. The package never embeds a model client. |\n| License | Community: MIT. Enterprise: commercial (see [LICENSE](../../packages/enterprise/LICENSE)). |\n| npm provenance + signing | Published with `npm publish --provenance` from GitHub Actions; integrity hashes in the npm registry. |\n| Source | 100% open source. `pnpm patch` works; everything in this monorepo is the same code that ships to npm. |\n\n## Runtime dependencies\n\n`@svgrid/grid` has **one runtime dependency**, [`esm-env`](https://www.npmjs.com/package/esm-env)\n(MIT), which has no dependencies of its own and only reports the build's\nbrowser / dev / SSR conditions. Beyond that the user's build pulls in\n`svelte` itself (peer). Verify with `npm view @svgrid/grid dependencies`.\n\n`@svgrid/enterprise` adds two **optional** peer dependencies, both lazy-loaded\non first use:\n\n| Peer | When loaded | License | Why optional |\n| --------------- | -------------------------------------------- | -------------- | ---------------------------------------------------------------- |\n| `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. |\n| `pdfmake` ^0.2 | `api.exportData({ format: 'pdf' })` | MIT | If you don't export to PDF, you don't install this peer. |\n\nNeither is bundled. Both are dynamically `import()`-ed at first call. If\nthe consumer hasn't installed the peer, the call throws a typed error\nnaming the missing module and the install command - the rest of the\nlibrary keeps working.\n\nOne piece of third-party code *is* bundled: `@svgrid/enterprise` ships the\nSmart UI export module (jQWidgets) as `dist/smart.export.js`, vendored\nunmodified. The SBOM lists it as a component with its version.\n\nCSV, TSV, HTML, JSON import/export, print, the AI assistant, and the\npivot helpers have **no extra peer dependencies** at all.\n\n## What the package does at runtime\n\nEvery observable side effect, mapped:\n\n| Surface | Side effect |\n| ------------------------------------ | -------------------------------------------------------------------------- |\n| `<SvGrid>` mount | Sets up `requestAnimationFrame`, `ResizeObserver`, and DOM event listeners on the grid container. |\n| Inline editing | Reads + writes `document` selection; commits via your `onCellValueChange`. |\n| Export to xlsx / pdf / csv / tsv / html | Creates a `Blob` and triggers a download via a synthetic `<a download>`. No network. CSV and TSV prefix formula-like text with `'` so a spreadsheet does not run it ([export](./export.md)). |\n| Import from xlsx / csv / tsv / json | Reads the user-provided `File` via `arrayBuffer()` / `text()`. No network. An .xlsx cell addressed outside the sheet (past column XFD) is rejected, and so is a sheet that would need more than ten million blank cells to lay out, so a crafted file cannot exhaust memory. |\n| Print | Opens a sandbox popup window with an isolated HTML document and calls its `print()`. |\n| AI helpers | Build a prompt locally and call the consumer-registered `AIProvider`. The grid itself never opens a connection. |\n| License key check | A 4-line string-prefix check against an in-memory revoked-key set. No network. |\n| Unlicensed watermark | Renders a small DOM badge linking to the pricing page. No network. |\n| Unlicensed upgrade prompt | On first unlicensed Enterprise feature call, appends a one-time DOM card linking to a trial. No network, no storage; one in-memory flag. |\n\n## CSP guidance\n\nThe community grid is CSP-friendly. A strict policy that works:\n\n```\ndefault-src 'self';\nscript-src 'self';\nstyle-src 'self' 'unsafe-inline';\nimg-src 'self' data:;\nconnect-src 'self';\n```\n\nNotes:\n\n- `'unsafe-inline'` on `style-src` is needed because Svelte 5 emits\n scoped style attributes inline. You can drop it if you switch to\n `unsafe-hashes` with a CSP nonce-aware build of Svelte.\n- `connect-src 'self'` is enough - the grid never opens a connection to\n a third-party origin.\n- `script-src` does NOT need `'unsafe-eval'` for community. (Enterprise pulls\n in `pdfmake` which historically used `eval`; check the pdfmake version\n if your CSP is strict.)\n- 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.\n\n## Source provenance\n\n- Source repository: `github.com/sv-grid/sv-grid` - all releases tagged.\n- Build pipeline: GitHub Actions. The release workflow signs and\n publishes to npm with `--provenance`. You can verify the signature\n via `npm audit signatures` (npm 9+) or by inspecting the\n package metadata on the registry.\n- No private patches. The code on npm is the code in the public\n monorepo at the tagged commit.\n\n## Vulnerability handling\n\n- Reports: open a draft security advisory on the GitHub repository, or\n email the address in\n [SECURITY.md](https://github.com/sv-grid/sv-grid/blob/main/SECURITY.md).\n [`/.well-known/security.txt`](https://svgrid.com/.well-known/security.txt)\n points to the same place.\n- Response SLA (paid customers): acknowledgement within one business\n day, advisory + patch within five business days for severity High +\n Critical.\n- Community: best-effort but every report is triaged.\n- Public advisories for Enterprise customers go out via the support Slack +\n email **before** the GitHub advisory page goes public.\n\n## SBOM\n\nWe publish a **CycloneDX 1.6** document per package in\n[`sbom/`](https://github.com/sv-grid/sv-grid/tree/main/sbom), covering runtime\nand peer dependencies to full declared depth, plus vendored code. Fetch the\none you need straight from the repo, or regenerate from a clone:\n\n```bash\npnpm sbom # write sbom/*.cdx.json\npnpm sbom:check # non-zero exit if they have drifted from the manifests\n```\n\nThe release workflow regenerates the SBOMs at the released versions and signs\nthem with a Sigstore build attestation, and the Test workflow runs\n`pnpm sbom:check` on every commit. To check that a copy is the one the\nrelease produced:\n\n```bash\ngh attestation verify sbom/svgrid-grid.cdx.json --repo sv-grid/sv-grid\n```\n\n`@svgrid/mcp` is the one package with a deeper graph (the MCP SDK, `zod`,\n`svelte`); its SBOM lists those top-level dependencies, not their own.\n\nIf your process prefers a scanner-produced document, or you want SPDX instead,\ngenerate one against your own installed tree:\n\n```bash\nnpx @cyclonedx/cdxgen -t npm -o sbom.json\n```\n\nFor Enterprise, the SBOM lists `jszip` and `pdfmake` as optional peers - flag\nto your scanner if you don't use those formats.\n\n## Data residency\n\nThe library processes data **in the browser**. Nothing leaves the user's\nmachine via the package itself.\n\nIf you wire `setAIProvider(fn)` to a remote endpoint, the prompt + row\nsample the helpers build (a column schema + at most ~25 sampled rows)\nis what goes through your adapter. The package gives you the prompt\nverbatim before sending - you decide whether to redact, route to an\non-prem model, or hash sensitive fields.\n\n## Audit-friendly defaults\n\n- **No global state** beyond a few module-scoped variables for the\n license + AI provider registration. No singletons that survive HMR.\n- **Pure-function helpers** for filtering / sorting / aggregation -\n every callable you import is testable in isolation (vitest suite\n proves this for 1000+ assertions).\n- **No prototype pollution surface.** Every helper uses\n `Object.create(null)` or own-property maps; no untyped object\n merging.\n- **No reflection-driven config.** Column definitions are plain\n objects; the grid never reads metadata via `eval` or `with`.\n\n## Frequently asked questions\n\n### Is SvGrid safe to use in a regulated or enterprise environment?\n\nYes. SvGrid is a client-side library: it makes no network calls of its own,\nsends no telemetry, and runs CSP-clean (no `eval`, no `new Function`, no inline\nscripts). All data stays in the browser, so it does not change your app's data\negress posture.\n\n### Does SvGrid send any telemetry or phone home?\n\nNo. There is zero outbound traffic from the library. Any network calls in your\napp are ones you write.\n\n### What is SvGrid's supply-chain footprint?\n\nThe Community core has a minimal dependency surface; Enterprise export/import features\nlazy-load their dependencies only when used. See this page for the full\ndependency and runtime-call accounting procurement asks for.\n\n## See also\n\n- [Browser support](./browser-support.md) - tested target matrix.\n- [Testing and quality](./testing-and-quality.md) - the test suite that\n underwrites this page's claims.\n- [API stability](./api-stability.md) - semver policy, deprecation\n lifecycle.\n"
6079
6086
  },
6080
6087
  {
6081
6088
  "slug": "help/server-side-data",
@@ -6817,7 +6824,7 @@ export const docs = [
6817
6824
  "path": "docs/help/ui-components/sv-display-primitives.md",
6818
6825
  "title": "Display primitives - SvKbd, SvCode, SvAspectRatio, SvVisuallyHidden",
6819
6826
  "section": "UI components",
6820
- "markdown": "# Display primitives - SvKbd, SvCode, SvAspectRatio, SvVisuallyHidden\n\nThe small display helpers you reach for constantly in docs, command palettes, and\nmedia layouts - each themed from the shared `--sg-*` tokens and dependency-free.\n\n- **SvKbd** - a keyboard-key hint (single key or a combo).\n- **SvCode** - monospace code, inline or as a scrolling block.\n- **SvAspectRatio** - hold a fixed width:height ratio to prevent layout shift.\n- **SvVisuallyHidden** - screen-reader-only content (the \"sr-only\" pattern).\n\nRelated: [SvCommand](sv-command.md) · [SvCode in docs](sv-rich-text.md) · [Tokens](../tokens.md)\n\n## Installation\n\nAdd them with the CLI:\n\n<div data-docs-add=\"add display\"></div>\n\nOr install the package and import them directly. They ship free in\n`@svgrid/grid` (dependency-free):\n\n<div data-docs-install=\"@svgrid/grid\"></div>\n\nThe examples on this page import from `@svgrid/grid`:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvAspectRatio, SvCode, SvKbd, SvVisuallyHidden } from '@svgrid/grid'\n</script>\n```\n\n```ts\nimport { SvKbd, SvCode, SvAspectRatio, SvVisuallyHidden } from '@svgrid/grid'\n```\n\n## Example\n\n<div data-docs-demo=\"410-typography-display\" data-height=\"520\" data-code></div>\n\n```svelte {runnable}\n<script lang=\"ts\">\n import { SvKbd, SvCode, SvAspectRatio, SvVisuallyHidden } from '@svgrid/grid'\n</script>\n\n<SvKbd keys={['Ctrl', 'K']} /> opens the palette.\n\n<SvCode>npm i @svgrid/grid</SvCode>\n\n<SvAspectRatio ratio={16 / 9}>\n <img src=\"/cover.jpg\" alt=\"\" />\n</SvAspectRatio>\n\n<button>★<SvVisuallyHidden>Add to favourites</SvVisuallyHidden></button>\n```\n\n## SvKbd\n\nPass `keys` for a combo (rendered as separate caps joined by `separator`), or a\nsingle `children` label.\n\n| Prop | Type | Default | Description |\n| ----------- | ---------- | ------- | ------------------------------------ |\n| `keys` | `string[]` | - | Key sequence, rendered as caps. |\n| `separator` | `string` | `+` | Separator shown between keys. |\n| `size` | `sm` \\| `md` | `md` | Cap size. |\n\n## SvCode\n\nInline by default; set `block` for a padded, horizontally-scrolling block. Pass\n`code` as a string or use the `children` snippet. No syntax highlighting - bring\nyour own if you need it.\n\n| Prop | Type | Default | Description |\n| ------- | --------- | ------- | ------------------------------------ |\n| `block` | `boolean` | `false` | Render a padded block, not inline. |\n| `code` | `string` | - | Code as a string (skip the snippet). |\n\n## SvAspectRatio\n\nHolds the ratio for its content (media, embeds, maps, skeletons); the single\nchild fills the box (`object-fit: cover`).\n\n| Prop | Type | Default | Description |\n| ------- | -------- | --------- | -------------------------------------------- |\n| `ratio` | `number` | `16 / 9` | Width / height ratio (e.g. `1`, `4 / 3`). |\n\n## SvVisuallyHidden\n\n| Prop | Type | Default | Description |\n| ----------- | --------- | ------- | ------------------------------------------------------------ |\n| `focusable` | `boolean` | `false` | Reveal on focus (for skip links). |\n| `as` | `string` | `span` | Element/tag to render. |\n\n## Accessibility\n\n- **SvVisuallyHidden** keeps content in the accessibility tree while hiding it\n visually - ideal for naming icon-only controls and for skip links (set\n `focusable` so the link appears when tabbed to).\n- **SvKbd** uses semantic `<kbd>` elements; the separator between keys is\n `aria-hidden` so screen readers announce the keys, not the \"+\".\n- **SvAspectRatio** is presentational - always give the media inside it a real\n `alt` (or `aria-hidden` when decorative).\n\n## Keys, code and a fixed ratio\n\nSmall pieces that show up constantly in documentation and settings screens.\n`SvKbd` takes the keys as data rather than as pre-joined text, so the separator\nis presentation and can differ per platform.\n\n```svelte {runnable}\n<script lang=\"ts\">\n import { SvKbd, SvCode, SvAspectRatio, SvText } from '@svgrid/grid'\n</script>\n\n<SvText>Press <SvKbd keys={['Cmd', 'K']} /> to open the palette.</SvText>\n\n<SvText>Install with <SvCode code=\"npm i @svgrid/grid\" />.</SvText>\n\n<SvCode block code={`const columns = [\n { field: \"name\", header: \"Name\" },\n]`} />\n\n<SvAspectRatio ratio={16 / 9}>\n <div style=\"width: 100%; height: 100%; display: grid; place-items: center; background: color-mix(in srgb, currentColor 8%, transparent);\">\n 16 : 9\n </div>\n</SvAspectRatio>\n```\n\n## See also\n\n- [Typography](sv-typography.md) - SvTitle / SvText / SvAnchor / SvBlockquote / SvMark / SvList.\n- [SvCommand](sv-command.md) - the command palette where `SvKbd` shortcuts live.\n"
6827
+ "markdown": "\n# Display primitives - SvKbd, SvCode, SvAspectRatio, SvVisuallyHidden\n\nThe small display helpers you reach for constantly in docs, command palettes, and\nmedia layouts - each themed from the shared `--sg-*` tokens and dependency-free.\n\n- **SvKbd** - a keyboard-key hint (single key or a combo).\n- **SvCode** - monospace code, inline or as a scrolling block.\n- **SvAspectRatio** - hold a fixed width:height ratio to prevent layout shift.\n- **SvVisuallyHidden** - screen-reader-only content (the \"sr-only\" pattern).\n\nRelated: [SvCommand](sv-command.md) · [SvCode in docs](sv-rich-text.md) · [Tokens](../tokens.md)\n\n## Installation\n\nAdd them with the CLI:\n\n<div data-docs-add=\"add display\"></div>\n\nOr install the package and import them directly. They ship free in\n`@svgrid/grid` (dependency-free):\n\n<div data-docs-install=\"@svgrid/grid\"></div>\n\nThe examples on this page import from `@svgrid/grid`:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvAspectRatio, SvCode, SvKbd, SvVisuallyHidden } from '@svgrid/grid'\n</script>\n```\n\n```ts\nimport { SvKbd, SvCode, SvAspectRatio, SvVisuallyHidden } from '@svgrid/grid'\n```\n\n## Example\n\n<div data-docs-demo=\"410-typography-display\" data-height=\"520\" data-code></div>\n\n```svelte {runnable}\n<script lang=\"ts\">\n import { SvKbd, SvCode, SvAspectRatio, SvVisuallyHidden } from '@svgrid/grid'\n</script>\n\n<SvKbd keys={['Ctrl', 'K']} /> opens the palette.\n\n<SvCode>npm i @svgrid/grid</SvCode>\n\n<SvAspectRatio ratio={16 / 9}>\n <img src=\"/cover.jpg\" alt=\"\" />\n</SvAspectRatio>\n\n<button>★<SvVisuallyHidden>Add to favourites</SvVisuallyHidden></button>\n```\n\n## SvKbd\n\nPass `keys` for a combo (rendered as separate caps joined by `separator`), or a\nsingle `children` label.\n\n| Prop | Type | Default | Description |\n| ----------- | ---------- | ------- | ------------------------------------ |\n| `keys` | `string[]` | - | Key sequence, rendered as caps. |\n| `separator` | `string` | `+` | Separator shown between keys. |\n| `size` | `sm` \\| `md` | `md` | Cap size. |\n\n## SvCode\n\nInline by default; set `block` for a padded, horizontally-scrolling block. Pass\n`code` as a string or use the `children` snippet. No syntax highlighting - bring\nyour own if you need it.\n\n| Prop | Type | Default | Description |\n| ------- | --------- | ------- | ------------------------------------ |\n| `block` | `boolean` | `false` | Render a padded block, not inline. |\n| `code` | `string` | - | Code as a string (skip the snippet). |\n\n## SvAspectRatio\n\nHolds the ratio for its content (media, embeds, maps, skeletons); the single\nchild fills the box (`object-fit: cover`).\n\n| Prop | Type | Default | Description |\n| ------- | -------- | --------- | -------------------------------------------- |\n| `ratio` | `number` | `16 / 9` | Width / height ratio (e.g. `1`, `4 / 3`). |\n\n## SvVisuallyHidden\n\n| Prop | Type | Default | Description |\n| ----------- | --------- | ------- | ------------------------------------------------------------ |\n| `focusable` | `boolean` | `false` | Reveal on focus (for skip links). |\n| `as` | `string` | `span` | Element/tag to render. |\n\n## Accessibility\n\n- **SvVisuallyHidden** keeps content in the accessibility tree while hiding it\n visually - ideal for naming icon-only controls and for skip links (set\n `focusable` so the link appears when tabbed to).\n- **SvKbd** uses semantic `<kbd>` elements; the separator between keys is\n `aria-hidden` so screen readers announce the keys, not the \"+\".\n- **SvAspectRatio** is presentational - always give the media inside it a real\n `alt` (or `aria-hidden` when decorative).\n\n## Keys, code and a fixed ratio\n\nSmall pieces that show up constantly in documentation and settings screens.\n`SvKbd` takes the keys as data rather than as pre-joined text, so the separator\nis presentation and can differ per platform.\n\n```svelte {runnable}\n<script lang=\"ts\">\n import { SvKbd, SvCode, SvAspectRatio, SvText } from '@svgrid/grid'\n</script>\n\n<SvText>Press <SvKbd keys={['Cmd', 'K']} /> to open the palette.</SvText>\n\n<SvText>Install with <SvCode code=\"npm i @svgrid/grid\" />.</SvText>\n\n<SvCode block code={`const columns = [\n { field: \"name\", header: \"Name\" },\n]`} />\n\n<SvAspectRatio ratio={16 / 9}>\n <div style=\"width: 100%; height: 100%; display: grid; place-items: center; background: color-mix(in srgb, currentColor 8%, transparent);\">\n 16 : 9\n </div>\n</SvAspectRatio>\n```\n\n## See also\n\n- [Typography](sv-typography.md) - SvTitle / SvText / SvAnchor / SvBlockquote / SvMark / SvList.\n- [SvCommand](sv-command.md) - the command palette where `SvKbd` shortcuts live.\n"
6821
6828
  },
6822
6829
  {
6823
6830
  "slug": "help/ui-components/sv-divider",
@@ -7244,7 +7251,7 @@ export const docs = [
7244
7251
  "path": "docs/help/ui-components/sv-typography.md",
7245
7252
  "title": "Typography - SvTitle, SvText, SvAnchor, SvBlockquote, SvMark, SvList",
7246
7253
  "section": "UI components",
7247
- "markdown": "# Typography - SvTitle, SvText, SvAnchor, SvBlockquote, SvMark, SvList\n\nA small set of prose primitives so headings, body copy, links, quotes,\nhighlights, and lists all pull from one type scale and the shared `--sg-*` tokens\n- instead of scattering ad-hoc font sizes and colours across your app.\n\n- **SvTitle** - headings (`h1`-`h6`) with size decoupled from semantic level.\n- **SvText** - body / inline text with size, weight, tone, truncation, line-clamp.\n- **SvAnchor** - a themed link with safe external handling.\n- **SvBlockquote** - a quotation with an accent rule and optional citation.\n- **SvMark** - highlighted inline text (a themed `<mark>`).\n- **SvList** - ordered / unordered / unstyled lists.\n\nRelated: [SvText as cell content](../../help/ui-components/sv-card.md) · [Tokens](../tokens.md)\n\n## Installation\n\nAdd them with the CLI:\n\n<div data-docs-add=\"add typography\"></div>\n\nOr install the package and import them directly. They ship free in\n`@svgrid/grid` (dependency-free):\n\n<div data-docs-install=\"@svgrid/grid\"></div>\n\nThe examples on this page import from `@svgrid/grid`:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvAnchor, SvMark, SvText, SvTitle } from '@svgrid/grid'\n</script>\n```\n\n```ts\nimport { SvTitle, SvText, SvAnchor, SvBlockquote, SvMark, SvList } from '@svgrid/grid'\n```\n\n## Example\n\n<div data-docs-demo=\"410-typography-display\" data-height=\"520\" data-code></div>\n\n```svelte {runnable}\n<script lang=\"ts\">\n import { SvTitle, SvText, SvMark, SvAnchor } from '@svgrid/grid'\n</script>\n\n<SvTitle order={1}>Dashboard</SvTitle>\n<SvText tone=\"muted\">Last synced 2 minutes ago.</SvText>\n<SvText>\n A <SvMark>highlighted</SvMark> phrase and an\n <SvAnchor href=\"https://svelte.dev\" external>external link</SvAnchor>.\n</SvText>\n```\n\n## SvTitle\n\n`order` sets the semantic level (`h1`-`h6`) and, by default, the visual size.\nPass `size` to make an `h3` look like an `h5` while staying semantically correct.\n\n| Prop | Type | Default | Description |\n| ---------- | --------------------------------- | ------- | -------------------------------------------- |\n| `order` | `1`-`6` | `2` | Semantic heading level (`h1`-`h6`). |\n| `size` | `1`-`6` | `order` | Visual size step, decoupled from `order`. |\n| `align` | `start` \\| `center` \\| `end` | - | Text alignment. |\n| `truncate` | `boolean` | `false` | Single-line ellipsis. |\n\n## SvText\n\n| Prop | Type | Default | Description |\n| ---------- | ---------------------------------------------------------------- | --------- | ------------------------------------------- |\n| `size` | `xs` \\| `sm` \\| `md` \\| `lg` \\| `xl` | `md` | Font size step. |\n| `weight` | `normal` \\| `medium` \\| `semibold` \\| `bold` | `normal` | Font weight. |\n| `tone` | `default` \\| `muted` \\| `accent` \\| `success` \\| `warning` \\| `error` | `default` | Semantic colour. |\n| `align` | `start` \\| `center` \\| `end` | - | Text alignment. |\n| `truncate` | `boolean` | `false` | Single-line ellipsis. |\n| `clamp` | `number` | - | Clamp to N lines (overrides `truncate`). |\n| `inline` | `boolean` | `false` | Render a `span` instead of a `p`. |\n| `as` | `string` | - | Override the element/tag. |\n\n## SvAnchor\n\n| Prop | Type | Default | Description |\n| ----------- | --------------------------------- | -------- | --------------------------------------------------- |\n| `href` | `string` | - | Link target. |\n| `external` | `boolean` | `false` | Open in a new tab with `rel=\"noopener noreferrer\"` + an offscreen \"opens in a new tab\" hint. |\n| `underline` | `hover` \\| `always` \\| `none` | `hover` | Underline behaviour. |\n| `tone` | `accent` \\| `default` \\| `muted` | `accent` | Colour. |\n| `size` | `sm` \\| `md` \\| `lg` | `md` | Font size step. |\n\n## SvBlockquote\n\n| Prop | Type | Default | Description |\n| ------ | ------------------------------------------------------- | -------- | --------------------------------- |\n| `cite` | `string` | - | Attribution shown under the quote.|\n| `tone` | `accent` \\| `muted` \\| `success` \\| `warning` \\| `error`| `accent` | Colour of the accent rule. |\n\n## SvMark\n\n| Prop | Type | Default | Description |\n| ------ | -------------------------------------------------------- | -------- | ------------- |\n| `tone` | `yellow` \\| `accent` \\| `success` \\| `warning` \\| `error`| `yellow` | Highlight tint.|\n\n## SvList\n\nPass `items` for the simple case, or a `children` snippet of `<li>` elements for\nfull control.\n\n| Prop | Type | Default | Description |\n| --------- | ------------------------------------- | ------------ | --------------------------------------- |\n| `type` | `unordered` \\| `ordered` \\| `none` | `unordered` | Marker style (`none` drops indentation).|\n| `items` | `string[]` | - | Simple string items. |\n| `spacing` | `sm` \\| `md` \\| `lg` | `md` | Vertical gap between items. |\n| `size` | `sm` \\| `md` \\| `lg` | `md` | Font size step. |\n\n## Accessibility\n\n- **SvTitle** renders a real heading element - keep the document outline logical\n (do not skip levels for looks; use `size` to adjust appearance instead).\n- **SvAnchor** with `external` includes an offscreen \"opens in a new tab\" note so\n the behaviour is announced, and shows a focus ring on keyboard focus.\n- **SvMark** conveys emphasis visually; do not rely on the highlight colour alone\n to carry meaning.\n\n## A heading, body and a link\n\nThese carry the type scale so a page reads consistently without a stylesheet\nper screen. `SvTitle` takes `order` for the heading level, which keeps the\ndocument outline correct even when the visual size does not match.\n\n```svelte {runnable}\n<script lang=\"ts\">\n import { SvTitle, SvText, SvAnchor, SvMark } from '@svgrid/grid'\n</script>\n\n<SvTitle order={2}>Release notes</SvTitle>\n\n<SvText>\n This release adds <SvMark>row spanning</SvMark> and a faster filter pass.\n</SvText>\n\n<SvText size=\"sm\" tone=\"muted\">\n Read the <SvAnchor href=\"/docs/\">documentation</SvAnchor> for the full list.\n</SvText>\n```\n\n## See also\n\n- [Display primitives](sv-display-primitives.md) - SvKbd / SvCode / SvAspectRatio / SvVisuallyHidden.\n- [Tokens](../tokens.md) - the `--sg-*` colours and font these components read.\n"
7254
+ "markdown": "\n# Typography - SvTitle, SvText, SvAnchor, SvBlockquote, SvMark, SvList\n\nA small set of prose primitives so headings, body copy, links, quotes,\nhighlights, and lists all pull from one type scale and the shared `--sg-*` tokens\n- instead of scattering ad-hoc font sizes and colours across your app.\n\n- **SvTitle** - headings (`h1`-`h6`) with size decoupled from semantic level.\n- **SvText** - body / inline text with size, weight, tone, truncation, line-clamp.\n- **SvAnchor** - a themed link with safe external handling.\n- **SvBlockquote** - a quotation with an accent rule and optional citation.\n- **SvMark** - highlighted inline text (a themed `<mark>`).\n- **SvList** - ordered / unordered / unstyled lists.\n\nRelated: [SvText as cell content](../../help/ui-components/sv-card.md) · [Tokens](../tokens.md)\n\n## Installation\n\nAdd them with the CLI:\n\n<div data-docs-add=\"add typography\"></div>\n\nOr install the package and import them directly. They ship free in\n`@svgrid/grid` (dependency-free):\n\n<div data-docs-install=\"@svgrid/grid\"></div>\n\nThe examples on this page import from `@svgrid/grid`:\n\n```svelte {preamble}\n<script lang=\"ts\">\n import { SvAnchor, SvMark, SvText, SvTitle } from '@svgrid/grid'\n</script>\n```\n\n```ts\nimport { SvTitle, SvText, SvAnchor, SvBlockquote, SvMark, SvList } from '@svgrid/grid'\n```\n\n## Example\n\n<div data-docs-demo=\"410-typography-display\" data-height=\"520\" data-code></div>\n\n```svelte {runnable}\n<script lang=\"ts\">\n import { SvTitle, SvText, SvMark, SvAnchor } from '@svgrid/grid'\n</script>\n\n<SvTitle order={1}>Dashboard</SvTitle>\n<SvText tone=\"muted\">Last synced 2 minutes ago.</SvText>\n<SvText>\n A <SvMark>highlighted</SvMark> phrase and an\n <SvAnchor href=\"https://svelte.dev\" external>external link</SvAnchor>.\n</SvText>\n```\n\n## SvTitle\n\n`order` sets the semantic level (`h1`-`h6`) and, by default, the visual size.\nPass `size` to make an `h3` look like an `h5` while staying semantically correct.\n\n| Prop | Type | Default | Description |\n| ---------- | --------------------------------- | ------- | -------------------------------------------- |\n| `order` | `1`-`6` | `2` | Semantic heading level (`h1`-`h6`). |\n| `size` | `1`-`6` | `order` | Visual size step, decoupled from `order`. |\n| `align` | `start` \\| `center` \\| `end` | - | Text alignment. |\n| `truncate` | `boolean` | `false` | Single-line ellipsis. |\n\n## SvText\n\n| Prop | Type | Default | Description |\n| ---------- | ---------------------------------------------------------------- | --------- | ------------------------------------------- |\n| `size` | `xs` \\| `sm` \\| `md` \\| `lg` \\| `xl` | `md` | Font size step. |\n| `weight` | `normal` \\| `medium` \\| `semibold` \\| `bold` | `normal` | Font weight. |\n| `tone` | `default` \\| `muted` \\| `accent` \\| `success` \\| `warning` \\| `error` | `default` | Semantic colour. |\n| `align` | `start` \\| `center` \\| `end` | - | Text alignment. |\n| `truncate` | `boolean` | `false` | Single-line ellipsis. |\n| `clamp` | `number` | - | Clamp to N lines (overrides `truncate`). |\n| `inline` | `boolean` | `false` | Render a `span` instead of a `p`. |\n| `as` | `string` | - | Override the element/tag. |\n\n## SvAnchor\n\n| Prop | Type | Default | Description |\n| ----------- | --------------------------------- | -------- | --------------------------------------------------- |\n| `href` | `string` | - | Link target. |\n| `external` | `boolean` | `false` | Open in a new tab with `rel=\"noopener noreferrer\"` + an offscreen \"opens in a new tab\" hint. |\n| `underline` | `hover` \\| `always` \\| `none` | `hover` | Underline behaviour. |\n| `tone` | `accent` \\| `default` \\| `muted` | `accent` | Colour. |\n| `size` | `sm` \\| `md` \\| `lg` | `md` | Font size step. |\n\n## SvBlockquote\n\n| Prop | Type | Default | Description |\n| ------ | ------------------------------------------------------- | -------- | --------------------------------- |\n| `cite` | `string` | - | Attribution shown under the quote.|\n| `tone` | `accent` \\| `muted` \\| `success` \\| `warning` \\| `error`| `accent` | Colour of the accent rule. |\n\n## SvMark\n\n| Prop | Type | Default | Description |\n| ------ | -------------------------------------------------------- | -------- | ------------- |\n| `tone` | `yellow` \\| `accent` \\| `success` \\| `warning` \\| `error`| `yellow` | Highlight tint.|\n\n## SvList\n\nPass `items` for the simple case, or a `children` snippet of `<li>` elements for\nfull control.\n\n| Prop | Type | Default | Description |\n| --------- | ------------------------------------- | ------------ | --------------------------------------- |\n| `type` | `unordered` \\| `ordered` \\| `none` | `unordered` | Marker style (`none` drops indentation).|\n| `items` | `string[]` | - | Simple string items. |\n| `spacing` | `sm` \\| `md` \\| `lg` | `md` | Vertical gap between items. |\n| `size` | `sm` \\| `md` \\| `lg` | `md` | Font size step. |\n\n## Accessibility\n\n- **SvTitle** renders a real heading element - keep the document outline logical\n (do not skip levels for looks; use `size` to adjust appearance instead).\n- **SvAnchor** with `external` includes an offscreen \"opens in a new tab\" note so\n the behaviour is announced, and shows a focus ring on keyboard focus.\n- **SvMark** conveys emphasis visually; do not rely on the highlight colour alone\n to carry meaning.\n\n## A heading, body and a link\n\nThese carry the type scale so a page reads consistently without a stylesheet\nper screen. `SvTitle` takes `order` for the heading level, which keeps the\ndocument outline correct even when the visual size does not match.\n\n```svelte {runnable}\n<script lang=\"ts\">\n import { SvTitle, SvText, SvAnchor, SvMark } from '@svgrid/grid'\n</script>\n\n<SvTitle order={2}>Release notes</SvTitle>\n\n<SvText>\n This release adds <SvMark>row spanning</SvMark> and a faster filter pass.\n</SvText>\n\n<SvText size=\"sm\" tone=\"muted\">\n Read the <SvAnchor href=\"/docs/\">documentation</SvAnchor> for the full list.\n</SvText>\n```\n\n## See also\n\n- [Display primitives](sv-display-primitives.md) - SvKbd / SvCode / SvAspectRatio / SvVisuallyHidden.\n- [Tokens](../tokens.md) - the `--sg-*` colours and font these components read.\n"
7248
7255
  },
7249
7256
  {
7250
7257
  "slug": "help/versioning",
@@ -7328,7 +7335,7 @@ export const docs = [
7328
7335
  "path": "docs/help/web-components/sv-sheet.md",
7329
7336
  "title": "<sv-sheet>: the spreadsheet as a custom element",
7330
7337
  "section": "Spreadsheet",
7331
- "markdown": "# `<sv-sheet>`: the spreadsheet as a custom element\n\nThe spreadsheet shell of `@svgrid/enterprise`, ribbon and formula engine\nincluded, as one custom element for a page or a host with no Svelte in its\nbuild: React, Vue, Angular, or a plain `<script>` tag. It is part of the\npaid pack, with its 30-day evaluation period: without a key it runs and\ndisplays the pack's watermark and console message, as every entry does.\n\n**The reference below is generated** from `<SvSheet>`'s own `Props` type by\n`packages/enterprise/scripts/generate-sheet-surface.mjs`, the same way the\n[`<sv-grid>`](sv-grid.md) and [`<sv-chart>`](sv-chart.md) references are,\nand the package's tests fail if it drifts.\n\n## Loading it\n\n```html\n<script type=\"module\" src=\"https://cdn.jsdelivr.net/npm/@svgrid/enterprise/dist/wc/sv-sheet-element.js\"></script>\n\n<sv-sheet id=\"sheet\" height=\"480\" rows=\"30\" columns=\"10\"></sv-sheet>\n<script type=\"module\">\n const sheet = document.getElementById('sheet')\n sheet.data = [{ name: 'Budget', cells: [['Item', 'Amount'], ['Rent', '1200'], ['Total', '=SUM(B2:B2)']] }]\n sheet.addEventListener('ready', () => console.log(sheet.getState()))\n sheet.addEventListener('change', (e) => console.log(e.detail)) // the reasons, once per tick\n sheet.addEventListener('action', (e) => {\n if (e.detail.action === 'file-save-xlsx') { e.preventDefault(); upload(sheet.toXlsx()) }\n })\n</script>\n```\n\nFrom npm, `import '@svgrid/enterprise/wc'` registers the element. The React\nand Vue wrappers are `@svgrid/enterprise/wc/react` and\n`@svgrid/enterprise/wc/vue`; Angular uses the element directly with\n`CUSTOM_ELEMENTS_SCHEMA`, the way the [Angular page](angular.md) shows for\n`<sv-grid>` before its wrapper existed.\n\nSave As and Open need `jszip`, an optional peer the element loads on demand.\nA page that uses them names it in an import map:\n\n```html\n<script type=\"importmap\">{ \"imports\": { \"jszip\": \"https://cdn.jsdelivr.net/npm/jszip@3/+esm\" } }</script>\n```\n\n## Attributes vs properties\n\nThe [same rule as the grid element](sv-grid.md#attributes-vs-properties):\nprimitives are attributes, arrays, objects and functions are properties.\n`data`, `workbook`, `document`, `formats`, `columnWidths`, `extras` and\n`localization` are properties; `height` takes a number or `\"100%\"`, so it\nkeeps a string attribute.\n\nA document built with `createSheetDocument` from `@svgrid/enterprise` is\nassigned as `sheet.document`; `ready` hands the api and the document back\nand parks both on the element (`sheet.api`, `sheet.document`), so a listener\nbound after the mount still reaches them.\n\n**Content assigned after the element is on the page is taken up.** A custom\nelement is upgraded the moment its definition loads, which on a plain page\nis before the script that sets its properties runs, so `sheet.data = [...]`\nin the quick start above arrives after the shell has already mounted on an\nempty sheet. The element remounts on it. That happens only while nothing has\nbeen done to the sheet: once a cell has been written, a later `data`,\n`workbook` or `document` is ignored rather than throwing the work away,\nwhich is what a React render passing a fresh array does on every parent\nupdate. To load content over a sheet that has been edited, call\n`setState(state)` or `newWorkbook()`.\n\n## Events and methods\n\nEvery callback of the component is an event with the callback's argument\nas `detail`. `action` is the one whose answer matters: a listener that calls\n`event.preventDefault()` has taken the action over, and the shell's own\ndialog stays closed, which is what returning `true` from `onAction` does.\n\nThe component's methods are on the element: `getState()`, `setState(state)`,\n`refresh()`, `act(action)`, `open(file)`, `toXlsx()`, `toCsv()`,\n`newWorkbook()`, `print()` and `printHtml()`.\n\n```js\nsheet.act('sort-asc')\nconst state = sheet.getState()\nlocalStorage.setItem('budget', JSON.stringify(state))\n```\n\n## React and Vue\n\n```tsx {nocheck}\nimport { useRef } from 'react'\nimport { SvSheet, type SvSheetHandle } from '@svgrid/enterprise/wc/react'\n\nconst ref = useRef<SvSheetHandle>(null)\n\n<SvSheet ref={ref} data={sheets} height={480}\n onAction={(detail, e) => { if (detail.action === 'file-print') { e.preventDefault(); printMyWay() } }}\n onChange={(reasons) => save(ref.current?.element?.getState())} />\n```\n\n```vue {nocheck}\n<script setup>\nimport { SvSheet } from '@svgrid/enterprise/wc/vue'\n</script>\n\n<SvSheet :data=\"sheets\" :height=\"480\" @change=\"save\" @ready=\"({ api }) => (grid = api)\" />\n```\n\nThe React wrapper assigns object props as properties (React 18 and earlier\nstringify them onto attributes) and binds the handlers once; the Vue wrapper\nforwards every prop with the `.prop` modifier. Both expose the element, with\nits methods, through the ref.\n\n<!-- BEGIN generated reference - packages/enterprise/scripts/generate-sheet-surface.mjs -->\n\n### Attributes (11)\n\nPrimitives, so they work in plain HTML as well as through a property.\n\n| Attribute | Property | Type |\n| --- | --- | --- |\n| `rows` | `rows` | `number` |\n| `columns` | `columns` | `number` |\n| `height` | `height` | `number \\| '100%'` |\n| `column-width` | `columnWidth` | `number` |\n| `row-height` | `rowHeight` | `number` |\n| `look` | `look` | `'excel' \\| 'theme'` |\n| `comment-author` | `commentAuthor` | `string` |\n| `show-ribbon` | `showRibbon` | `boolean` |\n| `show-formula-bar` | `showFormulaBar` | `boolean` |\n| `show-tabs` | `showTabs` | `boolean` |\n| `show-status-bar` | `showStatusBar` | `boolean` |\n\n### Properties only (9)\n\nArrays, objects and functions. An HTML attribute is a string, so these can\nonly be assigned in script: `el.document = doc`.\n\n| Property | Type |\n| --- | --- |\n| `document` | `SheetDocument` |\n| `workbook` | `Workbook` |\n| `data` | `ReadonlyArray<SheetData>` |\n| `gridSheets` | `Record<string, GridSheetSpec>` |\n| `columnWidths` | `Readonly<Record<string, number>>` |\n| `formats` | `Readonly<Record<string, CellFormatEntry>>` |\n| `extras` | `ReadonlyArray<'insert-table' \\| 'insert-chart'>` |\n| `localization` | `SheetLocalization` |\n| `presence` | `ReadonlyArray<SheetPresence>` |\n\n### Events (5)\n\n`detail` is the callback's argument, or an object keyed by the parameter names\nwhen it takes more than one. `action` is cancelable: `event.preventDefault()`\ntakes the action over, as returning `true` from `onAction` does.\n\n| Event | From | `detail` |\n| --- | --- | --- |\n| `action` | `onAction` | `{ action, cmd }` |\n| `cellaction` | `onCellAction` | `event` |\n| `ready` | `onReady` | `{ api, document }` |\n| `change` | `onChange` | `reasons` |\n| `presence` | `onPresence` | `me` |\n\n### Methods (12)\n\nThe component's own, on the element once `ready` has fired.\n\n| Method | What it does |\n| --- | --- |\n| `getState(): SheetState` | The document as plain JSON. |\n| `setState(state: SheetState): void` | Put a saved document back. |\n| `refresh(): void` | Repaint after a write the shell could not see. |\n| `act(action: RibbonActionId): void` | Run a ribbon action as if its button had been clicked. |\n| `open(file: Blob & { name?: string }): Promise<void>` | Replace the document with an .xlsx, .ods or .csv file. |\n| `toXlsx(): Promise<Blob>` | The document as an .xlsx Blob. |\n| `toOds(): Promise<Blob>` | The document as an .ods Blob, which LibreOffice Calc opens. |\n| `toXls(): Blob` | The document as an .xls Blob, which Excel 97-2003 opens. |\n| `toCsv(): string` | The active sheet as CSV. |\n| `newWorkbook(): void` | Start over with one empty sheet. |\n| `print(): void` | The active sheet in the print dialog. |\n| `printHtml(): string` | The page File > Print would open. |\n\n<!-- END generated reference -->\n\n## What it does not carry\n\nSvelte snippets cannot cross the custom-element boundary, and `<SvSheet>`\nhas none in its props, so nothing is left out. What the element cannot do\nis what the component cannot: see [the shell page](../cells/spreadsheet-shell.md#what-it-does-not-do).\n\n## See also\n\n- [The spreadsheet shell](../cells/spreadsheet-shell.md), the component\n behind the element: its ribbon, dialogs, document and files.\n- [Enterprise features from the element](enterprise.md), for the export,\n import, print and pivot entries that work beside `<sv-grid>`.\n"
7338
+ "markdown": "\n# `<sv-sheet>`: the spreadsheet as a custom element\n\nThe spreadsheet shell of `@svgrid/enterprise`, ribbon and formula engine\nincluded, as one custom element for a page or a host with no Svelte in its\nbuild: React, Vue, Angular, or a plain `<script>` tag. It is part of the\npaid pack, with its 30-day evaluation period: without a key it runs and\ndisplays the pack's watermark and console message, as every entry does.\n\n**The reference below is generated** from `<SvSheet>`'s own `Props` type by\n`packages/enterprise/scripts/generate-sheet-surface.mjs`, the same way the\n[`<sv-grid>`](sv-grid.md) and [`<sv-chart>`](sv-chart.md) references are,\nand the package's tests fail if it drifts.\n\n## Loading it\n\n```html\n<script type=\"module\" src=\"https://cdn.jsdelivr.net/npm/@svgrid/enterprise/dist/wc/sv-sheet-element.js\"></script>\n\n<sv-sheet id=\"sheet\" height=\"480\" rows=\"30\" columns=\"10\"></sv-sheet>\n<script type=\"module\">\n const sheet = document.getElementById('sheet')\n sheet.data = [{ name: 'Budget', cells: [['Item', 'Amount'], ['Rent', '1200'], ['Total', '=SUM(B2:B2)']] }]\n sheet.addEventListener('ready', () => console.log(sheet.getState()))\n sheet.addEventListener('change', (e) => console.log(e.detail)) // the reasons, once per tick\n sheet.addEventListener('action', (e) => {\n if (e.detail.action === 'file-save-xlsx') { e.preventDefault(); upload(sheet.toXlsx()) }\n })\n</script>\n```\n\nFrom npm, `import '@svgrid/enterprise/wc'` registers the element. The React\nand Vue wrappers are `@svgrid/enterprise/wc/react` and\n`@svgrid/enterprise/wc/vue`; Angular uses the element directly with\n`CUSTOM_ELEMENTS_SCHEMA`, the way the [Angular page](angular.md) shows for\n`<sv-grid>` before its wrapper existed.\n\nSave As and Open need `jszip`, an optional peer the element loads on demand.\nA page that uses them names it in an import map:\n\n```html\n<script type=\"importmap\">{ \"imports\": { \"jszip\": \"https://cdn.jsdelivr.net/npm/jszip@3/+esm\" } }</script>\n```\n\n## Attributes vs properties\n\nThe [same rule as the grid element](sv-grid.md#attributes-vs-properties):\nprimitives are attributes, arrays, objects and functions are properties.\n`data`, `workbook`, `document`, `formats`, `columnWidths`, `extras` and\n`localization` are properties; `height` takes a number or `\"100%\"`, so it\nkeeps a string attribute.\n\nA document built with `createSheetDocument` from `@svgrid/enterprise` is\nassigned as `sheet.document`; `ready` hands the api and the document back\nand parks both on the element (`sheet.api`, `sheet.document`), so a listener\nbound after the mount still reaches them.\n\n**Content assigned after the element is on the page is taken up.** A custom\nelement is upgraded the moment its definition loads, which on a plain page\nis before the script that sets its properties runs, so `sheet.data = [...]`\nin the quick start above arrives after the shell has already mounted on an\nempty sheet. The element remounts on it. That happens only while nothing has\nbeen done to the sheet: once a cell has been written, a later `data`,\n`workbook` or `document` is ignored rather than throwing the work away,\nwhich is what a React render passing a fresh array does on every parent\nupdate. To load content over a sheet that has been edited, call\n`setState(state)` or `newWorkbook()`.\n\n## Events and methods\n\nEvery callback of the component is an event with the callback's argument\nas `detail`. `action` is the one whose answer matters: a listener that calls\n`event.preventDefault()` has taken the action over, and the shell's own\ndialog stays closed, which is what returning `true` from `onAction` does.\n\nThe component's methods are on the element: `getState()`, `setState(state)`,\n`refresh()`, `act(action)`, `open(file)`, `toXlsx()`, `toCsv()`,\n`newWorkbook()`, `print()` and `printHtml()`.\n\n```js\nsheet.act('sort-asc')\nconst state = sheet.getState()\nlocalStorage.setItem('budget', JSON.stringify(state))\n```\n\n## React and Vue\n\n```tsx {nocheck}\nimport { useRef } from 'react'\nimport { SvSheet, type SvSheetHandle } from '@svgrid/enterprise/wc/react'\n\nconst ref = useRef<SvSheetHandle>(null)\n\n<SvSheet ref={ref} data={sheets} height={480}\n onAction={(detail, e) => { if (detail.action === 'file-print') { e.preventDefault(); printMyWay() } }}\n onChange={(reasons) => save(ref.current?.element?.getState())} />\n```\n\n```vue {nocheck}\n<script setup>\nimport { SvSheet } from '@svgrid/enterprise/wc/vue'\n</script>\n\n<SvSheet :data=\"sheets\" :height=\"480\" @change=\"save\" @ready=\"({ api }) => (grid = api)\" />\n```\n\nThe React wrapper assigns object props as properties (React 18 and earlier\nstringify them onto attributes) and binds the handlers once; the Vue wrapper\nforwards every prop with the `.prop` modifier. Both expose the element, with\nits methods, through the ref.\n\n<!-- BEGIN generated reference - packages/enterprise/scripts/generate-sheet-surface.mjs -->\n\n### Attributes (11)\n\nPrimitives, so they work in plain HTML as well as through a property.\n\n| Attribute | Property | Type |\n| --- | --- | --- |\n| `rows` | `rows` | `number` |\n| `columns` | `columns` | `number` |\n| `height` | `height` | `number \\| '100%'` |\n| `column-width` | `columnWidth` | `number` |\n| `row-height` | `rowHeight` | `number` |\n| `look` | `look` | `'excel' \\| 'theme'` |\n| `comment-author` | `commentAuthor` | `string` |\n| `show-ribbon` | `showRibbon` | `boolean` |\n| `show-formula-bar` | `showFormulaBar` | `boolean` |\n| `show-tabs` | `showTabs` | `boolean` |\n| `show-status-bar` | `showStatusBar` | `boolean` |\n\n### Properties only (9)\n\nArrays, objects and functions. An HTML attribute is a string, so these can\nonly be assigned in script: `el.document = doc`.\n\n| Property | Type |\n| --- | --- |\n| `document` | `SheetDocument` |\n| `workbook` | `Workbook` |\n| `data` | `ReadonlyArray<SheetData>` |\n| `gridSheets` | `Record<string, GridSheetSpec>` |\n| `columnWidths` | `Readonly<Record<string, number>>` |\n| `formats` | `Readonly<Record<string, CellFormatEntry>>` |\n| `extras` | `ReadonlyArray<'insert-table' \\| 'insert-chart'>` |\n| `localization` | `SheetLocalization` |\n| `presence` | `ReadonlyArray<SheetPresence>` |\n\n### Events (5)\n\n`detail` is the callback's argument, or an object keyed by the parameter names\nwhen it takes more than one. `action` is cancelable: `event.preventDefault()`\ntakes the action over, as returning `true` from `onAction` does.\n\n| Event | From | `detail` |\n| --- | --- | --- |\n| `action` | `onAction` | `{ action, cmd }` |\n| `cellaction` | `onCellAction` | `event` |\n| `ready` | `onReady` | `{ api, document }` |\n| `change` | `onChange` | `reasons` |\n| `presence` | `onPresence` | `me` |\n\n### Methods (12)\n\nThe component's own, on the element once `ready` has fired.\n\n| Method | What it does |\n| --- | --- |\n| `getState(): SheetState` | The document as plain JSON. |\n| `setState(state: SheetState): void` | Put a saved document back. |\n| `refresh(): void` | Repaint after a write the shell could not see. |\n| `act(action: RibbonActionId): void` | Run a ribbon action as if its button had been clicked. |\n| `open(file: Blob & { name?: string }): Promise<void>` | Replace the document with an .xlsx, .ods or .csv file. |\n| `toXlsx(): Promise<Blob>` | The document as an .xlsx Blob. |\n| `toOds(): Promise<Blob>` | The document as an .ods Blob, which LibreOffice Calc opens. |\n| `toXls(): Blob` | The document as an .xls Blob, which Excel 97-2003 opens. |\n| `toCsv(): string` | The active sheet as CSV. |\n| `newWorkbook(): void` | Start over with one empty sheet. |\n| `print(): void` | The active sheet in the print dialog. |\n| `printHtml(): string` | The page File > Print would open. |\n\n<!-- END generated reference -->\n\n## What it does not carry\n\nSvelte snippets cannot cross the custom-element boundary, and `<SvSheet>`\nhas none in its props, so nothing is left out. What the element cannot do\nis what the component cannot: see [the shell page](../cells/spreadsheet-shell.md#what-it-does-not-do).\n\n## See also\n\n- [The spreadsheet shell](../cells/spreadsheet-shell.md), the component\n behind the element: its ribbon, dialogs, document and files.\n- [Enterprise features from the element](enterprise.md), for the export,\n import, print and pivot entries that work beside `<sv-grid>`.\n"
7332
7339
  },
7333
7340
  {
7334
7341
  "slug": "help/web-components/typescript",
@@ -8448,8 +8455,8 @@ export const apiReference = {
8448
8455
  ]
8449
8456
  };
8450
8457
  export const apiSurface = {
8451
- "gridVersion": "3.0.22",
8452
- "enterpriseVersion": "3.1.25",
8458
+ "gridVersion": "3.0.23",
8459
+ "enterpriseVersion": "3.1.26",
8453
8460
  "grid": {
8454
8461
  "values": [
8455
8462
  "ALL_FILTER_OPERATORS",