@svgrid/enterprise 2.5.3 → 2.6.1

package/dist/pivot-chart.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pivot -> chart bridge.
+ *
+ * Turns a computed {@link PivotResult} (the row/column/value matrix the pivot
+ * engine produces) into a core {@link ChartSpec} the free `SvGridChart` can
+ * render - so one pivot layout drives both a table and a chart (the Excel
+ * PivotTable <-> PivotChart pairing).
+ *
+ * Mapping:
+ *   - categories = the row-axis LEAF rows (deepest grouping; subtotals and the
+ *     grand-total row are skipped). With no row dims, the single total row.
+ *   - series     = the column-axis leaf value columns (one per col-path x
+ *     measure). The grand-total column is excluded unless `includeTotals`.
+ *   - values     = each leaf row's aggregated cell for that series column.
+ */
+import type { ChartSpec, ChartType, TableFeatures } from '@svgrid/grid';
+import type { PivotResult } from './pivot';
+export type PivotChartOptions = {
+    /** Chart type. Default `'bar'`. */
+    type?: ChartType;
+    /** Stack the series. Default false. */
+    stacked?: boolean;
+    /** Include the grand-total column / row as a series / category. Default false. */
+    includeTotals?: boolean;
+    /** Cap the number of categories (row leaves) charted. */
+    maxCategories?: number;
+};
+export declare function pivotToChartSpec<TFeatures extends TableFeatures>(result: PivotResult<TFeatures>, opts?: PivotChartOptions): ChartSpec;

package/dist/pivot-chart.js

@@ -0,0 +1,71 @@
+export function pivotToChartSpec(result, opts = {}) {
+    const type = opts.type ?? 'bar';
+    // Category rows: the row-axis leaves. Fall back to the grand-total (single
+    // "All") row when no row dims are configured, then to every row.
+    let catRows = result.rows.filter((r) => r.__pivotKind === 'leaf');
+    if (!catRows.length)
+        catRows = result.rows.filter((r) => r.__pivotKind === 'grandTotal');
+    if (!catRows.length)
+        catRows = result.rows.slice();
+    if (opts.maxCategories && catRows.length > opts.maxCategories) {
+        catRows = catRows.slice(0, opts.maxCategories);
+    }
+    // Categories are the leaf's OWN label; when rows are nested, emit a parent
+    // tier (categoryGroups) so the axis reads "Americas | Canada · USA ..." as a
+    // grouped axis rather than colliding on a bare repeated leaf label.
+    const byId = new Map(result.rows.map((r) => [r.__pivotId, r]));
+    const ownLabel = (r) => String(r.__pivotLabel ?? '').trim() || '(blank)';
+    const categories = catRows.map(ownLabel);
+    const parentOf = (r) => r.__pivotParentId ? byId.get(r.__pivotParentId) : undefined;
+    const nested = catRows.length > 0 && catRows.every((r) => parentOf(r) !== undefined);
+    let categoryGroups;
+    if (nested) {
+        categoryGroups = [];
+        let prevId;
+        for (const r of catRows) {
+            const pid = r.__pivotParentId;
+            const last = categoryGroups[categoryGroups.length - 1];
+            if (last && pid === prevId)
+                last.span += 1;
+            else {
+                categoryGroups.push({ label: ownLabel(parentOf(r)), span: 1 });
+                prevId = pid;
+            }
+        }
+    }
+    const leaves = [];
+    const walk = (cols, path) => {
+        for (const c of cols ?? []) {
+            if (!c || c.id === '__pivotRowHeader')
+                continue;
+            // Skip the grand-total column group (and its leaves) unless asked for.
+            if (!opts.includeTotals && typeof c.id === 'string' && c.id.startsWith('pv_group__grand'))
+                continue;
+            if (Array.isArray(c.columns))
+                walk(c.columns, [...path, String(c.header ?? '')]);
+            else if (typeof c.id === 'string')
+                leaves.push({ id: c.id, path, header: String(c.header ?? '') });
+        }
+    };
+    walk(result.columns, []);
+    const filtered = opts.includeTotals ? leaves : leaves.filter((l) => !l.id.includes('__total'));
+    const uniqueHeaders = new Set(filtered.map((l) => l.header));
+    const series = filtered.map((l) => ({
+        label: l.path.length === 0
+            ? l.header
+            : uniqueHeaders.size > 1
+                ? [...l.path, l.header].join(' · ')
+                : l.path.join(' · '),
+        values: catRows.map((r) => {
+            const v = r[l.id];
+            return typeof v === 'number' ? v : Number(v) || 0;
+        }),
+    }));
+    return {
+        type,
+        categories,
+        series,
+        ...(categoryGroups && categoryGroups.length > 1 ? { categoryGroups } : {}),
+        ...(opts.stacked ? { stacked: true } : {}),
+    };
+}

package/dist/pivot-designer.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Types + helpers for the SvPivotDesigner component.
+ *
+ * Why a separate module: the component file (.svelte) imports these,
+ * and so do consumers wiring up custom presets, formatters, or wells.
+ * Keeping the pure-TS surface here also lets us unit-test the layout
+ * normalisation + serialisation without instantiating the component.
+ */
+import type { CellFormatConfig } from '@svgrid/grid';
+import type { PivotAggregatorId } from './pivot';
+/** One field the designer offers in its left-rail picker.
+ *  Dimensions land in Rows by default; measures land in Values. */
+export type PivotField<T extends Record<string, unknown> = Record<string, unknown>> = {
+    field: keyof T & string;
+    /** Display name shown in the picker + on chips. */
+    label: string;
+    /** Default well: 'dimension' -> Rows, 'measure' -> Values. */
+    kind: 'dimension' | 'measure';
+    /** Optional group name for the field picker (e.g. 'Demographics'). */
+    group?: string;
+    /** Optional formatter applied to value-well chips by default. */
+    format?: CellFormatConfig;
+    /** Optional default aggregator when added to Values (default 'sum'). */
+    defaultAgg?: PivotAggregatorId;
+};
+/** A single chip in the Values well. */
+export type PivotValueChip = {
+    field: string;
+    agg: PivotAggregatorId;
+    label?: string;
+    format?: CellFormatConfig;
+};
+/** A single chip in the Filters well. `allowed === null` => all values pass. */
+export type PivotFilterChip = {
+    field: string;
+    /** Distinct values that pass the filter. `null` means no restriction. */
+    allowed: string[] | null;
+};
+/** The full pivot layout. The designer is a controlled component that
+ *  reads + writes this single shape via `bind:layout`. */
+export type PivotLayout = {
+    rows: string[];
+    cols: string[];
+    values: PivotValueChip[];
+    filters: PivotFilterChip[];
+    /** Hide subtotal rows between groups. Default false. */
+    hideSubtotals?: boolean;
+    /** Hide grand-total row + column. Default false. */
+    hideGrandTotals?: boolean;
+};
+/** A saved layout the user can pick from the toolbar's preset menu. */
+export type PivotPreset = {
+    name: string;
+    layout: PivotLayout;
+};
+/** A built-in aggregator option. Consumers can pass a subset to
+ *  `aggregators` to restrict the chip menu (e.g. 'count' only). */
+export declare const ALL_AGGREGATORS: PivotAggregatorId[];
+/** Empty layout used by Reset + the initial state. */
+export declare const EMPTY_LAYOUT: PivotLayout;
+/** Build an initial layout from a field list - useful when the
+ *  consumer just wants "throw the first dimension in Rows + first
+ *  measure in Values" defaults. */
+export declare function defaultLayoutFor<T extends Record<string, unknown>>(fields: ReadonlyArray<PivotField<T>>): PivotLayout;
+/** Move / add / remove a chip across the four wells. The well names
+ *  match the layout shape. */
+export type Well = 'rows' | 'cols' | 'values' | 'filters';
+/** Pretty label for an aggregator id. */
+export declare const AGG_LABEL: Record<PivotAggregatorId, string>;

package/dist/pivot-designer.js

@@ -0,0 +1,38 @@
+/**
+ * Types + helpers for the SvPivotDesigner component.
+ *
+ * Why a separate module: the component file (.svelte) imports these,
+ * and so do consumers wiring up custom presets, formatters, or wells.
+ * Keeping the pure-TS surface here also lets us unit-test the layout
+ * normalisation + serialisation without instantiating the component.
+ */
+/** A built-in aggregator option. Consumers can pass a subset to
+ *  `aggregators` to restrict the chip menu (e.g. 'count' only). */
+export const ALL_AGGREGATORS = [
+    'sum', 'avg', 'min', 'max', 'count', 'countDistinct', 'first', 'last',
+];
+/** Empty layout used by Reset + the initial state. */
+export const EMPTY_LAYOUT = {
+    rows: [], cols: [], values: [], filters: [],
+};
+/** Build an initial layout from a field list - useful when the
+ *  consumer just wants "throw the first dimension in Rows + first
+ *  measure in Values" defaults. */
+export function defaultLayoutFor(fields) {
+    const dim = fields.find((f) => f.kind === 'dimension');
+    const meas = fields.find((f) => f.kind === 'measure');
+    return {
+        rows: dim ? [dim.field] : [],
+        cols: [],
+        values: meas
+            ? [{ field: meas.field, agg: meas.defaultAgg ?? 'sum', label: meas.label, format: meas.format }]
+            : [],
+        filters: [],
+    };
+}
+/** Pretty label for an aggregator id. */
+export const AGG_LABEL = {
+    sum: 'Sum', avg: 'Average', min: 'Min', max: 'Max',
+    count: 'Count', countDistinct: 'Distinct count',
+    first: 'First', last: 'Last',
+};

package/dist/pivot-enable.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Register the Enterprise pivot engine. Idempotent - safe to call from every
+ * component that uses `pivot`, or once at app start. Also invoked by
+ * {@link installEnterprise} so wiring the Pro API turns pivot on too.
+ */
+export declare function enablePivot(): void;

package/{src/pivot-enable.ts → dist/pivot-enable.js}

@@ -16,29 +16,24 @@
  * // then: <SvGrid {data} {columns} pivot={{ rows: ['region'], cols: ['quarter'], values: [{ field: 'sales', agg: 'sum' }] }} />
  * ```
  */
-import { registerPivotEngine, type PivotEngine } from '@svgrid/grid'
-import { isLicenseKeySet } from './license'
-import { emitUnlicensedNudge } from './watermark'
-import { createPivotModel, type PivotConfig } from './pivot'
-
-let enabled = false
-
+import { registerPivotEngine } from '@svgrid/grid';
+import { isLicenseKeySet } from './license';
+import { emitUnlicensedNudge } from './watermark';
+import { createPivotModel } from './pivot';
+let enabled = false;
 // The grid's `PivotEngine` seam is generic over row type; `createPivotModel` is
 // the concrete implementation. Bridge them with a single boundary cast.
-const pivotEngine: PivotEngine = (data, config) =>
-  createPivotModel(
-    data as ReadonlyArray<Record<string, unknown>>,
-    config as unknown as PivotConfig<Record<string, unknown>>,
-  ) as never
-
+const pivotEngine = (data, config) => createPivotModel(data, config);
 /**
  * Register the Enterprise pivot engine. Idempotent - safe to call from every
  * component that uses `pivot`, or once at app start. Also invoked by
  * {@link installEnterprise} so wiring the Pro API turns pivot on too.
  */
-export function enablePivot(): void {
-  if (enabled) return
-  enabled = true
-  registerPivotEngine(pivotEngine)
-  if (!isLicenseKeySet()) emitUnlicensedNudge()
+export function enablePivot() {
+    if (enabled)
+        return;
+    enabled = true;
+    registerPivotEngine(pivotEngine);
+    if (!isLicenseKeySet())
+        emitUnlicensedNudge();
 }

package/dist/pivot.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Pivot table (@svgrid/enterprise).
+ *
+ * Turns a flat array of rows + a pivot config into:
+ *   - `rows`: a flat array of pivot rows (group, subtotal, leaf, grand
+ *     total) suitable for `<SvGrid data={rows} />`.
+ *   - `columns`: a nested-header column tree suitable for
+ *     `<SvGrid columns={columns} />` - one column per (col-axis path
+ *      × value-measure) plus the row-axis "Header" first column.
+ *
+ * No DOM, no rendering. The grid renders the result with its
+ * `columns: ColumnDef[]` + `data: PivotRow[]` like any other dataset.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { createPivotModel } from '@svgrid/enterprise'
+ *
+ * const pivot = createPivotModel(orders, {
+ *   rows:   ['region', 'salesPerson'],
+ *   cols:   ['quarter'],
+ *   values: [
+ *     { field: 'amount', agg: 'sum', label: 'Total',  format: { type: 'currency', currency: 'USD' } },
+ *     { field: 'amount', agg: 'avg', label: 'Avg' },
+ *   ],
+ * })
+ *
+ * // then:
+ * <SvGrid data={pivot.rows} columns={pivot.columns} features={features} />
+ * ```
+ */
+import type { ColumnDef, CellFormatConfig, RowData, TableFeatures } from '@svgrid/grid';
+export type PivotAggregatorId = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'countDistinct' | 'first' | 'last';
+export type PivotAggregator = (values: ReadonlyArray<unknown>) => unknown;
+export type PivotValueConfig<TData> = {
+    /** Row field whose values get aggregated. */
+    field: keyof TData & string;
+    /** Built-in aggregator id, or a custom reducer. */
+    agg: PivotAggregatorId | PivotAggregator;
+    /** Display name in the column header. Defaults to `${field} (${agg})`. */
+    label?: string;
+    /** Optional cell formatter. */
+    format?: CellFormatConfig;
+};
+export type PivotConfig<TData> = {
+    /** Outer-most first. Each entry becomes one level of row grouping. */
+    rows: ReadonlyArray<keyof TData & string>;
+    /** Outer-most first. Each entry becomes one level of column grouping. */
+    cols: ReadonlyArray<keyof TData & string>;
+    /** One or more measures aggregated under each column-axis leaf. */
+    values: ReadonlyArray<PivotValueConfig<TData>>;
+    /** Grand-total row at the bottom. Default `true`. */
+    grandTotalRow?: boolean;
+    /** Grand-total column on the right. Default `true`. */
+    grandTotalCol?: boolean;
+    /** Subtotal rows between row groups. Default `true`. */
+    rowSubtotals?: boolean;
+    /** Optional sort for column-axis values per dim level (defaults to alpha). */
+    colSort?: (a: unknown, b: unknown, level: number) => number;
+    /** Optional sort for row-axis values per dim level (defaults to alpha). */
+    rowSort?: (a: unknown, b: unknown, level: number) => number;
+};
+export type PivotRowKind = 'group' | 'subtotal' | 'leaf' | 'grandTotal';
+/**
+ * Shape of one entry in `result.rows`. The first-column label lives at
+ * `__pivotLabel`; every value cell lives at the column id matching the
+ * leaf column generated for its (col-path × measure).
+ *
+ * `__pivotParentId` is the `__pivotId` of the row's row-axis parent
+ * (or `null` for top-level groups, the grand-total row, and the one
+ * synthetic "All" row when no row dims are configured). Use it with
+ * `filterCollapsedPivotRows` to hide leaves whose ancestor is
+ * collapsed - that's how expandable pivots are built on top of the
+ * model.
+ *
+ * `__pivotExpandable` is `true` for `group` rows that have at least
+ * one descendant. A renderer uses this to decide whether to show a
+ * chevron next to the label.
+ */
+export type PivotRow = {
+    __pivotId: string;
+    __pivotKind: PivotRowKind;
+    __pivotDepth: number;
+    __pivotLabel: string;
+    __pivotParentId: string | null;
+    __pivotExpandable: boolean;
+    /** Aggregated value cells - keyed by leaf column id. */
+    [columnId: string]: unknown;
+};
+export type PivotResult<TFeatures extends TableFeatures> = {
+    rows: PivotRow[];
+    columns: Array<ColumnDef<TFeatures, PivotRow>>;
+};
+export declare function createPivotModel<TFeatures extends TableFeatures, TData extends RowData>(data: ReadonlyArray<TData>, config: PivotConfig<TData>): PivotResult<TFeatures>;
+/**
+ * Public registry of built-in aggregators. Useful for surfacing the
+ * available options in a pivot designer UI.
+ */
+export declare const pivotAggregators: Record<PivotAggregatorId, PivotAggregator>;
+/**
+ * Filter a `result.rows` array down to only the rows the user should
+ * see given the current expansion state. A row stays in the output if
+ * its entire ancestor chain (via `__pivotParentId`) is in `expandedIds`.
+ *
+ * Pass `true` to bypass filtering (everything visible - the default
+ * shape `createPivotModel` already returns). Pass an empty array /
+ * empty Set to collapse every group to its subtotal row.
+ *
+ * The result is a new array; the input is not mutated.
+ */
+export declare function filterCollapsedPivotRows(rows: ReadonlyArray<PivotRow>, expandedIds: ReadonlyArray<string> | Set<string> | true): PivotRow[];