@alaarab/ogrid-core 2.4.2 → 2.5.0

package/dist/types/formula/cellAddressUtils.d.ts

@@ -2,15 +2,9 @@
  * Cell address parsing and formatting utilities for the formula system.
  * Extends the existing cellReference.ts with reverse parsing and absolute reference support.
  */
+import { columnLetterToIndex } from '../utils/cellReference';
 import type { ICellAddress, ICellRange, CellKey } from './types';
-/**
- * Parse a column letter string to a 0-based index.
- * @example columnLetterToIndex('A')  // 0
- * @example columnLetterToIndex('Z')  // 25
- * @example columnLetterToIndex('AA') // 26
- * @example columnLetterToIndex('AZ') // 51
- */
-export declare function columnLetterToIndex(letters: string): number;
+export { columnLetterToIndex };
 /**
  * Parse a cell reference string like "A1", "$B$2", "$A1", "A$1".
  * Returns null on invalid input.

package/dist/types/formula/index.d.ts

@@ -7,7 +7,10 @@ export { REF_ERROR, DIV_ZERO_ERROR, VALUE_ERROR, NAME_ERROR, CIRC_ERROR, GENERAL
 export { columnLetterToIndex, parseCellRef, parseRange, formatAddress, toCellKey, fromCellKey, adjustFormulaReferences, } from './cellAddressUtils';
 export { tokenize } from './tokenizer';
 export { parse } from './parser';
-export { FormulaEvaluator, toNumber, toString, toBoolean, flattenArgs, } from './evaluator';
+export { FormulaEvaluator, toNumber, toString, toString as formulaToString, toBoolean, flattenArgs, } from './evaluator';
 export { DependencyGraph } from './dependencyGraph';
 export { FormulaEngine } from './formulaEngine';
 export { createBuiltInFunctions } from './functions';
+export { extractFormulaReferences, processFormulaBarCommit, deriveFormulaBarText, handleFormulaBarKeyDown, canInsertReference, insertReferenceAtCursor, } from '../utils/formulaBarHelpers';
+export type { FormulaReference } from '../utils/formulaBarHelpers';
+export { FORMULA_REF_COLORS, FORMULA_BAR_CSS, FORMULA_BAR_STYLES } from '../constants/formulaBar';

package/dist/types/index.d.ts

@@ -42,13 +42,12 @@ export { applyFillValues } from './utils';
 export type { IFillFormulaOptions } from './utils';
 export { UndoRedoStack } from './utils';
 export { validateColumns, validateRowIds, validateVirtualScrollConfig } from './utils';
-export { indexToColumnLetter, formatCellReference } from './utils';
-export { extractFormulaReferences, processFormulaBarCommit, deriveFormulaBarText, handleFormulaBarKeyDown } from './utils';
+export { indexToColumnLetter, columnLetterToIndex, formatCellReference } from './utils';
 export type { FormulaReference } from './utils';
+export { getResponsiveHiddenColumns, RESPONSIVE_BREAKPOINTS, resolveResponsiveConfig, applyResponsiveHiding } from './utils';
+export type { IResponsiveColumnsConfig } from './utils';
 export { CHECKBOX_COLUMN_WIDTH, ROW_NUMBER_COLUMN_WIDTH, ROW_NUMBER_COLUMN_MIN_WIDTH, ROW_NUMBER_COLUMN_ID, DEFAULT_MIN_COLUMN_WIDTH, CELL_PADDING, GRID_BORDER_RADIUS, } from './constants';
 export { DEFAULT_DEBOUNCE_MS, PEOPLE_SEARCH_DEBOUNCE_MS, SIDEBAR_TRANSITION_MS, } from './constants';
 export { Z_INDEX } from './constants';
 export type { ZIndexKey } from './constants';
-export { FORMULA_REF_COLORS, FORMULA_BAR_CSS, FORMULA_BAR_STYLES } from './constants';
-export { FormulaError, FormulaEngine, FormulaEvaluator, DependencyGraph, tokenize, parse, createBuiltInFunctions, columnLetterToIndex, parseCellRef, parseRange, formatAddress, toCellKey, fromCellKey, adjustFormulaReferences, toNumber, toString as formulaToString, toBoolean, flattenArgs, isFormulaError, REF_ERROR, DIV_ZERO_ERROR, VALUE_ERROR, NAME_ERROR, CIRC_ERROR, GENERAL_ERROR, NA_ERROR, } from './formula';
 export type { ICellAddress, ICellRange, CellKey, FormulaErrorType, TokenType, Token, ASTNode, BinaryOp, IFormulaContext, IFormulaFunction, IEvaluator, IRecalcResult, IFormulaEngineConfig, IGridDataAccessor, INamedRange, IAuditEntry, IAuditTrail, } from './formula';

package/dist/types/types/columnTypes.d.ts

@@ -21,6 +21,12 @@ export interface IColumnMeta {
     filterable?: IColumnFilterDef;
     defaultVisible?: boolean;
     required?: boolean;
+    /**
+     * Responsive priority (0 = highest). Columns with higher numbers are hidden
+     * first when the container is narrow. Columns without a priority are never
+     * auto-hidden. `required` columns are never auto-hidden regardless of priority.
+     */
+    responsivePriority?: number;
     minWidth?: number;
     defaultWidth?: number;
     idealWidth?: number;

package/dist/types/utils/cellReference.d.ts

@@ -12,6 +12,14 @@
  * @example indexToColumnLetter(702) // 'AAA'
  */
 export declare function indexToColumnLetter(index: number): string;
+/**
+ * Parse a column letter string to a 0-based index.
+ * @example columnLetterToIndex('A')  // 0
+ * @example columnLetterToIndex('Z')  // 25
+ * @example columnLetterToIndex('AA') // 26
+ * @example columnLetterToIndex('AZ') // 51
+ */
+export declare function columnLetterToIndex(letters: string): number;
 /**
  * Format a cell reference string from a 0-based column index and a 1-based row number.
  * @example formatCellReference(0, 1)    // 'A1'

package/dist/types/utils/dataGridViewModel.d.ts

@@ -79,6 +79,8 @@ export interface CellRenderDescriptorInput<T> {
     getFormulaValue?: (col: number, row: number) => unknown;
     /** Check if a cell has a formula at the given coordinate. */
     hasFormula?: (col: number, row: number) => boolean;
+    /** Get the formula string for a cell (e.g. '=SUM(A1:A5)'). Used to populate the editor with the formula instead of the computed value. */
+    getFormula?: (col: number, row: number) => string | undefined;
     /** Monotonic counter incremented on each formula recalculation — used for cache invalidation. */
     formulaVersion?: number;
 }

package/dist/types/utils/formulaBarHelpers.d.ts

@@ -37,4 +37,21 @@ export declare function processFormulaBarCommit(text: string, col: number, row:
  * otherwise the stringified raw value.
  */
 export declare function deriveFormulaBarText(col: number | null, row: number | null, getFormula?: (col: number, row: number) => string | undefined, getRawValue?: (col: number, row: number) => unknown): string;
+/**
+ * Check whether a formula text is in a position where a cell reference can be inserted
+ * at the cursor. Returns true when the text starts with '=' and the character before the
+ * cursor is an operator, paren, comma, colon, whitespace, or the cursor is right after '='.
+ */
+export declare function canInsertReference(text: string, cursorPos: number): boolean;
+/**
+ * Insert a cell reference into formula text at the given cursor position.
+ * If `canInsertReference` returns false (cursor is adjacent to a token), the reference
+ * replaces the preceding token back to the last operator/delimiter.
+ *
+ * @returns Updated text and new cursor position after the inserted reference.
+ */
+export declare function insertReferenceAtCursor(text: string, cursorPos: number, reference: string): {
+    text: string;
+    cursorPos: number;
+};
 export declare function extractFormulaReferences(formula: string): FormulaReference[];

package/dist/types/utils/index.d.ts

@@ -39,6 +39,8 @@ export { applyFillValues } from './fillHelpers';
 export type { IFillFormulaOptions } from './fillHelpers';
 export { UndoRedoStack } from './undoRedoStack';
 export { validateColumns, validateRowIds, validateVirtualScrollConfig } from './validation';
-export { indexToColumnLetter, formatCellReference } from './cellReference';
-export { extractFormulaReferences, processFormulaBarCommit, deriveFormulaBarText, handleFormulaBarKeyDown } from './formulaBarHelpers';
+export { indexToColumnLetter, columnLetterToIndex, formatCellReference } from './cellReference';
+export { extractFormulaReferences, processFormulaBarCommit, deriveFormulaBarText, handleFormulaBarKeyDown, canInsertReference, insertReferenceAtCursor } from './formulaBarHelpers';
 export type { FormulaReference } from './formulaBarHelpers';
+export { getResponsiveHiddenColumns, RESPONSIVE_BREAKPOINTS, resolveResponsiveConfig, applyResponsiveHiding } from './responsiveColumns';
+export type { IResponsiveColumnsConfig } from './responsiveColumns';

package/dist/types/utils/responsiveColumns.d.ts

@@ -0,0 +1,46 @@
+import type { IColumnMeta } from '../types/columnTypes';
+/**
+ * Default breakpoints for responsive column hiding.
+ * Each threshold maps a minimum container width (px) to how many responsive
+ * priority levels are visible. At 0px all priority-0 columns are shown;
+ * wider containers show progressively more columns.
+ *
+ * Example with default thresholds:
+ *   container < 576px  → show only priority 0
+ *   container < 768px  → show priority 0–1
+ *   container < 992px  → show priority 0–2
+ *   container < 1200px → show priority 0–3
+ *   container ≥ 1200px → show all (no limit)
+ */
+export declare const RESPONSIVE_BREAKPOINTS: readonly {
+    minWidth: number;
+    maxPriority: number;
+}[];
+export interface IResponsiveColumnsConfig {
+    /** Custom breakpoints (ascending by minWidth). When omitted, uses RESPONSIVE_BREAKPOINTS. */
+    breakpoints?: readonly {
+        minWidth: number;
+        maxPriority: number;
+    }[];
+}
+/**
+ * Pure function: given a container width and column definitions, returns the set
+ * of column IDs that should be hidden due to responsive priority.
+ *
+ * Columns WITHOUT `responsivePriority` are never hidden.
+ * Columns with `required: true` are never hidden.
+ *
+ * @returns Set of columnIds to hide. Empty set means no responsive hiding.
+ */
+export declare function getResponsiveHiddenColumns<T extends IColumnMeta>(containerWidth: number, columns: readonly T[], config?: IResponsiveColumnsConfig): Set<string>;
+/**
+ * Normalize the `responsiveColumns` prop value (boolean | config | undefined)
+ * into a config object or undefined. Used by all framework packages so they
+ * don't each duplicate the `true → {}` coercion.
+ */
+export declare function resolveResponsiveConfig(value: boolean | IResponsiveColumnsConfig | undefined): IResponsiveColumnsConfig | undefined;
+/**
+ * Apply responsive column hiding to an already-filtered column list.
+ * Returns the input array unchanged when no columns need hiding (avoids allocation).
+ */
+export declare function applyResponsiveHiding<T extends IColumnMeta>(columns: readonly T[], containerWidth: number, config: IResponsiveColumnsConfig | undefined): readonly T[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/ogrid-core",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "description": "OGrid core – framework-agnostic types, algorithms, and utilities for OGrid data grids.",
   "main": "dist/esm/index.js",
   "module": "dist/esm/index.js",
@@ -10,6 +10,11 @@
       "types": "./dist/types/index.d.ts",
       "import": "./dist/esm/index.js",
       "default": "./dist/esm/index.js"
+    },
+    "./formula": {
+      "types": "./dist/types/formula/index.d.ts",
+      "import": "./dist/esm/formula/index.js",
+      "default": "./dist/esm/formula/index.js"
     }
   },
   "scripts": {