@shival99/z-ui 1.9.11 → 1.9.13

package/fesm2022/shival99-z-ui-components-z-table.mjs

@@ -33,14 +33,24 @@ import { ZSelectComponent } from '@shival99/z-ui/components/z-select';
 import { ZSwitchComponent } from '@shival99/z-ui/components/z-switch';
 import { Subject, debounceTime, distinctUntilChanged } from 'rxjs';
 
+// ─── Default Constants ───────────────────────────────────────────────────────
+/** Default row height in pixels for virtual scroll estimation */
 const Z_DEFAULT_ROW_HEIGHT = 40;
+/** How many extra rows to render outside the visible viewport (virtual scroll buffer) */
 const Z_DEFAULT_VIRTUAL_OVERSCAN = 5;
+/** Number of rows per virtual group — used for rowSpan grouping in virtual mode */
 const Z_DEFAULT_GROUP_SIZE = 1;
+/** Minimum column width in pixels; prevents columns from becoming too narrow */
 const Z_DEFAULT_COLUMN_MIN_SIZE = 100;
+/** Debounce delay (ms) for async state updates (filtering/sorting transitions) */
 const Z_DEFAULT_DEBOUNCE_TIME = 150;
+/** Row height used for skeleton loading placeholders */
 const Z_SKELETON_ROW_HEIGHT = 60;
+/** Width in pixels of each action button in the actions column */
 const Z_TABLE_DEFAULT_ACTION_BUTTON_WIDTH = 32;
+/** Max visible action buttons before overflow into dropdown */
 const Z_TABLE_DEFAULT_MAX_VISIBLE_ACTIONS = 3;
+/** Default size variant for the overflow dropdown trigger button */
 const Z_TABLE_DEFAULT_DROPDOWN_BUTTON_SIZE = 'sm';
 
 class ZTableActionsComponent {
@@ -246,6 +256,13 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
   `, changeDetection: ChangeDetectionStrategy.OnPush, styles: [":host{display:block}\n"] }]
         }], propDecorators: { zConfig: [{ type: i0.Input, args: [{ isSignal: true, alias: "zConfig", required: true }] }], zRow: [{ type: i0.Input, args: [{ isSignal: true, alias: "zRow", required: true }] }], zRowId: [{ type: i0.Input, args: [{ isSignal: true, alias: "zRowId", required: true }] }], zDropdownButtonSize: [{ type: i0.Input, args: [{ isSignal: true, alias: "zDropdownButtonSize", required: false }] }], zActionClick: [{ type: i0.Output, args: ["zActionClick"] }] } });
 
+// ─── Column Visibility Pre-filter ────────────────────────────────────────────
+/**
+ * Recursively filters columns based on their `visible` property.
+ * This runs BEFORE TanStack table creation — columns excluded here
+ * won't generate ColumnDef entries at all (unlike columnVisibility state
+ * which hides columns but keeps them in the column model).
+ */
 const filterVisibleColumns = (columns) => columns
     .filter(col => {
     const { visible } = col;
@@ -263,15 +280,29 @@ const filterVisibleColumns = (columns) => columns
     }
     return col;
 });
+// ─── Config Type Guards ──────────────────────────────────────────────────────
+/**
+ * Checks if a config value is a plain object (config struct) vs a primitive/template.
+ * Used to distinguish shorthand content (string/TemplateRef) from full config objects
+ * like ZTableHeaderColumnConfig, ZTableBodyColumnConfig, etc.
+ */
 const isObjectConfig = (config) => {
     if (!config || typeof config !== 'object') {
         return false;
     }
     return config.constructor === Object;
 };
+/** Type guard: is this a full header config object (not just content shorthand)? */
 const isHeaderConfig = (config) => isObjectConfig(config);
+/** Type guard: is this a full body config object (not just content shorthand)? */
 const isBodyConfig = (config) => isObjectConfig(config);
+/** Type guard: is this a full footer config object (not just content shorthand)? */
 const isFooterConfig = (config) => isObjectConfig(config);
+// ─── Config Extractors ───────────────────────────────────────────────────────
+/**
+ * Internal helper that normalizes header/footer config into a consistent shape.
+ * Handles both shorthand (just content) and full config objects.
+ */
 const getHeaderOrFooterConfigInternal = (col, type) => {
     const empty = {
         content: undefined,
@@ -305,7 +336,12 @@ const getHeaderOrFooterConfigInternal = (col, type) => {
         contentStyle: typedConfig.contentStyle,
     };
 };
+/** Extract and normalize header config from a column definition */
 const getHeaderConfig = (col) => getHeaderOrFooterConfigInternal(col, 'header');
+/**
+ * Extract and normalize body config from a column definition.
+ * Resolves dynamic properties (class, style, rowSpan, etc.) when CellContext is provided.
+ */
 const getBodyConfig = (col, ctx) => {
     const empty = {
         content: undefined,
@@ -345,6 +381,8 @@ const getBodyConfig = (col, ctx) => {
     };
 };
 const getFooterConfig = (col) => getHeaderOrFooterConfigInternal(col, 'footer');
+// ─── Shortcut Accessors ──────────────────────────────────────────────────────
+// These convenience functions extract a single property from the relevant config.
 const getHeaderContent = (col) => getHeaderConfig(col).content;
 const getBodyContent = (col) => {
     if (!col?.body) {
@@ -359,6 +397,11 @@ const getHeaderRowSpan = (col) => getHeaderConfig(col).rowSpan;
 const getHeaderColSpan = (col) => getHeaderConfig(col).colSpan;
 const getFooterRowSpan = (col) => getFooterConfig(col).rowSpan;
 const getFooterColSpan = (col) => getFooterConfig(col).colSpan;
+// ─── Icon Syntax Parsing ─────────────────────────────────────────────────────
+/**
+ * Parses inline icon syntax: `"Total [icon:lucideTrendingUp|size:16|class:text-green] Revenue"`
+ * Returns an array of text and icon segments for rendering by ZTableIconTextComponent.
+ */
 function parseIconString(content) {
     if (!content || typeof content !== 'string') {
         return [{ type: 'text', value: content || '' }];
@@ -398,18 +441,22 @@ function parseIconString(content) {
     }
     return parts.length > 0 ? parts : [{ type: 'text', value: content }];
 }
+/** Removes all `[icon:...]` syntax from a string, returning plain text */
 function stripIconSyntax(content) {
     if (!content || typeof content !== 'string') {
         return content || '';
     }
     return content.replace(/\[icon:[^\]]+\]/g, '').trim();
 }
+/** Returns true if the content string contains at least one `[icon:...]` segment */
 function hasIconSyntax(content) {
     if (!content || typeof content !== 'string') {
         return false;
     }
     return /\[icon:[^\]]+\]/.test(content);
 }
+// ─── Column Lookup ───────────────────────────────────────────────────────────
+/** Recursively search for a column config by ID within a (possibly nested) column array */
 const findColumnConfig = (columnId, columns) => {
     for (const col of columns) {
         if (col.id === columnId) {
@@ -424,9 +471,16 @@ const findColumnConfig = (columnId, columns) => {
     }
     return undefined;
 };
+// ─── Span Calculation ────────────────────────────────────────────────────────
+/**
+ * Walk down a chain of placeholder headers to find the deepest real header.
+ * Used to calculate how many rows a header cell should span in multi-level headers.
+ * Returns null if the header is already the deepest (no spanning needed).
+ */
 const deepestHeader = (header) => {
     let last = header;
     while (true) {
+        // Follow single-child placeholder chains (placeholders with colSpan=1)
         const next = last.isPlaceholder && last.colSpan === 1 && last.subHeaders.length === 1 ? last.subHeaders[0] : null;
         if (!next) {
             return last === header ? null : last;
@@ -434,12 +488,20 @@ const deepestHeader = (header) => {
         last = next;
     }
 };
+/** Calculate rowSpan for a TanStack header based on its depth vs deepest sub-header */
 const tableHeaderRowSpan = (header) => {
     const deepest = deepestHeader(header);
     const rowSpan = (deepest ? deepest.depth - header.depth : 0) + 1;
+    // If the header is more than 1 level above its column's natural depth, it's been
+    // consumed by a parent's rowSpan — return null to skip rendering
     const above = header.depth - header.column.depth;
     return above > 1 ? null : rowSpan;
 };
+/**
+ * Calculate rowSpan for body cells with static or dynamic rowSpan config.
+ * For static rowSpan: uses modular arithmetic (filteredIndex % rowSpan === 0)
+ * to determine which rows get the merged cell vs which are skipped.
+ */
 const calculateCellRowSpan = (cell, columnConfig, allRows) => {
     if (!columnConfig?.body || !isBodyConfig(columnConfig.body)) {
         return null;
@@ -565,6 +627,15 @@ const calculateFooterColSpan = (header, columnConfig) => {
     }
     return header.colSpan > 1 ? header.colSpan : null;
 };
+// ─── Render-Skip Logic ───────────────────────────────────────────────────────
+//
+// These functions determine which cells should NOT be rendered because they
+// are "covered" by a neighboring cell's rowSpan or colSpan. This prevents
+// duplicate DOM elements in merged cell scenarios.
+/**
+ * Checks if a body cell should be rendered based on rowSpan rules.
+ * Returns false for cells that fall within another cell's rowSpan range.
+ */
 const shouldCellRenderUtil = (cell, columnConfig, allRows) => {
     if (!columnConfig?.body || !isBodyConfig(columnConfig.body)) {
         return true;
@@ -587,6 +658,11 @@ const shouldCellRenderUtil = (cell, columnConfig, allRows) => {
     }
     return true;
 };
+/**
+ * Shared logic for determining if a header or footer cell should render.
+ * A cell should NOT render if a previous cell in the same row has a colSpan
+ * that covers this cell's position. Handles pinned column edge cases.
+ */
 const shouldHeaderOrFooterRender = (header, allHeaders, columns, type) => {
     const currentIndex = allHeaders.findIndex(h => h.id === header.id);
     if (currentIndex <= 0) {
@@ -643,6 +719,18 @@ const shouldBodyCellRenderColSpan = (cell, allCells, columns) => {
 };
 const shouldFooterRender = (header, allHeaders, columns) => shouldHeaderOrFooterRender(header, allHeaders, columns, 'footer');
 const shouldHeaderRender = (header, allHeaders, columns) => shouldHeaderOrFooterRender(header, allHeaders, columns, 'header');
+// ─── Column Config → TanStack ColumnDef Conversion ──────────────────────────
+/**
+ * Converts the consumer-facing ZTableColumnConfig into a TanStack ColumnDef.
+ * This is the bridge between the z-table API and TanStack Table internals.
+ *
+ * Handles:
+ * - Accessor mapping (accessorKey / accessorFn)
+ * - Header/body/footer content resolution
+ * - Sort and filter function wiring (local vs server mode)
+ * - Built-in filter functions for each filter type
+ * - Recursive nested column conversion
+ */
 function columnConfigToColumnDef(config) {
     const sortConfig = typeof config.sort === 'boolean' ? (config.sort ? { enabled: true } : undefined) : config.sort;
     const filterConfig = typeof config.filter === 'boolean' ? (config.filter ? { enabled: true } : undefined) : config.filter;
@@ -822,12 +910,15 @@ function columnConfigToColumnDef(config) {
     }
     return columnDef;
 }
+// ─── Generic Utility Helpers ─────────────────────────────────────────────────
+/** Resolve a value that may be static or a function of the row data */
 const resolveConfigValue = (config, row, defaultValue) => {
     if (config === undefined) {
         return defaultValue;
     }
     return typeof config === 'function' ? config(row) : config;
 };
+/** Pick only defined (non-undefined) keys from an object — used to spread optional virtualizer config */
 const pickDefined = (obj, keys) => keys.reduce((acc, key) => {
     if (obj[key] !== undefined) {
         acc[key] = obj[key];
@@ -2962,22 +3053,64 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
         }] });
 
 /* eslint-disable @stylistic/indent */
+/**
+ * Z-Table Component
+ *
+ * Feature-rich data table built on @tanstack/angular-table. Supports:
+ * - Local and server-side sorting, filtering, and pagination
+ * - Virtual scrolling with rowSpan-aware grouping
+ * - Column pinning (left/right) with scroll shadow indicators
+ * - Column resizing, reordering, and visibility toggling
+ * - Inline cell editing (text, number, select, date, etc.)
+ * - Row selection (single/multi with sub-row support)
+ * - Row expansion with custom templates
+ * - Row pinning (top/bottom)
+ * - Action buttons column with overflow dropdown
+ * - Settings drawer for column management
+ * - Persistent settings via ZCacheService (keyed by zKey)
+ * - Skeleton loading placeholder
+ * - Search bar with debounce
+ *
+ * Architecture notes:
+ * - All template computations use pipes (OnPush compliance, no method calls in templates)
+ * - Scroll sync between thead/tbody/tfoot is manual (independent scrollable containers)
+ * - Virtual scrolling groups rows to handle rowSpan correctly
+ * - Each column's sort/filter can independently be 'local' or 'server' mode
+ */
 class ZTableComponent {
+    // ─── Outputs ──────────────────────────────────────────────────────────────
+    /** Unified change event — parent listens to this for all table interactions */
     zChange = output();
+    /** Emits an imperative control handle for programmatic table manipulation */
     zControl = output();
+    // ─── Inputs ───────────────────────────────────────────────────────────────
+    /** Extra CSS classes merged onto the table container */
     zClass = input('', ...(ngDevMode ? [{ debugName: "zClass" }] : []));
+    /** Main configuration — data, columns, mode, features */
     zConfig = input({ data: [], columns: [], mode: 'local' }, ...(ngDevMode ? [{ debugName: "zConfig" }] : []));
+    /** External loading state (complementary to config.loading) */
     zLoading = input(false, ...(ngDevMode ? [{ debugName: "zLoading" }] : []));
+    /** Cache key for persisting column settings; no persistence when empty */
     zKey = input('', ...(ngDevMode ? [{ debugName: "zKey" }] : []));
+    /** Visual variant: 'default' has card shadow, 'borderless' has no container border */
     zVariant = input('default', ...(ngDevMode ? [{ debugName: "zVariant" }] : []));
+    // ─── Private State ────────────────────────────────────────────────────────
     _destroy$ = injectDestroy();
     _zTranslate = inject(ZTranslateService);
+    /** Prevents recursive scroll sync between thead/tbody/tfoot */
     _isSyncingScroll = signal(false, ...(ngDevMode ? [{ debugName: "_isSyncingScroll" }] : []));
+    /** Preserves horizontal scroll position across loading states */
     _savedScrollLeft = signal(0, ...(ngDevMode ? [{ debugName: "_savedScrollLeft" }] : []));
+    /** Observes tbody container height changes for skeleton row count calculation */
     _resizeObserver = null;
+    /** Debounces rapid settings changes (visibility/pin toggles) */
     _settingsDebounceTimeout = null;
+    /** Debounces filter change emissions to server */
     _filterEmitDebounceTimeout = null;
+    // ─── Template-bound State ─────────────────────────────────────────────────
+    /** Merged loading state from both zLoading input and config.loading */
     isLoading = computed(() => this.zConfig().loading ?? this.zLoading(), ...(ngDevMode ? [{ debugName: "isLoading" }] : []));
+    /** True during debounced async state transitions (sort/filter processing) */
     isProcessing = signal(false, ...(ngDevMode ? [{ debugName: "isProcessing" }] : []));
     theadWrapper = viewChild('theadWrapper', ...(ngDevMode ? [{ debugName: "theadWrapper" }] : []));
     tbodyContainer = viewChild('tbodyContainer', ...(ngDevMode ? [{ debugName: "tbodyContainer" }] : []));
@@ -2986,6 +3119,9 @@ class ZTableComponent {
     tfootWrapper = viewChild('tfootWrapper', ...(ngDevMode ? [{ debugName: "tfootWrapper" }] : []));
     expandedRowTemplate = viewChild('expandedRowTemplate', ...(ngDevMode ? [{ debugName: "expandedRowTemplate" }] : []));
     virtualRowElements = viewChildren('virtualRow', ...(ngDevMode ? [{ debugName: "virtualRowElements" }] : []));
+    // ─── TanStack Table State Signals ─────────────────────────────────────────
+    // These signals are the source of truth for table state. They are passed into
+    // createAngularTable() and updated via the on*Change callbacks.
     columnPinning = signal({ left: [], right: [] }, ...(ngDevMode ? [{ debugName: "columnPinning" }] : []));
     columnVisibility = signal({}, ...(ngDevMode ? [{ debugName: "columnVisibility" }] : []));
     columnOrder = signal([], ...(ngDevMode ? [{ debugName: "columnOrder" }] : []));
@@ -2994,10 +3130,17 @@ class ZTableComponent {
     rowPinning = signal({ top: [], bottom: [] }, ...(ngDevMode ? [{ debugName: "rowPinning" }] : []));
     columnFilters = signal([], ...(ngDevMode ? [{ debugName: "columnFilters" }] : []));
     globalFilter = signal('', ...(ngDevMode ? [{ debugName: "globalFilter" }] : []));
+    /** Note: pageIndex is 1-based here; converted to 0-based for TanStack via _tanstackPagination */
     pagination = signal({ pageIndex: 1, pageSize: 10 }, ...(ngDevMode ? [{ debugName: "pagination" }] : []));
     sorting = signal([], ...(ngDevMode ? [{ debugName: "sorting" }] : []));
+    /**
+     * Caches the last server-provided total to avoid flickering to 0
+     * during loading transitions in server-side pagination mode.
+     */
     _serverPaginationTotal = signal(0, ...(ngDevMode ? [{ debugName: "_serverPaginationTotal" }] : []));
+    /** Container CSS classes combining variant + user-provided classes */
     classTable = computed(() => zMergeClasses('z-table-container', this.zVariant() === 'default' ? 'shadow-card' : 'z-table-borderless', this.zClass()), ...(ngDevMode ? [{ debugName: "classTable" }] : []));
+    /** Convert 1-based pagination to TanStack's 0-based pageIndex */
     _tanstackPagination = computed(() => ({
         ...this.pagination(),
         pageIndex: Math.max(0, this.pagination().pageIndex - 1),
@@ -3026,19 +3169,32 @@ class ZTableComponent {
         }
         return this.table.getFilteredRowModel().rows.length;
     }, ...(ngDevMode ? [{ debugName: "paginationTotal" }] : []));
+    // ─── Scroll & Border State ────────────────────────────────────────────────
     hasVerticalScroll = signal(false, ...(ngDevMode ? [{ debugName: "hasVerticalScroll" }] : []));
     hasHorizontalScroll = signal(false, ...(ngDevMode ? [{ debugName: "hasHorizontalScroll" }] : []));
+    /** True when the last row touches or extends past the container bottom (no gap) */
     lastRowTouchesBottom = signal(true, ...(ngDevMode ? [{ debugName: "lastRowTouchesBottom" }] : []));
     showSettingsDrawer = signal(false, ...(ngDevMode ? [{ debugName: "showSettingsDrawer" }] : []));
     showHorizontalBorder = signal(true, ...(ngDevMode ? [{ debugName: "showHorizontalBorder" }] : []));
     showVerticalBorder = signal(true, ...(ngDevMode ? [{ debugName: "showVerticalBorder" }] : []));
     showHeaderFooterShadow = signal(true, ...(ngDevMode ? [{ debugName: "showHeaderFooterShadow" }] : []));
+    /** True when table body is scrolled away from left edge (shows left pin shadow) */
     hasScrollLeft = signal(false, ...(ngDevMode ? [{ debugName: "hasScrollLeft" }] : []));
+    /** True when table has right-pinned columns and body isn't scrolled to the end */
     hasScrollRight = signal(false, ...(ngDevMode ? [{ debugName: "hasScrollRight" }] : []));
+    /** Maps row IDs to measured DOM heights for pinned row offset calculations */
     pinnedRowHeights = signal({}, ...(ngDevMode ? [{ debugName: "pinnedRowHeights" }] : []));
+    // ─── Internal Change Tracking ──────────────────────────────────────────────
+    /** Bumped to force recomputation of pinned column IDs after programmatic pin changes */
     _columnPinVersion = signal(0, ...(ngDevMode ? [{ debugName: "_columnPinVersion" }] : []));
+    /** Bumped to trigger data refresh (e.g., after addItem/deleteItem via control API) */
     _dataForceUpdate = signal(0, ...(ngDevMode ? [{ debugName: "_dataForceUpdate" }] : []));
+    /** Set when a single row is updated via control API (for targeted re-render) */
     _rowUpdate = signal(null, ...(ngDevMode ? [{ debugName: "_rowUpdate" }] : []));
+    /**
+     * Column config lookup cache — cleared when column reference changes.
+     * Avoids repeated recursive searches during render cycles.
+     */
     _columnConfigCache = new Map();
     _lastColumnsRef = null;
     pinnedColumnIds = computed(() => {
@@ -3054,6 +3210,10 @@ class ZTableComponent {
     pendingVisibleColumns = signal([], ...(ngDevMode ? [{ debugName: "pendingVisibleColumns" }] : []));
     pendingColumnOrder = signal([], ...(ngDevMode ? [{ debugName: "pendingColumnOrder" }] : []));
     pendingShowHeaderFooterShadow = signal(true, ...(ngDevMode ? [{ debugName: "pendingShowHeaderFooterShadow" }] : []));
+    // ─── Feature Detection Computeds ──────────────────────────────────────────
+    // These computed signals scan the column config tree to determine which
+    // features are active, avoiding feature-gating at template render time.
+    /** True if ANY body column uses rowSpan — affects virtual grouping and expand column behavior */
     hasBodyRowSpan = computed(() => {
         const columns = this.zConfig().columns ?? [];
         const checkRowSpan = (col) => {
@@ -3254,10 +3414,17 @@ class ZTableComponent {
         const config = this.searchConfig();
         return config !== null && config.enabled;
     }, ...(ngDevMode ? [{ debugName: "isSearchEnabled" }] : []));
+    // ─── Core TanStack Data Signals ───────────────────────────────────────────
+    /** Data signal with force-update support for control API mutations */
     _data = computed(() => {
         this._dataForceUpdate();
         return this.zConfig().data ?? [];
     }, ...(ngDevMode ? [{ debugName: "_data" }] : []));
+    /**
+     * Converts ZTableColumnConfig[] into TanStack ColumnDef[].
+     * Handles special columns (select, expand, actionRowPin), action column sizing,
+     * and rowSpan/expand compatibility (expand column is removed when rowSpan is used).
+     */
     _columns = computed(() => {
         let cols = this.zConfig().columns ?? [];
         cols = filterVisibleColumns(cols);
@@ -3310,6 +3477,7 @@ class ZTableComponent {
             return colDef;
         });
     }, ...(ngDevMode ? [{ debugName: "_columns" }] : []));
+    // ─── Virtual Scrolling ────────────────────────────────────────────────────
     isVirtual = computed(() => {
         const { virtual } = this.zConfig();
         if (!virtual) {
@@ -3320,6 +3488,7 @@ class ZTableComponent {
         }
         return virtual.enabled;
     }, ...(ngDevMode ? [{ debugName: "isVirtual" }] : []));
+    /** Normalized virtual config with defaults applied */
     _virtualConfig = computed(() => {
         const { virtual } = this.zConfig();
         if (!virtual || typeof virtual === 'boolean') {
@@ -3351,6 +3520,11 @@ class ZTableComponent {
     groupSize = computed(() => this._virtualConfig().groupSize ?? Z_DEFAULT_GROUP_SIZE, ...(ngDevMode ? [{ debugName: "groupSize" }] : []));
     groupHeight = computed(() => this.groupSize() * this.virtualRowHeight(), ...(ngDevMode ? [{ debugName: "groupHeight" }] : []));
     _dynamicGroupsVersion = signal(0, ...(ngDevMode ? [{ debugName: "_dynamicGroupsVersion" }] : []));
+    /**
+     * Groups rows for virtual scrolling. When rowSpan is used, rows that share
+     * a merged cell are grouped together so the virtualizer treats them as
+     * a single unit, preserving the visual merge across scroll boundaries.
+     */
     dynamicGroups = computed(() => {
         if (!this.isVirtual()) {
             return [];
@@ -3561,6 +3735,11 @@ class ZTableComponent {
         }
         return colSizes;
     }, ...(ngDevMode ? [{ debugName: "columnSizeVars" }] : []));
+    // ─── TanStack Table Instance ──────────────────────────────────────────────
+    //
+    // The central table instance. All state signals flow in, and on*Change
+    // callbacks flow out. Features (sorting, filtering, pagination) are
+    // conditionally enabled based on column configs and table mode.
     table = createAngularTable(() => {
         const config = this.zConfig();
         const isServerMode = config.mode === 'server';
@@ -3726,6 +3905,7 @@ class ZTableComponent {
         const totalRows = untracked(() => this.table.getRowModel().rows.length);
         return Math.ceil(totalRows / this.groupSize());
     }, ...(ngDevMode ? [{ debugName: "_virtualGroupCount" }] : []));
+    /** Virtualizer instance — operates on groups rather than individual rows */
     virtualizer = injectVirtualizer(() => {
         const groups = this.dynamicGroups();
         const rowHeight = this.virtualRowHeight();
@@ -3767,7 +3947,13 @@ class ZTableComponent {
             this.virtualizer.measureElement(el.nativeElement);
         }
     }, ...(ngDevMode ? [{ debugName: "_measureVirtualItems" }] : []));
+    // ─── Constructor Effects ──────────────────────────────────────────────────
+    //
+    // Effects run in the constructor because Angular signals + effects don't
+    // have a separate "init" lifecycle. Each effect is responsible for one
+    // concern (data sync, config loading, scroll reset, settings persistence, etc.)
     constructor() {
+        // Force data refresh when language changes (re-evaluates translations in cells)
         explicitEffect([this._zTranslate.currentLang], () => {
             this._dataForceUpdate.update(v => v + 1);
         });
@@ -3961,6 +4147,7 @@ class ZTableComponent {
             this._saveConfig();
         }, { defer: true });
     }
+    // ─── Lifecycle ────────────────────────────────────────────────────────────
     ngAfterViewInit() {
         queueMicrotask(() => this._checkScrollState());
         this.zControl.emit({
@@ -4033,6 +4220,12 @@ class ZTableComponent {
             },
         });
     }
+    // ─── Selection Helpers ────────────────────────────────────────────────────
+    /**
+     * Syncs parent row selection state based on children.
+     * If all children are selected, the parent is auto-selected;
+     * if no children are selected, the parent is deselected.
+     */
     _handleRowSelectionWithParents(newState) {
         const stateRecord = newState;
         const finalState = { ...stateRecord };
@@ -4057,6 +4250,12 @@ class ZTableComponent {
             data: { selection: finalState },
         });
     }
+    // ─── Async State Helpers ──────────────────────────────────────────────────
+    /**
+     * Wraps state mutations with a debounced processing indicator.
+     * Shows a brief loading state to prevent UI flicker during
+     * filter/sort recomputation on large datasets.
+     */
     _runAsyncStateUpdate(updateFn, forceLocal = false) {
         const isServerMode = this.zConfig().mode === 'server';
         const hasLocalFiltering = this.hasLocalFiltering();
@@ -4213,6 +4412,7 @@ class ZTableComponent {
     hasRightPinnedColumns() {
         return this.table.getRightLeafColumns().length > 0;
     }
+    // ─── Scroll Event Handlers ────────────────────────────────────────────────
     onTbodyScroll(event) {
         if (this._isSyncingScroll()) {
             return;
@@ -4241,6 +4441,8 @@ class ZTableComponent {
             this._isSyncingScroll.set(false);
         });
     }
+    // ─── Sort / Pagination / Search Handlers ──────────────────────────────────
+    /** Handles sort click; auto-adds shiftKey for multi-sort when enabled */
     handleSort(event, handler) {
         event.preventDefault();
         if (this.zConfig().enableMultiSort) {
@@ -4329,6 +4531,7 @@ class ZTableComponent {
             },
         });
     }
+    // ─── Settings Drawer ─────────────────────────────────────────────────────
     openSettingsDrawer() {
         if (this.columnOrder().length === 0) {
             this.columnOrder.set(this.table.getAllLeafColumns().map(col => col.id));
@@ -4484,6 +4687,8 @@ class ZTableComponent {
         const movableColumns = order.filter(id => id !== 'select' && id !== 'expand' && id !== 'actions');
         return movableColumns.length > 0 && movableColumns[movableColumns.length - 1] === columnId;
     }
+    // ─── Settings Persistence ─────────────────────────────────────────────────
+    /** Saves current column layout, sizing, pinning, and visibility to ZCacheService */
     _saveConfig() {
         const key = this.zKey();
         if (!key) {
@@ -4527,6 +4732,7 @@ class ZTableComponent {
         collect(columns);
         return result;
     }
+    /** Loads cached config from ZCacheService; validates schema compatibility first */
     _loadConfigCache(key) {
         if (!key) {
             return false;
@@ -4568,6 +4774,11 @@ class ZTableComponent {
             return false;
         }
     }
+    /**
+     * Validates cached column info against current config.
+     * Returns false if columns have been added/removed/renamed since cache was saved,
+     * which triggers cache invalidation.
+     */
     _isColumnConfigValid(cachedColumnInfo) {
         if (!cachedColumnInfo || cachedColumnInfo.length === 0) {
             return true;
@@ -4593,6 +4804,9 @@ class ZTableComponent {
         }
         return true;
     }
+    // ─── Filter / Sort Mode Helpers ───────────────────────────────────────────
+    // These helpers determine whether a column's sort/filter changes should be
+    // processed locally by TanStack or emitted to the parent for server-side handling.
     _getChangedFilterColumnIds(oldState, newState) {
         const changedIds = [];
         const oldMap = new Map(oldState.map(f => [f.id, f.value]));
@@ -4651,6 +4865,11 @@ class ZTableComponent {
     _filterServerModeSorting(sorting) {
         return sorting.filter(sort => !this._isColumnSortModeLocal(sort.id));
     }
+    // ─── Column Config Lookup (Cached) ────────────────────────────────────────
+    /**
+     * Recursively finds a column config by ID with caching.
+     * Cache is invalidated when the column array reference changes.
+     */
     _findColumnConfig(columnId) {
         const { columns } = this.zConfig();
         if (columns !== this._lastColumnsRef) {