@svgrid/grid 2.6.19 → 2.6.21

package/dist/positioning.d.ts

@@ -37,6 +37,7 @@ export type Viewport = {
     width: number;
     height: number;
 };
+/** Where to put a floating element: its preferred side, offsets, and collision behaviour. */
 export type ComputePositionOptions = {
     /** Preferred placement. Default `'bottom-start'`. */
     placement?: Placement;
@@ -61,6 +62,7 @@ export type ComputePositionOptions = {
     /** Floor for the available main-axis size returned by `size`. Default 0. */
     minMainAxis?: number;
 };
+/** The resolved position, including the side actually used after collision handling. */
 export type ComputePositionResult = {
     /** Floating left, in viewport (fixed-position) coordinates. */
     x: number;

package/dist/scheduler-ical.d.ts

@@ -6,6 +6,7 @@
  * LOCATION. No `Date.now()` in the core - `toICS` accepts a stamp.
  */
 import type { RecurrenceRule } from './recurrence.js';
+/** One VEVENT: the fields SvGrid reads from and writes to an iCalendar feed. */
 export type ICalEvent = {
     uid?: string;
     title: string;

package/dist/scheduler-model.d.ts

@@ -171,6 +171,7 @@ export type DayLayout<TData = unknown> = {
     events: PositionedEvent<TData>[];
     overflows: OverflowMarker<TData>[];
 };
+/** Tuning for event layout: how overlapping events share horizontal space. */
 export type LayoutOptions = {
     dayStartHour?: number;
     dayEndHour?: number;

package/dist/summaries.js

@@ -1,3 +1,7 @@
+// summaries handlers extracted from the controller. Imperative event handlers
+// reading/writing controller state via the `ctx` handle; the reactive core
+// ($state/$derived/$effect) stays in the controller.
+import { applyGroupAggregate, } from "./index.js";
 import "./sv-grid-scrollbar.js";
 import { getCellKey, } from "./SvGrid.helpers.js";
 import { formatSummaryNumeric, } from "./cell-values.js";
@@ -25,6 +29,24 @@ export function createSummaries(ctx) {
             const fieldFn = def.fieldFn;
             const field = def.field;
             const columnId = column.id;
+            // A column that declares its own `summary` opts out of the default
+            // sum/count below. Only that column pays for the aggregator dispatch, so
+            // a grid that declares none keeps the original hot loop exactly as it was.
+            const declared = def.summary;
+            if (declared !== undefined) {
+                if (declared === false) {
+                    summary[columnId] = "";
+                    continue;
+                }
+                const value = applyGroupAggregate(declared, columnId, rows);
+                summary[columnId] =
+                    typeof value === "number" && Number.isFinite(value)
+                        ? formatSummaryNumeric(column, value)
+                        : value == null
+                            ? ""
+                            : String(value);
+                continue;
+            }
             let numericSum = 0;
             let numericCount = 0;
             for (let i = 0; i < rowCount; i += 1) {

package/dist/svgrid-wrapper.types.d.ts

@@ -3,6 +3,7 @@ import type { FilterOperator, Props } from './SvGrid.types.js';
 import type { GridExportOptions, GridClipboardOptions } from './export-format.js';
 import type { ChartSpec, ChartType } from './chart.js';
 import type { GridPredicateExpr } from './filtering/predicate-expr.js';
+/** The comparisons a column filter can use, as shown in the filter menu. */
 export type SvGridFilterOperator = FilterOperator;
 /**
  * A serializable snapshot of everything that makes up the current "view":
@@ -80,6 +81,7 @@ export type SvGridTransaction<TData> = {
     update?: ReadonlyArray<TData>;
     remove?: ReadonlyArray<TData | string>;
 };
+/** What a batched `applyTransaction` did: how many rows were added, updated and removed. */
 export type SvGridTransactionResult = {
     added: number;
     updated: number;
@@ -458,6 +460,7 @@ export type SvGridApi<TFeatures extends TableFeatures, TData extends RowData> =
     /** Force a recompute of the row pipeline + a re-render. */
     refresh(): void;
 };
+/** The props `<SvGrid>` accepts. See the SvGrid reference for the full list with defaults. */
 export type SvGridWrapperProps<TFeatures extends TableFeatures, TData extends RowData> = {
     data: ReadonlyArray<TData>;
     columns: Array<ColumnDef<TFeatures, TData>>;
@@ -505,6 +508,8 @@ export type SvGridWrapperProps<TFeatures extends TableFeatures, TData extends Ro
     enableCellSelection?: boolean;
     enableInlineEditing?: boolean;
     enableRowSummaries?: boolean;
+    /** Shortcut alias for `enableRowSummaries`; wins when both are set. */
+    summary?: boolean;
     /** Receives the imperative grid API when the component is ready. */
     onApiReady?: (api: SvGridApi<TFeatures, TData>) => void;
 };

package/dist/toast-store.svelte.d.ts

@@ -14,6 +14,7 @@
  * Mount a single <SvToaster /> once near the app root to render the queue.
  */
 import type { Snippet } from 'svelte';
+/** A toast's severity, which selects its colour and icon. */
 export type ToastVariant = 'info' | 'success' | 'warning' | 'error';
 /** A button rendered inside a toast (a primary `action` or a secondary `cancel`). */
 export type ToastAction = {
@@ -23,6 +24,7 @@ export type ToastAction = {
     /** Keep the toast open after the click (default: dismiss it). */
     keepOpen?: boolean;
 };
+/** Options for one toast: its variant, how long it stays, and any action button. */
 export type ToastOptions = {
     variant?: ToastVariant;
     /** Auto-dismiss after N ms. `0` = sticky (dismiss manually). Default 4000. */
@@ -38,6 +40,7 @@ export type ToastOptions = {
     /** Render a fully custom toast body instead of the icon + title + message. */
     render?: Snippet<[Toast]>;
 };
+/** A live toast: its options plus the id needed to dismiss it. */
 export type Toast = {
     id: number;
     message: string;
@@ -58,6 +61,7 @@ export type PromiseMessages<T> = {
     error: string | ((error: unknown) => string);
 };
 type VariantOptions = Omit<ToastOptions, 'variant'>;
+/** The callable toast API - `toast(msg)` plus `.success` / `.error` / friends. */
 export type ToastFn = {
     (message: string, options?: ToastOptions): number;
     info: (message: string, options?: VariantOptions) => number;

package/dist/validate.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Development-time configuration checks.
+ *
+ * The grid used to fail silently on the most common mistakes. A misspelled
+ * `field` rendered a column of empty cells with nothing on the console; a
+ * `pageSize` with no pagination was quietly ignored; a column marked
+ * `sortable` with no sorting enabled just did not sort. Each of those costs
+ * someone an afternoon, and none of them were detectable from the outside.
+ *
+ * This module is the check. It is pure and returns messages rather than
+ * printing them, so it can be unit-tested; the controller runs it in an effect
+ * and prints each message once, in dev builds only.
+ *
+ * Rules for anything added here:
+ *   - Never fire on valid config. A false positive teaches people to ignore
+ *     warnings, which is worse than staying silent.
+ *   - Say what happened, what it means, and how to fix it - the house style set
+ *     by the one pre-existing warning in server-data-source.ts.
+ *   - Stay O(columns), or O(columns x a fixed row sample). This runs on data
+ *     changes, and must not scale with row count.
+ */
+import type { ColumnDef, RowData, TableFeatures } from './core.js';
+export type ValidateInput<TFeatures extends TableFeatures, TData extends RowData> = {
+    data: ReadonlyArray<TData>;
+    columns: ReadonlyArray<ColumnDef<TFeatures, TData>>;
+    /** The resolved feature set, after the boolean shortcuts have injected theirs. */
+    features?: Record<string, unknown>;
+    sortable?: boolean;
+    pageable?: boolean;
+    showPagination?: boolean;
+    pageSize?: number;
+    groupBy?: ReadonlyArray<string>;
+    treeData?: {
+        parentField?: string;
+        idField?: string;
+        column?: string;
+    };
+    initialColumnPinning?: {
+        left?: ReadonlyArray<string>;
+        right?: ReadonlyArray<string>;
+    };
+    columnVirtualization?: boolean;
+    externalPagination?: boolean;
+    rowCount?: number;
+    externalSort?: boolean;
+    onSortingChange?: unknown;
+    externalFilter?: boolean;
+    onFiltersChange?: unknown;
+};
+export declare function validateGridConfig<TFeatures extends TableFeatures, TData extends RowData>(input: ValidateInput<TFeatures, TData>): string[];

package/dist/validate.js

@@ -0,0 +1,187 @@
+/** How many rows to sample when deciding whether a `field` exists. */
+const FIELD_SAMPLE_ROWS = 10;
+const DOCS = 'https://svgrid.com/docs/getting-started/3-data-and-columns/';
+/** Every leaf column, flattened through group columns. */
+function leaves(columns, out = []) {
+    for (const col of columns) {
+        if (col.columns?.length)
+            leaves(col.columns, out);
+        else
+            out.push(col);
+    }
+    return out;
+}
+export function validateGridConfig(input) {
+    const messages = [];
+    const cols = leaves(input.columns ?? []);
+    // ---- 1. A `field` that does not exist on the data -------------------------
+    // The single most expensive silent failure: the column renders, and every
+    // cell in it is blank. Sampled across several rows so genuinely sparse data
+    // (a key absent from row 0 but present later) does not trip it.
+    const sample = (input.data ?? []).slice(0, FIELD_SAMPLE_ROWS);
+    if (sample.length) {
+        const known = new Set();
+        for (const row of sample) {
+            if (row && typeof row === 'object')
+                for (const k of Object.keys(row))
+                    known.add(k);
+        }
+        for (const col of cols) {
+            const field = col.field;
+            // `fieldFn` computes its value, and an id-only column (actions, buttons)
+            // never reads the row - neither needs a matching key.
+            if (!field || col.fieldFn)
+                continue;
+            if (known.has(field))
+                continue;
+            const guess = nearest(field, [...known]);
+            messages.push(`[svgrid] Column field "${field}" does not exist on your row data, so that ` +
+                `column renders empty.${guess ? ` Did you mean "${guess}"?` : ''} ` +
+                `Available keys: ${[...known].slice(0, 12).join(', ')}. See ${DOCS}`);
+        }
+    }
+    // ---- 2. Duplicate column ids ---------------------------------------------
+    // Two columns resolving to the same id makes selection, sorting and column
+    // state address the wrong one, with no error anywhere.
+    const seen = new Map();
+    for (const col of cols) {
+        const id = (col.id ?? col.field);
+        if (!id)
+            continue;
+        seen.set(id, (seen.get(id) ?? 0) + 1);
+    }
+    for (const [id, n] of seen) {
+        if (n > 1) {
+            messages.push(`[svgrid] ${n} columns share the id "${id}". Column state (sorting, ` +
+                `filtering, pinning, width) is keyed by id, so they will act as one. ` +
+                `Give each an explicit \`id\`. See ${DOCS}`);
+        }
+    }
+    // ---- 3. `pageSize` with pagination never asked for ------------------------
+    // Only when BOTH pagination props are absent. `pageable={false}` is a
+    // deliberate statement - often a bound toggle that flips on later - whereas
+    // an unset prop means the author never considered it. Warning on the former
+    // fired on our own shortcut-config demo, which is exactly the kind of noise
+    // that teaches people to ignore warnings.
+    const paginationUnset = input.pageable === undefined && input.showPagination === undefined;
+    if (input.pageSize !== undefined && paginationUnset) {
+        messages.push('[svgrid] `pageSize` is set but pagination was never turned on, so it has ' +
+            'no effect and every row renders. Add `pageable` to switch the pager on.');
+    }
+    // ---- 4. A column asks to sort, but nothing enables sorting ----------------
+    // `sortable` on the grid injects rowSortingFeature, so only warn when neither
+    // the shortcut nor an explicitly registered feature is present.
+    const sortingEnabled = input.sortable === true || Boolean(input.features?.rowSortingFeature);
+    if (!sortingEnabled && cols.some((c) => c.sortable === true)) {
+        messages.push('[svgrid] A column sets `sortable: true`, but sorting is not enabled on the ' +
+            'grid, so its header does nothing. Add `sortable` to <SvGrid> (it registers ' +
+            'the sorting feature for you).');
+    }
+    // ---- 5. Column ids referenced by other props ------------------------------
+    // `groupBy` and `treeData.column` address columns by id. A name that matches
+    // nothing is silently ignored, so grouping or the tree expander just never
+    // appears and there is nothing to debug against.
+    const columnIds = new Set();
+    for (const col of cols) {
+        const id = (col.id ?? col.field);
+        if (id)
+            columnIds.add(id);
+    }
+    for (const id of input.groupBy ?? []) {
+        if (columnIds.has(id))
+            continue;
+        const guess = nearest(id, [...columnIds]);
+        messages.push(`[svgrid] \`groupBy\` refers to column "${id}", which does not exist, so ` +
+            `that grouping level is ignored.${guess ? ` Did you mean "${guess}"?` : ''} ` +
+            `Column ids: ${[...columnIds].slice(0, 12).join(', ')}`);
+    }
+    const treeColumn = input.treeData?.column;
+    if (treeColumn && !columnIds.has(treeColumn)) {
+        messages.push(`[svgrid] \`treeData.column\` refers to column "${treeColumn}", which does ` +
+            `not exist, so the expander falls back to the first visible column.`);
+    }
+    // ---- 6. treeData pointing at fields the data does not have ----------------
+    if (sample.length && input.treeData) {
+        const known = new Set();
+        for (const row of sample) {
+            if (row && typeof row === 'object')
+                for (const k of Object.keys(row))
+                    known.add(k);
+        }
+        const parentField = input.treeData.parentField;
+        if (parentField && !known.has(parentField)) {
+            const guess = nearest(parentField, [...known]);
+            messages.push(`[svgrid] \`treeData.parentField\` is "${parentField}", which is not on ` +
+                `your row data, so every row becomes a root and no hierarchy appears.` +
+                `${guess ? ` Did you mean "${guess}"?` : ''}`);
+        }
+        // `idField` defaults to 'id'; only check what was asked for explicitly.
+        const idField = input.treeData.idField;
+        if (idField && !known.has(idField)) {
+            messages.push(`[svgrid] \`treeData.idField\` is "${idField}", which is not on your row ` +
+                `data, so parent lookups cannot match and the tree stays flat.`);
+        }
+    }
+    // ---- 7. Pinning that column virtualization will hide ----------------------
+    // Documented incompatibility: the virtualizer recycles column DOM nodes, so
+    // sticky pinning cannot survive it. `columnVirtualization` defaults to ON,
+    // which means the natural way to write this silently does nothing.
+    const pinned = (input.initialColumnPinning?.left?.length ?? 0) +
+        (input.initialColumnPinning?.right?.length ?? 0);
+    if (pinned > 0 && input.columnVirtualization !== false) {
+        messages.push('[svgrid] `initialColumnPinning` is set while column virtualization is on ' +
+            '(its default), so the pinned columns will not stick - the virtualizer ' +
+            'recycles column nodes. Add `columnVirtualization={false}`.');
+    }
+    // ---- 8. Server-mode contracts left half-wired -----------------------------
+    // Each of these makes the grid hand control to the consumer. Miss the other
+    // half and the feature looks broken rather than unconfigured.
+    if (input.externalPagination === true && input.rowCount === undefined) {
+        messages.push('[svgrid] `externalPagination` is on but `rowCount` is not set, so the pager ' +
+            'cannot know how many pages exist. Pass the server total as `rowCount`.');
+    }
+    if (input.externalSort === true && !input.onSortingChange) {
+        messages.push('[svgrid] `externalSort` is on but there is no `onSortingChange` handler, so ' +
+            'clicking a header changes nothing - the grid stopped sorting and nobody ' +
+            'is listening. Add `onSortingChange` and re-fetch in your handler.');
+    }
+    if (input.externalFilter === true && !input.onFiltersChange) {
+        messages.push('[svgrid] `externalFilter` is on but there is no `onFiltersChange` handler, ' +
+            'so filtering the grid changes nothing. Add `onFiltersChange` and re-fetch ' +
+            'in your handler.');
+    }
+    return messages;
+}
+/** Closest key by edit distance, for a "did you mean" hint. Undefined if none is close. */
+function nearest(target, candidates) {
+    let best;
+    let bestScore = Infinity;
+    for (const c of candidates) {
+        const d = distance(target.toLowerCase(), c.toLowerCase());
+        if (d < bestScore) {
+            bestScore = d;
+            best = c;
+        }
+    }
+    // Only suggest a genuinely near miss - a third of the length, at most 3 edits.
+    const limit = Math.min(3, Math.floor(target.length / 3) + 1);
+    return bestScore <= limit ? best : undefined;
+}
+/** Levenshtein distance, iterative single-row. Inputs here are identifier-length. */
+function distance(a, b) {
+    if (a === b)
+        return 0;
+    const prev = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        let carry = prev[0];
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const next = Math.min(prev[j] + 1, prev[j - 1] + 1, carry + (a[i - 1] === b[j - 1] ? 0 : 1));
+            carry = prev[j];
+            prev[j] = next;
+        }
+    }
+    return prev[b.length];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svgrid/grid",
-  "version": "2.6.19",
+  "version": "2.6.21",
   "description": "Svelte 5-native data grid and data table. Headless-first engine with virtual scrolling for 100k+ rows, Excel-style filtering, inline editing, grouping, tree data, pivot, and server-side data. Drop-in <SvGrid> component. TypeScript, SSR-ready.",
   "author": "jQWidgets <boikom@jqwidgets.com>",
   "license": "MIT",
@@ -138,5 +138,8 @@
   },
   "peerDependencies": {
     "svelte": "^5.0.0"
+  },
+  "dependencies": {
+    "esm-env": "^1.2.2"
   }
 }

package/src/SvGrid.controller.svelte.ts

@@ -32,6 +32,7 @@ import {
   resolveMaxDomHeight,
 } from "./virtualization/scroll-scaling";
 import { buildPreMeasureItems } from "./virtualization/virtualizer";
+import { DEV } from "esm-env";
 import "./sv-grid-scrollbar";
 import {
     computeColumnStat,
@@ -61,6 +62,7 @@ import {
 import {
     createSummaries,
   } from "./summaries";
+
 import {
     createMenus,
   } from "./menus";
@@ -606,6 +608,17 @@ export function createSvGridController<
         (props.selectionMode ?? "both") === "both"),
   );
 
+  // The aggregate footer row. `summary` is the shortcut alias, so it wins over
+  // the fine-grained prop - the same precedence `selectable` uses.
+  //
+  // It starts OFF. It used to default ON, which meant a plain
+  // `<SvGrid {data} {columns} />` grew a totals row nobody asked for, and every
+  // caller that did not want one had to say so: 375 call sites in this repo
+  // passed `enableRowSummaries={false}` against 6 that opted in.
+  const rowSummariesEnabled = $derived(
+    props.summary ?? props.enableRowSummaries ?? false,
+  );
+
 
 
   // Internal source-of-truth for data and column defs. Seeded from props and
@@ -2583,7 +2596,7 @@ export function createSvGridController<
    */
   const eagerSummaries = $derived.by(() => {
     if (!summarize) return null;
-    if (!(props.enableRowSummaries ?? true)) return null;
+    if (!rowSummariesEnabled) return null;
     const rows = allRows;
     const columns = allColumns;
     if (rows.length * columns.length > SUMMARY_DEFER_CELL_LIMIT) return null;
@@ -2607,7 +2620,7 @@ export function createSvGridController<
     void editedCellValues;
     const rows = allRows;
     const columns = allColumns;
-    if (!(props.enableRowSummaries ?? true)) {
+    if (!rowSummariesEnabled) {
       deferredSummaries = {};
       return;
     }
@@ -3499,6 +3512,7 @@ export function createSvGridController<
     get showColumnFiltersEffective() { return showColumnFiltersEffective; },
     get showInlineColumnFilterEffective() { return showInlineColumnFilterEffective; },
     get showRowSelectionEffective() { return showRowSelectionEffective; },
+    get rowSummariesEnabled() { return rowSummariesEnabled; },
     get enableCellSelectionEffective() { return enableCellSelectionEffective; },
     get flushScheduledScrollSync() { return flushScheduledScrollSync; },
     get scheduleScrollSync() { return scheduleScrollSync; },
@@ -3945,6 +3959,58 @@ export function createSvGridController<
   const { buildApi } = createGridApi<TFeatures, TData>(ctx);
   const { readCellRaw, writeCellRaw, applyFillPattern, clearSelectedCellValues, startFillDrag, onFillPointerMove, onFillPointerUp, toggleBooleanCell, copySelectionToClipboard, clearSelectedCells, cutSelectionToClipboard } = createClipboard(ctx);
 
+  // Dev-time configuration checks. Silent misconfiguration was the grid's
+  // biggest usability gap - a misspelled `field` rendered a column of blank
+  // cells and printed nothing, and an inert `pageSize` was simply ignored.
+  //
+  // `validateGridConfig` is pure (see validate.ts) so it can be unit-tested;
+  // this only decides when to run it, and prints each distinct message once.
+  //
+  // It is loaded with `import()` rather than a static import so the checks live
+  // in a lazy chunk. The base bundle is size-budgeted and already sits at its
+  // limit, so a static import cost ~1 KB gzip that a production app would carry
+  // and never execute.
+  //
+  // `DEV` comes from `esm-env` because the alternatives do not work here:
+  // `process.env.NODE_ENV` is undefined in Vite's browser runtime (the checks
+  // silently never ran), and Vite's own flag makes svelte-package warn that it
+  // only works for Vite consumers. esm-env resolves through export conditions,
+  // so it is correct in dev and folds to `false` in a production build. It is
+  // already a direct dependency of Svelte, so it adds nothing to an install.
+  if (DEV) {
+    const warnedConfig = new Set<string>();
+    $effect(() => {
+      // Read the reactive values synchronously so the effect tracks them; the
+      // module load below is async and would otherwise register no dependencies.
+      const snapshot = {
+        data: internalData,
+        columns: internalColumns,
+        features: resolveEffectiveFeatures() as Record<string, unknown>,
+        sortable: props.sortable,
+        pageable: props.pageable,
+        showPagination: props.showPagination,
+        pageSize: props.pageSize,
+        groupBy: props.groupBy,
+        treeData: props.treeData,
+        initialColumnPinning: props.initialColumnPinning,
+        columnVirtualization: props.columnVirtualization,
+        externalPagination: props.externalPagination,
+        rowCount: props.rowCount,
+        externalSort: props.externalSort,
+        onSortingChange: props.onSortingChange,
+        externalFilter: props.externalFilter,
+        onFiltersChange: props.onFiltersChange,
+      };
+      void import("./validate").then(({ validateGridConfig }) => {
+        for (const message of validateGridConfig(snapshot as never)) {
+          if (warnedConfig.has(message)) continue;
+          warnedConfig.add(message);
+          console.warn(message);
+        }
+      });
+    });
+  }
+
   // Aligned grids: register in the shared group on mount, and mirror column
   // resizes to peers whenever columnWidths changes. Horizontal-scroll mirroring
   // is driven from onBodyScroll (via ctx.broadcastAlignedScroll).

package/src/SvGrid.svelte

@@ -184,6 +184,7 @@
     ctrl.showInlineColumnFilterEffective,
   );
   const showRowSelectionEffective = $derived(ctrl.showRowSelectionEffective);
+  const rowSummariesEnabled = $derived(ctrl.rowSummariesEnabled);
   const grid = $derived(ctrl.grid);
   const allColumns = $derived(ctrl.allColumns);
   const headerGroups = $derived(ctrl.headerGroups);
@@ -2519,7 +2520,7 @@
               {/each}
             </tbody>
           {/if}
-          {#if opt.enableRowSummaries ?? true}
+          {#if rowSummariesEnabled}
             <!-- svelte-ignore a11y_no_redundant_roles -->
             <tfoot class="sv-grid-foot" role="rowgroup">
               <tr