@svgrid/enterprise 3.0.2 → 3.1.0

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,28 +548,97 @@
   // 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)
   let chartStacked100 = $state(false)
@@ -832,13 +950,27 @@
           {/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>
@@ -903,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}
@@ -1097,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>
@@ -1145,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>
@@ -1166,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>
@@ -1187,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>
@@ -1230,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
@@ -1296,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!}
@@ -1426,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";