@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/SvPivotDesigner.svelte

@@ -19,6 +19,8 @@
    *
    *   SvPivotDesigner {data} {fields} bind:layout
    */
+  import { untrack } from 'svelte'
+
   import {
     SvGrid,
     SvGridChart,
@@ -26,6 +28,7 @@
     tableFeatures,
     rowSortingFeature,
     columnFilteringFeature,
+    renderComponent,
     renderSnippet,
     portalToBody,
     popIn,
@@ -35,7 +38,10 @@
     type ColumnDef,
     type ChartType,
     type MenuItem,
+    type ServerAggregation,
   } from '@svgrid/grid'
+  import SvGroupCell from './server/SvGroupCell.svelte'
+  import { serverGroupText, type ServerRowModel, type ServerRowModelGridRow } from './server/server-row-model'
   import { createPivotModel, filterCollapsedPivotRows, type PivotRow, type PivotAggregatorId } from './pivot'
   import { pivotToChartSpec } from './pivot-chart'
   import {
@@ -44,8 +50,8 @@
   } from './pivot-designer'
 
   type Props = {
-    /** Flat input rows. */
-    data: T[]
+    /** Flat input rows. Not read in server mode. */
+    data?: T[]
     /** All fields the user can pick from the rail. */
     fields: PivotField<T>[]
     /** The current pivot layout. Bindable so the consumer can persist it. */
@@ -87,7 +93,8 @@
       layout: PivotLayout,
     ) => ColumnDef<typeof features, PivotRow>[]
     /** Click handler forwarded to the embedded SvGrid - typically used
-     *  to drive a drill-through side panel. */
+     *  to drive a drill-through side panel. In server mode `row` is the
+     *  model's grid row (its `__group` says which group or leaf it is). */
     onCellClick?: (ctx: { columnId: string; row: PivotRow; value: unknown }) => void
     /** Offer a Table <-> Chart view toggle (same layout as a live chart). Default true. */
     chartable?: boolean
@@ -149,9 +156,29 @@
      * narrow the source rows (they drive `layout.filters`). Default false.
      */
     toolTabs?: boolean
+
+    // ---- Server mode ----------------------------------------------------
+    /**
+     * A `createServerRowModel` controller. The designer then drives it
+     * instead of pivoting in the browser - Rows become `groupBy`, Columns
+     * `pivotBy`, Values `aggregations` - and the embedded grid mounts it
+     * through `rowModel`, showing the columns the backend's
+     * `pivotResultFields` describe. `data` is not read. The Filters well,
+     * the subtotal switches and the chart view are off: filters belong to
+     * the grid's own filter UI, footers and totals to the model's options.
+     */
+    server?: ServerRowModel<T>
+    /** The group column the designer adds in server mode. */
+    groupColumn?: { header?: string; width?: number; leafField?: string }
+    /**
+     * `'immediate'` (default) sends every drag to `onLayoutChange` and the
+     * server. `'deferred'` collects edits and shows Apply / Cancel, so one
+     * slice-and-dice session is one request.
+     */
+    applyMode?: 'immediate' | 'deferred'
   }
   let {
-    data,
+    data = [],
     fields,
     layout = $bindable<PivotLayout>(defaultLayoutFor([])),
     onLayoutChange,
@@ -181,8 +208,27 @@
     hiddenFields = $bindable<string[]>([]),
     onHiddenFieldsChange,
     toolTabs = false,
+    server,
+    groupColumn,
+    applyMode = 'immediate',
   }: Props = $props()
 
+  // ---- Deferred apply -------------------------------------------------
+  // `layout` is what the wells show; `committed` is what the pivot (or the
+  // server) runs. They differ only in deferred mode, between an edit and
+  // Apply.
+  let committed = $state<PivotLayout>(layout)
+  const deferred = $derived(applyMode === 'deferred')
+  const applied = $derived(deferred ? committed : layout)
+  const dirty = $derived(deferred && JSON.stringify(layout) !== JSON.stringify(committed))
+  function applyLayout() {
+    committed = layout
+    onLayoutChange?.(layout)
+  }
+  function cancelLayout() {
+    layout = committed
+  }
+
   // ---- Columns / Filters tab rail ----------------------------------
   let activeTab = $state<'columns' | 'filters'>('columns')
   let filterCollapsed = $state<Set<string>>(new Set())
@@ -224,7 +270,7 @@
     return () => window.removeEventListener('mousedown', on)
   })
 
-  const showPivotToggle = $derived(!!flatColumns)
+  const showPivotToggle = $derived(!!flatColumns || !!server)
   function setPivotMode(on: boolean) {
     pivotMode = on
     onPivotModeChange?.(on)
@@ -236,10 +282,12 @@
   $effect.pre(() => {
     if (!layout || (!layout.rows.length && !layout.cols.length && !layout.values.length && !layout.filters.length)) {
       layout = defaultLayoutFor(fields)
+      committed = layout
     }
   })
 
   const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
+  const filtersWell = $derived(showFiltersWell && !server)
   const uid = `pvd-${Math.random().toString(36).slice(2, 8)}`
 
   // Lookup helpers -----------------------------------------------------
@@ -331,6 +379,7 @@
   // ---- Mutation helpers ---------------------------------------------
   function emit(next: PivotLayout) {
     layout = next
+    if (deferred) return
     onLayoutChange?.(next)
   }
   function defaultWellFor(field: PivotField<T>): Well {
@@ -484,9 +533,9 @@
   // The pivot model itself has no filtering, but the well clearly should:
   // a Filters chip with `allowed` restricts which rows reach the model.
   const filteredData = $derived.by(() => {
-    if (!layout.filters.length) return data
+    if (!applied.filters.length) return data
     return data.filter((row) => {
-      for (const f of layout.filters) {
+      for (const f of applied.filters) {
         if (f.allowed == null) continue
         const v = row[f.field]
         if (!f.allowed.includes(String(v))) return false
@@ -499,41 +548,145 @@
   // Whenever the layout or data changes, re-run the pivot. Empty layouts
   // are tolerated: the grid will show a friendly empty state.
   const pivot = $derived.by(() => {
-    if (!layout.values.length && !layout.rows.length && !layout.cols.length) return null
-    if (!layout.values.length) return null
+    if (server) return null
+    if (!applied.values.length && !applied.rows.length && !applied.cols.length) return null
+    if (!applied.values.length) return null
     return createPivotModel(filteredData, {
-      rows: layout.rows as Array<keyof T & string>,
-      cols: layout.cols as Array<keyof T & string>,
-      values: layout.values.map((v) => ({
+      rows: applied.rows as Array<keyof T & string>,
+      cols: applied.cols as Array<keyof T & string>,
+      values: applied.values.map((v) => ({
         field: v.field as keyof T & string,
         agg: v.agg,
         label: v.label,
         format: v.format,
       })),
-      grandTotalRow: !layout.hideGrandTotals,
-      grandTotalCol: !layout.hideGrandTotals,
-      rowSubtotals: !layout.hideSubtotals,
+      grandTotalRow: !applied.hideGrandTotals,
+      grandTotalCol: !applied.hideGrandTotals,
+      rowSubtotals: !applied.hideSubtotals,
     })
   })
   $effect(() => {
     if (pivot) onPivot?.(pivot.rows, pivot.columns)
   })
 
+  // ---- Server mode ----------------------------------------------------
+  // The applied layout drives the model in one call, so a designer edit is
+  // one reload. Aggregators the contract has no word for are left out.
+  const SERVER_FN: Partial<Record<PivotAggregatorId, ServerAggregation['fn']>> = {
+    sum: 'sum',
+    avg: 'avg',
+    min: 'min',
+    max: 'max',
+    count: 'count',
+  }
+  $effect(() => {
+    if (!server) return
+    const l = applied
+    server.setLayout({
+      groupBy: [...l.rows],
+      pivotBy: [...l.cols],
+      pivotMode: pivotMode && l.cols.length > 0,
+      aggregations: l.values.flatMap((v) => {
+        const fn = SERVER_FN[v.agg]
+        return fn ? [{ col: v.field, fn }] : []
+      }),
+      // The same switch the client pivot reads as its total column.
+      pivotRowTotals: !l.hideGrandTotals,
+    })
+  })
+  // The model is plain; a version bump re-reads its pivot columns.
+  let serverVersion = $state(0)
+  $effect(() => {
+    if (!server) return
+    return server.subscribe(() => {
+      serverVersion += 1
+    })
+  })
+  type ServerCol = ColumnDef<typeof features, ServerRowModelGridRow<T>>
+  const serverGroupColumn = $derived.by((): ServerCol | null => {
+    if (!server) return null
+    const model = server
+    return {
+      id: 'sv-group',
+      header: groupColumn?.header ?? 'Group',
+      width: groupColumn?.width ?? 260,
+      sortable: false,
+      filterable: false,
+      fieldFn: (row) => serverGroupText(row, groupColumn?.leafField as (keyof T & string) | undefined),
+      cell: (ctx) =>
+        renderComponent(SvGroupCell, {
+          row: ctx.row.original,
+          onToggle: () => model.group?.onToggle(ctx.row.original),
+          leafField: groupColumn?.leafField,
+        }),
+    } as ServerCol
+  })
+  // Pivot off: the group column (when grouping) and the app's own columns.
+  const serverColumns = $derived.by((): ServerCol[] => {
+    const own = (flatColumns ?? []) as unknown as ServerCol[]
+    return applied.rows.length && serverGroupColumn ? [serverGroupColumn, ...own] : own
+  })
+  // Pivot on: the group column, then the columns the model built from the
+  // backend's `pivotResultFields`. Undefined before the first pivoted
+  // response, so the grid keeps `serverColumns` until then.
+  const serverPivotColumns = $derived.by((): ServerCol[] | undefined => {
+    void serverVersion
+    if (!server) return undefined
+    const cols = server.pivotResultColumns as ServerCol[] | null
+    if (!cols) return undefined
+    return serverGroupColumn ? [serverGroupColumn, ...cols] : cols
+  })
+
   // ---- Table <-> Chart view (the same layout as a live pivot chart) ----
-  let view = $state<'table' | 'chart'>(defaultView === 'chart' && chartable ? 'chart' : 'table')
+  let view = $state<'table' | 'chart'>(untrack(() => (defaultView === 'chart' && chartable ? 'chart' : 'table')))
   let chartType = $state<ChartType>('bar')
   let chartStacked = $state(false)
-  const CHART_TYPES: Array<{ value: ChartType; label: string }> = [
-    { value: 'bar', label: 'Bar' },
-    { value: 'line', label: 'Line' },
-    { value: 'area', label: 'Area' },
-    { value: 'pie', label: 'Pie' },
+  let chartStacked100 = $state(false)
+  let chartHorizontal = $state(false)
+  // Every shape a pivot's categories + series can take, grouped the way the
+  // grid panel groups them. The ones missing (scatter, gauge, box plot,
+  // histogram, ranges, bullet, candles) read rows one by one.
+  const CHART_TYPES: Array<{ value: ChartType; label: string; group: string }> = [
+    { value: 'bar', label: 'Bar', group: 'Compare' },
+    { value: 'line', label: 'Line', group: 'Compare' },
+    { value: 'area', label: 'Area', group: 'Compare' },
+    { value: 'lollipop', label: 'Lollipop', group: 'Compare' },
+    { value: 'pareto', label: 'Pareto', group: 'Compare' },
+    { value: 'radial-column', label: 'Radial column', group: 'Compare' },
+    { value: 'radial-bar', label: 'Radial bar', group: 'Compare' },
+    { value: 'nightingale', label: 'Nightingale', group: 'Compare' },
+    { value: 'pie', label: 'Pie', group: 'Part of a whole' },
+    { value: 'funnel', label: 'Funnel', group: 'Flow' },
+    { value: 'waterfall', label: 'Waterfall', group: 'Flow' },
+    { value: 'radar', label: 'Radar', group: 'Distribution' },
+    { value: 'heatmap', label: 'Heat map', group: 'Distribution' },
+    { value: 'stream', label: 'Stream', group: 'Over time' },
   ]
-  const chartSpec = $derived.by(() =>
-    pivot && chartable && view === 'chart'
-      ? pivotToChartSpec(pivot, { type: chartType, stacked: chartStacked })
-      : null,
-  )
+  const CHART_GROUPS = [...new Set(CHART_TYPES.map((t) => t.group))]
+  const STACKABLE: ChartType[] = ['bar', 'line', 'area', 'radial-column']
+  // The measures' formats travel to the chart when they agree; a layout
+  // mixing a currency and a count formats plainly rather than putting a "$"
+  // on the count. The chip's own format wins over the field's.
+  const chartFormat = $derived.by(() => {
+    const formats = layout.values.map((v) => v.format ?? fields.find((f) => f.field === v.field)?.format)
+    const first = formats[0]
+    if (!first) return undefined
+    const same = formats.every((f) => f && f.type === first.type && (f.type !== 'currency' || (f as { currency?: string }).currency === (first as { currency?: string }).currency))
+    return same ? first : undefined
+  })
+  const chartSpec = $derived.by(() => {
+    if (!pivot || !chartable || view !== 'chart') return null
+    const spec = pivotToChartSpec(pivot, {
+      type: chartType,
+      stacked: chartStacked && STACKABLE.includes(chartType),
+      stacked100: chartStacked100 && (chartType === 'bar' || chartType === 'area'),
+      format: chartFormat,
+    })
+    if (chartHorizontal && chartType === 'bar') spec.orientation = 'horizontal'
+    // A stream is a stacked area on a wiggle baseline; the box has nothing to add.
+    if (chartType === 'stream') { spec.stacked = true; spec.stackOffset = 'wiggle' }
+    return spec
+  })
 
   // ---- Expand / collapse (when `expandable` is on) ------------------
   // We hold a `collapsed` set of pivot row ids; descendants of a
@@ -797,28 +950,56 @@
           {/if}
         </div>
       {/if}
-      <label class="pvd-toggle">
-        <input type="checkbox" checked={!layout.hideSubtotals} onchange={toggleHideSubtotals} /> Subtotals
-      </label>
-      <label class="pvd-toggle">
-        <input type="checkbox" checked={!layout.hideGrandTotals} onchange={toggleHideGrandTotals} /> Grand totals
-      </label>
-      {#if chartable}
+      {#if !server}
+        <label class="pvd-toggle">
+          <input type="checkbox" checked={!layout.hideSubtotals} onchange={toggleHideSubtotals} /> Subtotals
+        </label>
+        <label class="pvd-toggle">
+          <input type="checkbox" checked={!layout.hideGrandTotals} onchange={toggleHideGrandTotals} /> Grand totals
+        </label>
+      {:else}
+        <!-- The server model owns its grand-total row (a construction option);
+             the switch here is the Total column group, built without a request. -->
+        <label class="pvd-toggle">
+          <input type="checkbox" checked={!layout.hideGrandTotals} onchange={toggleHideGrandTotals} /> Row totals
+        </label>
+      {/if}
+      {#if deferred}
+        <div class="pvd-apply" role="group" aria-label="Apply layout">
+          <button type="button" class="pvd-btn pvd-btn-primary" disabled={!dirty} onclick={applyLayout}>Apply</button>
+          <button type="button" class="pvd-btn" disabled={!dirty} onclick={cancelLayout}>Cancel</button>
+        </div>
+      {/if}
+      {#if chartable && !server}
         <div class="pvd-viewswitch" role="group" aria-label="View">
           <button type="button" class="pvd-view-btn" class:is-active={view === 'table'} onclick={() => (view = 'table')}>{@render ic('table')} Table</button>
           <button type="button" class="pvd-view-btn" class:is-active={view === 'chart'} onclick={() => (view = 'chart')}>{@render ic('chart')} Chart</button>
         </div>
         {#if view === 'chart'}
           <label class="pvd-toggle">
-            <select class="pvd-select" value={chartType} onchange={(e) => (chartType = e.currentTarget.value as ChartType)}>
-              {#each CHART_TYPES as t (t.value)}<option value={t.value}>{t.label}</option>{/each}
+            <select class="pvd-select" aria-label="Chart type" value={chartType} onchange={(e) => (chartType = e.currentTarget.value as ChartType)}>
+              {#each CHART_GROUPS as g (g)}
+                <optgroup label={g}>
+                  {#each CHART_TYPES.filter((t) => t.group === g) as t (t.value)}<option value={t.value}>{t.label}</option>{/each}
+                </optgroup>
+              {/each}
             </select>
           </label>
-          {#if chartType !== 'pie'}
+          {#if STACKABLE.includes(chartType)}
             <label class="pvd-toggle">
               <input type="checkbox" checked={chartStacked} onchange={(e) => (chartStacked = e.currentTarget.checked)} /> Stacked
             </label>
           {/if}
+          {#if chartType === 'bar' || chartType === 'area'}
+            <label class="pvd-toggle">
+              <input type="checkbox" checked={chartStacked100} onchange={(e) => (chartStacked100 = e.currentTarget.checked)} /> 100%
+            </label>
+          {/if}
+          {#if chartType === 'bar'}
+            <label class="pvd-toggle">
+              <input type="checkbox" checked={chartHorizontal} onchange={(e) => (chartHorizontal = e.currentTarget.checked)} /> Horizontal
+            </label>
+          {/if}
         {/if}
       {/if}
       <div class="pvd-spacer"></div>
@@ -854,7 +1035,7 @@
       {/if}
       <div class="pvd-main">
         {#if showPivotToggle}<div class="pvd-topbar">{@render pivotToggle()}</div>{/if}
-        <div class="pvd-wells" class:two={!showFiltersWell}>{@render wellsBlock()}</div>
+        <div class="pvd-wells" class:two={!filtersWell}>{@render wellsBlock()}</div>
         {@render gridBlock()}
       </div>
     {/if}
@@ -1048,18 +1229,18 @@
 
 {#snippet wellsBlock()}
   <!-- Filters -->
-  {#if showFiltersWell}
-    <div class="pvd-well"
+  {#if filtersWell}
+    <div class="pvd-well" data-well="filters" role="group" aria-label="Filters"
       class:drag-over={dragOver === 'filters'}
       ondragover={(e) => onDragOver(e, 'filters')}
       ondragleave={onDragLeave}
       ondrop={(e) => onDrop(e, 'filters')}
       oncontextmenu={(e) => openCtx(e, wellMenu('filters'))}>
       <div class="pvd-well-head">{@render ic('filter')} Filters</div>
-      <div class="pvd-well-body">
+      <div class="pvd-well-body" role="list">
         {#each layout.filters as f (f.field)}
           {@const fd = fieldsByName.get(f.field)}
-          <div class="pvd-chip" draggable="true" ondragstart={(e) => onDragStart(e, f.field, 'filters')} oncontextmenu={(e) => openCtx(e, chipMenu('filters', f.field))}>
+          <div class="pvd-chip" role="listitem" draggable="true" ondragstart={(e) => onDragStart(e, f.field, 'filters')} oncontextmenu={(e) => openCtx(e, chipMenu('filters', f.field))}>
             <span class="pvd-chip-grip" aria-hidden="true">{@render ic('grip')}</span>
             <button type="button" class="pvd-chip-label" title="Choose which values pass" onclick={() => toggleFilterMenu(f.field)}>
               {fd?.label ?? f.field}{f.allowed ? `: ${f.allowed.length}` : ''} <span class="pvd-chip-caret">▾</span>
@@ -1096,17 +1277,17 @@
   {/if}
 
   <!-- Columns -->
-  <div class="pvd-well"
+  <div class="pvd-well" data-well="cols" role="group" aria-label="Cols"
     class:drag-over={dragOver === 'cols'}
     ondragover={(e) => onDragOver(e, 'cols')}
     ondragleave={onDragLeave}
     ondrop={(e) => onDrop(e, 'cols')}
     oncontextmenu={(e) => openCtx(e, wellMenu('cols'))}>
     <div class="pvd-well-head">{@render ic('columns')} Columns</div>
-    <div class="pvd-well-body">
+    <div class="pvd-well-body" role="list">
       {#each layout.cols as field (field)}
         {@const fd = fieldsByName.get(field)}
-        <div class="pvd-chip" draggable="true" ondragstart={(e) => onDragStart(e, field, 'cols')} oncontextmenu={(e) => openCtx(e, chipMenu('cols', field))}>
+        <div class="pvd-chip" role="listitem" draggable="true" ondragstart={(e) => onDragStart(e, field, 'cols')} oncontextmenu={(e) => openCtx(e, chipMenu('cols', field))}>
           <span class="pvd-chip-grip" aria-hidden="true">{@render ic('grip')}</span>
           <span class="pvd-chip-label">{fd?.label ?? field}</span>
           <button type="button" class="pvd-chip-x" onclick={() => removeFromWell(field, 'cols')} aria-label="Remove">×</button>
@@ -1117,17 +1298,17 @@
   </div>
 
   <!-- Rows -->
-  <div class="pvd-well"
+  <div class="pvd-well" data-well="rows" role="group" aria-label="Rows"
     class:drag-over={dragOver === 'rows'}
     ondragover={(e) => onDragOver(e, 'rows')}
     ondragleave={onDragLeave}
     ondrop={(e) => onDrop(e, 'rows')}
     oncontextmenu={(e) => openCtx(e, wellMenu('rows'))}>
     <div class="pvd-well-head">{@render ic('rows')} Rows</div>
-    <div class="pvd-well-body">
+    <div class="pvd-well-body" role="list">
       {#each layout.rows as field (field)}
         {@const fd = fieldsByName.get(field)}
-        <div class="pvd-chip" draggable="true" ondragstart={(e) => onDragStart(e, field, 'rows')} oncontextmenu={(e) => openCtx(e, chipMenu('rows', field))}>
+        <div class="pvd-chip" role="listitem" draggable="true" ondragstart={(e) => onDragStart(e, field, 'rows')} oncontextmenu={(e) => openCtx(e, chipMenu('rows', field))}>
           <span class="pvd-chip-grip" aria-hidden="true">{@render ic('grip')}</span>
           <span class="pvd-chip-label">{fd?.label ?? field}</span>
           <button type="button" class="pvd-chip-x" onclick={() => removeFromWell(field, 'rows')} aria-label="Remove">×</button>
@@ -1138,17 +1319,17 @@
   </div>
 
   <!-- Values -->
-  <div class="pvd-well"
+  <div class="pvd-well" data-well="values" role="group" aria-label="Values"
     class:drag-over={dragOver === 'values'}
     ondragover={(e) => onDragOver(e, 'values')}
     ondragleave={onDragLeave}
     ondrop={(e) => onDrop(e, 'values')}
     oncontextmenu={(e) => openCtx(e, wellMenu('values'))}>
     <div class="pvd-well-head">{@render ic('sigma')} Values</div>
-    <div class="pvd-well-body">
+    <div class="pvd-well-body" role="list">
       {#each layout.values as v, vi (v.field + '|' + v.agg + '|' + vi)}
         {@const fd = fieldsByName.get(v.field)}
-        <div class="pvd-chip pvd-chip-value" draggable="true" ondragstart={(e) => onDragStart(e, v.field, 'values', vi)} oncontextmenu={(e) => openCtx(e, chipMenu('values', v.field, vi))}>
+        <div class="pvd-chip pvd-chip-value" role="listitem" draggable="true" ondragstart={(e) => onDragStart(e, v.field, 'values', vi)} oncontextmenu={(e) => openCtx(e, chipMenu('values', v.field, vi))}>
           <span class="pvd-chip-grip" aria-hidden="true">{@render ic('grip')}</span>
           <button type="button" class="pvd-chip-label" onclick={() => toggleAggMenu(vi)}>
             <span class="pvd-chip-agg">{AGG_LABEL[v.agg]}</span>
@@ -1181,7 +1362,7 @@
 {#snippet columnsPanel()}
   {#if showPivotToggle}{@render pivotToggle()}{/if}
   {#if showFieldList}<div class="pvd-panel-rail">{@render railBlock()}</div>{/if}
-  <div class="pvd-wells pvd-wells--vertical" class:two={!showFiltersWell}>{@render wellsBlock()}</div>
+  <div class="pvd-wells pvd-wells--vertical" class:two={!filtersWell}>{@render wellsBlock()}</div>
 {/snippet}
 
 <!-- The Filters tab body: AG-style set filters. Each active column filter is a
@@ -1247,8 +1428,25 @@
 
 {#snippet gridBlock()}
   {#if embedGrid}
-    <div class="pvd-grid" style={`height:${typeof gridHeight === 'number' ? gridHeight + 'px' : gridHeight}`} oncontextmenu={(e) => openCtx(e, gridMenu())}>
-      {#if showPivotToggle && !pivotMode}
+    <div class="pvd-grid" role="region" aria-label="Pivot" style={`height:${typeof gridHeight === 'number' ? gridHeight + 'px' : gridHeight}`} oncontextmenu={(e) => openCtx(e, gridMenu())}>
+      {#if server}
+        <SvGrid
+          rowModel={server}
+          columns={serverColumns}
+          pivotResultColumns={pivotMode ? serverPivotColumns : undefined}
+          features={features}
+          sortable
+          selectionMode="none"
+          rowHeight={32}
+          containerHeight="100%"
+          fitColumns={gridFitColumns}
+          columnVirtualization={columnVirtualization}
+          enableRowSummaries={false}
+          onCellClick={onCellClick
+            ? (e) => onCellClick({ columnId: e.columnId, row: e.row as unknown as PivotRow, value: e.value })
+            : undefined}
+        />
+      {:else if showPivotToggle && !pivotMode}
         <SvGrid
           data={filteredData}
           columns={visibleFlatColumns!}
@@ -1264,7 +1462,9 @@
         />
       {:else if pivot && chartable && view === 'chart'}
         {#if chartSpec && chartSpec.series.length}
-          <div class="pvd-chart"><SvGridChart spec={chartSpec} interactive legend /></div>
+          <!-- The chart's own toolbar (PNG / SVG / PDF / print / copy) and the
+               spoken summary, at the pane's size. -->
+          <div class="pvd-chart"><SvGridChart spec={chartSpec} interactive legend="bottom" toolbar describe autosize /></div>
         {:else}
           <div class="pvd-empty pvd-grid-empty">Add a measure and a row / column field to chart the pivot.</div>
         {/if}
@@ -1375,6 +1575,15 @@
     border-color: var(--sg-accent, #2563eb);
   }
   .pvd-btn-primary:hover { opacity: 0.9; }
+  .pvd-btn:disabled { opacity: 0.5; cursor: default; }
+  /* Apply with nothing to apply reads as off, not as a paler Apply. */
+  .pvd-btn-primary:disabled {
+    opacity: 1;
+    background: var(--sg-header-bg, #f1f5f9);
+    border-color: var(--sg-border, #e2e8f0);
+    color: var(--sg-muted, #64748b);
+  }
+  .pvd-apply { display: inline-flex; gap: 6px; }
   .pvd-toggle {
     display: inline-flex;
     align-items: center;

package/dist/SvPivotDesigner.svelte.d.ts

@@ -1,28 +1,12 @@
 type PivotInputRow = Record<string, unknown>;
-/**
-   * SvPivotDesigner - Excel-style pivot table designer.
-   *
-   * Self-contained, controlled component. The consumer holds the data
-   * + the field list + the layout state; everything else (drag-and-drop,
-   * chip menus, search, presets, the inline pivot grid) is built in.
-   *
-   * Minimal wire-up (in a .svelte file):
-   *   const fields = [
-   *     { field: 'region',   label: 'Region',   kind: 'dimension' },
-   *     { field: 'quarter',  label: 'Quarter',  kind: 'dimension' },
-   *     { field: 'amount',   label: 'Revenue',  kind: 'measure', defaultAgg: 'sum' },
-   *   ]
-   *   let layout = $state(defaultLayoutFor(fields))
-   *
-   *   SvPivotDesigner {data} {fields} bind:layout
-   */
 import { type ColumnDef } from '@svgrid/grid';
+import { type ServerRowModel } from './server/server-row-model.js';
 import { type PivotRow, type PivotAggregatorId } from './pivot.js';
 import { type PivotField, type PivotLayout, type PivotPreset } from './pivot-designer.js';
 declare function $$render<T extends PivotInputRow>(): {
     props: {
-        /** Flat input rows. */
-        data: T[];
+        /** Flat input rows. Not read in server mode. */
+        data?: T[];
         /** All fields the user can pick from the rail. */
         fields: PivotField<T>[];
         /** The current pivot layout. Bindable so the consumer can persist it. */
@@ -80,7 +64,8 @@ declare function $$render<T extends PivotInputRow>(): {
             };
         }, PivotRow>[];
         /** Click handler forwarded to the embedded SvGrid - typically used
-         *  to drive a drill-through side panel. */
+         *  to drive a drill-through side panel. In server mode `row` is the
+         *  model's grid row (its `__group` says which group or leaf it is). */
         onCellClick?: (ctx: {
             columnId: string;
             row: PivotRow;
@@ -151,6 +136,28 @@ declare function $$render<T extends PivotInputRow>(): {
          * narrow the source rows (they drive `layout.filters`). Default false.
          */
         toolTabs?: boolean;
+        /**
+         * A `createServerRowModel` controller. The designer then drives it
+         * instead of pivoting in the browser - Rows become `groupBy`, Columns
+         * `pivotBy`, Values `aggregations` - and the embedded grid mounts it
+         * through `rowModel`, showing the columns the backend's
+         * `pivotResultFields` describe. `data` is not read. The Filters well,
+         * the subtotal switches and the chart view are off: filters belong to
+         * the grid's own filter UI, footers and totals to the model's options.
+         */
+        server?: ServerRowModel<T>;
+        /** The group column the designer adds in server mode. */
+        groupColumn?: {
+            header?: string;
+            width?: number;
+            leafField?: string;
+        };
+        /**
+         * `'immediate'` (default) sends every drag to `onLayoutChange` and the
+         * server. `'deferred'` collects edits and shows Apply / Cancel, so one
+         * slice-and-dice session is one request.
+         */
+        applyMode?: "immediate" | "deferred";
     };
     exports: {};
     bindings: "pivotMode" | "layout" | "hiddenFields";

package/dist/SvRibbonIcon.svelte

@@ -0,0 +1,46 @@
+<script lang="ts">
+  /**
+   * One ribbon icon, by name, at any size.
+   *
+   * The paths live in `sheet/ribbon-icons.ts` on a 16-unit grid; the SVG
+   * scales them, so a large button gets the same drawing at 32px without a
+   * second set. Everything is drawn in `currentColor`: the icon is the
+   * colour of the text around it, black on a light ribbon and white on a
+   * dark one, and nothing in the set carries a colour of its own.
+   */
+  import { RIBBON_ICONS, type RibbonIconName } from './sheet/ribbon-icons'
+
+  let { name, size = 16 }: { name: RibbonIconName; size?: number } = $props()
+
+  const paths = $derived(RIBBON_ICONS[name] ?? [])
+</script>
+
+<svg
+  class="sv-ribbon-icon"
+  width={size}
+  height={size}
+  viewBox="0 0 16 16"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="1.4"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+  aria-hidden="true"
+  focusable="false"
+>
+  {#each paths as path, i (i)}
+    <path
+      d={path.d}
+      fill={path.fill ? 'currentColor' : 'none'}
+      stroke-width={path.width}
+      stroke-dasharray={path.dash}
+    />
+  {/each}
+</svg>
+
+<style>
+  .sv-ribbon-icon {
+    display: block;
+    flex: 0 0 auto;
+  }
+</style>