@opencorestack/opengridx 2.0.4 → 3.0.0

package/lib/utils/aggregation/index.ts

@@ -0,0 +1,157 @@
+import type { GridAggregationModel, GridAggregationResult, GridColDef, GridRowModel } from '../../types';
+import { formatLocalDate, getCellValue, toNumber } from '../values';
+
+export type BuiltInAggFn = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'unique';
+
+/**
+ * A value that carries no data for aggregation: null, undefined, or a string that is empty or whitespace
+ * only. Blank cells come from edits, CSV imports and form inputs; they must not count as zero or as an item.
+ */
+/** Stable empty model: no aggregation (e.g. while pivoting, where the Grand Total row is the aggregate). */
+export const NO_AGGREGATION_MODEL: GridAggregationModel = {};
+
+export const isEmptyAggregateValue = (v: unknown): boolean =>
+    v == null || (typeof v === 'string' && v.trim() === '');
+
+// Numeric functions read values with the grid's shared toNumber (as filtering does): numbers, numeric
+// strings and Dates (as timestamps). Booleans, arrays and blank strings are skipped, since Number()
+// would coerce them to 0 or 1 and silently corrupt avg / min / max.
+const toNumbers = (values: unknown[]): number[] => {
+    const nums: number[] = [];
+    for (const v of values) {
+        const n = toNumber(v);
+        if (n !== null) nums.push(n);
+    }
+    return nums;
+};
+
+// The smallest / largest value. A loop, not Math.min(...nums): spreading >~120k arguments throws
+// RangeError. The extreme is returned as it was given when it is a Date, so min / max of a date
+// column is a date (formatted as one) rather than epoch milliseconds.
+const extremeOf = (values: unknown[], isBetter: (a: number, b: number) => boolean): number | Date | null => {
+    let best: number | null = null;
+    let bestValue: unknown = null;
+    for (const v of values) {
+        const n = toNumber(v);
+        if (n === null) continue;
+        if (best === null || isBetter(n, best)) {
+            best = n;
+            bestValue = v;
+        }
+    }
+    if (best === null) return null;
+    return bestValue instanceof Date ? bestValue : best;
+};
+
+export const AGGREGATION_FUNCTIONS: Record<BuiltInAggFn, (values: unknown[]) => unknown> = {
+    sum: (values) => toNumbers(values).reduce((acc, n) => acc + n, 0),
+    avg: (values) => {
+        const nums = toNumbers(values);
+        return nums.length ? nums.reduce((acc, n) => acc + n, 0) / nums.length : null;
+    },
+    count: (values) => values.filter((v) => !isEmptyAggregateValue(v)).length,
+    min: (values) => extremeOf(values, (a, b) => a < b),
+    max: (values) => extremeOf(values, (a, b) => a > b),
+    unique: (values) => new Set(values.filter((v) => !isEmptyAggregateValue(v))).size,
+};
+
+/**
+ * Whether `colDef` may be summarised with `fnName`: not when the column sets `aggregable: false`,
+ * and not with a function outside its `availableAggregationFunctions`. The footer, group rows,
+ * pivot values and exports all go through this, so a model entry the column forbids is ignored.
+ */
+export function isAggregationAllowed<R extends GridRowModel>(colDef: GridColDef<R> | undefined, fnName: string): boolean {
+    if (!colDef) return true;
+    if (colDef.aggregable === false) return false;
+    return !colDef.availableAggregationFunctions || colDef.availableAggregationFunctions.includes(fnName);
+}
+
+/**
+ * Aggregates each `aggregationModel` field over `rows`. Cells are read through the column's
+ * `valueGetter` (getCellValue), so a computed column totals what its cells show.
+ */
+export function computeAggregations<R extends GridRowModel>(
+    rows: R[],
+    aggregationModel: GridAggregationModel,
+    columnsLookup: Map<string, GridColDef<R>>,
+    warnPrefix: string,
+): GridAggregationResult {
+    const result: GridAggregationResult = {};
+    for (const [field, fnName] of Object.entries(aggregationModel)) {
+        const colDef = columnsLookup.get(field);
+        if (!isAggregationAllowed(colDef, fnName)) continue;
+        const fn = AGGREGATION_FUNCTIONS[fnName as BuiltInAggFn];
+        if (!fn) {
+            console.warn(`[${warnPrefix}] Unknown aggregation function: "${fnName}"`);
+            continue;
+        }
+        result[field] = fn(rows.map((row) => getCellValue(row, field, colDef as GridColDef | undefined)));
+    }
+    return result;
+}
+
+/** Default display string for an aggregate: `—` when missing, locale-grouped numbers, avg to 2 decimals. */
+export function formatAggregationValue(value: unknown, fnName: string): string {
+    if (value == null) return '—';
+    if (typeof value === 'number') {
+        if (fnName === 'avg') {
+            return value.toLocaleString(undefined, { maximumFractionDigits: 2 });
+        }
+        return value.toLocaleString();
+    }
+    return String(value);
+}
+
+const COUNT_FUNCTIONS = new Set<string>(['count', 'unique']);
+
+/**
+ * Whether an aggregation result is a number of values rather than a value of the column's kind:
+ * a count of a currency column is not an amount, so the column's valueFormatter must not format it.
+ */
+export function isCountAggregation(fnName: string | undefined): boolean {
+    return fnName !== undefined && COUNT_FUNCTIONS.has(fnName);
+}
+
+/**
+ * The aggregation result in the column's own terms: min / max of a `type: 'date'` column given as
+ * epoch milliseconds (as a server may return it) becomes a Date again.
+ */
+export function normalizeAggregateValue<R extends GridRowModel>(
+    colDef: GridColDef<R> | undefined,
+    fnName: string | undefined,
+    value: unknown,
+): unknown {
+    if (colDef?.type === 'date' && (fnName === 'min' || fnName === 'max') && typeof value === 'number' && Number.isFinite(value)) {
+        return new Date(value);
+    }
+    return value;
+}
+
+/**
+ * Display text for an aggregate of `colDef`'s values, used by the footer, group rows, pivot cells and
+ * every exporter so they all show the same thing.
+ * - count / unique are plain counts in the default format; the column's valueFormatter is not applied.
+ * - sum / avg / min / max go through the column's valueFormatter. Its `row` is the record of aggregated
+ *   values (the group row, the pivot row, or the footer's totals). A formatter that throws, typically
+ *   because it reads row data an aggregate does not have, falls back to the default format.
+ * - Without a formatter, dates show as locale dates and numbers in the default format.
+ */
+export function formatAggregateForColumn<R extends GridRowModel>(
+    value: unknown,
+    fnName: string,
+    colDef?: GridColDef<R>,
+    aggregates?: Record<string, unknown>,
+): string {
+    if (value == null) return '—';
+    if (isCountAggregation(fnName)) return formatAggregationValue(value, fnName);
+    const normalized = normalizeAggregateValue(colDef, fnName, value);
+    if (colDef?.valueFormatter) {
+        try {
+            return String(colDef.valueFormatter({ value: normalized, row: (aggregates ?? {}) as R, field: colDef.field }) ?? '');
+        } catch {
+            // Fall through to the default format rather than failing the whole grid or export.
+        }
+    }
+    if (normalized instanceof Date) return Number.isNaN(normalized.getTime()) ? '' : formatLocalDate(normalized);
+    return formatAggregationValue(normalized, fnName);
+}

package/lib/utils/aria/index.ts

@@ -0,0 +1,40 @@
+export interface GridAriaRowLayoutParams {
+    /** Header rows: the column header row plus any column-group rows. */
+    headerRowCount: number;
+    pinnedTopCount: number;
+    pinnedBottomCount: number;
+    /** Centre rows rendered for the current page. */
+    pageRowCount: number;
+    /** Centre rows across every page (the server's rowCount under server pagination). */
+    totalCenterRowCount: number;
+    /** Centre rows on the pages before the current one. */
+    pageOffset: number;
+}
+
+export interface GridAriaRowLayout {
+    /** `aria-rowcount` of the grid. */
+    rowCount: number;
+    /** `aria-rowindex` of the first top-pinned row. */
+    topBase: number;
+    /** Added to a centre row's `rowIndex` (which counts top-pinned rows) to get its `aria-rowindex`. */
+    centerOffset: number;
+    /** `aria-rowindex` of the first bottom-pinned row. */
+    bottomBase: number;
+    /** `rowIndex` of the first bottom-pinned row (top-pinned + centre rows of this page). */
+    bottomRowIndexOffset: number;
+}
+
+/**
+ * Row positions for assistive technology. Header rows come first; data rows are numbered across
+ * the whole dataset, so page 2 does not restart at 1 and bottom-pinned rows follow every page.
+ */
+export function getAriaRowLayout(params: GridAriaRowLayoutParams): GridAriaRowLayout {
+    const { headerRowCount, pinnedTopCount, pinnedBottomCount, pageRowCount, totalCenterRowCount, pageOffset } = params;
+    return {
+        rowCount: headerRowCount + pinnedTopCount + totalCenterRowCount + pinnedBottomCount,
+        topBase: headerRowCount + 1,
+        centerOffset: headerRowCount + pageOffset + 1,
+        bottomBase: headerRowCount + pinnedTopCount + totalCenterRowCount + 1,
+        bottomRowIndexOffset: pinnedTopCount + pageRowCount,
+    };
+}

package/lib/utils/columnGroups.ts

@@ -0,0 +1,110 @@
+import type { GridColumnGroup, GridColumnGroupingModel, GridPinnedPosition } from '../types';
+
+/** Number of group header rows a model renders (its maximum nesting depth; 0 when there is none). */
+export function getColumnGroupDepth(model?: GridColumnGroupingModel): number {
+    if (!model) return 0;
+    let depth = 0;
+    const walk = (group: GridColumnGroup, level: number) => {
+        depth = Math.max(depth, level);
+        for (const child of group.children) {
+            if (typeof child !== 'string') walk(child, level + 1);
+        }
+    };
+    model.forEach(group => walk(group, 1));
+    return depth;
+}
+
+/** Maps every leaf field to its group path, outermost group first. */
+export function getColumnGroupPaths(model?: GridColumnGroupingModel): Map<string, GridColumnGroup[]> {
+    const paths = new Map<string, GridColumnGroup[]>();
+    if (!model) return paths;
+    const walk = (group: GridColumnGroup, path: GridColumnGroup[]) => {
+        const next = [...path, group];
+        for (const child of group.children) {
+            if (typeof child === 'string') {
+                if (!paths.has(child)) paths.set(child, next);
+            } else {
+                walk(child, next);
+            }
+        }
+    };
+    model.forEach(group => walk(group, []));
+    return paths;
+}
+
+/**
+ * Whether moving `fromField` to the position of `toField` keeps every column group contiguous:
+ * both fields must sit in the same innermost group (or both be ungrouped).
+ */
+export function canReorderWithinColumnGroups(model: GridColumnGroupingModel | undefined, fromField: string, toField: string): boolean {
+    if (!model || model.length === 0) return true;
+    const paths = getColumnGroupPaths(model);
+    const from = paths.get(fromField);
+    const to = paths.get(toField);
+    return (from?.[from.length - 1] ?? null) === (to?.[to.length - 1] ?? null);
+}
+
+export interface ColumnGroupRowColumn {
+    field: string;
+    width: number;
+    flex?: number;
+    pinned: GridPinnedPosition | null;
+    /** Horizontal-virtualization spacer: counts as ungrouped width. */
+    isSpacer?: boolean;
+}
+
+export interface ColumnGroupRowCell {
+    key: string;
+    isGroup: boolean;
+    label: string;
+    headerClassName?: string;
+    width: number;
+    flexGrow: number;
+    /** Data (non-spacer) fields the cell covers, in order. */
+    fields: string[];
+    /** Index of the first covered data column among all rendered data columns. */
+    firstDataIndex: number;
+    pinned: GridPinnedPosition | null;
+}
+
+/**
+ * Builds one group header row (level 0 = outermost). Consecutive columns that share the group at
+ * `level` and the same pinned section form one cell; consecutive ungrouped columns form one filler.
+ * A group whose columns are not adjacent (hidden columns excepted) renders one cell per run.
+ */
+export function buildColumnGroupRow(
+    columns: ColumnGroupRowColumn[],
+    paths: Map<string, GridColumnGroup[]>,
+    level: number,
+): ColumnGroupRowCell[] {
+    const cells: ColumnGroupRowCell[] = [];
+    let dataIndex = 0;
+    let current: ColumnGroupRowCell | null = null;
+    let currentGroup: GridColumnGroup | null = null;
+
+    for (const column of columns) {
+        const group = column.isSpacer ? null : (paths.get(column.field)?.[level] ?? null);
+        if (current === null || currentGroup !== group || current.pinned !== column.pinned) {
+            current = {
+                key: `${group ? group.groupId : 'filler'}-${level}-${column.field}`,
+                isGroup: group !== null,
+                label: group?.headerName ?? '',
+                headerClassName: group?.headerClassName,
+                width: 0,
+                flexGrow: 0,
+                fields: [],
+                firstDataIndex: dataIndex,
+                pinned: column.pinned,
+            };
+            currentGroup = group;
+            cells.push(current);
+        }
+        current.width += column.width;
+        current.flexGrow += column.flex ?? 0;
+        if (!column.isSpacer) {
+            current.fields.push(column.field);
+            dataIndex++;
+        }
+    }
+    return cells;
+}

package/lib/utils/columnLookup.ts

@@ -0,0 +1,33 @@
+import type { GridColDef } from '../types';
+
+/**
+ * Column information the client-side filter and sort need: the column definition for each field
+ * (for `valueGetter` and `type`) and the columns the quick filter searches.
+ */
+export interface GridColumnLookup {
+    /** Column definitions keyed by field. */
+    byField: ReadonlyMap<string, GridColDef>;
+    /** Visible, filterable columns. The quick filter searches only these. */
+    quickFilterColumns: readonly GridColDef[];
+}
+
+/**
+ * Build the lookup from the grid's columns. Columns hidden through `columnVisibilityModel`,
+ * columns with `filterable: false` and internal `__`-prefixed columns are not searched by the
+ * quick filter; column filter items still apply to every column.
+ */
+export function buildColumnLookup(
+    columns: readonly GridColDef[],
+    columnVisibilityModel: Record<string, boolean> = {},
+): GridColumnLookup {
+    const byField = new Map<string, GridColDef>();
+    const quickFilterColumns: GridColDef[] = [];
+    for (const col of columns) {
+        byField.set(col.field, col);
+        if (col.isSpacer || col.field.startsWith('__')) continue;
+        if (col.filterable === false) continue;
+        if (columnVisibilityModel[col.field] === false) continue;
+        quickFilterColumns.push(col);
+    }
+    return { byField, quickFilterColumns };
+}

package/lib/utils/columnWidth.ts

@@ -0,0 +1,22 @@
+import type { GridColDef, GridRowModel } from '../types';
+
+/** Clamps a column width the way CSS applies `min-width` / `max-width` (min-width wins a conflict). */
+export function clampColumnWidth(width: number, minWidth?: number, maxWidth?: number): number {
+    return Math.max(minWidth ?? 0, Math.min(maxWidth ?? Infinity, width));
+}
+
+/**
+ * The width a rendered column occupies: the user's resize override, else its width (the
+ * layout-resolved pixel width for grid columns), clamped to `minWidth` / `maxWidth` exactly as
+ * the cell and header CSS clamp it. Non-numeric widths fall back to `fallback`.
+ */
+export function getRenderedColumnWidth<R extends GridRowModel>(
+    col: GridColDef<R>,
+    columnWidths: Record<string, number>,
+    fallback = 100,
+): number {
+    if (col.isSpacer) return typeof col.width === 'number' ? col.width : 0;
+    const raw = columnWidths[col.field] ?? col.width;
+    const width = typeof raw === 'number' && Number.isFinite(raw) ? raw : fallback;
+    return clampColumnWidth(width, col.minWidth, col.maxWidth);
+}

package/lib/utils/dataSource/index.ts

@@ -0,0 +1,46 @@
+export interface ServerDrivenParams {
+    dataSource?: unknown;
+    paginationMode?: string;
+    sortingMode?: string;
+    filterMode?: string;
+}
+
+/**
+ * True when a dataSource is present and the server shapes the rows: any of pagination (including
+ * infinite scroll), sorting or filtering is done on the server. The grid then holds only the rows
+ * the server returned, so anything computed over "all rows" (such as aggregation totals) must come
+ * from the server. With every mode on 'client' the grid fetches all rows once and computes
+ * everything itself.
+ */
+export function isServerDrivenDataSource({ dataSource, paginationMode, sortingMode, filterMode }: ServerDrivenParams): boolean {
+    return Boolean(dataSource) && (
+        paginationMode === 'server'
+        || paginationMode === 'infinite'
+        || sortingMode === 'server'
+        || filterMode === 'server'
+    );
+}
+
+/**
+ * `endRow` of a request for every row: sent when the grid pages on the client (`paginationMode`
+ * 'client') and when it loads the children of a server-side tree node. `endRow` is exclusive, and
+ * `Number.MAX_SAFE_INTEGER` keeps both `rows.slice(startRow, endRow)` and
+ * `LIMIT endRow - startRow` returning everything while staying JSON-serializable.
+ */
+export const GRID_ALL_ROWS_END_ROW = Number.MAX_SAFE_INTEGER;
+
+/** Shown when a failed getRows call gives no usable message. */
+export const DATA_SOURCE_ERROR_FALLBACK_MESSAGE = 'An unexpected error occurred while loading the data.';
+
+/**
+ * The message of the value a getRows call rejected with: an `Error`, a string, or any object with a
+ * string `message` (the usual shape of fetch and HTTP-client errors).
+ */
+export function getDataSourceErrorMessage(error: unknown): string {
+    if (typeof error === 'string' && error) return error;
+    if (typeof error === 'object' && error !== null && 'message' in error
+        && typeof error.message === 'string' && error.message) {
+        return error.message;
+    }
+    return DATA_SOURCE_ERROR_FALLBACK_MESSAGE;
+}

package/lib/utils/detailPanel.ts

@@ -0,0 +1,66 @@
+import type { GridDetailPanelHeight, GridRowId, GridRowMeta } from '../types';
+import { callSafely } from './values';
+
+/** Panel height used when `getDetailPanelHeight` is omitted or returns something unusable. */
+export const DEFAULT_DETAIL_PANEL_HEIGHT = 200;
+
+/**
+ * Normalises a `getDetailPanelHeight` result. The layout and the rendered panel both go through
+ * this, so they always agree: `0` is a 0px panel, `'auto'` fits the content, and a missing,
+ * negative or non-numeric value is the 200px default.
+ */
+export function resolveDetailPanelHeight(height: GridDetailPanelHeight | string | null | undefined): number | 'auto' {
+    if (height === 'auto') return 'auto';
+    const value = typeof height === 'string' ? Number.parseFloat(height) : height;
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0) return value;
+    return DEFAULT_DETAIL_PANEL_HEIGHT;
+}
+
+/**
+ * Calls `getDetailPanelHeight`; a callback that throws gets the default height (with a one-time
+ * dev warning) instead of crashing the grid. The layout and both row renderers call this.
+ */
+export function callGetDetailPanelHeight<P>(
+    getDetailPanelHeight: ((params: P) => GridDetailPanelHeight) | undefined,
+    params: P,
+): GridDetailPanelHeight | undefined {
+    if (!getDetailPanelHeight) return undefined;
+    return callSafely<GridDetailPanelHeight | undefined>(
+        () => getDetailPanelHeight(params),
+        undefined,
+        'getDetailPanelHeight',
+        'getDetailPanelHeight threw; the panel uses the default height',
+    );
+}
+
+/**
+ * The height the layout reserves for an expanded panel: its fixed height, or for an `'auto'`
+ * panel the height it was measured at (the default until it has rendered once).
+ */
+export function getDetailPanelLayoutHeight(
+    height: GridDetailPanelHeight | string | null | undefined,
+    measuredHeight: number | undefined,
+): number {
+    const resolved = resolveDetailPanelHeight(height);
+    if (resolved === 'auto') return measuredHeight ?? DEFAULT_DETAIL_PANEL_HEIGHT;
+    return resolved;
+}
+
+/**
+ * The expanded detail-panel ids that can actually show a panel: synthetic hierarchy rows
+ * (row-grouping groups, generated tree parents) have no detail panel, so an id of one in a
+ * controlled `detailPanelExpandedRowIds` is ignored. Returns the same set when nothing is dropped.
+ */
+export function getDetailPanelRowIds(
+    expandedRowIds: Set<GridRowId>,
+    rowMetaMap: ReadonlyMap<GridRowId, GridRowMeta>,
+): Set<GridRowId> {
+    if (rowMetaMap.size === 0 || expandedRowIds.size === 0) return expandedRowIds;
+    let dropped = false;
+    const ids = new Set<GridRowId>();
+    for (const id of expandedRowIds) {
+        if (rowMetaMap.get(id)?.isGroupRow) dropped = true;
+        else ids.add(id);
+    }
+    return dropped ? ids : expandedRowIds;
+}

package/lib/utils/dragData.ts

@@ -0,0 +1,44 @@
+/**
+ * HTML5 drag-and-drop helpers shared by row and column reorder.
+ *
+ * Each reorder drag puts a MIME type of its own into the DataTransfer. Firefox only starts a drag
+ * when dragstart sets some data, and drop targets use the type to accept only the grid's own drag,
+ * so a file, a text selection or another grid's drag is never taken for a reorder.
+ */
+
+export const ROW_DRAG_MIME = 'application/x-ogx-row';
+export const COLUMN_DRAG_MIME = 'application/x-ogx-column';
+
+interface DragEventLike {
+    dataTransfer?: Partial<Pick<DataTransfer, 'setData' | 'types'>> | null;
+}
+
+/** Stores the drag token (and a plain-text copy) on dragstart. */
+export function setDragToken(event: DragEventLike, mime: string, value: string): void {
+    const dataTransfer = event.dataTransfer;
+    if (!dataTransfer || typeof dataTransfer.setData !== 'function') return;
+    dataTransfer.setData(mime, value);
+    dataTransfer.setData('text/plain', value);
+}
+
+/**
+ * False when the drag carries data types and the grid's token is not among them. When the
+ * browser (or a test double) exposes no type list, the drag is not rejected on that ground.
+ */
+export function hasDragToken(event: DragEventLike, mime: string): boolean {
+    const types = event.dataTransfer?.types;
+    if (!types) return true;
+    return Array.from(types).includes(mime);
+}
+
+/**
+ * Calls `onEnd` once when the drag that started on `source` ends. The listener sits on the
+ * source node itself, so it also fires when that node has been unmounted mid-drag (a virtualized
+ * row scrolled out of the render window), which React's delegated `onDragEnd` never sees.
+ */
+export function onNativeDragEnd(source: EventTarget | null | undefined, onEnd: () => void): () => void {
+    if (!source || typeof source.addEventListener !== 'function') return () => {};
+    const handler = () => onEnd();
+    source.addEventListener('dragend', handler, { once: true });
+    return () => source.removeEventListener('dragend', handler);
+}

package/lib/utils/editing/index.ts

@@ -0,0 +1,30 @@
+import type { GridCellParams, GridRowMeta, GridRowModel } from '../../types';
+
+// Cells are read through the one `getCellValue` in `lib/utils/values`.
+
+export interface CellEditabilityParams<R extends GridRowModel = GridRowModel> extends GridCellParams<R> {
+    rowMeta?: GridRowMeta;
+}
+
+/**
+ * Whether a body cell may enter edit mode. Double-click, Enter, Tab stops and `aria-readonly` all use
+ * this one rule:
+ * - the column must have `editable: true` (`isCellEditable` can only restrict, never grant);
+ * - the row must be a real data row, not a synthetic row-grouping header or an auto-generated tree
+ *   ancestor (`rowMeta.isGroupRow`). Tree-data parents are real rows and stay editable;
+ * - `isCellEditable`, when given, must return true. A predicate that throws counts as read-only.
+ */
+export function resolveCellEditable<R extends GridRowModel>(
+    params: CellEditabilityParams<R>,
+    isCellEditable?: (params: GridCellParams<R>) => boolean
+): boolean {
+    const { row, field, value, colDef, rowIndex, colIndex, rowMeta } = params;
+    if (!colDef.editable) return false;
+    if (rowMeta?.isGroupRow || row._isSkeleton) return false;
+    if (!isCellEditable) return true;
+    try {
+        return Boolean(isCellEditable({ row, field, value, colDef, rowIndex, colIndex }));
+    } catch {
+        return false;
+    }
+}