@gp-grid/core 0.16.0 → 0.17.0

package/README.md

@@ -3,9 +3,9 @@
 <div align="center">
     <a href="https://www.gp-grid.io">
         <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/GioPat/gp-grid-docs/refs/heads/master/public/logo-light.svg"/>
-        <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/GioPat/gp-grid-docs/refs/heads/master/public/logo-dark.svg"/>
-        <img width="50%" alt="AG Grid Logo" src="https://raw.githubusercontent.com/GioPat/gp-grid-docs/refs/heads/master/public/logo-dark.svg"/>
+        <source media="(prefers-color-scheme: dark)" srcset="https://www.gp-grid.io/logo-light.svg"/>
+        <source media="(prefers-color-scheme: light)" srcset="https://www.gp-grid.io/logo-dark.svg"/>
+        <img width="50%" alt="gp-grid Logo" src="https://www.gp-grid.io/logo-dark.svg"/>
         </picture>
     </a>
     <div align="center">

package/dist/index.d.ts

@@ -242,6 +242,19 @@ interface ColumnDefinition {
   movable?: boolean;
   /** Whether this column acts as a drag handle for row dragging. Default: false */
   rowDrag?: boolean;
+  /**
+   * Whether double-clicking a non-editable cell opens a read-only peek overlay
+   * that wraps the value across multiple lines. Ignored when `editable` is true
+   * (double-click starts editing instead). Default: true.
+   */
+  peekable?: boolean;
+  /**
+   * Whether to set a native `title` attribute on cells in this column so the
+   * browser shows the full formatted value on hover. Useful when text is
+   * truncated by the cell width. Default: true. Set false to opt out — e.g.
+   * for cells whose custom renderer already provides its own tooltip.
+   */
+  tooltip?: boolean;
   /** Renderer key for adapter lookup, or inline renderer function */
   cellRenderer?: string | ((params: CellRendererParams) => unknown);
   editRenderer?: string | ((params: EditRendererParams) => unknown);
@@ -252,6 +265,14 @@ interface ColumnDefinition {
    * default JSON.stringify may not be suitable (e.g., display a single field of an object).
    */
   valueFormatter?: (value: CellValue) => string;
+  /**
+   * Pre-supplied set of all possible values for the filter popup's "values" mode.
+   * When provided, the grid skips scanning row data to discover distinct values —
+   * use this for large datasets to avoid an O(n) scan when the value domain is
+   * known up front (e.g., enums, fixed tag lists). Values are still de-duplicated
+   * and sorted by their display string.
+   */
+  distinctValues?: CellValue[];
   /**
    * Per-column override for column-level highlighting.
    * If defined, overrides grid-level computeColumnClasses for this column.
@@ -435,6 +456,16 @@ interface CommitEditInstruction {
   col: number;
   value: CellValue;
 }
+/** Open a peek overlay on a cell */
+interface StartPeekInstruction {
+  type: "START_PEEK";
+  row: number;
+  col: number;
+}
+/** Close the active peek overlay */
+interface StopPeekInstruction {
+  type: "STOP_PEEK";
+}
 /** Programmatic scroll instruction — tells the framework to set container.scrollTop */
 interface ScrollToInstruction {
   type: "SCROLL_TO";
@@ -617,7 +648,7 @@ interface CancelRowDragInstruction {
   type: "CANCEL_ROW_DRAG";
 }
 /** Union type of all instructions */
-type GridInstruction = /** Slot lifecycle */CreateSlotInstruction | DestroySlotInstruction | AssignSlotInstruction | MoveSlotInstruction /** Scroll */ | ScrollToInstruction /** Selection */ | SetActiveCellInstruction | SetSelectionRangeInstruction | UpdateVisibleRangeInstruction /** Highlighting */ | SetHoverPositionInstruction /** Editing */ | StartEditInstruction | StopEditInstruction | CommitEditInstruction /** Layout */ | SetContentSizeInstruction | UpdateHeaderInstruction /** Filter popup */ | OpenFilterPopupInstruction | CloseFilterPopupInstruction /** Fill handle */ | StartFillInstruction | UpdateFillInstruction | CommitFillInstruction | CancelFillInstruction /** Data */ | DataLoadingInstruction | DataLoadedInstruction | DataErrorInstruction /** Transactions */ | RowsAddedInstruction | RowsRemovedInstruction | RowsUpdatedInstruction | TransactionProcessedInstruction /** Column changes */ | ColumnsChangedInstruction /** Column resize */ | StartColumnResizeInstruction | UpdateColumnResizeInstruction | CommitColumnResizeInstruction | CancelColumnResizeInstruction /** Column move */ | StartColumnMoveInstruction | UpdateColumnMoveInstruction | CommitColumnMoveInstruction | CancelColumnMoveInstruction /** Row drag */ | StartRowDragInstruction | UpdateRowDragInstruction | CommitRowDragInstruction | CancelRowDragInstruction;
+type GridInstruction = /** Slot lifecycle */CreateSlotInstruction | DestroySlotInstruction | AssignSlotInstruction | MoveSlotInstruction /** Scroll */ | ScrollToInstruction /** Selection */ | SetActiveCellInstruction | SetSelectionRangeInstruction | UpdateVisibleRangeInstruction /** Highlighting */ | SetHoverPositionInstruction /** Editing */ | StartEditInstruction | StopEditInstruction | CommitEditInstruction /** Peek (read-only expand) */ | StartPeekInstruction | StopPeekInstruction /** Layout */ | SetContentSizeInstruction | UpdateHeaderInstruction /** Filter popup */ | OpenFilterPopupInstruction | CloseFilterPopupInstruction /** Fill handle */ | StartFillInstruction | UpdateFillInstruction | CommitFillInstruction | CancelFillInstruction /** Data */ | DataLoadingInstruction | DataLoadedInstruction | DataErrorInstruction /** Transactions */ | RowsAddedInstruction | RowsRemovedInstruction | RowsUpdatedInstruction | TransactionProcessedInstruction /** Column changes */ | ColumnsChangedInstruction /** Column resize */ | StartColumnResizeInstruction | UpdateColumnResizeInstruction | CommitColumnResizeInstruction | CancelColumnResizeInstruction /** Column move */ | StartColumnMoveInstruction | UpdateColumnMoveInstruction | CommitColumnMoveInstruction | CancelColumnMoveInstruction /** Row drag */ | StartRowDragInstruction | UpdateRowDragInstruction | CommitRowDragInstruction | CancelRowDragInstruction;
 /** Instruction listener: Single instruction Listener that receives a single instruction, used by frameworks to update their state */
 type InstructionListener = (instruction: GridInstruction) => void;
 /** Batch instruction listener: Batch instruction Listener that receives an array of instructions, used by frameworks to update their state */
@@ -1407,6 +1438,7 @@ declare class SortFilterManager<TData = Record<string, unknown>> {
   private sortModel;
   private filterModel;
   private openFilterColIndex;
+  private readonly scanWarnedCols;
   onInstruction: (listener: InstructionListener) => () => void;
   private readonly emit;
   constructor(options: SortFilterManagerOptions<TData>);
@@ -1427,20 +1459,22 @@ declare class SortFilterManager<TData = Record<string, unknown>> {
    */
   isColumnFilterable(colIndex: number): boolean;
   /**
-   * Get distinct values for a column (for filter dropdowns)
-   * For array-type columns (like tags), each unique array combination is returned.
-   * Arrays are sorted internally for consistent comparison.
-   * Limited to maxValues distinct results and maxScanRows rows scanned.
+   * Get distinct values for a column (for filter dropdowns).
+   *
+   * When the column defines `distinctValues`, that list is used directly
+   * (deduplicated + sorted by display string). Otherwise the manager scans
+   * every cached row to compute the set. The previous stride-sampling
+   * fallback was removed because the stride could share a factor with a
+   * repeating value pool, causing some values to be unreachable (the
+   * `bio` field in the demo dataset was a real example: stride 15 with a
+   * pool size of 6 yielded only 2 of 6 values).
    *
-   * When the total exceeds maxScanRows we stride-sample across the full
-   * dataset instead of scanning the first N rows. Sequential scan was
-   * broken under an active sort: Map iteration follows insertion order,
-   * which after sort is the sorted order — so the first 100k rows only
-   * covered the "smallest" values of the column. Stride sampling covers
-   * the whole range at the cost of possibly missing rare values, which
-   * the maxValues cap would have dropped anyway.
+   * For datasets above {@link DISTINCT_SCAN_WARN_THRESHOLD}, a one-time
+   * console warning advises the consumer to pre-supply `distinctValues`
+   * on the column to skip the full scan.
    */
-  getDistinctValuesForColumn(colId: string, maxValues?: number, maxScanRows?: number): CellValue[];
+  getDistinctValuesForColumn(colId: string, maxValues?: number): CellValue[];
+  private scanDistinctValues;
   /**
    * Normalize a cell value into a dedup key and the value to store.
    * Arrays are sorted lexicographically so different orderings produce the same key.
@@ -1875,6 +1909,19 @@ declare class GridCore<TData = unknown> {
   getSortModel(): SortModel[];
   getFilterModel(): FilterModel;
   startEdit(row: number, col: number): void;
+  /**
+   * Open a read-only peek overlay on a cell. The default cell renderer is
+   * shown in a multi-line container so long values are fully visible.
+   * Returns true if the peek opened (column must be `peekable !== false`
+   * and not currently being edited).
+   */
+  startPeek(row: number, col: number): boolean;
+  /** Close any active peek overlay. */
+  stopPeek(): void;
+  getPeekState(): {
+    row: number;
+    col: number;
+  } | null;
   updateEditValue(value: CellValue): void;
   commitEdit(): void;
   cancelEdit(): void;
@@ -1888,7 +1935,9 @@ declare class GridCore<TData = unknown> {
   private emitHeaders;
   private emitVisibleRange;
   /**
-   * Set the width of a column and recompute layout.
+   * Set the displayed width of a column and recompute layout. `width` is the
+   * post-redistribution displayed width — the stored `column.width` is
+   * back-solved so the column ends up exactly `width` pixels wide.
    */
   setColumnWidth(colIndex: number, width: number): void;
   /**
@@ -2105,6 +2154,8 @@ interface GridState<TData = unknown> {
     col: number;
     initialValue: CellValue;
   } | null;
+  /** Cell currently shown in a read-only peek overlay (multi-line expand on double-click) */
+  peekCell: CellPosition | null;
   contentWidth: number;
   contentHeight: number;
   /** Viewport width (container's visible width) for column scaling */
@@ -2208,6 +2259,22 @@ interface PopupPosition {
  */
 declare const calculateFilterPopupPosition: (headerCell: HTMLElement, popupEl: HTMLElement, viewportPadding?: number) => PopupPosition;
 //#endregion
+//#region src/utils/peek-select-all.d.ts
+/**
+ * Scope Ctrl/Cmd+A to the peek overlay's content.
+ *
+ * Pure CSS (`user-select: none` outside the overlay) only hides the visual
+ * highlight — the browser still constructs a Selection range across the whole
+ * document, and form controls use a separate selection model that CSS does
+ * not affect. This helper intercepts the shortcut, builds a Range covering
+ * the overlay node, and installs it as the active Selection so only the
+ * overlay's text is highlighted.
+ *
+ * Returns a cleanup function the caller invokes on unmount.
+ * SSR-safe: no-op when `document` is undefined.
+ */
+declare const bindPeekSelectAll: (overlay: HTMLElement) => (() => void);
+//#endregion
 //#region src/slot-pool.d.ts
 interface SlotPoolManagerOptions {
   /** Get current row height */
@@ -2328,6 +2395,7 @@ interface EditManagerOptions {
  */
 declare class EditManager {
   private editState;
+  private peekState;
   private readonly options;
   private readonly emitter;
   onInstruction: (listener: InstructionListener) => () => void;
@@ -2350,6 +2418,21 @@ declare class EditManager {
    * Returns true if edit was started, false if cell is not editable.
    */
   startEdit(row: number, col: number): boolean;
+  /**
+   * Get the cell currently shown in a peek overlay, or null.
+   */
+  getPeekState(): CellPosition | null;
+  /**
+   * Open a peek overlay on a cell. Caller is responsible for guarding on
+   * `column.peekable` — the manager only refuses when an edit is in progress
+   * (edit and peek are mutually exclusive).
+   * Returns true if the peek was opened.
+   */
+  startPeek(row: number, col: number): boolean;
+  /**
+   * Close any active peek overlay. No-op if none is open.
+   */
+  stopPeek(): void;
   /**
    * Update the current edit value.
    */
@@ -2761,6 +2844,7 @@ interface BatchChangeSetters {
   setSelectionRange: (v: CellRange | null) => void;
   setEditingCell: (v: EditingCell) => void;
   setHoverPosition: (v: CellPosition | null) => void;
+  setPeekCell: (v: CellPosition | null) => void;
   setColumnsOverride: (v: ColumnDefinition[]) => void;
   onFilterPopupChange: (v: FilterPopupState | null) => void;
 }
@@ -2874,4 +2958,4 @@ declare class InputEventAdapter<TData = unknown> {
   private dispatchCellDragStart;
 }
 //#endregion
-export { type AssignSlotInstruction, AutoScrollDriver, type BatchChangeSetters, type BatchInstructionListener, type CalculateFillHandlePositionParams, type CancelColumnMoveInstruction, type CancelColumnResizeInstruction, type CancelFillInstruction, type CancelRowDragInstruction, type CellDataType, type CellPointerAction, type CellPosition, type CellRange, type CellRendererParams, type CellValue, type CellValueChangedEvent, type CloseFilterPopupInstruction, type ColumnDefinition, type ColumnFilterModel, type ColumnMoveDragState, type ColumnResizeDragState, type ColumnsChangedInstruction, type CommitColumnMoveInstruction, type CommitColumnResizeInstruction, type CommitEditInstruction, type CommitFillInstruction, type CommitRowDragInstruction, type ContainerBounds, type CreateSlotInstruction, type DataChangeListener, type DataErrorInstruction, type DataLoadedInstruction, type DataLoadingInstruction, type DataSource, type DataSourceLoadMode, DataSourceOwner, type DataSourceRange, type DataSourceRequest, type DataSourceResponse, type DateFilterCondition, type DateFilterOperator, type DestroySlotInstruction, type Direction, type DragEndResult, type DragMoveResult, type DragState, EditManager, type EditManagerOptions, type EditRendererParams, type EditState, type FillHandlePosition, type FillHandleState, FillManager, type FillPointerAction, type FilterCombination, type FilterCondition, type FilterModel, type FilterPopupState, GridCore, type GridCoreOptions, type GridInstruction, type GridState, type HeaderData, type HeaderRendererParams, type HighlightContext, HighlightManager, type HighlightingOptions, IndexedDataStore, type IndexedDataStoreOptions, type InitialStateArgs, InputEventAdapter, type InputEventAdapterDeps, InputHandler, type InputHandlerDeps, type InputResult, type InstructionListener, type KeyEventData, type KeyboardResult, type MoveSlotInstruction, type MultiColumnSortedChunk, type MutableClientDataSourceOptions, type MutableDataSource, type NumberFilterCondition, type NumberFilterOperator, type OpenFilterPopupInstruction, ParallelSortManager, type ParallelSortOptions, PendingRowDragController, type PendingRowDragDeps, type PointerEventData, type PopupPosition, type RowCacheEviction, type RowCacheOptions, RowDataManager, type RowDataManagerOptions, type RowDragState, type RowId, type RowLoadingMode, type RowLoadingOptions, RowMutationManager, type RowMutationManagerOptions, type RowSortCache, type RowsAddedInstruction, type RowsRemovedInstruction, type RowsUpdatedInstruction, ScrollVirtualizationManager, type ScrollVirtualizationManagerOptions, SelectionManager, type SelectionState, type ServerDataSourceOptions, type SetActiveCellInstruction, type SetContentSizeInstruction, type SetHoverPositionInstruction, type SetSelectionRangeInstruction, type SlotData, type BatchInstructionListener$1 as SlotPoolBatchListener, SlotPoolManager, type SlotPoolManagerOptions, type SlotState, type SortDirection, SortFilterManager, type SortFilterManagerOptions, type SortModel, type SortedChunk, type StartColumnMoveInstruction, type StartColumnResizeInstruction, type StartEditInstruction, type StartFillInstruction, type StartRowDragInstruction, type StopEditInstruction, type TextFilterCondition, type TextFilterOperator, type Transaction, TransactionManager, type TransactionManagerOptions, type TransactionProcessedInstruction, type TransactionResult, type UpdateColumnMoveInstruction, type UpdateColumnResizeInstruction, type UpdateFillInstruction, type UpdateHeaderInstruction, type UpdateRowDragInstruction, type VisibleColumnInfo, WorkerPool, type WorkerPoolOptions, applyBatchInstructions, applyInstruction, buildCellClasses, calculateColumnPositions, calculateFillHandlePosition, calculateFilterPopupPosition, calculateScaledColumnPositions, cellStyles, compareValues, computeValueHash, containerStyles, createClientDataSource, createDataSourceFromArray, createInitialState, createMutableClientDataSource, createServerDataSource, detectBoundaryCollisions, evaluateColumnFilter, evaluateDateCondition, evaluateNumberCondition, evaluateTextCondition, filtersStyles, findColumnAtX, findSlotForRow, formatCellValue, getFieldValue, getTotalWidth, gridStyles, headerStyles, isCellActive, isCellEditing, isCellInFillPreview, isCellSelected, isColumnInSelectionRange, isRowInSelectionRange, isRowVisible, isSameDay, kWayMerge, kWayMergeMultiColumn, rowDragStyles, rowPassesFilter, scrollCellIntoView, scrollbarStyles, setFieldValue, statesStyles, stringToSortableNumber, toPointerEventData, variablesStyles };
+export { type AssignSlotInstruction, AutoScrollDriver, type BatchChangeSetters, type BatchInstructionListener, type CalculateFillHandlePositionParams, type CancelColumnMoveInstruction, type CancelColumnResizeInstruction, type CancelFillInstruction, type CancelRowDragInstruction, type CellDataType, type CellPointerAction, type CellPosition, type CellRange, type CellRendererParams, type CellValue, type CellValueChangedEvent, type CloseFilterPopupInstruction, type ColumnDefinition, type ColumnFilterModel, type ColumnMoveDragState, type ColumnResizeDragState, type ColumnsChangedInstruction, type CommitColumnMoveInstruction, type CommitColumnResizeInstruction, type CommitEditInstruction, type CommitFillInstruction, type CommitRowDragInstruction, type ContainerBounds, type CreateSlotInstruction, type DataChangeListener, type DataErrorInstruction, type DataLoadedInstruction, type DataLoadingInstruction, type DataSource, type DataSourceLoadMode, DataSourceOwner, type DataSourceRange, type DataSourceRequest, type DataSourceResponse, type DateFilterCondition, type DateFilterOperator, type DestroySlotInstruction, type Direction, type DragEndResult, type DragMoveResult, type DragState, EditManager, type EditManagerOptions, type EditRendererParams, type EditState, type FillHandlePosition, type FillHandleState, FillManager, type FillPointerAction, type FilterCombination, type FilterCondition, type FilterModel, type FilterPopupState, GridCore, type GridCoreOptions, type GridInstruction, type GridState, type HeaderData, type HeaderRendererParams, type HighlightContext, HighlightManager, type HighlightingOptions, IndexedDataStore, type IndexedDataStoreOptions, type InitialStateArgs, InputEventAdapter, type InputEventAdapterDeps, InputHandler, type InputHandlerDeps, type InputResult, type InstructionListener, type KeyEventData, type KeyboardResult, type MoveSlotInstruction, type MultiColumnSortedChunk, type MutableClientDataSourceOptions, type MutableDataSource, type NumberFilterCondition, type NumberFilterOperator, type OpenFilterPopupInstruction, ParallelSortManager, type ParallelSortOptions, PendingRowDragController, type PendingRowDragDeps, type PointerEventData, type PopupPosition, type RowCacheEviction, type RowCacheOptions, RowDataManager, type RowDataManagerOptions, type RowDragState, type RowId, type RowLoadingMode, type RowLoadingOptions, RowMutationManager, type RowMutationManagerOptions, type RowSortCache, type RowsAddedInstruction, type RowsRemovedInstruction, type RowsUpdatedInstruction, ScrollVirtualizationManager, type ScrollVirtualizationManagerOptions, SelectionManager, type SelectionState, type ServerDataSourceOptions, type SetActiveCellInstruction, type SetContentSizeInstruction, type SetHoverPositionInstruction, type SetSelectionRangeInstruction, type SlotData, type BatchInstructionListener$1 as SlotPoolBatchListener, SlotPoolManager, type SlotPoolManagerOptions, type SlotState, type SortDirection, SortFilterManager, type SortFilterManagerOptions, type SortModel, type SortedChunk, type StartColumnMoveInstruction, type StartColumnResizeInstruction, type StartEditInstruction, type StartFillInstruction, type StartPeekInstruction, type StartRowDragInstruction, type StopEditInstruction, type StopPeekInstruction, type TextFilterCondition, type TextFilterOperator, type Transaction, TransactionManager, type TransactionManagerOptions, type TransactionProcessedInstruction, type TransactionResult, type UpdateColumnMoveInstruction, type UpdateColumnResizeInstruction, type UpdateFillInstruction, type UpdateHeaderInstruction, type UpdateRowDragInstruction, type VisibleColumnInfo, WorkerPool, type WorkerPoolOptions, applyBatchInstructions, applyInstruction, bindPeekSelectAll, buildCellClasses, calculateColumnPositions, calculateFillHandlePosition, calculateFilterPopupPosition, calculateScaledColumnPositions, cellStyles, compareValues, computeValueHash, containerStyles, createClientDataSource, createDataSourceFromArray, createInitialState, createMutableClientDataSource, createServerDataSource, detectBoundaryCollisions, evaluateColumnFilter, evaluateDateCondition, evaluateNumberCondition, evaluateTextCondition, filtersStyles, findColumnAtX, findSlotForRow, formatCellValue, getFieldValue, getTotalWidth, gridStyles, headerStyles, isCellActive, isCellEditing, isCellInFillPreview, isCellSelected, isColumnInSelectionRange, isRowInSelectionRange, isRowVisible, isSameDay, kWayMerge, kWayMergeMultiColumn, rowDragStyles, rowPassesFilter, scrollCellIntoView, scrollbarStyles, setFieldValue, statesStyles, stringToSortableNumber, toPointerEventData, variablesStyles };