@alaarab/ogrid-core 2.0.1 → 2.0.3

package/dist/esm/utils/columnReorder.js

@@ -0,0 +1,102 @@
+/**
+ * Determine which pin zone a column belongs to.
+ */
+export function getPinStateForColumn(columnId, pinnedColumns) {
+    if (!pinnedColumns)
+        return 'unpinned';
+    if (pinnedColumns.left?.includes(columnId))
+        return 'left';
+    if (pinnedColumns.right?.includes(columnId))
+        return 'right';
+    return 'unpinned';
+}
+/**
+ * Remove `columnId` from `order` and insert it at `targetIndex`.
+ * Returns a new array (does not mutate the input).
+ */
+export function reorderColumnArray(order, columnId, targetIndex) {
+    const filtered = order.filter(id => id !== columnId);
+    const clampedIndex = Math.max(0, Math.min(targetIndex, filtered.length));
+    const result = [...filtered];
+    result.splice(clampedIndex, 0, columnId);
+    return result;
+}
+/**
+ * Calculate the drop target for a dragged column based on mouse position.
+ *
+ * Iterates visible column header elements (queried via `[data-column-id]`),
+ * finds the midpoint of each header cell, and determines insertion side.
+ * Respects pinning zones: a left-pinned column can only drop among left-pinned, etc.
+ *
+ * @param mouseX - Current mouse X position (client coordinates)
+ * @param columnOrder - Current column display order (array of column ids)
+ * @param draggedColumnId - The column being dragged
+ * @param draggedPinState - Pin state of the dragged column
+ * @param tableElement - The table (or grid container) DOM element to query headers from
+ * @param pinnedColumns - Pinned column configuration
+ * @returns Drop target with insertion index and indicator X, or null if no valid target.
+ */
+export function calculateDropTarget(mouseX, columnOrder, draggedColumnId, draggedPinState, tableElement, pinnedColumns) {
+    const headerCells = tableElement.querySelectorAll('[data-column-id]');
+    if (headerCells.length === 0)
+        return null;
+    // Build ordered list of header rects for columns in the same pin zone
+    const targets = [];
+    headerCells.forEach(cell => {
+        const colId = cell.getAttribute('data-column-id');
+        if (!colId)
+            return;
+        const pinState = getPinStateForColumn(colId, pinnedColumns);
+        if (pinState !== draggedPinState)
+            return;
+        const rect = cell.getBoundingClientRect();
+        const orderIndex = columnOrder.indexOf(colId);
+        if (orderIndex === -1)
+            return;
+        targets.push({
+            columnId: colId,
+            left: rect.left,
+            right: rect.right,
+            midX: rect.left + rect.width / 2,
+            orderIndex,
+        });
+    });
+    if (targets.length === 0)
+        return null;
+    // Sort by visual position (left edge)
+    targets.sort((a, b) => a.left - b.left);
+    // Find where mouse falls relative to column midpoints
+    let targetIndex;
+    let indicatorX;
+    if (mouseX <= targets[0].midX) {
+        // Before the first target
+        targetIndex = targets[0].orderIndex;
+        indicatorX = targets[0].left;
+    }
+    else if (mouseX >= targets[targets.length - 1].midX) {
+        // After the last target
+        const last = targets[targets.length - 1];
+        targetIndex = last.orderIndex + 1;
+        indicatorX = last.right;
+    }
+    else {
+        // Between two targets — find the boundary
+        let matchIndex = -1;
+        for (let i = 0; i < targets.length - 1; i++) {
+            if (mouseX >= targets[i].midX && mouseX < targets[i + 1].midX) {
+                matchIndex = i;
+                break;
+            }
+        }
+        if (matchIndex === -1)
+            return null;
+        targetIndex = targets[matchIndex].orderIndex + 1;
+        indicatorX = targets[matchIndex].right;
+    }
+    // Check if this is a no-op (dropping at same position)
+    const currentIndex = columnOrder.indexOf(draggedColumnId);
+    if (currentIndex === targetIndex || currentIndex + 1 === targetIndex) {
+        return { targetIndex, indicatorX: null };
+    }
+    return { targetIndex, indicatorX };
+}

package/dist/esm/utils/index.js

@@ -10,3 +10,5 @@ export { parseValue, numberParser, currencyParser, dateParser, emailParser, bool
 export { computeAggregations } from './aggregationUtils';
 export { processClientSideData } from './clientSideData';
 export { areGridRowPropsEqual, isRowInRange } from './gridRowComparator';
+export { getPinStateForColumn, reorderColumnArray, calculateDropTarget, } from './columnReorder';
+export { computeVisibleRange, computeTotalHeight, getScrollTopForRow, } from './virtualScroll';

package/dist/esm/utils/virtualScroll.js

@@ -0,0 +1,46 @@
+/**
+ * Compute the range of rows that should be rendered for a given scroll position.
+ *
+ * @param scrollTop - Current vertical scroll offset (px)
+ * @param rowHeight - Fixed height of each row (px)
+ * @param containerHeight - Visible height of the scroll container (px)
+ * @param totalRows - Total number of rows in the dataset
+ * @param overscan - Number of extra rows to render above and below the visible area (default: 5)
+ * @returns The visible range with start/end indices and top/bottom spacer offsets
+ */
+export function computeVisibleRange(scrollTop, rowHeight, containerHeight, totalRows, overscan = 5) {
+    if (totalRows === 0 || rowHeight <= 0 || containerHeight <= 0) {
+        return { startIndex: 0, endIndex: -1, offsetTop: 0, offsetBottom: 0 };
+    }
+    const startIndex = Math.max(0, Math.floor(scrollTop / rowHeight) - overscan);
+    const endIndex = Math.min(totalRows - 1, Math.ceil((scrollTop + containerHeight) / rowHeight) + overscan);
+    const offsetTop = startIndex * rowHeight;
+    const offsetBottom = Math.max(0, (totalRows - endIndex - 1) * rowHeight);
+    return { startIndex, endIndex, offsetTop, offsetBottom };
+}
+/**
+ * Compute the total scrollable height for all rows.
+ */
+export function computeTotalHeight(totalRows, rowHeight) {
+    return totalRows * rowHeight;
+}
+/**
+ * Compute the scrollTop value needed to bring a specific row into view.
+ *
+ * @param rowIndex - The row to scroll to
+ * @param rowHeight - Fixed height of each row (px)
+ * @param containerHeight - Visible height of the scroll container (px)
+ * @param align - Where to position the row: 'start' (top), 'center', or 'end' (bottom). Default: 'start'.
+ * @returns The scrollTop value to set on the container
+ */
+export function getScrollTopForRow(rowIndex, rowHeight, containerHeight, align = 'start') {
+    const rowTop = rowIndex * rowHeight;
+    switch (align) {
+        case 'start':
+            return rowTop;
+        case 'center':
+            return Math.max(0, rowTop - (containerHeight - rowHeight) / 2);
+        case 'end':
+            return Math.max(0, rowTop - containerHeight + rowHeight);
+    }
+}

package/dist/types/types/dataGridTypes.d.ts

@@ -128,6 +128,20 @@ export interface ISideBarDef {
     /** Position of the side bar (default: 'right'). */
     position?: 'left' | 'right';
 }
+/** Configuration for virtual scrolling. */
+export interface IVirtualScrollConfig {
+    /** Enable virtual scrolling (default: false). */
+    enabled?: boolean;
+    /** Fixed row height in pixels (required when enabled). */
+    rowHeight?: number;
+    /** Number of extra rows to render above/below the visible area (default: 5). */
+    overscan?: number;
+}
+/** Configuration for column reordering via drag-and-drop. */
+export interface IColumnReorderConfig {
+    /** Enable column reordering (default: false). */
+    enabled?: boolean;
+}
 /** Imperative grid API exposed via ref. */
 export interface IOGridApi<T> {
     /** Set row data (client-side only; no-op when using dataSource). */
@@ -160,4 +174,12 @@ export interface IOGridApi<T> {
     getDisplayedRows: () => T[];
     /** Re-trigger a data fetch (server-side only; no-op for client-side). */
     refreshData: () => void;
+    /** Scroll to a specific row by index (virtual scrolling). */
+    scrollToRow: (index: number, options?: {
+        align?: 'start' | 'center' | 'end';
+    }) => void;
+    /** Get the current column display order (array of column ids). */
+    getColumnOrder: () => string[];
+    /** Set the column display order. */
+    setColumnOrder: (order: string[]) => void;
 }

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

@@ -1,3 +1,3 @@
 export type { ColumnFilterType, IDateFilterValue, IColumnFilterDef, IColumnMeta, IValueParserParams, IColumnDef, ICellValueChangedEvent, ICellEditorProps, CellEditorParams, IColumnGroupDef, HeaderCell, HeaderRow, IColumnDefinition, } from './columnTypes';
-export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, IOGridApi, } from './dataGridTypes';
+export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, IVirtualScrollConfig, IColumnReorderConfig, IOGridApi, } from './dataGridTypes';
 export { toUserLike, isInSelectionRange, normalizeSelectionRange, } from './dataGridTypes';

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

@@ -0,0 +1,40 @@
+/** Column pinning state for reorder zone constraints. */
+export type ColumnPinState = 'left' | 'right' | 'unpinned';
+/** Result of computing a drop target during column drag. */
+export interface IDropTarget {
+    /** The index in the column order array where the dragged column should be inserted. */
+    targetIndex: number;
+    /** X position (px) for the visual drop indicator, or null if dropping at the same position (no-op). */
+    indicatorX: number | null;
+}
+/**
+ * Determine which pin zone a column belongs to.
+ */
+export declare function getPinStateForColumn(columnId: string, pinnedColumns?: {
+    left?: string[];
+    right?: string[];
+}): ColumnPinState;
+/**
+ * Remove `columnId` from `order` and insert it at `targetIndex`.
+ * Returns a new array (does not mutate the input).
+ */
+export declare function reorderColumnArray(order: string[], columnId: string, targetIndex: number): string[];
+/**
+ * Calculate the drop target for a dragged column based on mouse position.
+ *
+ * Iterates visible column header elements (queried via `[data-column-id]`),
+ * finds the midpoint of each header cell, and determines insertion side.
+ * Respects pinning zones: a left-pinned column can only drop among left-pinned, etc.
+ *
+ * @param mouseX - Current mouse X position (client coordinates)
+ * @param columnOrder - Current column display order (array of column ids)
+ * @param draggedColumnId - The column being dragged
+ * @param draggedPinState - Pin state of the dragged column
+ * @param tableElement - The table (or grid container) DOM element to query headers from
+ * @param pinnedColumns - Pinned column configuration
+ * @returns Drop target with insertion index and indicator X, or null if no valid target.
+ */
+export declare function calculateDropTarget(mouseX: number, columnOrder: string[], draggedColumnId: string, draggedPinState: ColumnPinState, tableElement: Element, pinnedColumns?: {
+    left?: string[];
+    right?: string[];
+}): IDropTarget | null;

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

@@ -17,3 +17,7 @@ export type { AggregationResult } from './aggregationUtils';
 export { processClientSideData } from './clientSideData';
 export { areGridRowPropsEqual, isRowInRange } from './gridRowComparator';
 export type { GridRowComparatorProps } from './gridRowComparator';
+export { getPinStateForColumn, reorderColumnArray, calculateDropTarget, } from './columnReorder';
+export type { ColumnPinState, IDropTarget } from './columnReorder';
+export { computeVisibleRange, computeTotalHeight, getScrollTopForRow, } from './virtualScroll';
+export type { IVisibleRange } from './virtualScroll';

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

@@ -0,0 +1,36 @@
+/** The visible row range and spacer offsets for virtual scrolling. */
+export interface IVisibleRange {
+    /** First visible row index (inclusive, accounting for overscan). */
+    startIndex: number;
+    /** Last visible row index (inclusive, accounting for overscan). */
+    endIndex: number;
+    /** Pixel height of the top spacer (to push visible rows into correct scroll position). */
+    offsetTop: number;
+    /** Pixel height of the bottom spacer (to maintain correct scroll height). */
+    offsetBottom: number;
+}
+/**
+ * Compute the range of rows that should be rendered for a given scroll position.
+ *
+ * @param scrollTop - Current vertical scroll offset (px)
+ * @param rowHeight - Fixed height of each row (px)
+ * @param containerHeight - Visible height of the scroll container (px)
+ * @param totalRows - Total number of rows in the dataset
+ * @param overscan - Number of extra rows to render above and below the visible area (default: 5)
+ * @returns The visible range with start/end indices and top/bottom spacer offsets
+ */
+export declare function computeVisibleRange(scrollTop: number, rowHeight: number, containerHeight: number, totalRows: number, overscan?: number): IVisibleRange;
+/**
+ * Compute the total scrollable height for all rows.
+ */
+export declare function computeTotalHeight(totalRows: number, rowHeight: number): number;
+/**
+ * Compute the scrollTop value needed to bring a specific row into view.
+ *
+ * @param rowIndex - The row to scroll to
+ * @param rowHeight - Fixed height of each row (px)
+ * @param containerHeight - Visible height of the scroll container (px)
+ * @param align - Where to position the row: 'start' (top), 'center', or 'end' (bottom). Default: 'start'.
+ * @returns The scrollTop value to set on the container
+ */
+export declare function getScrollTopForRow(rowIndex: number, rowHeight: number, containerHeight: number, align?: 'start' | 'center' | 'end'): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/ogrid-core",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "OGrid core – framework-agnostic types, algorithms, and utilities for OGrid data grids.",
   "main": "dist/esm/index.js",
   "module": "dist/esm/index.js",