@opencorestack/opengridx 3.4.0 → 3.5.0

package/lib/utils/aiAssistant.ts

@@ -0,0 +1,205 @@
+// Pure helpers of the `aiAssistant` panel: which parts of a reply it may apply, what to restore on
+// Undo, the removable chips and what a state looks like without one of them. No AI code: the reply
+// was validated by the `/ai` entry point before it reaches the grid.
+import type {
+    GridAiChip,
+    GridAiPart,
+    GridAiState,
+    GridAiValidationError,
+    GridApi,
+    GridFilterGroup,
+    GridFilterItem,
+} from '../types';
+
+export const AI_PARTS: readonly GridAiPart[] = ['filter', 'sort', 'grouping', 'aggregation', 'pivot', 'columnVisibility'];
+
+const PART_KEYS: Record<GridAiPart, keyof GridAiState> = {
+    filter: 'filterModel',
+    sort: 'sortModel',
+    grouping: 'rowGroupingModel',
+    aggregation: 'aggregationModel',
+    pivot: 'pivotModel',
+    columnVisibility: 'columnVisibilityModel',
+};
+
+type StateKey = keyof GridAiState;
+
+function keysOf(state: GridAiState): StateKey[] {
+    return AI_PARTS.map((part) => PART_KEYS[part]).filter((key) => state[key] !== undefined);
+}
+
+/** The parts of `state` that `parts` allows, and an error for each part it does not. */
+export function pickAllowedParts(state: GridAiState, parts: readonly GridAiPart[]): { state: GridAiState; errors: GridAiValidationError[] } {
+    const picked: GridAiState = {};
+    const errors: GridAiValidationError[] = [];
+    for (const part of AI_PARTS) {
+        const key = PART_KEYS[part];
+        if (state[key] === undefined) continue;
+        if (parts.includes(part)) Object.assign(picked, { [key]: state[key] });
+        else errors.push({ path: key, message: 'Part not allowed' });
+    }
+    return { state: picked, errors };
+}
+
+function isEmptyPart(state: GridAiState, key: StateKey): boolean {
+    const value = state[key];
+    if (Array.isArray(value)) return value.length === 0;
+    if (key === 'filterModel') {
+        const model = state.filterModel;
+        return !model || ((model.items ?? []).length === 0 && (model.quickFilterValues ?? []).length === 0);
+    }
+    if (key === 'pivotModel') {
+        const model = state.pivotModel;
+        return !model || (model.rowFields.length === 0 && model.columnFields.length === 0 && model.valueFields.length === 0);
+    }
+    return typeof value === 'object' && value !== null && Object.keys(value).length === 0;
+}
+
+/** The state key an error path starts with (`'sortModel[0].field'` → `'sortModel'`). */
+function errorKey(path: string): string {
+    let end = path.length;
+    for (const sep of ['.', '[']) {
+        const at = path.indexOf(sep);
+        if (at >= 0 && at < end) end = at;
+    }
+    return path.slice(0, end);
+}
+
+/**
+ * Leaves out a part that is empty only because the validator dropped everything in it (`sortModel`
+ * naming an unknown field comes back as `[]`): applying it would clear the grid's model, which the
+ * reply did not ask for. An empty part without errors ("clear the sort") is kept.
+ */
+export function dropEmptiedParts(state: GridAiState, errors: readonly GridAiValidationError[]): GridAiState {
+    const failed = new Set(errors.map((error) => errorKey(typeof error.path === 'string' ? error.path : '')));
+    const out: GridAiState = {};
+    for (const key of keysOf(state)) {
+        if (!(failed.has(key) && isEmptyPart(state, key))) Object.assign(out, { [key]: state[key] });
+    }
+    return out;
+}
+
+/** The current values of the parts `state` changes: what Undo restores. */
+export function snapshotParts(state: GridAiState, current: GridAiState): GridAiState {
+    const snapshot: GridAiState = {};
+    for (const key of keysOf(state)) Object.assign(snapshot, { [key]: current[key] });
+    return snapshot;
+}
+
+/**
+ * The models to apply for `applied` over `previous` (the snapshot taken before the reply): column
+ * visibility is merged over the previous model; a part removed from `applied` gets its previous value back.
+ */
+export function effectiveState(applied: GridAiState, previous: GridAiState): GridAiState {
+    const out: GridAiState = {};
+    for (const key of AI_PARTS.map((part) => PART_KEYS[part])) {
+        if (!(key in previous) && applied[key] === undefined) continue;
+        if (applied[key] === undefined) Object.assign(out, { [key]: previous[key] });
+        else if (key === 'columnVisibilityModel') out.columnVisibilityModel = { ...previous.columnVisibilityModel, ...applied.columnVisibilityModel };
+        else Object.assign(out, { [key]: applied[key] });
+    }
+    return out;
+}
+
+type GridAiStateSetters = Pick<GridApi, 'setFilterModel' | 'setSortModel' | 'setRowGroupingModel' | 'setAggregationModel' | 'setPivotModel' | 'setColumnVisibilityModel'>;
+
+/** Applies every part present in `state` through the API (each fires its change callback). */
+export function applyGridAiState(api: GridAiStateSetters, state: GridAiState): void {
+    if (state.filterModel) api.setFilterModel(state.filterModel);
+    if (state.sortModel) api.setSortModel(state.sortModel);
+    if (state.rowGroupingModel) api.setRowGroupingModel(state.rowGroupingModel);
+    if (state.aggregationModel) api.setAggregationModel(state.aggregationModel);
+    if (state.pivotModel) api.setPivotModel(state.pivotModel);
+    if (state.columnVisibilityModel) api.setColumnVisibilityModel(state.columnVisibilityModel);
+}
+
+function valueText(value: unknown): string {
+    if (Array.isArray(value)) return value.map(valueText).join(', ');
+    if (value instanceof Date) return value.toISOString().slice(0, 10);
+    return value === undefined || value === null ? '' : String(value);
+}
+
+function filterLabel(node: GridFilterItem | GridFilterGroup, label: (field: string) => string): string {
+    if ('items' in node) return `(${node.items.map((child) => filterLabel(child, label)).join(` ${node.logicOperator} `)})`;
+    return [label(node.field), node.operator, valueText(node.value)].filter(Boolean).join(' ');
+}
+
+const FN_LABELS: Record<string, string> = { sum: 'Sum', avg: 'Average', count: 'Count', min: 'Min', max: 'Max', unique: 'Unique' };
+
+/** One chip per change: filter item, quick-filter words, sort key, grouping field, aggregation, visibility change, pivot. */
+export function buildAiChips(applied: GridAiState, label: (field: string) => string): GridAiChip[] {
+    const chips: GridAiChip[] = [];
+    const { filterModel, sortModel, rowGroupingModel, aggregationModel, pivotModel, columnVisibilityModel } = applied;
+    if (filterModel) {
+        const items = filterModel.items ?? [];
+        items.forEach((item, i) => chips.push({ id: `filter:${i}`, part: 'filter', label: filterLabel(item, label) }));
+        const words = filterModel.quickFilterValues ?? [];
+        if (words.length > 0) chips.push({ id: 'filter:quick', part: 'filter', label: `Search: ${words.join(' ')}` });
+        if (items.length === 0 && words.length === 0) chips.push({ id: 'filter:clear', part: 'filter', label: 'No filters' });
+    }
+    if (sortModel) {
+        sortModel.forEach((s, i) => chips.push({ id: `sort:${i}`, part: 'sort', label: `Sort: ${label(s.field)}, ${s.sort === 'desc' ? 'descending' : 'ascending'}` }));
+        if (sortModel.length === 0) chips.push({ id: 'sort:clear', part: 'sort', label: 'No sorting' });
+    }
+    if (rowGroupingModel) {
+        rowGroupingModel.forEach((field, i) => chips.push({ id: `grouping:${i}`, part: 'grouping', label: `Group: ${label(field)}` }));
+        if (rowGroupingModel.length === 0) chips.push({ id: 'grouping:clear', part: 'grouping', label: 'No grouping' });
+    }
+    if (aggregationModel) {
+        const fields = Object.keys(aggregationModel);
+        fields.forEach((field) => {
+            const fn = aggregationModel[field];
+            chips.push({ id: `aggregation:${field}`, part: 'aggregation', label: `${FN_LABELS[fn] ?? fn}: ${label(field)}` });
+        });
+        if (fields.length === 0) chips.push({ id: 'aggregation:clear', part: 'aggregation', label: 'No summaries' });
+    }
+    if (pivotModel) {
+        const fields = [...pivotModel.rowFields, ...pivotModel.columnFields, ...pivotModel.valueFields.map((v) => v.field)];
+        chips.push({ id: 'pivot', part: 'pivot', label: fields.length > 0 ? `Pivot: ${fields.map(label).join(', ')}` : 'No pivot' });
+    }
+    if (columnVisibilityModel) {
+        for (const field of Object.keys(columnVisibilityModel)) {
+            chips.push({ id: `columnVisibility:${field}`, part: 'columnVisibility', label: `${columnVisibilityModel[field] ? 'Show' : 'Hide'}: ${label(field)}` });
+        }
+    }
+    return chips;
+}
+
+/**
+ * `applied` without the change a chip stands for. A part left with no change is dropped, so
+ * `effectiveState` gives it its value from before the reply.
+ */
+export function removeAiChip(applied: GridAiState, id: string): GridAiState {
+    const next: GridAiState = { ...applied };
+    const sep = id.indexOf(':');
+    const part = sep < 0 ? id : id.slice(0, sep);
+    const rest = sep < 0 ? '' : id.slice(sep + 1);
+    const index = Number(rest);
+    if (part === 'filter' && next.filterModel) {
+        const model = { ...next.filterModel };
+        if (rest === 'quick') delete model.quickFilterValues;
+        else if (rest === 'clear') model.items = [];
+        else model.items = (model.items ?? []).filter((_, i) => i !== index);
+        if ((model.items ?? []).length === 0 && (model.quickFilterValues ?? []).length === 0) delete next.filterModel;
+        else next.filterModel = model;
+    } else if (part === 'sort' && next.sortModel) {
+        next.sortModel = next.sortModel.filter((_, i) => i !== index);
+        if (next.sortModel.length === 0 || rest === 'clear') delete next.sortModel;
+    } else if (part === 'grouping' && next.rowGroupingModel) {
+        next.rowGroupingModel = next.rowGroupingModel.filter((_, i) => i !== index);
+        if (next.rowGroupingModel.length === 0 || rest === 'clear') delete next.rowGroupingModel;
+    } else if (part === 'aggregation' && next.aggregationModel) {
+        const model = { ...next.aggregationModel };
+        delete model[rest];
+        if (Object.keys(model).length === 0) delete next.aggregationModel;
+        else next.aggregationModel = model;
+    } else if (part === 'columnVisibility' && next.columnVisibilityModel) {
+        const model = { ...next.columnVisibilityModel };
+        delete model[rest];
+        if (Object.keys(model).length === 0) delete next.columnVisibilityModel;
+        else next.columnVisibilityModel = model;
+    } else if (part === 'pivot') {
+        delete next.pivotModel;
+    }
+    return next;
+}

package/lib/utils/aiBrand.ts

@@ -0,0 +1,17 @@
+// The "validated" brand of the AI toolkit. `validateGridAiState` (in the `/ai` entry point) puts it on
+// its result and on the result's `state`; the grid's `aiAssistant` applies a state only when it carries
+// it. Shared by both bundles, so it holds no AI code: just the registered symbol and two helpers.
+
+/** `Symbol.for('opengridx.ai.validated')`: the same symbol in every bundle and realm. */
+export const GRID_AI_VALIDATED_BRAND: symbol = Symbol.for('opengridx.ai.validated');
+
+/** Brands `value` (non-enumerable, so it does not change equality, spreading or JSON) and returns it. */
+export function brandGridAiValidated<T extends object>(value: T): T {
+    Object.defineProperty(value, GRID_AI_VALIDATED_BRAND, { value: true, enumerable: false });
+    return value;
+}
+
+/** Whether `value` carries the brand. */
+export function isGridAiValidated(value: unknown): boolean {
+    return typeof value === 'object' && value !== null && (value as Record<symbol, unknown>)[GRID_AI_VALIDATED_BRAND] === true;
+}

package/lib/utils/cellSelection.ts

@@ -184,26 +184,43 @@ export interface GridRowCellRange {
     isBottom: boolean;
     /** Rows from this one to the bottom of the range; only set (else 0) when the grid has row spans. */
     bottomOffset: number;
+    /** Data column index (`columnIndexMap`) of the cell carrying the fill handle; only set on its row. @since v3.5 */
+    fillHandleCol?: number;
+}
+
+/** Where the fill handle is drawn: a renderable row index and a data column index (`columnIndexMap`). */
+export interface GridFillHandlePosition {
+    row: number;
+    col: number;
 }
 
 export function getRowCellRange(
     range: { top: number; bottom: number; left: number; right: number } | null | undefined,
     rowIndex: number,
     hasRowSpan: boolean,
+    fillHandle?: GridFillHandlePosition | null,
 ): GridRowCellRange | null {
-    if (!range || rowIndex < range.top || rowIndex > range.bottom) return null;
-    return {
+    const handleCol = fillHandle && fillHandle.row === rowIndex ? fillHandle.col : undefined;
+    if (!range || rowIndex < range.top || rowIndex > range.bottom) {
+        // A single selected cell draws no range, only the handle: an empty column interval.
+        return handleCol === undefined
+            ? null
+            : { left: 0, right: -1, isTop: false, isBottom: false, bottomOffset: 0, fillHandleCol: handleCol };
+    }
+    const rowRange: GridRowCellRange = {
         left: range.left,
         right: range.right,
         isTop: rowIndex === range.top,
         isBottom: rowIndex === range.bottom,
         bottomOffset: hasRowSpan ? range.bottom - rowIndex : 0,
     };
+    if (handleCol !== undefined) rowRange.fillHandleCol = handleCol;
+    return rowRange;
 }
 
 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);
+        && a.bottomOffset === b.bottomOffset && a.fillHandleCol === b.fillHandleCol);
 
 /** Bit flags a cell receives for its place in the range (a number keeps memoised cells stable). */
 export const RANGE_CELL = 1;
@@ -211,6 +228,8 @@ export const RANGE_TOP = 2;
 export const RANGE_BOTTOM = 4;
 export const RANGE_LEFT = 8;
 export const RANGE_RIGHT = 16;
+/** The cell carries the fill handle (v3.5). */
+export const RANGE_FILL_HANDLE = 32;
 
 /**
  * The flags of the cell at data column `colIndex` (spanning `colSpan` columns and `rowSpan` rows from
@@ -218,9 +237,10 @@ export const RANGE_RIGHT = 16;
  */
 export function getCellRangeFlags(rowRange: GridRowCellRange | null | undefined, colIndex: number, colSpan: number, rowSpan: number): number {
     if (!rowRange) return 0;
+    const handle = rowRange.fillHandleCol === colIndex ? RANGE_FILL_HANDLE : 0;
     const lastCol = colIndex + Math.max(1, colSpan) - 1;
-    if (colIndex < rowRange.left || lastCol > rowRange.right) return 0;
-    let flags = RANGE_CELL;
+    if (colIndex < rowRange.left || lastCol > rowRange.right) return handle;
+    let flags = RANGE_CELL | handle;
     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;

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;