@svgrid/enterprise 3.0.2 → 3.0.3

package/dist/node/studio.js

@@ -8511,6 +8511,7 @@ var 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"
 			},
 			{
@@ -8533,6 +8534,13 @@ var 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",
@@ -8964,6 +8972,14 @@ var 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",
@@ -9169,6 +9185,34 @@ var 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",
@@ -9177,11 +9221,41 @@ var 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"
 			},
 			{
@@ -9206,6 +9280,13 @@ var 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",
@@ -9323,7 +9404,7 @@ var 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",
@@ -9391,6 +9472,24 @@ var 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",
@@ -9402,6 +9501,12 @@ var 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."
 			}
 		]
 	}
@@ -12148,6 +12253,10 @@ var blockPalette = [
 		kind: "detail",
 		label: "Detail page"
 	},
+	{
+		kind: "sheet",
+		label: "Spreadsheet"
+	},
 	{
 		kind: "filter",
 		label: "Filter panel"
@@ -12339,6 +12448,10 @@ function defaultBlockConfig(kind, entity) {
 				...metrics.length ? { metricFields: metrics } : {}
 			};
 		}
+		case "sheet": return {
+			kind,
+			totals: entity.fields.some((f) => f.type === "number" && !f.primaryKey)
+		};
 		case "component": return {
 			kind,
 			component: "",
@@ -12370,6 +12483,7 @@ var DEFAULT_SPAN = {
 	board: 3,
 	calendar: 3,
 	detail: 3,
+	sheet: 3,
 	component: 1
 };
 function makeBlock(kind, entity, taken) {
@@ -13289,6 +13403,7 @@ function dockPaneTitle(block) {
 		accordion: "Accordion",
 		kpi: "KPI",
 		gauge: "Gauge",
+		sheet: "Spreadsheet",
 		component: "Component"
 	}[c.kind] || "Panel";
 }
@@ -15913,7 +16028,7 @@ function hasFieldConditions(schema) {
 *
 * `version.test.ts` asserts this matches `package.json`, so the two cannot drift.
 */
-var SVGRID_VERSION = "3.0.2";
+var SVGRID_VERSION = "3.0.3";
 //#endregion
 //#region src/studio/emit-project.ts
 var has = (blocks, kind) => blocks.some((b) => b.config.kind === kind);
@@ -16251,6 +16366,17 @@ ${panels}
 			const onOpen = openRoute ? ` onOpen={(id) => goto('/${openRoute}?id=' + encodeURIComponent(id))}` : "";
 			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;
+			const specs = (cfg.fields?.length ? cfg.fields : entity.fields.map((f) => f.field)).map((field) => ({
+				field,
+				label: entity.fields.find((f) => f.field === field)?.label ?? field
+			}));
+			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": {
@@ -17586,7 +17712,7 @@ function screenPage(schema, rawSchema, screen, resolve, rawResolve, accessEnable
 	const apiVarFor = (b) => codeGrid && b.id === codeGridBlockId ? "gridApi" : b.config.kind === "grid" && gridHasExport(b.config) ? `gridApi_${b.id.replace(/-/g, "_")}` : void 0;
 	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;
-	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");
 	const gridSpecs = [];
 	if (needsController) gridSpecs.push("SvGrid", "createServerDataSource", ...hasRowActions || hasCellRenderers || hasTreeGrid ? ["renderSnippet", "type CellContext"] : [], "type ServerState");
 	if (usesScheduler) gridSpecs.push("SvGrid");
@@ -17612,6 +17738,7 @@ function screenPage(schema, rawSchema, screen, resolve, rawResolve, accessEnable
 	if (has(allBlocks, "board")) entImports.push("SvBoard");
 	if (has(allBlocks, "calendar")) 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);
 	if (kpiCfgs.some((c) => c.format && c.format !== "auto")) entImports.push("formatKpiValue");
@@ -41637,21 +41764,26 @@ function parseLicenseExpiry(key) {
 function checkLicenseKey(key, now = /* @__PURE__ */ new Date()) {
 	if (key == null || key === "") return {
 		status: "unset",
-		valid: false
+		valid: false,
+		edition: "suite"
 	};
 	if (!key.startsWith("SVENTERPRISE-")) return {
 		status: "invalid",
-		valid: false
+		valid: false,
+		edition: "suite"
 	};
 	if (REVOKED_KEYS.has(key)) return {
 		status: "revoked",
-		valid: false
+		valid: false,
+		edition: "suite"
 	};
 	const expiresAt = parseLicenseExpiry(key) ?? void 0;
 	const expired = expiresAt ? now.getTime() > expiresAt.getTime() : void 0;
+	const status = key.startsWith("SVENTERPRISE-DEV") ? "dev" : key.startsWith("SVENTERPRISE-EVAL") ? "eval" : "licensed";
 	return {
-		status: key.startsWith("SVENTERPRISE-DEV") ? "dev" : key.startsWith("SVENTERPRISE-EVAL") ? "eval" : "licensed",
+		status,
 		valid: true,
+		edition: status === "licensed" && key.startsWith(`SVENTERPRISE-GRID-`) ? "grid" : "suite",
 		expiresAt,
 		expired
 	};

package/dist/pivot-enable.js

@@ -6,8 +6,8 @@
  * prop + config types for free and looks the engine up through the
  * `registerPivotEngine` seam.
  *
- * Soft-gated like the rest of Enterprise: it works without a license key but the
- * grid shows the unlicensed watermark + a one-time console nudge.
+ * Like the rest of Enterprise it runs without a license key during the
+ * evaluation; the grid shows the watermark and a one-time console notice.
  *
  * ```ts
  * import { setLicenseKey, enablePivot } from '@svgrid/enterprise'

package/dist/scheduler-dependencies.d.ts

@@ -63,6 +63,12 @@ export declare function hasCycle(deps: ReadonlyArray<SchedulerDependency>): bool
  * FS / SS / FF / SF semantics plus `lag` (minutes).
  */
 export declare function requiredStart(predTimes: EventTimes, dep: SchedulerDependency, successorDurationMs: number): Date;
+/** A hard limit on where one event may be scheduled, from a planning
+ *  constraint (`SNET`, `FNLT` and the rest). Both ends are optional. */
+export type CascadeBound = {
+    minStart?: Date;
+    maxEnd?: Date;
+};
 /** Options for {@link cascade}. */
 export type CascadeOptions = {
     /**
@@ -71,6 +77,35 @@ export type CascadeOptions = {
      * shifts / business hours; omit for calendar-time scheduling).
      */
     snapForward?: (start: Date) => Date;
+    /**
+     * Only what lies downstream of these keys may move: their successors,
+     * transitively, and never the keys themselves. A move passes the moved
+     * task (a phase move its whole subtree), so a task dropped too early for
+     * its predecessor stays where it was dropped with the link drawn as
+     * violated instead of springing forward, and a violation elsewhere in the
+     * plan is left alone until its own task moves. Omitted, every task in the
+     * graph is eligible.
+     */
+    from?: Iterable<string>;
+    /**
+     * Per-key limits the cascade may not push past. A `minStart` raises the floor
+     * (the event cannot begin before it); a `maxEnd` caps the ceiling, and a
+     * cascade that would need to go further stops AT the cap rather than moving
+     * past it. The link is then left unsatisfied, which {@link violations}
+     * reports - the honest outcome, because a constraint and a link that
+     * disagree have no schedule that satisfies both.
+     */
+    bounds?: ReadonlyMap<string, CascadeBound>;
+    /**
+     * The span a pushed event keeps. By default it keeps its calendar length:
+     * `end = start + (end - start)`. A day-granular planner passes working-time
+     * arithmetic here so a five-working-day task pushed over a weekend stays
+     * five working days long instead of shrinking to three. `endFor` gives the
+     * new end for a new start; `startFor` the new start for a capped end (the
+     * ceiling case). Both receive the event's times before the push.
+     */
+    endFor?: (start: Date, original: EventTimes) => Date;
+    startFor?: (end: Date, original: EventTimes) => Date;
 };
 /**
  * Forward-cascade successors so every dependency is satisfied. `times` maps row

package/dist/scheduler-dependencies.js

@@ -120,8 +120,26 @@ export function cascade(times, deps, opts = {}) {
     const cur = new Map();
     for (const [k, v] of times)
         cur.set(k, { start: v.start, end: v.end });
+    // With roots, the eligible set is their downstream closure minus the roots.
+    let eligible = null;
+    if (opts.from) {
+        const roots = new Set(opts.from);
+        eligible = new Set();
+        const stack = [...roots];
+        while (stack.length) {
+            const k = stack.pop();
+            for (const dep of graph.succ.get(k) ?? []) {
+                if (cyclicIds.has(dep.id) || roots.has(dep.to) || eligible.has(dep.to))
+                    continue;
+                eligible.add(dep.to);
+                stack.push(dep.to);
+            }
+        }
+    }
     const changed = new Map();
     for (const key of order) {
+        if (eligible && !eligible.has(key))
+            continue;
         const links = graph.pred.get(key);
         if (!links || !links.length)
             continue;
@@ -140,12 +158,29 @@ export function cascade(times, deps, opts = {}) {
             if (req > minStartMs)
                 minStartMs = req;
         }
+        // A floor constraint applies whether or not a link moved the event.
+        const bound = opts.bounds?.get(key);
+        if (bound?.minStart && bound.minStart.getTime() > minStartMs) {
+            minStartMs = bound.minStart.getTime();
+        }
         if (minStartMs <= self.start.getTime())
             continue; // already legal - never pull earlier
         let newStart = new Date(minStartMs);
         if (opts.snapForward)
             newStart = opts.snapForward(newStart);
-        const newEnd = new Date(newStart.getTime() + durationMs);
+        // A ceiling stops the cascade at the cap instead of pushing past it. The
+        // link stays unsatisfied and `violations` says so, rather than the
+        // constraint being silently overrun.
+        if (bound?.maxEnd) {
+            const latestStart = opts.startFor
+                ? opts.startFor(bound.maxEnd, self).getTime()
+                : bound.maxEnd.getTime() - durationMs;
+            if (newStart.getTime() > latestStart)
+                newStart = new Date(latestStart);
+        }
+        if (newStart.getTime() <= self.start.getTime())
+            continue;
+        const newEnd = opts.endFor ? opts.endFor(newStart, self) : new Date(newStart.getTime() + durationMs);
         const next = { start: newStart, end: newEnd };
         cur.set(key, next);
         changed.set(key, next);

package/dist/scheduler.js

@@ -5,8 +5,8 @@
  * its config types for free; the *renderer* (SvGridScheduler) is Pro and plugs
  * in through the grid's `registerSchedulerView` seam.
  *
- * Soft-gated like the rest of Enterprise: it works without a license key but the
- * grid shows the "unlicensed" watermark + a one-time console nudge.
+ * Like the rest of Enterprise it runs without a license key during the
+ * evaluation; the grid shows the watermark and a one-time console notice.
  *
  * ```ts
  * import { setLicenseKey, enableSchedulerView } from '@svgrid/enterprise'

package/dist/selection-bar.js

@@ -9,8 +9,8 @@
  * `registerSelectionBarView` seam. Without it the grid shows a short upsell
  * note where the bar would be.
  *
- * Soft-gated like the rest of Enterprise: it works without a license key but
- * the grid shows the "unlicensed" watermark + a one-time console nudge.
+ * Like the rest of Enterprise it runs without a license key during the
+ * evaluation; the grid shows the watermark and a one-time console notice.
  *
  * ```ts
  * import { setLicenseKey, enableSelectionBar } from '@svgrid/enterprise'

package/dist/server/SvGroupCell.svelte

@@ -0,0 +1,213 @@
+<!--
+  Built-in group cell for the server-side group/tree model. Drop it into the
+  grouping column and it draws the expander + indentation for group rows (and an
+  indented leaf value) - no hand-written cell recipe. Pair with `serverGroupRows`
+  to feed `<SvGrid data>`, and wire `onToggle` to the controller's `toggleGroup`.
+
+      cell: (ctx) => renderComponent(SvGroupCell, {
+        row: ctx.row.original, onToggle: ctl.toggleGroup, leafField: 'name',
+      })
+-->
+<script lang="ts" generics="TData">
+  import type { GridIcons, ServerDisplayRow, ServerPlaceholderRow } from '@svgrid/grid'
+  import { fillMessage, resolveServerGroupMessages, type ServerGroupMessages } from './messages'
+
+  // Rows from either model: the display-row union, plus the block-cached
+  // model's shared placeholder (which the grid renders itself, so it never
+  // reaches this cell - but the type has to admit it).
+  type GroupGridRow = { __group?: ServerDisplayRow<TData> | ServerPlaceholderRow } & Record<string, unknown>
+  type Props = {
+    /** The grid row from `serverGroupRows` (carries the `__group` marker). */
+    row: GroupGridRow
+    /**
+     * Expand / collapse a group, or load more children. Receives the grid row;
+     * wire to `serverGroupNav(ctl).onToggle` (which drives clicks and keyboard).
+     */
+    onToggle: (row: GroupGridRow) => void
+    /**
+     * Field to show for leaf rows in the group column (blank if omitted).
+     * Under `treeData` every row is a node of the same shape, so it names
+     * the label of expandable nodes too; a group row's key is otherwise
+     * the text.
+     */
+    leafField?: string
+    /** Pixels of indentation per level. Default 18. */
+    indent?: number
+    /**
+     * Icon overrides, the same map `<SvGrid icons>` takes. Only
+     * `chevron-right` is drawn here. You mount this component yourself, so it
+     * cannot inherit the grid's icons - pass the same object to both to keep
+     * the expander consistent with the rest of the chrome.
+     */
+    icons?: GridIcons
+    /**
+     * Strings, for localization: the "load more" row, the footer and grand
+     * total labels. Partial; missing keys keep the English default. Pass the
+     * same map to `SvRowGroupPanel` and `serverGroupText`.
+     */
+    messages?: Partial<ServerGroupMessages>
+    /** Locale for the child count and the "load more" number. Default: the browser's. */
+    locale?: string | ReadonlyArray<string>
+  }
+
+  let { row, onToggle, leafField, indent = 18, icons, messages, locale }: Props = $props()
+  const chevron = $derived(icons?.['chevron-right'])
+  const meta = $derived(row.__group)
+  const m = $derived(resolveServerGroupMessages(messages))
+  const num = (n: number) => n.toLocaleString(locale as string | string[] | undefined)
+  // A tree node's key is its id (`field` is empty under treeData); the
+  // label is the leaf field then, the same as for its leaves.
+  const label = $derived(
+    meta?.kind === 'group' && meta.field === '' && leafField ? String(row[leafField] ?? '') : meta?.kind === 'group' ? meta.key : '',
+  )
+</script>
+
+{#if meta && meta.kind === 'group' && meta.expandable === false}
+  <!-- Nothing opens beneath it (the innermost level under a server pivot),
+       so no expander: the key and the count, indented like its siblings. -->
+  <span class="sv-group-cell sv-group-cell-leaf" style={`padding-inline-start: ${meta.level * indent}px`}>
+    <span class="sv-group-chev sv-group-chev-none" aria-hidden="true"></span>
+    <span class="sv-group-key">{label}</span>
+    {#if meta.childCount != null}<span class="sv-group-count">({num(meta.childCount)})</span>{/if}
+  </span>
+{:else if meta && meta.kind === 'group'}
+  <!-- The button's accessible name is the group itself ("Germany (1,234)");
+       expanded and busy are states, on aria-expanded / aria-busy, so a
+       screen reader hears what it is opening rather than "Expand group". -->
+  <button
+    type="button"
+    class="sv-group-cell"
+    style={`padding-inline-start: ${meta.level * indent}px`}
+    aria-expanded={meta.expanded}
+    aria-busy={meta.loading ? 'true' : undefined}
+    onclick={() => onToggle(row)}
+  >
+    {#if meta.loading}
+      <!-- The level's block is in flight: the expander's slot holds a
+           spinner until it lands, so the wait is visible on the row itself. -->
+      <span class="sv-group-chev sv-group-spinner" aria-hidden="true"></span>
+    {:else}
+      <!-- Same chevron the grid's own expanders and SvTree draw, so every
+           expander in the library looks identical. -->
+      <span class="sv-group-chev" class:open={meta.expanded} aria-hidden="true">
+        {#if chevron}
+          {@render chevron()}
+        {:else}
+          <svg viewBox="0 0 24 24" width="12" height="12" fill="none" stroke="currentColor"
+            stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="m9 18 6-6-6-6" /></svg>
+        {/if}
+      </span>
+    {/if}
+    <span class="sv-group-key">{label}</span>
+    {#if meta.childCount != null}<span class="sv-group-count">({num(meta.childCount)})</span>{/if}
+  </button>
+{:else if meta && meta.kind === 'more'}
+  <!-- aria-disabled rather than disabled: a disabled button drops keyboard
+       focus the moment it is pressed, and this one is pressed to wait. -->
+  <button
+    type="button"
+    class="sv-group-more"
+    style={`padding-inline-start: ${meta.level * indent}px`}
+    aria-disabled={meta.loading ? 'true' : undefined}
+    aria-busy={meta.loading ? 'true' : undefined}
+    onclick={() => {
+      if (!meta.loading) onToggle(row)
+    }}
+  >
+    {meta.loading ? m.loading : fillMessage(m.loadMore, { count: num(meta.remaining) })}
+  </button>
+{:else if meta && meta.kind === 'footer'}
+  <span class="sv-group-footer" style={`padding-inline-start: ${meta.level * indent}px`}>{fillMessage(m.total, { label: meta.key })}</span>
+{:else if meta && meta.kind === 'skeleton'}
+  <span class="sv-group-skeleton" style={`margin-inline-start: ${meta.level * indent}px`} aria-hidden="true"></span>
+{:else if meta && meta.kind === 'grandTotal'}
+  <span class="sv-group-footer sv-group-grand-total">{m.grandTotal}</span>
+{:else if meta && meta.kind === 'placeholder'}
+  <!-- The grid draws placeholder rows itself; nothing to add here. -->
+{:else if meta}
+  <span class="sv-group-leaf" style={`padding-inline-start: ${(meta.level + 1) * indent}px`}>
+    {leafField ? (row[leafField] ?? '') : ''}
+  </span>
+{/if}
+
+<style>
+  .sv-group-cell {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    background: none;
+    border: 0;
+    padding: 0;
+    font: inherit;
+    color: inherit;
+    cursor: pointer;
+    border-radius: 3px;
+  }
+  .sv-group-cell-leaf { cursor: default; }
+  /* The same ring the grid's own tree toggle draws, so keyboard focus looks
+     alike whichever expander it lands on. */
+  .sv-group-cell:focus-visible,
+  .sv-group-more:focus-visible {
+    outline: 2px solid var(--sg-accent, #2563eb);
+    outline-offset: 2px;
+  }
+  .sv-group-chev {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 12px;
+    height: 12px;
+    transition: transform 0.15s;
+    color: var(--sg-muted, #64748b);
+  }
+  /* An `icons` override renders inside this wrapper, and this style block is
+     scoped, so its markup needs :global() to be reached. Sizing it here means
+     a custom chevron lands in the same box as the built-in and rotates with
+     the wrapper rather than needing to know the rule exists. */
+  .sv-group-chev :global(svg),
+  .sv-group-chev :global(img) {
+    width: 100%;
+    height: 100%;
+    display: block;
+  }
+  .sv-group-chev.open { transform: rotate(90deg); }
+  .sv-group-key { font-weight: 600; }
+  .sv-group-count { color: var(--sg-muted, #64748b); font-size: 12px; }
+  .sv-group-spinner {
+    box-sizing: border-box;
+    border-radius: 50%;
+    border: 2px solid color-mix(in srgb, var(--sg-muted, #64748b) 35%, transparent);
+    border-top-color: var(--sg-accent, #2563eb);
+    animation: sv-group-spin 0.8s linear infinite;
+  }
+  @keyframes sv-group-spin {
+    to { transform: rotate(360deg); }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .sv-group-spinner { animation: none; border-top-color: var(--sg-muted, #64748b); }
+  }
+  .sv-group-leaf { color: var(--sg-muted, #64748b); }
+  .sv-group-more {
+    background: none;
+    border: 0;
+    padding: 0;
+    font: inherit;
+    font-size: 13px;
+    color: var(--sg-accent, #2563eb);
+    cursor: pointer;
+    border-radius: 3px;
+  }
+  .sv-group-more[aria-disabled='true'] { color: var(--sg-muted, #64748b); cursor: default; }
+  .sv-group-footer { font-weight: 600; color: var(--sg-muted, #64748b); font-size: 12px; text-transform: uppercase; letter-spacing: 0.03em; }
+  .sv-group-skeleton {
+    display: inline-block;
+    width: 60%;
+    height: 10px;
+    border-radius: 5px;
+    background: linear-gradient(90deg, var(--sg-border, #e2e8f0) 25%, var(--sg-header-bg, #f1f5f9) 50%, var(--sg-border, #e2e8f0) 75%);
+    background-size: 200% 100%;
+    animation: sv-group-shimmer 1.2s infinite;
+  }
+  @keyframes sv-group-shimmer { from { background-position: 200% 0; } to { background-position: -200% 0; } }
+  @media (prefers-reduced-motion: reduce) { .sv-group-skeleton { animation: none; } }
+</style>