@svgrid/enterprise 3.0.2 → 3.1.0

package/dist/sources/rest.js

@@ -1,5 +1,5 @@
 import { resolveIdField } from '../schema.js';
-import { nudgeEnterprise } from '../license.js';
+import { nudgeEnterpriseFor } from '../license.js';
 import { normalizeFilters } from './filters.js';
 const encodePredicate = (p) => {
     if (p.op === 'in')
@@ -48,22 +48,57 @@ function defaultBuildQuery(request) {
         if (aggs.length)
             params.aggregate = aggs.map((a) => `${a.fn}:${a.col}`).join(',');
     }
+    // The grid wants a grand-total row it does not have yet. An endpoint that
+    // supports it answers with `grandTotal` in the body (the aggregates over
+    // the filtered set, path excluded); one that does not simply ignores the
+    // flag and the grid shows no total. The aggregate list is sent either
+    // way, so a leaf-level request still says what to total.
+    if (request.needsGrandTotal) {
+        params.grandTotal = '1';
+        const aggs = request.aggregations ?? [];
+        if (aggs.length && !params.aggregate)
+            params.aggregate = aggs.map((a) => `${a.fn}:${a.col}`).join(',');
+    }
+    // Pivot: the columns whose values become fields, on a grouped request.
+    // The endpoint answers with the pivoted fields on each group row and
+    // lists them in `pivotResultFields`; see the SQL source for the shape.
+    //
+    //   ?groupBy=region&aggregate=sum:amount&pivot=year,quarter
+    if (request.pivotMode && request.pivotBy?.length && params.groupBy) {
+        params.pivot = request.pivotBy.join(',');
+    }
     return params;
 }
-function defaultParse(body, response) {
+/**
+ * The count when the API sent none: a short block is the last one, so the
+ * end is known; a full block says nothing, so the count is unknown (`-1`)
+ * and an infinite-scrolling grid discovers the end from a later short
+ * block. Claiming `rows.length` would tell a pager there is one page.
+ */
+function countWithoutTotal(rows, request) {
+    const asked = Math.max(1, request.endRow - request.startRow);
+    return rows.length < asked ? request.startRow + rows.length : -1;
+}
+function defaultParse(body, response, request) {
     if (Array.isArray(body)) {
         // Total from a Content-Range header (`items 0-9/240`) when present.
         const range = response.headers.get('content-range');
         const total = range && /\/(\d+)\s*$/.exec(range);
-        return { rows: body, rowCount: total ? Number(total[1]) : body.length };
+        return { rows: body, rowCount: total ? Number(total[1]) : countWithoutTotal(body, request) };
     }
     const b = (body ?? {});
+    // `grandTotal` rides along in an envelope body when the endpoint answered
+    // the request for one. Absent means "keep what you have", `null` means
+    // "there is none" - the same three-way contract as ServerResult.
+    const grandTotal = 'grandTotal' in b ? { grandTotal: (b.grandTotal ?? null) } : {};
     const rows = (b.rows ?? b.data ?? b.items ?? []);
-    const rowCount = Number(b.rowCount ?? b.total ?? b.count ?? rows.length);
-    return { rows, rowCount };
+    const declared = b.rowCount ?? b.total ?? b.count;
+    const rowCount = declared == null ? countWithoutTotal(rows, request) : Number(declared);
+    const pivot = Array.isArray(b.pivotResultFields) ? { pivotResultFields: b.pivotResultFields } : {};
+    return { rows, rowCount, ...grandTotal, ...pivot };
 }
 export function createRestDataSource(config) {
-    nudgeEnterprise('Studio'); // soft-gate; never blocks
+    nudgeEnterpriseFor('studio', 'Studio'); // evaluation nudge; never blocks
     const doFetch = config.fetch ?? globalThis.fetch;
     const idField = config.idField ?? (config.schema ? resolveIdField(config.schema) : 'id');
     const base = config.url.replace(/\/+$/, '');
@@ -86,7 +121,7 @@ export function createRestDataSource(config) {
             const qs = new URLSearchParams({ ...config.query, ...buildQuery(request) }).toString();
             const url = qs ? `${base}?${qs}` : base;
             const { body, res } = (await send(url, { headers: headers() }));
-            return parse(body, res);
+            return parse(body, res, request);
         },
         async createRow(input) {
             const { body } = (await send(base, {

package/dist/sources/supabase.d.ts

@@ -12,7 +12,7 @@
  * with `searchColumns`. The primary key comes from the schema (`idField`) and is
  * stripped from inserts (it's database-generated).
  */
-import type { RowData } from '@svgrid/grid';
+import type { RowData, ServerRequest, ServerResult } from '@svgrid/grid';
 import { type EntitySchema } from '../schema.js';
 import type { WritableDataSource } from '../sveltekit/types.js';
 /** The slice of a `supabase-js` client this adapter needs. */
@@ -29,5 +29,14 @@ export type SupabaseDataSourceConfig<TData extends RowData> = {
      * schema's text + enum fields.
      */
     searchColumns?: string[];
+    /**
+     * Server-side pivot. PostgREST has no way to turn values into columns, so
+     * a pivoted request (`pivotMode` with `pivotBy`) goes to this function
+     * instead - typically an RPC (`client.rpc(...)`) that returns the group
+     * rows with one field per (pivot key x aggregation) and lists them in
+     * `pivotResultFields`; the SQL source documents the shape. Without it a
+     * pivoted request is answered as plain grouping, with a warning once.
+     */
+    pivot?: (request: ServerRequest) => Promise<ServerResult<TData>>;
 };
 export declare function createSupabaseDataSource<TData extends RowData>(config: SupabaseDataSourceConfig<TData>): WritableDataSource<TData>;

package/dist/sources/supabase.js

@@ -1,15 +1,27 @@
 import { resolveIdField } from '../schema.js';
-import { nudgeEnterprise } from '../license.js';
+import { nudgeEnterpriseFor } from '../license.js';
 import { normalizeFilters } from './filters.js';
 const sanitize = (term) => term.replace(/[%,()]/g, '');
 export function createSupabaseDataSource(config) {
-    nudgeEnterprise('Studio'); // soft-gate; never blocks
+    nudgeEnterpriseFor('studio', 'Studio'); // evaluation nudge; never blocks
     const { client, table, schema } = config;
     const idField = resolveIdField(schema);
     const searchColumns = config.searchColumns ??
         schema.fields.filter((f) => f.type === 'text' || f.type === 'enum').map((f) => String(f.field));
+    let warnedPivot = false;
     return {
         async getRows(request) {
+            // ---- Server-side pivot ----------------------------------------------
+            // Only a grouped level pivots; the leaves under a path do not.
+            const grouped = (request.groupKeys?.length ?? 0) < (request.groupBy?.length ?? 0);
+            if (grouped && request.pivotMode && request.pivotBy?.length) {
+                if (config.pivot)
+                    return config.pivot(request);
+                if (!warnedPivot) {
+                    warnedPivot = true;
+                    console.warn('[svgrid] createSupabaseDataSource: a pivoted request needs the `pivot` option (an RPC that pivots); answering it as plain grouping.');
+                }
+            }
             // ---- Server-side grouping -------------------------------------------
             // The grid asks one level at a time. The already-chosen path becomes
             // ordinary `.eq()` filters below; at this level we ask PostgREST for the
@@ -26,50 +38,61 @@ export function createSupabaseDataSource(config) {
             const groupCols = request.groupBy ?? [];
             const groupKeys = request.groupKeys ?? [];
             const groupField = groupKeys.length < groupCols.length ? groupCols[groupKeys.length] : undefined;
+            const aggregateSelects = (request.aggregations ?? []).map((a) => a.fn === 'count' ? `${a.col}:count()` : `${a.col}:${a.col}.${a.fn}()`);
+            // The innermost group level can say how many rows each group holds
+            // (a plain count). Higher levels would need COUNT(DISTINCT next),
+            // which PostgREST does not expose, so those group rows carry no
+            // childCount and the grid shows no badge for them.
+            const innermost = groupField != null && groupKeys.length === groupCols.length - 1;
             const selectExpr = groupField
-                ? [
-                    groupField,
-                    ...(request.aggregations ?? []).map((a) => a.fn === 'count' ? `${a.col}:count()` : `${a.col}:${a.col}.${a.fn}()`),
-                ].join(',')
+                ? [groupField, ...aggregateSelects, ...(innermost ? ['childCount:count()'] : [])].join(',')
                 : '*';
             let q = client.from(table).select(selectExpr, { count: 'exact' });
+            // The filters are applied to two queries when a grand total was asked
+            // for: the level itself (below, with the group path) and the total
+            // (the filters alone). Build them once.
+            const applyFilters = (query) => {
+                let out = query;
+                const { predicates, search } = normalizeFilters(request.filterModel);
+                for (const p of predicates) {
+                    switch (p.op) {
+                        case 'in':
+                            out = out.in(p.column, p.values);
+                            break;
+                        case 'contains':
+                            out = out.ilike(p.column, `%${p.value}%`);
+                            break;
+                        case 'startsWith':
+                            out = out.ilike(p.column, `${p.value}%`);
+                            break;
+                        case 'eq':
+                            out = out.eq(p.column, p.value);
+                            break;
+                        case 'gt':
+                            out = out.gt(p.column, p.value);
+                            break;
+                        case 'lt':
+                            out = out.lt(p.column, p.value);
+                            break;
+                        case 'between':
+                            out = out.gte(p.column, p.value).lte(p.column, p.valueTo);
+                            break;
+                        case 'isNull':
+                            out = out.is(p.column, null);
+                            break;
+                    }
+                }
+                if (search && searchColumns.length) {
+                    const term = sanitize(search);
+                    out = out.or(searchColumns.map((c) => `${c}.ilike.%${term}%`).join(','));
+                }
+                return out;
+            };
             // The path constrains the rows before grouping.
             for (let i = 0; i < groupKeys.length && i < groupCols.length; i += 1) {
                 q = q.eq(groupCols[i], groupKeys[i]);
             }
-            const { predicates, search } = normalizeFilters(request.filterModel);
-            for (const p of predicates) {
-                switch (p.op) {
-                    case 'in':
-                        q = q.in(p.column, p.values);
-                        break;
-                    case 'contains':
-                        q = q.ilike(p.column, `%${p.value}%`);
-                        break;
-                    case 'startsWith':
-                        q = q.ilike(p.column, `${p.value}%`);
-                        break;
-                    case 'eq':
-                        q = q.eq(p.column, p.value);
-                        break;
-                    case 'gt':
-                        q = q.gt(p.column, p.value);
-                        break;
-                    case 'lt':
-                        q = q.lt(p.column, p.value);
-                        break;
-                    case 'between':
-                        q = q.gte(p.column, p.value).lte(p.column, p.valueTo);
-                        break;
-                    case 'isNull':
-                        q = q.is(p.column, null);
-                        break;
-                }
-            }
-            if (search && searchColumns.length) {
-                const term = sanitize(search);
-                q = q.or(searchColumns.map((c) => `${c}.ilike.%${term}%`).join(','));
-            }
+            q = applyFilters(q);
             // When grouping, only columns the grouped select actually produces can be
             // ordered on - PostgREST rejects an ORDER BY over a column that is
             // neither grouped nor aggregated. Fall back to the group key so the
@@ -95,7 +118,17 @@ export function createSupabaseDataSource(config) {
             const { data, count, error } = await q.range(request.startRow, request.endRow - 1);
             if (error)
                 throw new Error(error.message);
-            return { rows: (data ?? []), rowCount: count ?? 0 };
+            const result = { rows: (data ?? []), rowCount: count ?? 0 };
+            // The grand total: one aggregate-only select over the filtered set,
+            // with no group column (so PostgREST returns a single row) and no path.
+            if (request.needsGrandTotal && aggregateSelects.length) {
+                const total = applyFilters(client.from(table).select(aggregateSelects.join(',')));
+                const { data: totalRows, error: totalError } = await total;
+                if (totalError)
+                    throw new Error(totalError.message);
+                result.grandTotal = (totalRows?.[0] ?? null);
+            }
+            return result;
         },
         async createRow(input) {
             const rest = { ...input };

package/dist/studio/emit-project.js

@@ -478,6 +478,17 @@ ${panels}
             // Dragging a card updates its groupBy value in the local row state (optimistic).
             return `    <div ${wrapperStyle(block)}${cls}>
       <SvBoard schema={${schemaVar}} rows={allRows} loading={!allRowsReady} groupBy=${JSON.stringify(cfg.groupBy)} titleField=${JSON.stringify(asText(cfg.titleField))}${badge}${sub}${onOpen} height={${h}} onMove={(id, value) => { allRows = allRows.map((r) => String((r as Record<string, unknown>)[idField]) === String(id) ? ({ ...r, ['${cfg.groupBy}']: value }) : r) }} />
+    </div>`;
+        }
+        case 'sheet': {
+            const h = block.height ?? 480;
+            // The shell reads `data` once at mount, so it mounts once the rows are in.
+            const chosen = cfg.fields?.length ? cfg.fields : entity.fields.map((f) => f.field);
+            const specs = chosen.map((field) => ({ field, label: entity.fields.find((f) => f.field === field)?.label ?? field }));
+            // Excel's sheet-name rules: none of []:*?/\ and at most 31 characters.
+            const sheetName = (entity.label ?? entity.name).replace(/[[\]:*?/\\]/g, ' ').trim().slice(0, 31) || 'Sheet1';
+            return `    <div ${wrapperStyle(block, `min-height: ${h}px`)}${cls}>
+      {#if allRowsReady}<SvSheet data={[{ name: ${JSON.stringify(sheetName)}, cells: sheetCellsFromRows(${rowsExpr}, ${JSON.stringify(specs)}, { totals: ${cfg.totals ? 'true' : 'false'} }) }]} height={${h}} />{/if}
     </div>`;
         }
         case 'calendar': {
@@ -1981,7 +1992,7 @@ function screenPage(schema, rawSchema, screen, resolve, rawResolve, accessEnable
     const exportApiVars = blocks.filter((b) => b.config.kind === 'grid' && gridHasExport(b.config) && !(codeGrid && b.id === codeGridBlockId)).map((b) => `gridApi_${b.id.replace(/-/g, '_')}`);
     const needsGridApiType = codeGrid || exportApiVars.length > 0;
     // The pivot reads the whole table (like charts / dashboards).
-    const needsAllRows = hasAgg || hasMD || hasPivot || hasBoundComponent || hasGroupedGrid || hasTreeGrid || hasSchedulerGrid || has(allBlocks, 'board') || has(allBlocks, 'calendar') || has(allBlocks, 'detail');
+    const needsAllRows = hasAgg || hasMD || hasPivot || hasBoundComponent || hasGroupedGrid || hasTreeGrid || hasSchedulerGrid || has(allBlocks, 'board') || has(allBlocks, 'calendar') || has(allBlocks, 'detail') || has(allBlocks, 'sheet');
     // --- imports ---
     const gridSpecs = [];
     if (needsController)
@@ -2030,6 +2041,8 @@ function screenPage(schema, rawSchema, screen, resolve, rawResolve, accessEnable
         entImports.push('schemaToColumns');
     if (has(allBlocks, 'detail'))
         entImports.push('SvRecordDetail');
+    if (has(allBlocks, 'sheet'))
+        entImports.push('SvSheet', 'sheetCellsFromRows');
     if (has(allBlocks, 'kpi') || has(allBlocks, 'gauge') || hasAggregateBinding)
         entImports.push('reduceValue');
     const kpiCfgs = allBlocks.filter((b) => b.config.kind === 'kpi').map((b) => b.config);

package/dist/studio/index.js

@@ -36,6 +36,6 @@ export { resolveDeployTarget, deployCommands, missingEnvKeys, } from './deploy-c
 export { runStudioAdd, runStudioAddApp, resolveSchema, resolveSchemas, } from './cli.js';
 // Re-export the schema surface so consumers get everything from one entry.
 export { resolveIdField, schemaToColumns, schemaToFormFields, isFieldHidden, linkRelationLabels, pickLabelField, } from '../schema.js';
-// Pure license classification, so the Node/MCP generator can soft-gate with the
+// Pure license classification, so the Node/MCP generator can nudge with the
 // same rules as the browser (see license-core.ts). No DOM, safe in Node.
 export { checkLicenseKey } from '../license-core.js';

package/dist/studio/project.d.ts

@@ -95,7 +95,7 @@ export type EntityDataSource = MemorySource | RestSource | SqlSource | SupabaseS
 /** The kinds of block a screen can hold: data-bound (entity-derived) or the
  *  entity-agnostic `'component'` (a UI-kit component from `UI_COMPONENT_REGISTRY`,
  *  usable on any screen, including a freestanding one with no entity). */
-export type BlockKind = 'grid' | 'form' | 'chart' | 'dashboard' | 'kpi' | 'gauge' | 'tree' | 'tabs' | 'accordion' | 'master-detail' | 'lookup' | 'pivot' | 'filter' | 'record' | 'board' | 'calendar' | 'detail' | 'component';
+export type BlockKind = 'grid' | 'form' | 'chart' | 'dashboard' | 'kpi' | 'gauge' | 'tree' | 'tabs' | 'accordion' | 'master-detail' | 'lookup' | 'pivot' | 'filter' | 'record' | 'board' | 'calendar' | 'detail' | 'sheet' | 'component';
 export type GridAlign = 'left' | 'center' | 'right';
 /** No-code per-column value formatting. Compiles to the grid's `format` (CellFormatConfig):
  *  a raw `1234.5` becomes `$1,234.50` / `42%` / `Jun 27, 2026` without a code renderer. */
@@ -516,6 +516,15 @@ export type DetailConfig = {
     }[];
     related?: DetailRelated[];
 };
+/** The entity's rows on the spreadsheet shell (SvSheet): a header row of field
+ *  labels, a row per record, and, with `totals`, a SUM row under every numeric
+ *  column. `fields` narrows and orders the columns (empty = every field). The
+ *  sheet is Excel over the dataset: formulas, formats, filters and an xlsx out. */
+export type SheetConfig = {
+    kind: 'sheet';
+    fields?: string[];
+    totals?: boolean;
+};
 /** A UI-kit component (from `UI_COMPONENT_REGISTRY`, keyed by `component`) dropped
  *  onto a screen. Entity-agnostic - works on a freestanding page or mixed onto an
  *  entity-bound screen alike. `props` holds its configured "chrome" values, keyed
@@ -543,7 +552,7 @@ export type ComponentConfig = {
     name?: string;
     bindings?: Record<string, ComponentBinding>;
 };
-export type BlockConfig = GridConfig | FormConfig | ChartConfig | KpiConfig | GaugeConfig | TreeConfig | TabsConfig | AccordionConfig | DashboardConfig | MasterDetailConfig | LookupConfig | PivotConfig | FilterPanelConfig | RecordConfig | BoardConfig | CalendarConfig | DetailConfig | ComponentConfig;
+export type BlockConfig = GridConfig | FormConfig | ChartConfig | KpiConfig | GaugeConfig | TreeConfig | TabsConfig | AccordionConfig | DashboardConfig | MasterDetailConfig | LookupConfig | PivotConfig | FilterPanelConfig | RecordConfig | BoardConfig | CalendarConfig | DetailConfig | SheetConfig | ComponentConfig;
 /** Block kinds allowed inside a Tabs / Accordion container: the controller-free,
  *  `allRows`-driven display blocks (no grid / form / master-detail, which need the
  *  screen controller). `component` covers any UI-kit component added by key. */

package/dist/studio/project.js

@@ -432,6 +432,7 @@ export const blockPalette = [
     { kind: 'board', label: 'Board' },
     { kind: 'calendar', label: 'Calendar' },
     { kind: 'detail', label: 'Detail page' },
+    { kind: 'sheet', label: 'Spreadsheet' },
     { kind: 'filter', label: 'Filter panel' },
     { kind: 'record', label: 'Record panel' },
     { kind: 'lookup', label: 'Lookup' },
@@ -538,6 +539,8 @@ export function defaultBlockConfig(kind, entity) {
             const metrics = nonKey.filter((f) => f.type === 'number').slice(0, 3).map((f) => f.field);
             return { kind, titleField: titleF, ...(subF ? { subtitleField: subF } : {}), ...(statusF ? { statusField: statusF } : {}), ...(metrics.length ? { metricFields: metrics } : {}) };
         }
+        case 'sheet':
+            return { kind, totals: entity.fields.some((f) => f.type === 'number' && !f.primaryKey) };
         case 'component':
             // Entity-agnostic - built directly by `addComponentBlock`, never through here.
             return { kind, component: '', props: {} };
@@ -554,7 +557,7 @@ export function pickFacetFields(entity) {
 }
 const facetRank = (t) => (t === 'enum' ? 0 : t === 'boolean' ? 1 : 2);
 const DEFAULT_SPAN = {
-    grid: 3, form: 1, chart: 2, dashboard: 3, kpi: 1, gauge: 1, tree: 2, tabs: 3, accordion: 3, 'master-detail': 3, lookup: 1, pivot: 3, filter: 1, record: 1, board: 3, calendar: 3, detail: 3, component: 1,
+    grid: 3, form: 1, chart: 2, dashboard: 3, kpi: 1, gauge: 1, tree: 2, tabs: 3, accordion: 3, 'master-detail': 3, lookup: 1, pivot: 3, filter: 1, record: 1, board: 3, calendar: 3, detail: 3, sheet: 3, component: 1,
 };
 function makeBlock(kind, entity, taken) {
     return { id: uid(`${kind}-`, taken), span: DEFAULT_SPAN[kind], config: defaultBlockConfig(kind, entity) };
@@ -1249,7 +1252,7 @@ function dockPaneTitle(block) {
         grid: 'Grid', form: 'Form', chart: 'Chart', dashboard: 'Dashboard', tree: 'Tree', pivot: 'Pivot',
         filter: 'Filters', record: 'Record', detail: 'Detail', board: 'Board', calendar: 'Calendar',
         'master-detail': 'Master / detail', lookup: 'Lookup', tabs: 'Tabs', accordion: 'Accordion',
-        kpi: 'KPI', gauge: 'Gauge', component: 'Component',
+        kpi: 'KPI', gauge: 'Gauge', sheet: 'Spreadsheet', component: 'Component',
     };
     return c.label || c.title || c.name || c.component || byKind[c.kind] || 'Panel';
 }

package/dist/studio/ui-components.generated.js

@@ -6583,6 +6583,7 @@ export const GENERATED_UI_SURFACE = {
                 "key": "data",
                 "label": "Data",
                 "type": "json",
+                "description": "The rows to render. Optional only because `rowModel` can supply them instead; a grid with neither renders empty. When both are present `data` wins.",
                 "group": "common"
             },
             {
@@ -6605,6 +6606,13 @@ export const GENERATED_UI_SURFACE = {
                 "description": "Scheduler / calendar mode. When set, the grid renders its rows as events on a Month / Week / Day / Agenda calendar instead of a table. See .",
                 "group": "common"
             },
+            {
+                "key": "gantt",
+                "label": "Gantt",
+                "type": "json",
+                "description": "Gantt mode. When set, the grid renders its rows as a task table beside a time chart: one bar per row by start / end, a work-breakdown tree from `parentField`, and dependency arrows. See . A view of the grid like the board and scheduler; the renderer ships in `@svgrid/enterprise` (call `enableGanttView()`).",
+                "group": "common"
+            },
             {
                 "key": "chart",
                 "label": "Chart",
@@ -7036,6 +7044,14 @@ export const GENERATED_UI_SURFACE = {
                 "code": true,
                 "group": "advanced"
             },
+            {
+                "key": "includeCollapsedRows",
+                "label": "Include Collapsed Rows",
+                "type": "json",
+                "description": "Whether a collapsed row still takes part in a copy or a fill that spans it. Left out, both skip every collapsed row, which is what \"filter, copy, paste\" needs and what a fill dragged over a filtered list expects: the series runs over the rows that show. A spreadsheet answers per row: a row hidden by hand is copied and filled, as Excel does, while a row a filter folded away is not.",
+                "code": true,
+                "group": "advanced"
+            },
             {
                 "key": "clipboardHtml",
                 "label": "Clipboard Html",
@@ -7244,6 +7260,34 @@ export const GENERATED_UI_SURFACE = {
                 "description": "Which rows feed the min/max range that `colorScale` / `dataBar` formats scale against. - `filtered` (default): every row that survives the filters, ignoring the page slice. The scale follows what you filtered to but does not shift when you page, so the same value keeps the same colour on page 1 and page 2. - `visible`: only the rows currently on screen. Rescales per page - use it when you want each page's heat map normalized to that page. - `all`: the full unfiltered dataset, for a scale that stays put as you filter.",
                 "group": "common"
             },
+            {
+                "key": "rowPlaceholder",
+                "label": "Row Placeholder",
+                "type": "json",
+                "description": "Marks a row as one whose data has not arrived: `\"loading\"` draws a shimmer in every cell, `\"failed\"` draws a full-width \"could not load\" row with a Retry button, and `null` (the default for every row) renders normally. Placeholder rows are inert - not selectable, not editable, and skipped by cell navigation - because there is nothing there to act on yet. `createServerDataSource` in `infinite` mode fills the gaps with rows this recognises, so the usual wiring is `rowPlaceholder={rowPlaceholderState}` (or nothing at all, via `rowModel`).",
+                "code": true,
+                "group": "advanced"
+            },
+            {
+                "key": "rowModel",
+                "label": "Row Model",
+                "type": "json",
+                "description": "Drive the grid from a row model instead of wiring a dozen props. `createServerDataSource` returns one, and so does the Enterprise server-side row model, so server-backed grids become: ```svelte <SvGrid rowModel={ctl} {columns} /> ``` The model supplies `data`, `loading`, `getRowId`, the external sort and filter wiring, the visible range, placeholder rows, group accessors, selection and paging - each one only if it implements that part. A prop written explicitly on the grid always wins, so you can adopt it and still override one piece.",
+                "group": "common"
+            },
+            {
+                "key": "pivotResultColumns",
+                "label": "Pivot Result Columns",
+                "type": "json",
+                "description": "Columns that REPLACE `columns` while set. The server-side row model supplies them in pivot mode - one column per pivoted value, grouped under a header per pivot key - and clears them when pivot mode ends, so `columns` stays the app's own list. Rarely set by hand.",
+                "group": "common"
+            },
+            {
+                "key": "rowSelectionModel",
+                "label": "Row Selection Model",
+                "type": "json",
+                "group": "common"
+            },
             {
                 "key": "isDetailRow",
                 "label": "Is Detail Row",
@@ -7252,11 +7296,41 @@ export const GENERATED_UI_SURFACE = {
                 "code": true,
                 "group": "advanced"
             },
+            {
+                "key": "detailRowHeight",
+                "label": "Detail Row Height",
+                "type": "number",
+                "description": "The height of a detail row, in px, or a function of its data. With it the virtualizer can size detail rows, so master-detail works with `virtualization` on (the panel scrolls inside its cell when taller). Without it a detail row is auto height, which needs `virtualization={false}`.",
+                "group": "common"
+            },
+            {
+                "key": "showDetailToggle",
+                "label": "Show Detail Toggle",
+                "type": "boolean",
+                "description": "A row-header column of chevrons that open and close detail rows. It sits with the row-number and selection columns: sticky at the left, no column menu, not resizable, not reorderable, outside the active cell and the selection. The chevron calls `onDetailToggle` (or, on a server row model, the model's own toggle) and reads `isDetailOpen` for its direction; `hasDetail` hides it on rows that have nothing to open. Detail rows themselves get an empty cell.",
+                "group": "common"
+            },
+            {
+                "key": "isDetailOpen",
+                "label": "Is Detail Open",
+                "type": "json",
+                "description": "Whether the detail under a row is open: the chevron's direction and `aria-expanded`.",
+                "code": true,
+                "group": "advanced"
+            },
+            {
+                "key": "hasDetail",
+                "label": "Has Detail",
+                "type": "json",
+                "description": "Whether a row has a detail to open; the chevron is left out where this returns false.",
+                "code": true,
+                "group": "advanced"
+            },
             {
                 "key": "serverGroup",
                 "label": "Server Group",
                 "type": "json",
-                "description": "Server-side group / tree keyboard + accessibility, built into the grid. When set, the grid uses the treegrid role and marks matching rows with `aria-level` / `aria-expanded`, and ArrowRight / ArrowLeft expand / collapse the focused group row (no app-level key handling). Pair with `serverGroupRows` + `SvGroupCell` for the visual expander. Every accessor receives the row data.",
+                "description": "Server-side group / tree keyboard + accessibility, built into the grid. When set, the grid uses the treegrid role and marks matching rows with `aria-level` / `aria-expanded`, and ArrowRight / ArrowLeft expand / collapse the focused group row (no app-level key handling). Pair with `serverGroupRows` + `SvGroupCell` from `@svgrid/enterprise` for the visual expander, or drive it from your own tree state. Every accessor receives the row data.",
                 "group": "common"
             },
             {
@@ -7281,6 +7355,13 @@ export const GENERATED_UI_SURFACE = {
                 "description": "Freeze the first N rows: they stay under the header while the body scrolls, and unlike `pinnedTopRows` they are the grid's own rows, still editable, selectable and numbered as rows 1..N. Excel's Freeze Panes, for the row half; the column half is `columnPinning`. Under `virtualization` the frozen rows are always rendered and the window skips them.",
                 "group": "common"
             },
+            {
+                "key": "stickyGroupRows",
+                "label": "Sticky Group Rows",
+                "type": "boolean",
+                "description": "Keep the group a row belongs to in view: while the rows of an open group scroll past, the group's row (and its parents' rows) stay under the header, the way a section heading stays put in a long list, so a screen deep inside a 60,000-row group still says which group it is. Works for server-side groups (`rowModel` / `serverGroup`), client grouping and tree data. Under `virtualization` the band shows a copy of each ancestor row; without it the rows themselves stick. Off by default.",
+                "group": "common"
+            },
             {
                 "key": "mergedCells",
                 "label": "Merged Cells",
@@ -7398,7 +7479,7 @@ export const GENERATED_UI_SURFACE = {
                 "key": "cellSelectionChange",
                 "label": "Cell Selection Change",
                 "prop": "onCellSelectionChange",
-                "description": "Fires whenever the cell-selection rectangle changes (mouse, keyboard, or `api.selectCells()`). `ranges` matches `api.getSelected()` - `[rowStart, colStart, rowEnd, colEnd]` rectangles in grid coords. Empty array when the user clears the selection."
+                "description": "Fires whenever the cell selection changes (mouse, keyboard, or `api.selectCells()`). `ranges` is every selected rectangle, matching `api.getSelected()`: the ones a Ctrl+click committed and the active one last, each `[rowStart, colStart, rowEnd, colEnd]` in grid coords. Empty array when the user clears the selection."
             },
             {
                 "key": "sortingChange",
@@ -7466,6 +7547,24 @@ export const GENERATED_UI_SURFACE = {
                 "prop": "onScrollBottomReached",
                 "description": "Fires once each time the body is scrolled to (within ~32px of) the bottom. Re-arms after the user scrolls back up. The canonical hook for infinite / lazy loading - append more rows to `data` when it fires."
             },
+            {
+                "key": "visibleRangeChange",
+                "label": "Visible Range Change",
+                "prop": "onVisibleRangeChange",
+                "description": "Fires when the range of rows on screen changes, with the first and last row INDEX (not pixels). Coalesced to one call per frame, so it is cheap to wire to something that fetches. This is the hook a block-loading data source needs and `onScrollBottomReached` cannot give it: \"the user is looking at rows 4,000-4,020\" answers which block to fetch and which to keep, while \"they hit the bottom\" only ever means \"append more\". Both are free; use this one with `createServerDataSource({ mode: 'infinite' })`, or let `rowModel` wire it for you. Reports `0, data.length - 1` when virtualization is off, since every row really is rendered."
+            },
+            {
+                "key": "retryRow",
+                "label": "Retry Row",
+                "prop": "onRetryRow",
+                "description": "Called by the Retry button on a `\"failed\"` placeholder row."
+            },
+            {
+                "key": "detailToggle",
+                "label": "Detail Toggle",
+                "prop": "onDetailToggle",
+                "description": "Open or close the detail under a row. The chevron of `showDetailToggle` and Ctrl+Enter on a row call it; you keep the open set and insert or remove the detail row in `data`. A server row model supplies its own (the `rowModel` prop wires `toggleDetail`), so this is the client side."
+            },
             {
                 "key": "columnOrderChange",
                 "label": "Column Order Change",
@@ -7477,6 +7576,12 @@ export const GENERATED_UI_SURFACE = {
                 "label": "Row Drag End",
                 "prop": "onRowDragEnd",
                 "description": "Fires on the TARGET grid after a managed row drag settles, with the moved row, its landing index, whether it stayed in the same grid, and the source / target grid ids. Use it to mirror the move into your own state (persistence, server sync). The grid has already applied the change to its internal data by the time this fires."
+            },
+            {
+                "key": "rowDrop",
+                "label": "Row Drop",
+                "prop": "onRowDrop",
+                "description": "Take the drop yourself. With this set the grid keeps the drag affordance and the drop indicator but does not touch its data: the handler gets the dragged row, the row it landed on (null for the empty space below the rows) and the side - `before` / `after`, or `into` when it landed on the middle of a group or tree row, which makes it that row's child. The path for a `rowModel`, whose rows the grid does not own: hand the move to the model (`moveRow`) or to your server. Only fires within one grid; a drop from another grid stays managed."
             }
         ]
     }

package/dist/sveltekit/in-memory.d.ts

@@ -5,10 +5,10 @@
  * do, and is genuinely useful on its own for small datasets, tests, demos,
  * and prototyping a schema before a database exists behind it.
  */
-import type { RowData } from '@svgrid/grid';
+import type { RowData, ServerDataSource } from '@svgrid/grid';
 import { type EntitySchema } from '../schema.js';
 import type { WritableDataSource } from './types.js';
 import { type AggregateSource } from '../sources/aggregate.js';
-export declare function createInMemoryDataSource<TData extends RowData>(initial: ReadonlyArray<TData>, schema: EntitySchema<TData>): WritableDataSource<TData> & AggregateSource & {
+export declare function createInMemoryDataSource<TData extends RowData>(initial: ReadonlyArray<TData>, schema: EntitySchema<TData>): WritableDataSource<TData> & Required<Pick<ServerDataSource<TData>, 'updateWhere'>> & AggregateSource & {
     rows(): ReadonlyArray<TData>;
 };