@alaarab/ogrid-angular 2.6.0 → 2.6.1

package/dist/esm/services/ogrid.service.js

@@ -0,0 +1,1094 @@
+import { Injectable, signal, computed, effect, DestroyRef, inject } from '@angular/core';
+import { mergeFilter, deriveFilterOptionsFromData, getMultiSelectFilterFields, flattenColumns, processClientSideData, processClientSideDataAsync, computeNextSortState, shouldUseWorkerSort, validateColumns, validateRowIds, columnLetterToIndex, getCellValue, } from '@alaarab/ogrid-core';
+import { extractFormulaReferences, deriveFormulaBarText } from '@alaarab/ogrid-core/formula';
+import { FormulaEngineService } from './formula-engine.service';
+import * as i0 from "@angular/core";
+const DEFAULT_PAGE_SIZE = 25;
+const EMPTY_LOADING_OPTIONS = {};
+const DEFAULT_PANELS = ['columns', 'filters'];
+/**
+ * Top-level orchestration service for OGrid: manages pagination, sorting, filtering,
+ * column visibility, sidebar, and server-side data fetching via Angular signals.
+ *
+ * Port of React's useOGrid hook.
+ */
+export class OGridService {
+    constructor() {
+        this.destroyRef = inject(DestroyRef);
+        // --- Input signals (set by the component consuming this service) ---
+        this.columnsProp = signal([], ...(ngDevMode ? [{ debugName: "columnsProp" }] : []));
+        this.getRowId = signal((item) => item['id'], ...(ngDevMode ? [{ debugName: "getRowId" }] : []));
+        this.data = signal(undefined, ...(ngDevMode ? [{ debugName: "data" }] : []));
+        this.dataSource = signal(undefined, ...(ngDevMode ? [{ debugName: "dataSource" }] : []));
+        this.controlledPage = signal(undefined, ...(ngDevMode ? [{ debugName: "controlledPage" }] : []));
+        this.controlledPageSize = signal(undefined, ...(ngDevMode ? [{ debugName: "controlledPageSize" }] : []));
+        this.controlledSort = signal(undefined, ...(ngDevMode ? [{ debugName: "controlledSort" }] : []));
+        this.controlledFilters = signal(undefined, ...(ngDevMode ? [{ debugName: "controlledFilters" }] : []));
+        this.controlledVisibleColumns = signal(undefined, ...(ngDevMode ? [{ debugName: "controlledVisibleColumns" }] : []));
+        this.controlledLoading = signal(undefined, ...(ngDevMode ? [{ debugName: "controlledLoading" }] : []));
+        this.onPageChange = signal(undefined, ...(ngDevMode ? [{ debugName: "onPageChange" }] : []));
+        this.onPageSizeChange = signal(undefined, ...(ngDevMode ? [{ debugName: "onPageSizeChange" }] : []));
+        this.onSortChange = signal(undefined, ...(ngDevMode ? [{ debugName: "onSortChange" }] : []));
+        this.onFiltersChange = signal(undefined, ...(ngDevMode ? [{ debugName: "onFiltersChange" }] : []));
+        this.onVisibleColumnsChange = signal(undefined, ...(ngDevMode ? [{ debugName: "onVisibleColumnsChange" }] : []));
+        this.columnOrder = signal(undefined, ...(ngDevMode ? [{ debugName: "columnOrder" }] : []));
+        this.internalColumnOrder = signal(undefined, ...(ngDevMode ? [{ debugName: "internalColumnOrder" }] : []));
+        this.onColumnOrderChange = signal(undefined, ...(ngDevMode ? [{ debugName: "onColumnOrderChange" }] : []));
+        this.onColumnResized = signal(undefined, ...(ngDevMode ? [{ debugName: "onColumnResized" }] : []));
+        this.onAutosizeColumn = signal(undefined, ...(ngDevMode ? [{ debugName: "onAutosizeColumn" }] : []));
+        this.onColumnPinned = signal(undefined, ...(ngDevMode ? [{ debugName: "onColumnPinned" }] : []));
+        this.defaultPageSize = signal(DEFAULT_PAGE_SIZE, ...(ngDevMode ? [{ debugName: "defaultPageSize" }] : []));
+        this.defaultSortBy = signal(undefined, ...(ngDevMode ? [{ debugName: "defaultSortBy" }] : []));
+        this.defaultSortDirection = signal('asc', ...(ngDevMode ? [{ debugName: "defaultSortDirection" }] : []));
+        this.toolbar = signal(undefined, ...(ngDevMode ? [{ debugName: "toolbar" }] : []));
+        this.toolbarBelow = signal(undefined, ...(ngDevMode ? [{ debugName: "toolbarBelow" }] : []));
+        this.emptyState = signal(undefined, ...(ngDevMode ? [{ debugName: "emptyState" }] : []));
+        this.entityLabelPlural = signal('items', ...(ngDevMode ? [{ debugName: "entityLabelPlural" }] : []));
+        this.className = signal(undefined, ...(ngDevMode ? [{ debugName: "className" }] : []));
+        this.layoutMode = signal('fill', ...(ngDevMode ? [{ debugName: "layoutMode" }] : []));
+        this.suppressHorizontalScroll = signal(undefined, ...(ngDevMode ? [{ debugName: "suppressHorizontalScroll" }] : []));
+        this.stickyHeader = signal(true, ...(ngDevMode ? [{ debugName: "stickyHeader" }] : []));
+        this.fullScreen = signal(false, ...(ngDevMode ? [{ debugName: "fullScreen" }] : []));
+        this.editable = signal(undefined, ...(ngDevMode ? [{ debugName: "editable" }] : []));
+        this.cellSelection = signal(undefined, ...(ngDevMode ? [{ debugName: "cellSelection" }] : []));
+        this.density = signal('normal', ...(ngDevMode ? [{ debugName: "density" }] : []));
+        this.rowHeight = signal(undefined, ...(ngDevMode ? [{ debugName: "rowHeight" }] : []));
+        this.onCellValueChanged = signal(undefined, ...(ngDevMode ? [{ debugName: "onCellValueChanged" }] : []));
+        this.onUndo = signal(undefined, ...(ngDevMode ? [{ debugName: "onUndo" }] : []));
+        this.onRedo = signal(undefined, ...(ngDevMode ? [{ debugName: "onRedo" }] : []));
+        this.canUndo = signal(undefined, ...(ngDevMode ? [{ debugName: "canUndo" }] : []));
+        this.canRedo = signal(undefined, ...(ngDevMode ? [{ debugName: "canRedo" }] : []));
+        this.rowSelection = signal('none', ...(ngDevMode ? [{ debugName: "rowSelection" }] : []));
+        this.selectedRows = signal(undefined, ...(ngDevMode ? [{ debugName: "selectedRows" }] : []));
+        this.onSelectionChange = signal(undefined, ...(ngDevMode ? [{ debugName: "onSelectionChange" }] : []));
+        this.statusBar = signal(undefined, ...(ngDevMode ? [{ debugName: "statusBar" }] : []));
+        this.pageSizeOptions = signal(undefined, ...(ngDevMode ? [{ debugName: "pageSizeOptions" }] : []));
+        this.sideBarConfig = signal(undefined, ...(ngDevMode ? [{ debugName: "sideBarConfig" }] : []));
+        this.onFirstDataRendered = signal(undefined, ...(ngDevMode ? [{ debugName: "onFirstDataRendered" }] : []));
+        this.onError = signal(undefined, ...(ngDevMode ? [{ debugName: "onError" }] : []));
+        this.columnChooserProp = signal(undefined, ...(ngDevMode ? [{ debugName: "columnChooserProp" }] : []));
+        this.columnReorder = signal(undefined, ...(ngDevMode ? [{ debugName: "columnReorder" }] : []));
+        this.responsiveColumns = signal(undefined, ...(ngDevMode ? [{ debugName: "responsiveColumns" }] : []));
+        this.virtualScroll = signal(undefined, ...(ngDevMode ? [{ debugName: "virtualScroll" }] : []));
+        this.ariaLabel = signal(undefined, ...(ngDevMode ? [{ debugName: "ariaLabel" }] : []));
+        this.ariaLabelledBy = signal(undefined, ...(ngDevMode ? [{ debugName: "ariaLabelledBy" }] : []));
+        this.workerSort = signal(false, ...(ngDevMode ? [{ debugName: "workerSort" }] : []));
+        this.showRowNumbers = signal(false, ...(ngDevMode ? [{ debugName: "showRowNumbers" }] : []));
+        this.cellReferences = signal(false, ...(ngDevMode ? [{ debugName: "cellReferences" }] : []));
+        this.formulasEnabled = signal(false, ...(ngDevMode ? [{ debugName: "formulasEnabled" }] : []));
+        this.initialFormulas = signal(undefined, ...(ngDevMode ? [{ debugName: "initialFormulas" }] : []));
+        this.onFormulaRecalc = signal(undefined, ...(ngDevMode ? [{ debugName: "onFormulaRecalc" }] : []));
+        this.formulaFunctions = signal(undefined, ...(ngDevMode ? [{ debugName: "formulaFunctions" }] : []));
+        this.namedRanges = signal(undefined, ...(ngDevMode ? [{ debugName: "namedRanges" }] : []));
+        this.sheets = signal(undefined, ...(ngDevMode ? [{ debugName: "sheets" }] : []));
+        this.sheetDefs = signal(undefined, ...(ngDevMode ? [{ debugName: "sheetDefs" }] : []));
+        this.activeSheet = signal(undefined, ...(ngDevMode ? [{ debugName: "activeSheet" }] : []));
+        this.onSheetChange = signal(undefined, ...(ngDevMode ? [{ debugName: "onSheetChange" }] : []));
+        this.onSheetAdd = signal(undefined, ...(ngDevMode ? [{ debugName: "onSheetAdd" }] : []));
+        /** Active cell reference string (e.g. 'A1') updated by DataGridTable when cellReferences is enabled. */
+        this.activeCellRef = signal(null, ...(ngDevMode ? [{ debugName: "activeCellRef" }] : []));
+        /** Active cell coordinates (0-based col/row). */
+        this.activeCellCoords = signal(null, ...(ngDevMode ? [{ debugName: "activeCellCoords" }] : []));
+        /** Stable callback passed to DataGridTable to update activeCellRef + coords. */
+        this.handleActiveCellChange = (ref) => {
+            this.activeCellRef.set(ref);
+            if (ref) {
+                const m = ref.match(/^([A-Z]+)(\d+)$/);
+                if (m) {
+                    this.activeCellCoords.set({ col: columnLetterToIndex(m[1]), row: parseInt(m[2], 10) - 1 });
+                }
+                else {
+                    this.activeCellCoords.set(null);
+                }
+            }
+            else {
+                this.activeCellCoords.set(null);
+            }
+        };
+        // --- Formula bar state ---
+        this.formulaBarEditing = signal(false, ...(ngDevMode ? [{ debugName: "formulaBarEditing" }] : []));
+        this.formulaBarEditText = signal('', ...(ngDevMode ? [{ debugName: "formulaBarEditText" }] : []));
+        // --- Formula engine ---
+        this.formulaService = new FormulaEngineService();
+        /** Monotonic counter incremented on formula recalculation  -  drives cache invalidation. */
+        this.formulaVersion = signal(0, ...(ngDevMode ? [{ debugName: "formulaVersion" }] : []));
+        // Stable formula method references for dataGridProps (avoid per-recompute arrow functions)
+        this.getFormulaValueFn = (col, row) => this.formulaService.getValue(col, row);
+        this.hasFormulaFn = (col, row) => this.formulaService.hasFormula(col, row);
+        this.getFormulaFn = (col, row) => this.formulaService.getFormula(col, row);
+        this.setFormulaFn = (col, row, formula) => this.formulaService.setFormula(col, row, formula ?? '');
+        this.onFormulaCellChangedFn = (col, row) => this.formulaService.onCellChanged(col, row);
+        this.getPrecedentsFn = (col, row) => this.formulaService.getPrecedents(col, row);
+        this.getDependentsFn = (col, row) => this.formulaService.getDependents(col, row);
+        this.getAuditTrailFn = (col, row) => this.formulaService.getAuditTrail(col, row);
+        // --- Internal state signals ---
+        this.internalData = signal([], ...(ngDevMode ? [{ debugName: "internalData" }] : []));
+        this.internalLoading = signal(false, ...(ngDevMode ? [{ debugName: "internalLoading" }] : []));
+        this.internalPage = signal(1, ...(ngDevMode ? [{ debugName: "internalPage" }] : []));
+        this.internalPageSizeOverride = signal(null, ...(ngDevMode ? [{ debugName: "internalPageSizeOverride" }] : []));
+        this.internalSortOverride = signal(null, ...(ngDevMode ? [{ debugName: "internalSortOverride" }] : []));
+        this.internalFilters = signal({}, ...(ngDevMode ? [{ debugName: "internalFilters" }] : []));
+        this.internalVisibleColumnsOverride = signal(null, ...(ngDevMode ? [{ debugName: "internalVisibleColumnsOverride" }] : []));
+        this.internalSelectedRows = signal(new Set(), ...(ngDevMode ? [{ debugName: "internalSelectedRows" }] : []));
+        this.columnWidthOverrides = signal({}, ...(ngDevMode ? [{ debugName: "columnWidthOverrides" }] : []));
+        this.pinnedOverrides = signal({}, ...(ngDevMode ? [{ debugName: "pinnedOverrides" }] : []));
+        // Server-side state
+        this.serverItems = signal([], ...(ngDevMode ? [{ debugName: "serverItems" }] : []));
+        this.serverTotalCount = signal(0, ...(ngDevMode ? [{ debugName: "serverTotalCount" }] : []));
+        this.serverLoading = signal(true, ...(ngDevMode ? [{ debugName: "serverLoading" }] : []));
+        this.fetchAbortController = null;
+        this.filterAbortController = null;
+        this.refreshCounter = signal(0, ...(ngDevMode ? [{ debugName: "refreshCounter" }] : []));
+        this.firstDataRendered = signal(false, ...(ngDevMode ? [{ debugName: "firstDataRendered" }] : []));
+        // Worker sort async state
+        this.asyncClientItems = signal(null, ...(ngDevMode ? [{ debugName: "asyncClientItems" }] : []));
+        this.workerSortAbortId = 0;
+        // Stable sorted order (index-based, same approach as React/Vue).
+        // sortedIndices stores indices into displayData() from the last explicit sort/filter pass.
+        // When only displayData changes (cell edit), we reuse these indices to look up updated row
+        // objects - preserving order without re-sorting. Matches Excel behavior.
+        this.sortedIndices = null;
+        this.sortedPrevSortVersion = -1;
+        this.sortedPrevFilters = null;
+        this.sortedPrevColumns = null;
+        this.sortedPrevDataLength = -1;
+        this.sortSnapshotVersion = signal(0, ...(ngDevMode ? [{ debugName: "sortSnapshotVersion" }] : []));
+        // Side bar state
+        this.sideBarActivePanel = signal(null, ...(ngDevMode ? [{ debugName: "sideBarActivePanel" }] : []));
+        // Filter options state
+        this.serverFilterOptions = signal({}, ...(ngDevMode ? [{ debugName: "serverFilterOptions" }] : []));
+        this.loadingFilterOptions = signal({}, ...(ngDevMode ? [{ debugName: "loadingFilterOptions" }] : []));
+        // --- Derived computed signals ---
+        this.columns = computed(() => flattenColumns(this.columnsProp()), ...(ngDevMode ? [{ debugName: "columns" }] : []));
+        this.isServerSide = computed(() => this.dataSource() != null, ...(ngDevMode ? [{ debugName: "isServerSide" }] : []));
+        this.isClientSide = computed(() => !this.isServerSide(), ...(ngDevMode ? [{ debugName: "isClientSide" }] : []));
+        this.displayData = computed(() => this.data() ?? this.internalData(), ...(ngDevMode ? [{ debugName: "displayData" }] : []));
+        this.displayLoading = computed(() => this.controlledLoading() ?? this.internalLoading(), ...(ngDevMode ? [{ debugName: "displayLoading" }] : []));
+        this.defaultSortField = computed(() => this.defaultSortBy() ?? this.columns()[0]?.columnId ?? '', ...(ngDevMode ? [{ debugName: "defaultSortField" }] : []));
+        this.page = computed(() => this.controlledPage() ?? this.internalPage(), ...(ngDevMode ? [{ debugName: "page" }] : []));
+        this.pageSize = computed(() => this.controlledPageSize() ?? this.internalPageSizeOverride() ?? this.defaultPageSize(), ...(ngDevMode ? [{ debugName: "pageSize" }] : []));
+        this.sort = computed(() => this.controlledSort() ?? this.internalSortOverride() ?? {
+            field: this.defaultSortField(),
+            direction: this.defaultSortDirection(),
+        }, ...(ngDevMode ? [{ debugName: "sort" }] : []));
+        this.filters = computed(() => this.controlledFilters() ?? this.internalFilters(), ...(ngDevMode ? [{ debugName: "filters" }] : []));
+        this.visibleColumns = computed(() => {
+            const controlled = this.controlledVisibleColumns();
+            if (controlled)
+                return controlled;
+            const override = this.internalVisibleColumnsOverride();
+            if (override)
+                return override;
+            const cols = this.columns();
+            if (cols.length === 0)
+                return new Set();
+            const visible = cols.filter((c) => c.defaultVisible !== false).map((c) => c.columnId);
+            return new Set(visible.length > 0 ? visible : cols.map((c) => c.columnId));
+        }, ...(ngDevMode ? [{ debugName: "visibleColumns" }] : []));
+        this.effectiveColumnOrder = computed(() => this.columnOrder() ?? this.internalColumnOrder(), ...(ngDevMode ? [{ debugName: "effectiveColumnOrder" }] : []));
+        this.effectiveSelectedRows = computed(() => this.selectedRows() ?? this.internalSelectedRows(), ...(ngDevMode ? [{ debugName: "effectiveSelectedRows" }] : []));
+        this.columnChooserPlacement = computed(() => {
+            const prop = this.columnChooserProp();
+            return prop === false ? 'none' : prop === 'sidebar' ? 'sidebar' : 'toolbar';
+        }, ...(ngDevMode ? [{ debugName: "columnChooserPlacement" }] : []));
+        this.multiSelectFilterFields = computed(() => getMultiSelectFilterFields(this.columns()), ...(ngDevMode ? [{ debugName: "multiSelectFilterFields" }] : []));
+        this.hasServerFilterOptions = computed(() => this.dataSource()?.fetchFilterOptions != null, ...(ngDevMode ? [{ debugName: "hasServerFilterOptions" }] : []));
+        this.clientFilterOptions = computed(() => {
+            if (this.hasServerFilterOptions())
+                return this.serverFilterOptions();
+            return deriveFilterOptionsFromData(this.displayData(), this.columns());
+        }, ...(ngDevMode ? [{ debugName: "clientFilterOptions" }] : []));
+        this.workerSortEnabled = computed(() => shouldUseWorkerSort(this.workerSort(), this.displayData().length, {
+            columns: this.columns(),
+            filters: this.filters(),
+            sortBy: this.sort().field,
+        }), ...(ngDevMode ? [{ debugName: "workerSortEnabled" }] : []));
+        /** Sync path: used when workerSort is off. */
+        this.clientItemsAndTotal = computed(() => {
+            if (!this.isClientSide() || this.workerSortEnabled())
+                return null;
+            const data = this.displayData();
+            const cols = this.columns();
+            const f = this.filters();
+            const sv = this.sortSnapshotVersion(); // reactive: increments on explicit sort
+            const sortField = this.sort().field;
+            const sortDir = this.sort().direction;
+            const needsResort = sv !== this.sortedPrevSortVersion ||
+                f !== this.sortedPrevFilters ||
+                cols !== this.sortedPrevColumns ||
+                data.length !== this.sortedPrevDataLength;
+            let orderedRows;
+            if (needsResort || this.sortedIndices === null) {
+                this.sortedPrevSortVersion = sv;
+                this.sortedPrevFilters = f;
+                this.sortedPrevColumns = cols;
+                this.sortedPrevDataLength = data.length;
+                const sorted = processClientSideData(data, cols, f, sortField, sortDir);
+                const indexMap = new Map();
+                for (let i = 0; i < data.length; i++)
+                    indexMap.set(data[i], i);
+                this.sortedIndices = sorted.map((row) => {
+                    const idx = indexMap.get(row);
+                    return idx !== undefined ? idx : -1;
+                }).filter((idx) => idx !== -1);
+                orderedRows = sorted;
+            }
+            else {
+                // Cell edit: preserve existing order, look up updated row objects by index.
+                orderedRows = this.sortedIndices.map((idx) => data[idx]).filter((r) => r !== undefined);
+            }
+            const total = orderedRows.length;
+            const start = (this.page() - 1) * this.pageSize();
+            const paged = orderedRows.slice(start, start + this.pageSize());
+            return { items: paged, totalCount: total };
+        }, ...(ngDevMode ? [{ debugName: "clientItemsAndTotal" }] : []));
+        /** Resolved client items  -  sync or async depending on workerSort. */
+        this.resolvedClientItems = computed(() => {
+            // Sync path
+            const syncResult = this.clientItemsAndTotal();
+            if (syncResult)
+                return syncResult;
+            // Async path
+            return this.asyncClientItems();
+        }, ...(ngDevMode ? [{ debugName: "resolvedClientItems" }] : []));
+        this.displayItems = computed(() => {
+            const cit = this.resolvedClientItems();
+            return this.isClientSide() && cit ? cit.items : this.serverItems();
+        }, ...(ngDevMode ? [{ debugName: "displayItems" }] : []));
+        this.displayTotalCount = computed(() => {
+            const cit = this.resolvedClientItems();
+            return this.isClientSide() && cit ? cit.totalCount : this.serverTotalCount();
+        }, ...(ngDevMode ? [{ debugName: "displayTotalCount" }] : []));
+        this.hasActiveFilters = computed(() => {
+            return Object.values(this.filters()).some((v) => v !== undefined);
+        }, ...(ngDevMode ? [{ debugName: "hasActiveFilters" }] : []));
+        this.columnChooserColumns = computed(() => this.columns().map((c) => ({
+            columnId: c.columnId,
+            name: c.name,
+            required: c.required === true,
+        })), ...(ngDevMode ? [{ debugName: "columnChooserColumns" }] : []));
+        this.statusBarConfig = computed(() => {
+            const sb = this.statusBar();
+            if (!sb)
+                return undefined;
+            if (typeof sb === 'object')
+                return sb;
+            const totalData = this.isClientSide() ? (this.data()?.length ?? 0) : this.serverTotalCount();
+            const filteredData = this.displayTotalCount();
+            return {
+                totalCount: totalData,
+                filteredCount: this.hasActiveFilters() ? filteredData : undefined,
+                selectedCount: this.effectiveSelectedRows().size,
+                suppressRowCount: true,
+            };
+        }, ...(ngDevMode ? [{ debugName: "statusBarConfig" }] : []));
+        this.isLoadingResolved = computed(() => {
+            return (this.isServerSide() && this.serverLoading()) || this.displayLoading();
+        }, ...(ngDevMode ? [{ debugName: "isLoadingResolved" }] : []));
+        // Side bar
+        this.sideBarEnabled = computed(() => {
+            const config = this.sideBarConfig();
+            return config != null && config !== false;
+        }, ...(ngDevMode ? [{ debugName: "sideBarEnabled" }] : []));
+        this.sideBarParsed = computed(() => {
+            const config = this.sideBarConfig();
+            if (!this.sideBarEnabled() || config === true) {
+                return { panels: DEFAULT_PANELS, position: 'right', defaultPanel: null };
+            }
+            const def = config;
+            return {
+                panels: def.panels ?? DEFAULT_PANELS,
+                position: def.position ?? 'right',
+                defaultPanel: def.defaultPanel ?? null,
+            };
+        }, ...(ngDevMode ? [{ debugName: "sideBarParsed" }] : []));
+        this.filterableColumns = computed(() => this.columns()
+            .filter((c) => c.filterable && c.filterable.type)
+            .map((c) => ({
+            columnId: c.columnId,
+            name: c.name,
+            filterField: c.filterable?.filterField ?? c.columnId,
+            filterType: c.filterable?.type,
+        })), ...(ngDevMode ? [{ debugName: "filterableColumns" }] : []));
+        this.sideBarState = computed(() => ({
+            isEnabled: this.sideBarEnabled(),
+            activePanel: this.sideBarActivePanel(),
+            setActivePanel: (panel) => this.sideBarActivePanel.set(panel),
+            panels: this.sideBarParsed().panels,
+            position: this.sideBarParsed().position,
+            isOpen: this.sideBarActivePanel() !== null,
+            toggle: (panel) => this.sideBarActivePanel.update((p) => p === panel ? null : panel),
+            close: () => this.sideBarActivePanel.set(null),
+        }), ...(ngDevMode ? [{ debugName: "sideBarState" }] : []));
+        // --- Formula bar derived state ---
+        /** Display text derived from active cell (formula string or raw value). */
+        this.formulaBarDisplayText = computed(() => {
+            const coords = this.activeCellCoords();
+            if (!coords)
+                return '';
+            const getFormula = this.formulaService.enabled()
+                ? (c, r) => this.formulaService.getFormula(c, r)
+                : undefined;
+            const items = this.displayItems();
+            const cols = this.columns();
+            const getRawValue = (c, r) => {
+                if (r < 0 || r >= items.length || c < 0 || c >= cols.length)
+                    return undefined;
+                return getCellValue(items[r], cols[c]);
+            };
+            return deriveFormulaBarText(coords.col, coords.row, getFormula, getRawValue);
+        }, ...(ngDevMode ? [{ debugName: "formulaBarDisplayText" }] : []));
+        /** Formula text shown in the bar: edit text when editing, display text otherwise. */
+        this.formulaBarText = computed(() => this.formulaBarEditing() ? this.formulaBarEditText() : this.formulaBarDisplayText(), ...(ngDevMode ? [{ debugName: "formulaBarText" }] : []));
+        /** References extracted from the current formula text (for highlighting). */
+        this.formulaBarReferences = computed(() => extractFormulaReferences(this.formulaBarText()), ...(ngDevMode ? [{ debugName: "formulaBarReferences" }] : []));
+        // Stable formula bar callbacks (avoid new closures per computed)
+        this.formulaBarOnInputChangeFn = (text) => { this.formulaBarEditText.set(text); };
+        this.formulaBarOnCommitFn = () => { this.commitFormulaBar(); };
+        this.formulaBarOnCancelFn = () => { this.cancelFormulaBar(); };
+        this.formulaBarStartEditingFn = () => { this.startFormulaBarEditing(); };
+        /** Aggregate formula bar state for template consumption. */
+        this.formulaBarState = computed(() => ({
+            cellRef: this.activeCellRef(),
+            formulaText: this.formulaBarText(),
+            isEditing: this.formulaBarEditing(),
+            onInputChange: this.formulaBarOnInputChangeFn,
+            onCommit: this.formulaBarOnCommitFn,
+            onCancel: this.formulaBarOnCancelFn,
+            startEditing: this.formulaBarStartEditingFn,
+            referencedCells: this.formulaBarReferences(),
+        }), ...(ngDevMode ? [{ debugName: "formulaBarState" }] : []));
+        // --- Pre-computed stable callback references for dataGridProps ---
+        // These avoid recreating arrow functions on every dataGridProps recomputation.
+        this.handleSortFn = (columnKey, direction) => this.handleSort(columnKey, direction);
+        this.handleColumnResizedFn = (columnId, width) => this.handleColumnResized(columnId, width);
+        this.handleColumnPinnedFn = (columnId, pinned) => this.handleColumnPinned(columnId, pinned);
+        this.handleSelectionChangeFn = (event) => this.handleSelectionChange(event);
+        this.handleFilterChangeFn = (key, value) => this.handleFilterChange(key, value);
+        this.clearAllFiltersFn = () => this.setFilters({});
+        this.setPageFn = (p) => this.setPage(p);
+        this.setPageSizeFn = (size) => this.setPageSize(size);
+        this.handleVisibilityChangeFn = (columnKey, isVisible) => this.handleVisibilityChange(columnKey, isVisible);
+        // --- Data grid props computed ---
+        this.dataGridProps = computed(() => ({
+            items: this.displayItems(),
+            columns: this.columnsProp(),
+            getRowId: this.getRowId(),
+            sortBy: this.sort().field,
+            sortDirection: this.sort().direction,
+            onColumnSort: this.handleSortFn,
+            visibleColumns: this.visibleColumns(),
+            columnOrder: this.effectiveColumnOrder(),
+            onColumnOrderChange: this.onColumnOrderChange(),
+            onColumnResized: this.handleColumnResizedFn,
+            onAutosizeColumn: this.onAutosizeColumn(),
+            onColumnPinned: this.handleColumnPinnedFn,
+            pinnedColumns: this.pinnedOverrides(),
+            initialColumnWidths: this.columnWidthOverrides(),
+            editable: this.editable(),
+            cellSelection: this.cellSelection(),
+            density: this.density(),
+            rowHeight: this.rowHeight(),
+            onCellValueChanged: this.onCellValueChanged(),
+            onUndo: this.onUndo(),
+            onRedo: this.onRedo(),
+            canUndo: this.canUndo(),
+            canRedo: this.canRedo(),
+            rowSelection: this.rowSelection(),
+            selectedRows: this.effectiveSelectedRows(),
+            onSelectionChange: this.handleSelectionChangeFn,
+            showRowNumbers: this.showRowNumbers() || this.cellReferences() || this.formulasEnabled(),
+            showColumnLetters: !!(this.cellReferences() || this.formulasEnabled()),
+            showNameBox: !!(this.cellReferences() && !this.formulasEnabled()),
+            onActiveCellChange: (this.cellReferences() || this.formulasEnabled()) ? this.handleActiveCellChange : undefined,
+            currentPage: this.page(),
+            pageSize: this.pageSize(),
+            statusBar: this.statusBarConfig(),
+            isLoading: this.isLoadingResolved(),
+            filters: this.filters(),
+            onFilterChange: this.handleFilterChangeFn,
+            filterOptions: this.clientFilterOptions(),
+            loadingFilterOptions: this.dataSource()?.fetchFilterOptions ? this.loadingFilterOptions() : EMPTY_LOADING_OPTIONS,
+            peopleSearch: this.dataSource()?.searchPeople?.bind(this.dataSource()),
+            getUserByEmail: this.dataSource()?.getUserByEmail?.bind(this.dataSource()),
+            layoutMode: this.layoutMode(),
+            suppressHorizontalScroll: this.suppressHorizontalScroll(),
+            stickyHeader: this.stickyHeader(),
+            columnReorder: this.columnReorder(),
+            responsiveColumns: this.responsiveColumns(),
+            virtualScroll: this.virtualScroll(),
+            'aria-label': this.ariaLabel(),
+            'aria-labelledby': this.ariaLabelledBy(),
+            emptyState: {
+                hasActiveFilters: this.hasActiveFilters(),
+                onClearAll: this.clearAllFiltersFn,
+                message: this.emptyState()?.message,
+                render: this.emptyState()?.render,
+            },
+            formulas: this.formulasEnabled(),
+            formulaVersion: this.formulaVersion(),
+            formulaReferences: this.formulaBarReferences().length > 0 ? this.formulaBarReferences() : undefined,
+            ...(this.formulaService.enabled() ? {
+                getFormulaValue: this.getFormulaValueFn,
+                hasFormula: this.hasFormulaFn,
+                getFormula: this.getFormulaFn,
+                setFormula: this.setFormulaFn,
+                onFormulaCellChanged: this.onFormulaCellChangedFn,
+                getPrecedents: this.getPrecedentsFn,
+                getDependents: this.getDependentsFn,
+                getAuditTrail: this.getAuditTrailFn,
+            } : {}),
+        }), ...(ngDevMode ? [{ debugName: "dataGridProps" }] : []));
+        this.pagination = computed(() => ({
+            page: this.page(),
+            pageSize: this.pageSize(),
+            displayTotalCount: this.displayTotalCount(),
+            setPage: this.setPageFn,
+            setPageSize: this.setPageSizeFn,
+            pageSizeOptions: this.pageSizeOptions(),
+            entityLabelPlural: this.entityLabelPlural(),
+        }), ...(ngDevMode ? [{ debugName: "pagination" }] : []));
+        this.columnChooser = computed(() => ({
+            columns: this.columnChooserColumns(),
+            visibleColumns: this.visibleColumns(),
+            onVisibilityChange: this.handleVisibilityChangeFn,
+            placement: this.columnChooserPlacement(),
+        }), ...(ngDevMode ? [{ debugName: "columnChooser" }] : []));
+        this.filtersResult = computed(() => ({
+            hasActiveFilters: this.hasActiveFilters(),
+            setFilters: (f) => this.setFilters(f),
+        }), ...(ngDevMode ? [{ debugName: "filtersResult" }] : []));
+        this.sideBarProps = computed(() => {
+            const state = this.sideBarState();
+            if (!state.isEnabled)
+                return null;
+            return {
+                activePanel: state.activePanel,
+                onPanelChange: state.setActivePanel,
+                panels: state.panels,
+                position: state.position,
+                columns: this.columnChooserColumns(),
+                visibleColumns: this.visibleColumns(),
+                onVisibilityChange: (columnKey, visible) => this.handleVisibilityChange(columnKey, visible),
+                onSetVisibleColumns: (cols) => this.setVisibleColumns(cols),
+                filterableColumns: this.filterableColumns(),
+                filters: this.filters(),
+                onFilterChange: (key, value) => this.handleFilterChange(key, value),
+                filterOptions: this.clientFilterOptions(),
+            };
+        }, ...(ngDevMode ? [{ debugName: "sideBarProps" }] : []));
+        // Validate columns once (on first non-empty columns signal)
+        let columnsValidated = false;
+        effect(() => {
+            const cols = this.columns();
+            if (!columnsValidated && cols.length > 0) {
+                columnsValidated = true;
+                validateColumns(cols);
+            }
+        });
+        // Worker sort async effect  -  runs processClientSideDataAsync when workerSort is on
+        // Uses the same index-based snapshot approach as the sync path.
+        let asyncSortedIndices = null;
+        let asyncPrevSortVersion = -1;
+        let asyncPrevFilters = null;
+        let asyncPrevColumns = null;
+        let asyncPrevDataLength = -1;
+        effect((onCleanup) => {
+            if (!this.isClientSide() || !this.workerSortEnabled())
+                return;
+            const data = this.displayData();
+            const cols = this.columns();
+            const filters = this.filters();
+            const sv = this.sortSnapshotVersion(); // reactive trigger for explicit sort changes
+            const sortField = this.sort().field;
+            const sortDir = this.sort().direction;
+            const page = this.page();
+            const ps = this.pageSize();
+            const needsResortAsync = sv !== asyncPrevSortVersion ||
+                filters !== asyncPrevFilters ||
+                cols !== asyncPrevColumns ||
+                data.length !== asyncPrevDataLength;
+            const abortId = ++this.workerSortAbortId;
+            if (needsResortAsync || asyncSortedIndices === null) {
+                asyncPrevSortVersion = sv;
+                asyncPrevFilters = filters;
+                asyncPrevColumns = cols;
+                asyncPrevDataLength = data.length;
+                asyncSortedIndices = null;
+                processClientSideDataAsync(data, cols, filters, sortField, sortDir)
+                    .then((rows) => {
+                    if (abortId !== this.workerSortAbortId)
+                        return; // stale
+                    const indexMap = new Map();
+                    for (let i = 0; i < data.length; i++)
+                        indexMap.set(data[i], i);
+                    asyncSortedIndices = rows.map((row) => {
+                        const idx = indexMap.get(row);
+                        return idx !== undefined ? idx : -1;
+                    }).filter((idx) => idx !== -1);
+                    const total = rows.length;
+                    const start = (page - 1) * ps;
+                    const paged = rows.slice(start, start + ps);
+                    this.asyncClientItems.set({ items: paged, totalCount: total });
+                })
+                    .catch(() => {
+                    if (abortId !== this.workerSortAbortId)
+                        return;
+                    // Fallback: use sync
+                    const rows = processClientSideData(data, cols, filters, sortField, sortDir);
+                    const indexMap = new Map();
+                    for (let i = 0; i < data.length; i++)
+                        indexMap.set(data[i], i);
+                    asyncSortedIndices = rows.map((row) => {
+                        const idx = indexMap.get(row);
+                        return idx !== undefined ? idx : -1;
+                    }).filter((idx) => idx !== -1);
+                    const total = rows.length;
+                    const start = (page - 1) * ps;
+                    const paged = rows.slice(start, start + ps);
+                    this.asyncClientItems.set({ items: paged, totalCount: total });
+                });
+            }
+            else {
+                // Preserve order: look up updated rows by stored indices.
+                const orderedRows = asyncSortedIndices.map((idx) => data[idx]).filter((r) => r !== undefined);
+                const total = orderedRows.length;
+                const start = (page - 1) * ps;
+                const paged = orderedRows.slice(start, start + ps);
+                this.asyncClientItems.set({ items: paged, totalCount: total });
+            }
+            onCleanup(() => {
+                this.workerSortAbortId++;
+            });
+        });
+        // Server-side data fetching effect
+        effect((onCleanup) => {
+            const ds = this.dataSource();
+            if (!this.isServerSide() || !ds) {
+                if (!this.isServerSide())
+                    this.serverLoading.set(false);
+                return;
+            }
+            const page = this.page();
+            const pageSize = this.pageSize();
+            const sort = this.sort();
+            const filters = this.filters();
+            // Read refreshCounter to trigger re-fetches
+            this.refreshCounter();
+            const controller = new AbortController();
+            this.fetchAbortController = controller;
+            this.serverLoading.set(true);
+            ds.fetchPage({
+                page,
+                pageSize,
+                sort: { field: sort.field, direction: sort.direction },
+                filters,
+                signal: controller.signal,
+            })
+                .then((res) => {
+                if (controller.signal.aborted)
+                    return;
+                this.serverItems.set(res.items);
+                this.serverTotalCount.set(res.totalCount);
+            })
+                .catch((err) => {
+                if (controller.signal.aborted)
+                    return;
+                this.onError()?.(err);
+                this.serverItems.set([]);
+                this.serverTotalCount.set(0);
+            })
+                .finally(() => {
+                if (!controller.signal.aborted)
+                    this.serverLoading.set(false);
+            });
+            onCleanup(() => {
+                controller.abort();
+            });
+        });
+        // Fire onFirstDataRendered once; also validate row IDs on first data
+        let rowIdsValidated = false;
+        effect(() => {
+            const items = this.displayItems();
+            if (!this.firstDataRendered() && items.length > 0) {
+                this.firstDataRendered.set(true);
+                this.onFirstDataRendered()?.();
+            }
+            if (!rowIdsValidated && items.length > 0) {
+                rowIdsValidated = true;
+                validateRowIds(items, this.getRowId());
+            }
+        });
+        // Load server filter options
+        effect((onCleanup) => {
+            const ds = this.dataSource();
+            const fields = this.multiSelectFilterFields();
+            const fetcher = ds && 'fetchFilterOptions' in ds && typeof ds.fetchFilterOptions === 'function'
+                ? ds.fetchFilterOptions.bind(ds)
+                : undefined;
+            if (!fetcher || fields.length === 0) {
+                this.serverFilterOptions.set({});
+                this.loadingFilterOptions.set({});
+                return;
+            }
+            const controller = new AbortController();
+            this.filterAbortController = controller;
+            const loading = {};
+            fields.forEach((f) => { loading[f] = true; });
+            this.loadingFilterOptions.set(loading);
+            const results = {};
+            Promise.all(fields.map(async (field) => {
+                try {
+                    results[field] = await fetcher(field);
+                }
+                catch {
+                    results[field] = [];
+                }
+            })).then(() => {
+                if (controller.signal.aborted)
+                    return;
+                this.serverFilterOptions.set(results);
+                this.loadingFilterOptions.set({});
+            });
+            onCleanup(() => {
+                controller.abort();
+            });
+        });
+        // Initialize sidebar default panel
+        effect(() => {
+            const parsed = this.sideBarParsed();
+            if (parsed.defaultPanel) {
+                this.sideBarActivePanel.set(parsed.defaultPanel);
+            }
+        });
+        // Reset formula bar editing when active cell changes
+        effect(() => {
+            // Read active cell coords to trigger on cell change
+            this.activeCellCoords();
+            this.formulaBarEditing.set(false);
+        });
+        // Formula engine: configure when formula signals change
+        effect(() => {
+            const userRecalcCb = this.onFormulaRecalc();
+            this.formulaService.configure({
+                formulas: this.formulasEnabled(),
+                initialFormulas: this.initialFormulas(),
+                formulaFunctions: this.formulaFunctions(),
+                onFormulaRecalc: (result) => {
+                    this.formulaVersion.update((v) => v + 1);
+                    userRecalcCb?.(result);
+                },
+                namedRanges: this.namedRanges(),
+                sheets: this.sheets(),
+            });
+        });
+        // Formula engine: keep data in sync with display items + columns
+        effect(() => {
+            const items = this.displayItems();
+            const cols = this.columns();
+            this.formulaService.setData(items, cols);
+        });
+        // Cleanup on destroy  -  abort in-flight requests and reset callback signals
+        this.destroyRef.onDestroy(() => {
+            this.fetchAbortController?.abort();
+            this.filterAbortController?.abort();
+            this.fetchAbortController = null;
+            this.filterAbortController = null;
+            this.onPageChange.set(undefined);
+            this.onPageSizeChange.set(undefined);
+            this.onSortChange.set(undefined);
+            this.onFiltersChange.set(undefined);
+            this.onVisibleColumnsChange.set(undefined);
+            this.onColumnOrderChange.set(undefined);
+            this.onColumnResized.set(undefined);
+            this.onAutosizeColumn.set(undefined);
+            this.onColumnPinned.set(undefined);
+            this.onCellValueChanged.set(undefined);
+            this.onSelectionChange.set(undefined);
+            this.onFirstDataRendered.set(undefined);
+            this.onError.set(undefined);
+            this.onUndo.set(undefined);
+            this.onRedo.set(undefined);
+        });
+    }
+    // --- Setters ---
+    setPage(p) {
+        if (this.controlledPage() === undefined)
+            this.internalPage.set(p);
+        this.onPageChange()?.(p);
+    }
+    setPageSize(size) {
+        if (this.controlledPageSize() === undefined)
+            this.internalPageSizeOverride.set(size);
+        this.onPageSizeChange()?.(size);
+        this.setPage(1);
+    }
+    setSort(s) {
+        if (this.controlledSort() === undefined)
+            this.internalSortOverride.set(s);
+        this.onSortChange()?.(s);
+        this.setPage(1);
+        // Invalidate sorted indices so clientItemsAndTotal re-sorts with the new field/direction.
+        this.sortedIndices = null;
+        this.sortSnapshotVersion.update((v) => v + 1);
+    }
+    setFilters(f) {
+        if (this.controlledFilters() === undefined)
+            this.internalFilters.set(f);
+        this.onFiltersChange()?.(f);
+        this.setPage(1);
+    }
+    setVisibleColumns(cols) {
+        if (this.controlledVisibleColumns() === undefined)
+            this.internalVisibleColumnsOverride.set(cols);
+        this.onVisibleColumnsChange()?.(cols);
+    }
+    handleSort(columnKey, direction) {
+        this.setSort(computeNextSortState(this.sort(), columnKey, direction));
+    }
+    handleFilterChange(key, value) {
+        this.setFilters(mergeFilter(this.filters(), key, value));
+    }
+    handleVisibilityChange(columnKey, isVisible) {
+        const next = new Set(this.visibleColumns());
+        if (isVisible)
+            next.add(columnKey);
+        else
+            next.delete(columnKey);
+        this.setVisibleColumns(next);
+    }
+    handleSelectionChange(event) {
+        if (this.selectedRows() === undefined) {
+            this.internalSelectedRows.set(new Set(event.selectedRowIds));
+        }
+        this.onSelectionChange()?.(event);
+    }
+    handleColumnResized(columnId, width) {
+        this.columnWidthOverrides.update((prev) => ({ ...prev, [columnId]: width }));
+        this.onColumnResized()?.(columnId, width);
+    }
+    handleColumnPinned(columnId, pinned) {
+        this.pinnedOverrides.update((prev) => {
+            if (pinned === null) {
+                const { [columnId]: _removed, ...rest } = prev;
+                return rest;
+            }
+            return { ...prev, [columnId]: pinned };
+        });
+        this.onColumnPinned()?.(columnId, pinned);
+    }
+    // --- Formula bar methods ---
+    startFormulaBarEditing() {
+        this.formulaBarEditText.set(this.formulaBarDisplayText());
+        this.formulaBarEditing.set(true);
+    }
+    commitFormulaBar() {
+        const coords = this.activeCellCoords();
+        if (!coords)
+            return;
+        const text = this.formulaBarEditText().trim();
+        if (text.startsWith('=')) {
+            this.formulaService.setFormula(coords.col, coords.row, text);
+            this.formulaVersion.update((v) => v + 1);
+        }
+        else {
+            this.formulaService.setFormula(coords.col, coords.row, null);
+            this.onCellValueChanged()?.({
+                rowIndex: coords.row,
+                columnId: this.columns()[coords.col]?.columnId ?? '',
+                oldValue: undefined,
+                newValue: text,
+            });
+        }
+        this.formulaBarEditing.set(false);
+    }
+    cancelFormulaBar() {
+        this.formulaBarEditing.set(false);
+        this.formulaBarEditText.set('');
+    }
+    // --- Configure from props ---
+    configure(props) {
+        this.columnsProp.set(props.columns);
+        // Initialize pinned overrides from column definitions on first configure
+        if (Object.keys(this.pinnedOverrides()).length === 0) {
+            const initial = {};
+            for (const col of flattenColumns(props.columns)) {
+                if (col.pinned)
+                    initial[col.columnId] = col.pinned;
+            }
+            if (Object.keys(initial).length > 0)
+                this.pinnedOverrides.set(initial);
+        }
+        this.getRowId.set(props.getRowId);
+        if ('data' in props && props.data !== undefined)
+            this.data.set(props.data);
+        if ('dataSource' in props && props.dataSource !== undefined)
+            this.dataSource.set(props.dataSource);
+        if (props.page !== undefined)
+            this.controlledPage.set(props.page);
+        if (props.pageSize !== undefined)
+            this.controlledPageSize.set(props.pageSize);
+        if (props.sort !== undefined)
+            this.controlledSort.set(props.sort);
+        if (props.filters !== undefined)
+            this.controlledFilters.set(props.filters);
+        if (props.visibleColumns !== undefined)
+            this.controlledVisibleColumns.set(props.visibleColumns);
+        if (props.isLoading !== undefined)
+            this.controlledLoading.set(props.isLoading);
+        if (props.onPageChange)
+            this.onPageChange.set(props.onPageChange);
+        if (props.onPageSizeChange)
+            this.onPageSizeChange.set(props.onPageSizeChange);
+        if (props.onSortChange)
+            this.onSortChange.set(props.onSortChange);
+        if (props.onFiltersChange)
+            this.onFiltersChange.set(props.onFiltersChange);
+        if (props.onVisibleColumnsChange)
+            this.onVisibleColumnsChange.set(props.onVisibleColumnsChange);
+        if (props.columnOrder !== undefined)
+            this.columnOrder.set(props.columnOrder);
+        if (props.onColumnOrderChange)
+            this.onColumnOrderChange.set(props.onColumnOrderChange);
+        if (props.onColumnResized)
+            this.onColumnResized.set(props.onColumnResized);
+        if (props.onAutosizeColumn)
+            this.onAutosizeColumn.set(props.onAutosizeColumn);
+        if (props.onColumnPinned)
+            this.onColumnPinned.set(props.onColumnPinned);
+        if (props.defaultPageSize !== undefined)
+            this.defaultPageSize.set(props.defaultPageSize);
+        if (props.defaultSortBy !== undefined)
+            this.defaultSortBy.set(props.defaultSortBy);
+        if (props.defaultSortDirection !== undefined)
+            this.defaultSortDirection.set(props.defaultSortDirection);
+        if (props.editable !== undefined)
+            this.editable.set(props.editable);
+        if (props.cellSelection !== undefined)
+            this.cellSelection.set(props.cellSelection);
+        if (props.density !== undefined)
+            this.density.set(props.density);
+        if (props.rowHeight !== undefined)
+            this.rowHeight.set(props.rowHeight);
+        if (props.onCellValueChanged)
+            this.onCellValueChanged.set(props.onCellValueChanged);
+        if (props.onUndo)
+            this.onUndo.set(props.onUndo);
+        if (props.onRedo)
+            this.onRedo.set(props.onRedo);
+        if (props.canUndo !== undefined)
+            this.canUndo.set(props.canUndo);
+        if (props.canRedo !== undefined)
+            this.canRedo.set(props.canRedo);
+        if (props.rowSelection !== undefined)
+            this.rowSelection.set(props.rowSelection);
+        if (props.selectedRows !== undefined)
+            this.selectedRows.set(props.selectedRows);
+        if (props.onSelectionChange)
+            this.onSelectionChange.set(props.onSelectionChange);
+        if (props.statusBar !== undefined)
+            this.statusBar.set(props.statusBar);
+        if (props.pageSizeOptions !== undefined)
+            this.pageSizeOptions.set(props.pageSizeOptions);
+        if (props.sideBar !== undefined)
+            this.sideBarConfig.set(props.sideBar);
+        if (props.onFirstDataRendered)
+            this.onFirstDataRendered.set(props.onFirstDataRendered);
+        if (props.onError)
+            this.onError.set(props.onError);
+        if (props.columnChooser !== undefined)
+            this.columnChooserProp.set(props.columnChooser);
+        if (props.columnReorder !== undefined)
+            this.columnReorder.set(props.columnReorder);
+        if (props.responsiveColumns !== undefined)
+            this.responsiveColumns.set(props.responsiveColumns);
+        if (props.virtualScroll !== undefined)
+            this.virtualScroll.set(props.virtualScroll);
+        if (props.workerSort !== undefined)
+            this.workerSort.set(props.workerSort);
+        if (props.showRowNumbers !== undefined)
+            this.showRowNumbers.set(props.showRowNumbers);
+        if (props.cellReferences !== undefined)
+            this.cellReferences.set(props.cellReferences);
+        if (props.formulas !== undefined)
+            this.formulasEnabled.set(props.formulas);
+        if (props.initialFormulas !== undefined)
+            this.initialFormulas.set(props.initialFormulas);
+        if (props.onFormulaRecalc)
+            this.onFormulaRecalc.set(props.onFormulaRecalc);
+        if (props.formulaFunctions !== undefined)
+            this.formulaFunctions.set(props.formulaFunctions);
+        if (props.namedRanges !== undefined)
+            this.namedRanges.set(props.namedRanges);
+        if (props.sheets !== undefined)
+            this.sheets.set(props.sheets);
+        if (props.sheetDefs !== undefined)
+            this.sheetDefs.set(props.sheetDefs);
+        if (props.activeSheet !== undefined)
+            this.activeSheet.set(props.activeSheet);
+        if (props.onSheetChange)
+            this.onSheetChange.set(props.onSheetChange);
+        if (props.onSheetAdd)
+            this.onSheetAdd.set(props.onSheetAdd);
+        if (props.entityLabelPlural !== undefined)
+            this.entityLabelPlural.set(props.entityLabelPlural);
+        if (props.className !== undefined)
+            this.className.set(props.className);
+        if (props.layoutMode !== undefined)
+            this.layoutMode.set(props.layoutMode);
+        if (props.suppressHorizontalScroll !== undefined)
+            this.suppressHorizontalScroll.set(props.suppressHorizontalScroll);
+        if (props.stickyHeader !== undefined)
+            this.stickyHeader.set(props.stickyHeader);
+        if (props.fullScreen !== undefined)
+            this.fullScreen.set(props.fullScreen);
+        if (props['aria-label'] !== undefined)
+            this.ariaLabel.set(props['aria-label']);
+        if (props['aria-labelledby'] !== undefined)
+            this.ariaLabelledBy.set(props['aria-labelledby']);
+    }
+    // --- API ---
+    // --- Column Pinning Methods ---
+    /**
+     * Pin a column to the left or right edge.
+     */
+    pinColumn(columnId, side) {
+        this.pinnedOverrides.update((prev) => ({ ...prev, [columnId]: side }));
+        this.onColumnPinned()?.(columnId, side);
+    }
+    /**
+     * Unpin a column (remove sticky positioning).
+     */
+    unpinColumn(columnId) {
+        this.pinnedOverrides.update((prev) => {
+            const { [columnId]: _, ...next } = prev;
+            return next;
+        });
+        this.onColumnPinned()?.(columnId, null);
+    }
+    /**
+     * Check if a column is pinned and which side.
+     */
+    isPinned(columnId) {
+        return this.pinnedOverrides()[columnId];
+    }
+    /**
+     * Compute sticky left offsets for left-pinned columns.
+     * Returns a map of columnId -> left offset in pixels.
+     */
+    computeLeftOffsets(visibleCols, columnWidths, defaultWidth, hasCheckboxColumn, checkboxColumnWidth) {
+        const offsets = {};
+        const pinned = this.pinnedOverrides();
+        let left = hasCheckboxColumn ? checkboxColumnWidth : 0;
+        for (const col of visibleCols) {
+            if (pinned[col.columnId] === 'left') {
+                offsets[col.columnId] = left;
+                left += columnWidths[col.columnId] ?? defaultWidth;
+            }
+        }
+        return offsets;
+    }
+    /**
+     * Compute sticky right offsets for right-pinned columns.
+     * Returns a map of columnId -> right offset in pixels.
+     */
+    computeRightOffsets(visibleCols, columnWidths, defaultWidth) {
+        const offsets = {};
+        const pinned = this.pinnedOverrides();
+        let right = 0;
+        for (let i = visibleCols.length - 1; i >= 0; i--) {
+            const col = visibleCols[i];
+            if (pinned[col.columnId] === 'right') {
+                offsets[col.columnId] = right;
+                right += columnWidths[col.columnId] ?? defaultWidth;
+            }
+        }
+        return offsets;
+    }
+    getApi() {
+        return {
+            setRowData: (d) => {
+                if (!this.isServerSide())
+                    this.internalData.set(d);
+            },
+            setLoading: (loading) => this.internalLoading.set(loading),
+            getColumnState: () => ({
+                visibleColumns: Array.from(this.visibleColumns()),
+                sort: this.sort(),
+                columnOrder: this.effectiveColumnOrder() ?? undefined,
+                columnWidths: Object.keys(this.columnWidthOverrides()).length > 0 ? this.columnWidthOverrides() : undefined,
+                filters: Object.keys(this.filters()).length > 0 ? this.filters() : undefined,
+                pinnedColumns: Object.keys(this.pinnedOverrides()).length > 0 ? this.pinnedOverrides() : undefined,
+            }),
+            applyColumnState: (state) => {
+                if (state.visibleColumns)
+                    this.setVisibleColumns(new Set(state.visibleColumns));
+                if (state.sort)
+                    this.setSort(state.sort);
+                if (state.columnOrder) {
+                    if (this.columnOrder() === undefined)
+                        this.internalColumnOrder.set(state.columnOrder);
+                    this.onColumnOrderChange()?.(state.columnOrder);
+                }
+                if (state.columnWidths)
+                    this.columnWidthOverrides.set(state.columnWidths);
+                if (state.filters)
+                    this.setFilters(state.filters);
+                if (state.pinnedColumns)
+                    this.pinnedOverrides.set(state.pinnedColumns);
+            },
+            setFilterModel: (filters) => this.setFilters(filters),
+            getSelectedRows: () => Array.from(this.effectiveSelectedRows()),
+            setSelectedRows: (rowIds) => {
+                if (this.selectedRows() === undefined)
+                    this.internalSelectedRows.set(new Set(rowIds));
+            },
+            selectAll: () => {
+                const allIds = new Set(this.displayItems().map((item) => this.getRowId()(item)));
+                if (this.selectedRows() === undefined)
+                    this.internalSelectedRows.set(allIds);
+                this.onSelectionChange()?.({
+                    selectedRowIds: Array.from(allIds),
+                    selectedItems: this.displayItems(),
+                });
+            },
+            deselectAll: () => {
+                if (this.selectedRows() === undefined)
+                    this.internalSelectedRows.set(new Set());
+                this.onSelectionChange()?.({ selectedRowIds: [], selectedItems: [] });
+            },
+            clearFilters: () => this.setFilters({}),
+            clearSort: () => this.setSort({ field: this.defaultSortField(), direction: this.defaultSortDirection() }),
+            resetGridState: (options) => {
+                this.setFilters({});
+                this.setSort({ field: this.defaultSortField(), direction: this.defaultSortDirection() });
+                if (!options?.keepSelection) {
+                    if (this.selectedRows() === undefined)
+                        this.internalSelectedRows.set(new Set());
+                    this.onSelectionChange()?.({ selectedRowIds: [], selectedItems: [] });
+                }
+            },
+            getDisplayedRows: () => this.displayItems(),
+            refreshData: () => {
+                if (this.isServerSide()) {
+                    this.refreshCounter.update((c) => c + 1);
+                }
+            },
+            getColumnOrder: () => this.effectiveColumnOrder() ?? this.columns().map((c) => c.columnId),
+            setColumnOrder: (order) => {
+                if (this.columnOrder() === undefined)
+                    this.internalColumnOrder.set(order);
+                this.onColumnOrderChange()?.(order);
+            },
+            scrollToRow: (_index, _options) => {
+                // Scrolling is handled by VirtualScrollService at the UI layer.
+                // The UI component should wire this to VirtualScrollService.scrollToRow().
+            },
+        };
+    }
+    static { this.ɵfac = function OGridService_Factory(__ngFactoryType__) { return new (__ngFactoryType__ || OGridService)(); }; }
+    static { this.ɵprov = /*@__PURE__*/ i0.ɵɵdefineInjectable({ token: OGridService, factory: OGridService.ɵfac }); }
+}
+(() => { (typeof ngDevMode === "undefined" || ngDevMode) && i0.ɵsetClassMetadata(OGridService, [{
+        type: Injectable
+    }], () => [], null); })();