@opencorestack/opengridx 3.4.0 → 3.5.1

package/lib/utils/editing/fill.ts

@@ -0,0 +1,238 @@
+import type { GridFillDirection, GridRowId } from '../../types';
+import type { CellRangeRect } from '../cellSelection';
+
+/**
+ * Pure helpers of the fill handle (v3.5): what a fill writes (series detection) and where (the target
+ * rectangle the pointer asks for, the cells of each line).
+ */
+
+/** Digits after the decimal point of a finite number, or null for exponent notation. */
+function decimalPlaces(value: number): number | null {
+    const text = String(value);
+    if (text.includes('e') || text.includes('E')) return null;
+    const dot = text.indexOf('.');
+    return dot === -1 ? 0 : text.length - dot - 1;
+}
+
+/** Rounds to `places` decimals (no rounding for null), so 0.1 + 0.2 reads 0.3. */
+function roundTo(value: number, places: number | null): number {
+    if (places === null) return value;
+    return Number(value.toFixed(Math.min(places, 20)));
+}
+
+function numberSeries(source: readonly number[], count: number): number[] | null {
+    let places: number | null = 0;
+    for (const value of source) {
+        const p = decimalPlaces(value);
+        places = p === null || places === null ? null : Math.max(places, p);
+    }
+    const step = roundTo(source[1] - source[0], places);
+    for (let i = 2; i < source.length; i++) {
+        if (roundTo(source[i] - source[i - 1], places) !== step) return null;
+    }
+    const last = source[source.length - 1];
+    const out: number[] = [];
+    for (let k = 1; k <= count; k++) out.push(roundTo(last + step * k, places));
+    return out;
+}
+
+const MS_PER_DAY = 86_400_000;
+const timeOfDay = (d: Date) => ((d.getHours() * 60 + d.getMinutes()) * 60 + d.getSeconds()) * 1000 + d.getMilliseconds();
+const dayNumber = (d: Date) => Math.round(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()) / MS_PER_DAY);
+const monthNumber = (d: Date) => d.getFullYear() * 12 + d.getMonth();
+const daysInMonth = (year: number, month: number) => new Date(year, month + 1, 0).getDate();
+
+/** The equal step between consecutive keys, or null. */
+function equalStep(keys: readonly number[]): number | null {
+    const step = keys[1] - keys[0];
+    for (let i = 2; i < keys.length; i++) {
+        if (keys[i] - keys[i - 1] !== step) return null;
+    }
+    return step;
+}
+
+function dateSeries(source: readonly Date[], count: number): Date[] | null {
+    const last = source[source.length - 1];
+    const sameTime = source.every(d => timeOfDay(d) === timeOfDay(last));
+    // Same day of the month, months apart by an equal step: continue by months (31 Jan + 1 month is
+    // the last day of February).
+    if (sameTime && source.every(d => d.getDate() === last.getDate())) {
+        const step = equalStep(source.map(monthNumber));
+        if (step !== null && step !== 0) {
+            const out: Date[] = [];
+            for (let k = 1; k <= count; k++) {
+                const month = last.getMonth() + step * k;
+                const year = last.getFullYear() + Math.floor(month / 12);
+                const m = ((month % 12) + 12) % 12;
+                const date = new Date(last.getTime());
+                date.setFullYear(year, m, Math.min(last.getDate(), daysInMonth(year, m)));
+                out.push(date);
+            }
+            return out;
+        }
+    }
+    // Whole days apart (calendar days, so a daylight-saving change does not break the step).
+    if (sameTime) {
+        const step = equalStep(source.map(dayNumber));
+        if (step === null) return null;
+        const out: Date[] = [];
+        for (let k = 1; k <= count; k++) {
+            const date = new Date(last.getTime());
+            date.setDate(last.getDate() + step * k);
+            out.push(date);
+        }
+        return out;
+    }
+    const step = equalStep(source.map(d => d.getTime()));
+    if (step === null) return null;
+    const out: Date[] = [];
+    for (let k = 1; k <= count; k++) out.push(new Date(last.getTime() + step * k));
+    return out;
+}
+
+const isFiniteNumber = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value);
+const isValidDate = (value: unknown): value is Date => value instanceof Date && !Number.isNaN(value.getTime());
+
+/**
+ * The continued series of `source` (two or more numbers, or two or more dates, with an exactly equal
+ * step), `count` values long, or null when `source` is not such a series.
+ */
+export function detectFillSeries(source: readonly unknown[], count: number): unknown[] | null {
+    if (source.length < 2) return null;
+    if (source.every(isFiniteNumber)) return numberSeries(source, count);
+    if (source.every(isValidDate)) return dateSeries(source, count);
+    return null;
+}
+
+/** A value repeated into another cell: dates are copied, so cells never share one Date object. */
+const cloneValue = (value: unknown): unknown => (value instanceof Date ? new Date(value.getTime()) : value);
+
+/**
+ * The `count` values a fill writes after `source` (in fill order): the continued series when `series`
+ * is allowed and `source` is one, otherwise `source` repeated (one value: a copy).
+ */
+export function computeFillValues(source: readonly unknown[], count: number, series: boolean): unknown[] {
+    if (source.length === 0 || count <= 0) return [];
+    const continued = series ? detectFillSeries(source, count) : null;
+    if (continued) return continued;
+    const out: unknown[] = [];
+    for (let k = 0; k < count; k++) out.push(cloneValue(source[k % source.length]));
+    return out;
+}
+
+/**
+ * Where a fill-handle drag reaches: the source rectangle extended in one direction to the cell under
+ * the pointer, or null while the pointer is over the source. When the cell lies beyond the source
+ * both down/up and right/left, the larger pointer offset (px, `dx` / `dy` from where the drag
+ * started) decides between vertical and horizontal.
+ */
+export function fillTargetFromPointer(
+    source: CellRangeRect,
+    head: { row: number; col: number },
+    dx: number,
+    dy: number,
+): { rect: CellRangeRect; direction: GridFillDirection } | null {
+    const outVertical = head.row > source.bottom || head.row < source.top;
+    const outHorizontal = head.col > source.right || head.col < source.left;
+    if (!outVertical && !outHorizontal) return null;
+    const vertical = outVertical && (!outHorizontal || Math.abs(dy) >= Math.abs(dx));
+    if (vertical) {
+        return head.row > source.bottom
+            ? { rect: { ...source, bottom: head.row }, direction: 'down' }
+            : { rect: { ...source, top: head.row }, direction: 'up' };
+    }
+    return head.col > source.right
+        ? { rect: { ...source, right: head.col }, direction: 'right' }
+        : { rect: { ...source, left: head.col }, direction: 'left' };
+}
+
+/** One line of a fill: the source positions in fill order and the positions it fills, in order. */
+export interface FillLine {
+    /** Row index for a vertical fill, column index for a horizontal one. */
+    line: number;
+    source: number[];
+    targets: number[];
+}
+
+/** The lines (columns for a vertical fill, rows for a horizontal one) of a fill from `source` to `target`. */
+export function fillLines(source: CellRangeRect, target: CellRangeRect, direction: GridFillDirection): FillLine[] {
+    const range = (from: number, to: number) => {
+        const out: number[] = [];
+        if (from <= to) for (let i = from; i <= to; i++) out.push(i);
+        else for (let i = from; i >= to; i--) out.push(i);
+        return out;
+    };
+    const vertical = direction === 'down' || direction === 'up';
+    const lines = vertical ? range(source.left, source.right) : range(source.top, source.bottom);
+    let sourceOrder: number[];
+    let targets: number[];
+    switch (direction) {
+        case 'down':
+            sourceOrder = range(source.top, source.bottom);
+            targets = target.bottom > source.bottom ? range(source.bottom + 1, target.bottom) : [];
+            break;
+        case 'up':
+            sourceOrder = range(source.bottom, source.top);
+            targets = target.top < source.top ? range(source.top - 1, target.top) : [];
+            break;
+        case 'right':
+            sourceOrder = range(source.left, source.right);
+            targets = target.right > source.right ? range(source.right + 1, target.right) : [];
+            break;
+        default:
+            sourceOrder = range(source.right, source.left);
+            targets = target.left < source.left ? range(source.left - 1, target.left) : [];
+    }
+    return lines.map(line => ({ line, source: sourceOrder, targets }));
+}
+
+/**
+ * The corners the range takes after a fill (or during a fill drag): the original anchor when it is a
+ * corner of `rect`, otherwise the corner on the source side of the fill, so focus stays near it.
+ */
+export function fillRangeCorners(
+    rect: CellRangeRect,
+    direction: GridFillDirection,
+    anchor: { row: number; col: number },
+): { anchor: { row: number; col: number }; head: { row: number; col: number } } {
+    const isCornerRow = anchor.row === rect.top || anchor.row === rect.bottom;
+    const isCornerCol = anchor.col === rect.left || anchor.col === rect.right;
+    let row = anchor.row;
+    let col = anchor.col;
+    if (!isCornerRow || !isCornerCol) {
+        const vertical = direction === 'down' || direction === 'up';
+        if (vertical) {
+            row = direction === 'down' ? rect.top : rect.bottom;
+            col = anchor.col === rect.right ? rect.right : rect.left;
+        } else {
+            col = direction === 'right' ? rect.left : rect.right;
+            row = anchor.row === rect.bottom ? rect.bottom : rect.top;
+        }
+    }
+    return {
+        anchor: { row, col },
+        head: { row: row === rect.top ? rect.bottom : rect.top, col: col === rect.left ? rect.right : rect.left },
+    };
+}
+
+/** The cell the fill handle sits on: the bottom-right cell of the range, or the origin of the span covering it. */
+export function fillHandleCell(
+    rect: CellRangeRect,
+    rowIdAt: (row: number) => GridRowId | undefined,
+    fields: readonly string[],
+    getSpanOrigin?: (rowId: GridRowId, field: string) => { rowId: GridRowId; field: string } | null,
+): { row: number; field: string } | null {
+    const rowId = rowIdAt(rect.bottom);
+    const field = fields[rect.right];
+    if (rowId === undefined || field === undefined) return null;
+    const origin = getSpanOrigin?.(rowId, field);
+    if (!origin || (origin.rowId === rowId && origin.field === field)) return { row: rect.bottom, field };
+    // A span covers the corner: the handle goes on the cell that renders it, a few rows up.
+    for (let r = rect.bottom; r >= Math.max(0, rect.bottom - MAX_SPAN_LOOKBACK); r--) {
+        if (rowIdAt(r) === origin.rowId) return { row: r, field: origin.field };
+    }
+    return null;
+}
+
+/** How far up a span origin is looked for. */
+const MAX_SPAN_LOOKBACK = 1000;

package/lib/utils/filtering/index.ts

@@ -367,3 +367,17 @@ export function getOperatorsForType(type?: string): GridFilterOperator[] {
       return ['contains', 'equals', 'startsWith', 'endsWith', 'isEmpty', 'isNotEmpty'];
   }
 }
+
+/**
+ * The text an input shows for a committed filter value: dates as `YYYY-MM-DD`, lists joined with
+ * commas. Never used to emit anything (the filter panel and the header filter row).
+ */
+export function filterValueToInputText(value: unknown, colType?: string): string {
+  if (value == null) return '';
+  if (colType === 'date' || value instanceof Date) {
+    const day = toLocalDateString(value);
+    return day || (typeof value === 'string' ? value : '');
+  }
+  if (Array.isArray(value)) return value.map(v => String(v)).join(', ');
+  return String(value);
+}

package/lib/utils/focus/index.ts

@@ -13,12 +13,14 @@ export interface FocusedCell {
     /** Row id of the focused body cell, or `null` when a column header cell is focused. */
     id: GridRowId | null;
     field: string;
+    /** With `id: null`: the cell of the header filter row (`headerFilters`), not the column header. */
+    headerFilter?: boolean;
     /** Index in the renderable rows when focus was set; used to pick a neighbour if the row disappears. */
     rowIndex?: number;
 }
 
 export const isSameCell = (a: FocusedCell | null, b: FocusedCell | null): boolean =>
-    a === b || (a !== null && b !== null && a.id === b.id && a.field === b.field);
+    a === b || (a !== null && b !== null && a.id === b.id && a.field === b.field && !a.headerFilter === !b.headerFilter);
 
 /**
  * Where a keydown came from, from the grid's point of view:
@@ -81,7 +83,9 @@ export function focusedCellFromElement<T>(
     const field = cell?.dataset.field;
     if (!cell || !field) return null;
     if (cell.getAttribute('role') === 'columnheader') {
-        return cell.parentElement?.classList.contains('ogx__header') ? { id: null, field } : null;
+        const headerRow = cell.parentElement;
+        if (headerRow?.classList.contains('ogx__header')) return { id: null, field };
+        return headerRow?.classList.contains('ogx__header-filter-row') ? { id: null, field, headerFilter: true } : null;
     }
     const rowIndex = Number(cell.parentElement?.getAttribute('data-rowindex'));
     const row = Number.isInteger(rowIndex) ? rows[rowIndex] : undefined;
@@ -100,7 +104,9 @@ function childWithField(parent: Element | null, field: string): HTMLElement | nu
 export function findFocusTarget(viewport: HTMLElement, cell: FocusedCell, rowIndex: number): HTMLElement | null {
     if (cell.id === null) {
         // The header sits in the sticky top block together with the top-pinned rows.
-        const header = viewport.querySelector(':scope > .ogx__content > .ogx__sticky-top > .ogx__header-wrap > .ogx__header');
+        const header = viewport.querySelector(
+            `:scope > .ogx__content > .ogx__sticky-top > .ogx__header-wrap > ${cell.headerFilter ? '.ogx__header-filter-row' : '.ogx__header'}`
+        );
         const el = childWithField(header, cell.field);
         if (el && cell.field === CHECKBOX_FIELD) return el.querySelector('input') ?? el;
         return el;

package/lib/utils/headerFilters.ts

@@ -0,0 +1,189 @@
+import type { GridColDef, GridFilterGroup, GridFilterItem, GridFilterModel, GridFilterOperator } from '../types';
+import { NO_VALUE_OPERATORS, getOperatorsForType, isEmptyFilterValue } from './filtering';
+import { isSystemField } from './focus';
+
+/** Prefix of the ids of the filter items the header filter row owns: `header:<field>`. */
+export const HEADER_FILTER_ID_PREFIX = 'header:';
+
+/** Default height of the header filter row, in pixels. */
+export const DEFAULT_HEADER_FILTER_HEIGHT = 40;
+
+/** Debounce for typed values, the same as the filter panel's. */
+export const HEADER_FILTER_DEBOUNCE_MS = 300;
+
+/** The synthetic row-grouping column; it has no header filter. */
+const GROUPING_FIELD = '__group__';
+
+type FilterEntry = GridFilterItem | GridFilterGroup;
+
+const NO_ENTRIES: FilterEntry[] = [];
+
+export function getHeaderFilterItemId(field: string): string {
+    return `${HEADER_FILTER_ID_PREFIX}${field}`;
+}
+
+function isFilterGroup(entry: FilterEntry): entry is GridFilterGroup {
+    return 'items' in entry && Array.isArray(entry.items);
+}
+
+/** Whether a column gets a control in the header filter row. */
+export function hasHeaderFilter(col: Pick<GridColDef, 'field' | 'type' | 'filterable' | 'headerFilter' | 'isSpacer'>): boolean {
+    if (col.isSpacer || isSystemField(col.field) || col.field === GROUPING_FIELD) return false;
+    return col.headerFilter !== false && col.filterable !== false && col.type !== 'image';
+}
+
+/** The operator a new header filter starts with: `headerFilterOperator`, else the default for the type. */
+export function getHeaderFilterDefaultOperator(col: Pick<GridColDef, 'type' | 'headerFilterOperator'>): GridFilterOperator {
+    if (col.headerFilterOperator) return col.headerFilterOperator;
+    switch (col.type) {
+        case 'number': return '=';
+        case 'date':
+        case 'boolean':
+        case 'singleSelect':
+            return 'is';
+        default:
+            return 'contains';
+    }
+}
+
+/** The operators the operator menu offers: the type's operators, with the starting one first if the type does not list it. */
+export function getHeaderFilterOperators(col: Pick<GridColDef, 'type' | 'headerFilterOperator'>): GridFilterOperator[] {
+    const operators = getOperatorsForType(col.type);
+    const start = getHeaderFilterDefaultOperator(col);
+    return operators.includes(start) ? operators : [start, ...operators];
+}
+
+/**
+ * What a header filter cell shows:
+ * - `editable`: the cell owns `item` (the root-level item `header:<field>`), or there is none yet;
+ * - `custom`: the model holds a condition on the field the row cannot show (root `logicOperator`
+ *   `'or'`, another root item on the field, the field inside a nested group). The cell is read-only.
+ */
+export type GridHeaderFilterState =
+    | { kind: 'editable'; item: GridFilterItem | undefined }
+    | { kind: 'custom' };
+
+function groupMentionsField(group: GridFilterGroup, field: string): boolean {
+    return group.items.some(entry => (isFilterGroup(entry) ? groupMentionsField(entry, field) : entry.field === field));
+}
+
+/** Whether a model's root combines its items with OR (with something to combine). */
+export function isOrRootModel(model: GridFilterModel | null | undefined): boolean {
+    return (model?.logicOperator ?? 'and') === 'or' && (model?.items?.length ?? 0) > 0;
+}
+
+export function getHeaderFilterState(model: GridFilterModel | null | undefined, field: string): GridHeaderFilterState {
+    const items = model?.items ?? NO_ENTRIES;
+    if (isOrRootModel(model)) return { kind: 'custom' };
+    const ownId = getHeaderFilterItemId(field);
+    let own: GridFilterItem | undefined;
+    for (const entry of items) {
+        if (isFilterGroup(entry)) {
+            if (groupMentionsField(entry, field)) return { kind: 'custom' };
+            continue;
+        }
+        if (entry.field !== field) continue;
+        if (entry.id !== ownId || own) return { kind: 'custom' };
+        own = entry;
+    }
+    return { kind: 'editable', item: own };
+}
+
+/**
+ * The model with the header filter item for `field` replaced by `item` (added at the end when
+ * absent, removed when `item` is null). Every other entry, the logic operator and the quick filter
+ * pass through untouched. Returns `model` itself when the cell cannot own the field's filter.
+ */
+export function setHeaderFilterItem(model: GridFilterModel | null | undefined, field: string, item: GridFilterItem | null): GridFilterModel {
+    const base: GridFilterModel = model ?? { items: [] };
+    if (getHeaderFilterState(base, field).kind !== 'editable') return base;
+    const ownId = getHeaderFilterItemId(field);
+    const items = base.items ?? NO_ENTRIES;
+    const index = items.findIndex(entry => !isFilterGroup(entry) && entry.id === ownId);
+    const nextItem: GridFilterItem | null = item ? { ...item, id: ownId, field } : null;
+    let next: FilterEntry[];
+    if (index === -1) {
+        if (!nextItem) return base;
+        // With no items the logic operator means nothing yet; a leftover 'or' would make the
+        // next column's cell read the model as custom, so it starts as 'and'.
+        if (items.length === 0 && base.logicOperator === 'or') return { ...base, logicOperator: 'and', items: [nextItem] };
+        next = [...items, nextItem];
+    } else if (nextItem) {
+        next = items.map((entry, i) => (i === index ? nextItem : entry));
+    } else {
+        next = items.filter((_, i) => i !== index);
+    }
+    return { ...base, items: next };
+}
+
+/**
+ * The item a header filter cell stores for an operator and value, or null when it should hold no
+ * item: an empty value with the starting operator. An empty value with another operator keeps the
+ * item, so the chosen operator stays while the value is retyped (an empty value never filters).
+ */
+export function buildHeaderFilterItem(
+    col: Pick<GridColDef, 'field' | 'type' | 'headerFilterOperator'>,
+    operator: GridFilterOperator,
+    value: unknown,
+): GridFilterItem | null {
+    const noValue = NO_VALUE_OPERATORS.has(operator);
+    if (!noValue && isEmptyFilterValue(value) && operator === getHeaderFilterDefaultOperator(col)) return null;
+    return { id: getHeaderFilterItemId(col.field), field: col.field, operator, value: noValue ? undefined : value };
+}
+
+/** Carries a value over to a newly picked operator: lists for isAnyOf, scalars for the rest. */
+export function convertHeaderFilterValue(value: unknown, operator: GridFilterOperator): unknown {
+    if (NO_VALUE_OPERATORS.has(operator)) return undefined;
+    if (operator === 'isAnyOf') {
+        if (value == null || value === '') return [];
+        return Array.isArray(value) ? value : [value];
+    }
+    if (Array.isArray(value)) return value.length > 0 ? value[0] : '';
+    return value ?? '';
+}
+
+/** Short label shown on the operator button. */
+export const HEADER_FILTER_OPERATOR_SYMBOLS: Record<GridFilterOperator, string> = {
+    contains: '∋',
+    equals: '=',
+    startsWith: 'a…',
+    endsWith: '…a',
+    isEmpty: '∅',
+    isNotEmpty: '!∅',
+    isAnyOf: '∈',
+    '=': '=',
+    '!=': '≠',
+    '>': '>',
+    '>=': '≥',
+    '<': '<',
+    '<=': '≤',
+    is: '=',
+    not: '≠',
+    after: '>',
+    onOrAfter: '≥',
+    before: '<',
+    onOrBefore: '≤',
+};
+
+/** Readable operator names for the operator menu and labels. */
+export const HEADER_FILTER_OPERATOR_LABELS: Record<GridFilterOperator, string> = {
+    contains: 'Contains',
+    equals: 'Equals',
+    startsWith: 'Starts with',
+    endsWith: 'Ends with',
+    isEmpty: 'Is empty',
+    isNotEmpty: 'Is not empty',
+    isAnyOf: 'Is any of',
+    '=': 'Equals',
+    '!=': 'Does not equal',
+    '>': 'Greater than',
+    '>=': 'Greater than or equal',
+    '<': 'Less than',
+    '<=': 'Less than or equal',
+    is: 'Is',
+    not: 'Is not',
+    after: 'After',
+    onOrAfter: 'On or after',
+    before: 'Before',
+    onOrBefore: 'On or before',
+};

package/lib/utils/maxElementHeight.ts

@@ -0,0 +1,53 @@
+/**
+ * The tallest element this browser lays out. Browsers cap element heights: Chromium and Safari at
+ * about 33.5M px, Firefox at about 17.9M px. Firefox does not clamp an element that is taller — it
+ * collapses it, so a grid whose content is taller than the cap cannot be scrolled at all.
+ *
+ * Measured once per document with an invisible probe (one layout), from the largest candidate down.
+ * Returns `Infinity` where there is no layout engine (jsdom, SSR), so nothing is capped there.
+ */
+const CANDIDATES = [33_554_400, 17_895_000, 10_000_000, 5_000_000] as const;
+
+const cache = new WeakMap<Document, number>();
+
+function measure(doc: Document): number {
+    const body = doc.body;
+    if (!body) return Infinity;
+    const probe = doc.createElement('div');
+    probe.setAttribute('aria-hidden', 'true');
+    probe.style.cssText = 'position:absolute;top:0;left:-10000px;width:1px;visibility:hidden;pointer-events:none;';
+    body.appendChild(probe);
+    try {
+        probe.style.height = '100px';
+        // No layout engine: every element reads 0 tall.
+        if (Math.abs(probe.getBoundingClientRect().height - 100) > 1) return Infinity;
+        for (const height of CANDIDATES) {
+            probe.style.height = `${height}px`;
+            if (Math.abs(probe.getBoundingClientRect().height - height) < 2) return height;
+        }
+        return CANDIDATES[CANDIDATES.length - 1];
+    } finally {
+        probe.remove();
+    }
+}
+
+export function getMaxElementHeight(doc: Document | null | undefined): number {
+    if (!doc) return Infinity;
+    const known = cache.get(doc);
+    if (known !== undefined) return known;
+    const height = measure(doc);
+    cache.set(doc, height);
+    return height;
+}
+
+/** How many of the unpinned rows end at or above `limit` px (the rows a user can scroll to). */
+export function countReachableRows(cumulativeHeights: readonly number[], limit: number): number {
+    if (!Number.isFinite(limit)) return cumulativeHeights.length;
+    let lo = 0;
+    let hi = cumulativeHeights.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (cumulativeHeights[mid] <= limit) lo = mid + 1; else hi = mid;
+    }
+    return lo;
+}