@opencorestack/opengridx 3.2.2 → 3.4.0

package/lib/utils/cellSelection.ts

@@ -0,0 +1,238 @@
+import type { GridCellCoordinates, GridCellRange, GridCellSelectionModel, GridRowId } from '../types';
+import { isSystemField } from './focus';
+
+/**
+ * Pure helpers of cell range selection (`cellSelection`). A range is stored as two corner cells
+ * (ids and fields); everything here works it out against the current display order.
+ */
+
+/** The synthetic row-grouping column. Like the system columns, it never joins a range. */
+export const GROUPING_COLUMN_FIELD = '__group__';
+
+/** Whether cells of this column can be part of a range: data columns only. */
+export function isRangeColumnField(field: string): boolean {
+    return !isSystemField(field) && field !== GROUPING_COLUMN_FIELD;
+}
+
+export const isSameCoordinates = (a: GridCellCoordinates | null | undefined, b: GridCellCoordinates | null | undefined): boolean =>
+    a === b || (!!a && !!b && a.id === b.id && a.field === b.field);
+
+export const isSingleCellRange = (range: GridCellRange): boolean => isSameCoordinates(range.anchor, range.head);
+
+/** A model holding the same range(s) as `b`. */
+export function isSameCellSelectionModel(a: GridCellSelectionModel, b: GridCellSelectionModel): boolean {
+    if (a === b) return true;
+    if (a.length !== b.length) return false;
+    return a.every((range, i) => isSameCoordinates(range.anchor, b[i].anchor) && isSameCoordinates(range.head, b[i].head));
+}
+
+/** A rectangle in display indices: rows of the renderable rows, columns of the range columns. Inclusive. */
+export interface CellRangeRect {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+
+/** The rectangle of a range, plus where its two corners are. */
+export interface ResolvedCellRange extends CellRangeRect {
+    anchorRow: number;
+    anchorCol: number;
+    headRow: number;
+    headCol: number;
+}
+
+/** Span information, from useGridSpanning. */
+export interface CellRangeSpanLookup {
+    /** For a cell covered by a span, the origin cell of that span; `null` for any other cell. */
+    getSpanOrigin: (rowId: GridRowId, field: string) => { rowId: GridRowId; field: string } | null;
+    /** The colSpan of a span origin (1 for other cells). */
+    getColSpan: (rowId: GridRowId, field: string) => number;
+    /** The rowSpan of a span origin (1 for other cells). */
+    getRowSpan: (rowId: GridRowId, field: string) => number;
+}
+
+export interface CellRangeContext {
+    /** Ids of the renderable rows (top-pinned, page rows, bottom-pinned), in display order. */
+    rowIds: readonly GridRowId[];
+    rowIndexById: ReadonlyMap<GridRowId, number>;
+    /** Range columns in screen order: left-pinned, centre, right-pinned. */
+    fields: readonly string[];
+    colIndexByField: ReadonlyMap<string, number>;
+    /** Present when the grid has column or row spans. */
+    spans?: CellRangeSpanLookup;
+}
+
+/** The merged area (span) that contains a cell, or the cell itself. */
+function mergedArea(r: number, c: number, ctx: CellRangeContext): CellRangeRect {
+    const { rowIds, fields, rowIndexById, colIndexByField, spans } = ctx;
+    const single = { top: r, bottom: r, left: c, right: c };
+    if (!spans) return single;
+    const rowId = rowIds[r];
+    const field = fields[c];
+    const origin = spans.getSpanOrigin(rowId, field) ?? { rowId, field };
+    const originRow = rowIndexById.get(origin.rowId);
+    const originCol = colIndexByField.get(origin.field);
+    if (originRow === undefined || originCol === undefined) return single;
+    const rowSpan = Math.max(1, spans.getRowSpan(origin.rowId, origin.field));
+    const colSpan = Math.max(1, spans.getColSpan(origin.rowId, origin.field));
+    return {
+        top: originRow,
+        bottom: Math.min(rowIds.length - 1, originRow + rowSpan - 1),
+        left: originCol,
+        right: Math.min(fields.length - 1, originCol + colSpan - 1),
+    };
+}
+
+/**
+ * Grows a rectangle until no span crosses its edge, as Excel does with merged cells. A span that
+ * crosses the edge holds a cell on the edge, so only the edge cells are looked at.
+ */
+export function growRectToSpans(rect: CellRangeRect, ctx: CellRangeContext): CellRangeRect {
+    if (!ctx.spans) return rect;
+    let { top, bottom, left, right } = rect;
+    let changed = true;
+    const take = (area: CellRangeRect) => {
+        if (area.top < top) { top = area.top; changed = true; }
+        if (area.bottom > bottom) { bottom = area.bottom; changed = true; }
+        if (area.left < left) { left = area.left; changed = true; }
+        if (area.right > right) { right = area.right; changed = true; }
+    };
+    while (changed) {
+        changed = false;
+        for (let r = top; r <= bottom; r++) {
+            take(mergedArea(r, left, ctx));
+            if (right !== left) take(mergedArea(r, right, ctx));
+        }
+        for (let c = left + 1; c < right; c++) {
+            take(mergedArea(top, c, ctx));
+            if (bottom !== top) take(mergedArea(bottom, c, ctx));
+        }
+    }
+    return { top, bottom, left, right };
+}
+
+/**
+ * Where a range lies in the current display order, or `null` when one of its corners is not
+ * displayed (its row was filtered, paged or removed, or its column hidden).
+ */
+export function resolveCellRange(range: GridCellRange, ctx: CellRangeContext): ResolvedCellRange | null {
+    const anchorRow = ctx.rowIndexById.get(range.anchor.id);
+    const headRow = ctx.rowIndexById.get(range.head.id);
+    const anchorCol = ctx.colIndexByField.get(range.anchor.field);
+    const headCol = ctx.colIndexByField.get(range.head.field);
+    if (anchorRow === undefined || headRow === undefined || anchorCol === undefined || headCol === undefined) return null;
+    const rect = growRectToSpans({
+        top: Math.min(anchorRow, headRow),
+        bottom: Math.max(anchorRow, headRow),
+        left: Math.min(anchorCol, headCol),
+        right: Math.max(anchorCol, headCol),
+    }, ctx);
+    return { ...rect, anchorRow, anchorCol, headRow, headCol };
+}
+
+export const rectCellCount = (rect: CellRangeRect): number => (rect.bottom - rect.top + 1) * (rect.right - rect.left + 1);
+
+/**
+ * The new head for a Shift+navigation key, as display indices, or `null` when it does not move.
+ * Shift+Arrow moves one cell and does not wrap to the next row. Extending moves from the far edge
+ * of the rectangle, so the head steps out of a span it grew over.
+ */
+export function nextRangeHead(
+    resolved: ResolvedCellRange,
+    key: string,
+    withModifier: boolean,
+    pageSize: number,
+    lastRow: number,
+    lastCol: number,
+): { row: number; col: number } | null {
+    const { headRow, headCol, anchorRow, anchorCol, top, bottom, left, right } = resolved;
+    let row = headRow;
+    let col = headCol;
+    switch (key) {
+        case 'ArrowRight': col = headCol >= anchorCol ? right + 1 : headCol + 1; break;
+        case 'ArrowLeft': col = headCol <= anchorCol ? left - 1 : headCol - 1; break;
+        case 'ArrowDown': row = headRow >= anchorRow ? bottom + 1 : headRow + 1; break;
+        case 'ArrowUp': row = headRow <= anchorRow ? top - 1 : headRow - 1; break;
+        case 'Home':
+            col = 0;
+            if (withModifier) row = 0;
+            break;
+        case 'End':
+            col = lastCol;
+            if (withModifier) row = lastRow;
+            break;
+        case 'PageUp': row = headRow - pageSize; break;
+        case 'PageDown': row = headRow + pageSize; break;
+        default: return null;
+    }
+    row = Math.min(Math.max(row, 0), lastRow);
+    col = Math.min(Math.max(col, 0), lastCol);
+    if (row === headRow && col === headCol) return null;
+    return { row, col };
+}
+
+/**
+ * The range flags one row passes to its cells, or `null` for a row outside the range. Rows outside
+ * keep `null`, so a drag only re-renders the rows it enters or leaves. `left` / `right` are data
+ * column indices (`columnIndexMap`).
+ */
+export interface GridRowCellRange {
+    left: number;
+    right: number;
+    isTop: boolean;
+    isBottom: boolean;
+    /** Rows from this one to the bottom of the range; only set (else 0) when the grid has row spans. */
+    bottomOffset: number;
+}
+
+export function getRowCellRange(
+    range: { top: number; bottom: number; left: number; right: number } | null | undefined,
+    rowIndex: number,
+    hasRowSpan: boolean,
+): GridRowCellRange | null {
+    if (!range || rowIndex < range.top || rowIndex > range.bottom) return null;
+    return {
+        left: range.left,
+        right: range.right,
+        isTop: rowIndex === range.top,
+        isBottom: rowIndex === range.bottom,
+        bottomOffset: hasRowSpan ? range.bottom - rowIndex : 0,
+    };
+}
+
+export const isSameRowCellRange = (a: GridRowCellRange | null | undefined, b: GridRowCellRange | null | undefined): boolean =>
+    a === b || (!!a && !!b && a.left === b.left && a.right === b.right && a.isTop === b.isTop && a.isBottom === b.isBottom
+        && a.bottomOffset === b.bottomOffset);
+
+/** Bit flags a cell receives for its place in the range (a number keeps memoised cells stable). */
+export const RANGE_CELL = 1;
+export const RANGE_TOP = 2;
+export const RANGE_BOTTOM = 4;
+export const RANGE_LEFT = 8;
+export const RANGE_RIGHT = 16;
+
+/**
+ * The flags of the cell at data column `colIndex` (spanning `colSpan` columns and `rowSpan` rows from
+ * this row), or 0 when it is outside the range.
+ */
+export function getCellRangeFlags(rowRange: GridRowCellRange | null | undefined, colIndex: number, colSpan: number, rowSpan: number): number {
+    if (!rowRange) return 0;
+    const lastCol = colIndex + Math.max(1, colSpan) - 1;
+    if (colIndex < rowRange.left || lastCol > rowRange.right) return 0;
+    let flags = RANGE_CELL;
+    if (rowRange.isTop) flags |= RANGE_TOP;
+    if (rowRange.isBottom || (rowSpan > 1 && rowSpan - 1 >= rowRange.bottomOffset)) flags |= RANGE_BOTTOM;
+    if (colIndex === rowRange.left) flags |= RANGE_LEFT;
+    if (lastCol === rowRange.right) flags |= RANGE_RIGHT;
+    return flags;
+}
+
+/** The default screen-reader text after a range change. */
+export function defaultCellSelectionAnnouncement(cellCount: number, rowCount: number, columnCount: number): string {
+    const plural = (n: number, one: string, many: string) => `${n} ${n === 1 ? one : many}`;
+    return `${plural(cellCount, 'cell', 'cells')} selected, ${plural(rowCount, 'row', 'rows')} by ${plural(columnCount, 'column', 'columns')}`;
+}
+
+/** Above this many cells a copy warns (development only) that exportToCsv suits the job better. */
+export const LARGE_RANGE_COPY_CELLS = 100_000;

package/lib/utils/editing/commit.ts

@@ -0,0 +1,69 @@
+import type { GridColDef, GridRowId, GridRowModel } from '../../types';
+
+/**
+ * The steps every committed edit shares: a single-cell edit (`useGridEditing`) and a batch edit
+ * (`useGridBatchEdit`: paste, range clear, undo, redo) build the row the same way and report errors
+ * the same way.
+ */
+
+/** A misuse of the editing contract (e.g. processRowUpdate returned nothing), as opposed to a consumer rejection. */
+export class OpenGridXEditError extends Error {}
+
+/** One committed cell change: the value before and the value stored after (both read through `getCellValue`). */
+export interface GridCellChange {
+    id: GridRowId;
+    field: string;
+    before: unknown;
+    after: unknown;
+}
+
+/** Cell values compare equal: dates by time, anything else with `Object.is`. */
+export function isSameValue(a: unknown, b: unknown): boolean {
+    if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+    return Object.is(a, b);
+}
+
+export function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+    return typeof value === 'object' && value !== null && typeof (value as { then?: unknown }).then === 'function';
+}
+
+/**
+ * Sends an edit failure to `onProcessRowUpdateError`. Without one, a misuse of the contract is logged
+ * in development; a consumer rejection is the consumer's own and stays silent.
+ */
+export function reportEditError(error: unknown, onError: ((error: unknown) => void) | undefined): void {
+    if (onError) {
+        onError(error);
+    } else if (process.env.NODE_ENV !== 'production' && error instanceof OpenGridXEditError) {
+        console.error(error.message);
+    }
+}
+
+/** The error for a `processRowUpdate` that resolved to something other than a row object. */
+export function invalidProcessedRowError(processed: unknown, outcome: string): OpenGridXEditError {
+    return new OpenGridXEditError(
+        `[OpenGridX] processRowUpdate must return the updated row object (or a Promise of it); ` +
+        `it returned ${processed === null ? 'null' : typeof processed}. ${outcome}`
+    );
+}
+
+/** The row with one cell changed: through the column's `valueSetter`, else `row[field] = value`. */
+export function buildEditedRow<R extends GridRowModel>(
+    row: R,
+    cell: { field: string; value: unknown },
+    colDef: GridColDef<R> | undefined,
+    warnedFields: Set<string>
+): R {
+    if (colDef?.valueSetter) {
+        return colDef.valueSetter({ value: cell.value, row, field: cell.field });
+    }
+    if (colDef?.valueGetter && process.env.NODE_ENV !== 'production' && !warnedFields.has(cell.field)) {
+        warnedFields.add(cell.field);
+        console.warn(
+            `[OpenGridX] Column "${cell.field}" is editable and has a valueGetter but no valueSetter. ` +
+            `The edited value was written to row["${cell.field}"], which the valueGetter may ignore, so the cell ` +
+            'can keep showing the old value. Add a valueSetter that maps the value back onto the row.'
+        );
+    }
+    return { ...row, [cell.field]: cell.value };
+}

package/lib/utils/editing/targets.ts

@@ -0,0 +1,109 @@
+import type { GridCellCoordinates, GridCellParams, GridColDef, GridRowId, GridRowMeta, GridRowModel } from '../../types';
+import { isRangeColumnField } from '../cellSelection';
+import type { CellRangeRect } from '../cellSelection';
+import { isSystemField } from '../focus';
+import { isSyntheticRowId } from '../syntheticRows';
+import { resolveCellEditable } from './index';
+import { getCellValue } from '../values';
+
+/**
+ * Where batch edits (paste, range clear, undo/redo) land: the renderable rows and the range columns
+ * (data columns, no system or grouping column) in display order, the same coordinates as a cell range.
+ */
+export interface GridEditTargetContext<R extends GridRowModel> {
+    rows: readonly R[];
+    rowIds: GridRowId[];
+    rowIndexById: Map<GridRowId, number>;
+    /** Range columns in screen order. */
+    columns: GridColDef<R>[];
+    colIndexByField: Map<string, number>;
+    /** Number of system columns before the data columns (for `isCellEditable`'s `colIndex`). */
+    dataColumnOffset: number;
+}
+
+export function buildEditTargetContext<R extends GridRowModel>(
+    rows: readonly R[],
+    getRowId: (row: R) => GridRowId,
+    navigationColumns: ReadonlyArray<GridColDef<R>>,
+): GridEditTargetContext<R> {
+    const rowIds = rows.map(getRowId);
+    const rowIndexById = new Map<GridRowId, number>();
+    rowIds.forEach((id, index) => { if (!rowIndexById.has(id)) rowIndexById.set(id, index); });
+    const columns = navigationColumns.filter(c => isRangeColumnField(c.field));
+    const colIndexByField = new Map<string, number>();
+    columns.forEach((c, index) => { colIndexByField.set(c.field, index); });
+    const dataColumnOffset = navigationColumns.filter(c => isSystemField(c.field)).length;
+    return { rows, rowIds, rowIndexById, columns, colIndexByField, dataColumnOffset };
+}
+
+export interface GridEditTargetRules<R extends GridRowModel> {
+    isCellEditable?: (params: GridCellParams<R>) => boolean;
+    rowMetaMap?: ReadonlyMap<GridRowId, GridRowMeta>;
+    /** For a cell covered by a span, the origin cell (`null` otherwise). */
+    getSpanOrigin?: (rowId: GridRowId, field: string) => { rowId: GridRowId; field: string } | null;
+}
+
+/**
+ * Whether a batch edit may write the cell at display position (r, c): a data row (not synthetic),
+ * not covered by a span whose origin is another cell, and editable by the same rule as double-click.
+ */
+export function isEditTargetWritable<R extends GridRowModel>(
+    ctx: GridEditTargetContext<R>,
+    rules: GridEditTargetRules<R>,
+    row: R,
+    r: number,
+    c: number,
+): boolean {
+    const id = ctx.rowIds[r];
+    const colDef = ctx.columns[c];
+    if (!colDef || isSyntheticRowId(id, rules.rowMetaMap)) return false;
+    const origin = rules.getSpanOrigin?.(id, colDef.field);
+    if (origin && (origin.rowId !== id || origin.field !== colDef.field)) return false;
+    return resolveCellEditable({
+        row,
+        field: colDef.field,
+        value: getCellValue(row, colDef.field, colDef),
+        colDef,
+        rowIndex: r,
+        colIndex: ctx.dataColumnOffset + c,
+        rowMeta: rules.rowMetaMap?.get(id),
+    }, rules.isCellEditable);
+}
+
+/** The rectangle around the displayed cells among `cells`, or null when none is displayed. */
+export function boundingTargetRect<R extends GridRowModel>(
+    ctx: GridEditTargetContext<R>,
+    cells: ReadonlyArray<{ id: GridRowId; field: string }>,
+): CellRangeRect | null {
+    let top = Infinity;
+    let bottom = -Infinity;
+    let left = Infinity;
+    let right = -Infinity;
+    for (const cell of cells) {
+        const r = ctx.rowIndexById.get(cell.id);
+        const c = ctx.colIndexByField.get(cell.field);
+        if (r === undefined || c === undefined) continue;
+        if (r < top) top = r;
+        if (r > bottom) bottom = r;
+        if (c < left) left = c;
+        if (c > right) right = c;
+    }
+    return top === Infinity ? null : { top, bottom, left, right };
+}
+
+/** The two corner cells of a rectangle. */
+export function rectCorners<R extends GridRowModel>(
+    ctx: GridEditTargetContext<R>,
+    rect: CellRangeRect,
+): { anchor: GridCellCoordinates; head: GridCellCoordinates } {
+    return {
+        anchor: { id: ctx.rowIds[rect.top], field: ctx.columns[rect.left].field },
+        head: { id: ctx.rowIds[rect.bottom], field: ctx.columns[rect.right].field },
+    };
+}
+
+/** Columns whose empty value is `''` rather than `null`. */
+export function isTextColumn(colDef: Pick<GridColDef, 'type'> | undefined): boolean {
+    const type = colDef?.type;
+    return type === undefined || type === 'string' || type === 'image';
+}

package/lib/utils/headerWrap.ts

@@ -0,0 +1,23 @@
+/**
+ * Line height of a wrapped header title in pixels. Must match `line-height` of
+ * `.ogx__header-cell--wrap .ogx__header-cell-title` in Header.css.
+ */
+export const HEADER_WRAP_LINE_HEIGHT = 16;
+
+/** Vertical padding of a header cell (`--ogx-grid-cell-padding-y`, 8px by default), top plus bottom. */
+const HEADER_VERTICAL_PADDING = 16;
+
+/**
+ * How many lines a wrapped header title may take inside a header of `headerHeight` pixels: 2 at 56px,
+ * 3 at 72px, 4 at 88px. One line less when the aggregation label sits under the title. Never below 1.
+ */
+export function getHeaderLineClamp(headerHeight: number, hasAggregationLabel = false): number {
+    const available = Number.isFinite(headerHeight) ? headerHeight - HEADER_VERTICAL_PADDING : 0;
+    const lines = Math.floor(available / HEADER_WRAP_LINE_HEIGHT) - (hasAggregationLabel ? 1 : 0);
+    return Math.max(1, lines);
+}
+
+/** Whether a column's header title wraps: the column's own `wrapHeaderText` wins over the grid's. */
+export function shouldWrapHeaderText(columnWrap: boolean | undefined, gridWrap: boolean | undefined): boolean {
+    return columnWrap ?? gridWrap ?? false;
+}