photon-grid-core 0.0.1

package/column-groups/display-group-header-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-group-header-builder.d.ts","sourceRoot":"","sources":["../../src/column-groups/display-group-header-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EACV,iBAAiB,EAGjB,gBAAgB,EAEjB,MAAM,uBAAuB,CAAC;AAG/B;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,8FAA8F;IAC9F,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD,oEAAoE;IACpE,aAAa,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACnE;;;OAGG;IACH,sBAAsB,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,WAAW,KAAK,IAAI,CAAC;IAC1F;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC;IAC9B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,WAAW,KAAK,IAAI,CAAC;CACvF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,yBAAyB;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAAZ,YAAY,EAAE,YAAY;IAIvD;;;;;;OAMG;IACH,cAAc,CACZ,IAAI,EAAK,iBAAiB,EAC1B,OAAO,EAAE,uBAAuB,GAC/B,WAAW,EAAE;IAKhB;;;;;;;OAOG;IACH,eAAe,CACb,MAAM,EAAG,WAAW,EAAE,EACtB,IAAI,EAAK,iBAAiB,EAC1B,OAAO,EAAE,uBAAuB,GAC/B,IAAI;IAWP,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,SAAS;IAkBjB;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IA4FtB,OAAO,CAAC,mBAAmB;IAyB3B;;;;;;;;OAQG;IACH,OAAO,CAAC,gBAAgB;CA2BzB"}

package/column-groups/display-group-header-builder.js

@@ -0,0 +1,224 @@
+import { createDiv } from '../renderer/dom-utils';
+/**
+ * Builds the multi-row grouped header DOM from a {@link DisplayHeaderTree}.
+ *
+ * ### Layout model
+ * ```
+ * pg-header-group-row depth-0  ← group cells (position: absolute)
+ * pg-header-group-row depth-1  ← deeper group cells (if nested)
+ * pg-header-row                ← leaf headers (built by HeaderRenderer)
+ * ```
+ *
+ * Group rows use `position: relative` with absolutely-positioned cells,
+ * allowing arbitrary column widths and nesting depths without flex constraints.
+ * Filler cells occupy the group-row space of flat/shallow columns, making them
+ * appear to span the full header height.
+ *
+ * ### Responsibilities
+ * - Build one `HTMLElement` per group depth row (`buildGroupRows`).
+ * - Rebuild existing rows in place without re-mounting (`updateGroupRows`).
+ * - Render group cells: label, collapse button, resize handle.
+ * - Render filler cells for flat/shallow columns.
+ */
+export class DisplayGroupHeaderBuilder {
+    constructor(iconRenderer) {
+        this.iconRenderer = iconRenderer;
+    }
+    // ── Public: build / update ────────────────────────────────────────────────
+    /**
+     * Build one `HTMLElement` per group depth row from the given display tree.
+     * Returns an empty array when `maxGroupDepth === 0` (no groups present).
+     *
+     * @param tree    - Fully-computed display header tree.
+     * @param options - Callbacks and configuration for interactive cells.
+     */
+    buildGroupRows(tree, options) {
+        if (tree.maxGroupDepth === 0)
+            return [];
+        return tree.groupRows.map((row) => this.buildRow(row, options));
+    }
+    /**
+     * Rebuild the contents of existing group-row elements in place.
+     * Called when column widths change or collapse state is toggled.
+     *
+     * @param rowEls  - Previously built row elements (from `buildGroupRows`).
+     * @param tree    - Updated display header tree.
+     * @param options - Callbacks and configuration.
+     */
+    updateGroupRows(rowEls, tree, options) {
+        if (rowEls.length === 0 || tree.maxGroupDepth === 0)
+            return;
+        const count = Math.min(rowEls.length, tree.groupRows.length);
+        for (let d = 0; d < count; d++) {
+            rowEls[d].innerHTML = '';
+            this.populateRow(rowEls[d], tree.groupRows[d], options);
+        }
+    }
+    // ── Private: DOM building ─────────────────────────────────────────────────
+    buildRow(row, options) {
+        const el = createDiv(`pg-header-group-row pg-header-group-row--depth-${row.depth}`);
+        el.setAttribute('role', 'row');
+        el.setAttribute('data-group-depth', String(row.depth));
+        this.populateRow(el, row, options);
+        return el;
+    }
+    populateRow(rowEl, row, options) {
+        for (const cell of row.cells) {
+            rowEl.appendChild(this.buildCell(cell, options));
+        }
+    }
+    buildCell(cell, options) {
+        if (cell.kind === 'filler') {
+            // Filler cells occupy group-row space for flat/shallow columns.
+            // They have the header background but no interactive elements.
+            // data-col-id is stamped here so the group-drag CSS-transform path can
+            // apply --pg-drag-x offsets to the filler cell via the same [data-col-id]
+            // rule that shifts the corresponding leaf header and body cells.
+            const filler = createDiv('pg-th pg-th--depth-filler');
+            filler.setAttribute('data-filler-id', cell.id);
+            filler.setAttribute('data-col-id', cell.colId);
+            filler.style.left = `${cell.left}px`;
+            filler.style.width = `${cell.width}px`;
+            return filler;
+        }
+        return this.buildGroupCell(cell.node, cell.left, cell.width, options);
+    }
+    /**
+     * Build a single interactive group header cell.
+     *
+     * @param group   - Display group node supplying all rendering data.
+     * @param left    - Pixel left offset within the row.
+     * @param width   - Pixel width of the cell.
+     * @param options - Interactive callbacks.
+     */
+    buildGroupCell(group, left, width, options) {
+        const isCollapsed = group.collapsed;
+        const classes = ['pg-th', 'pg-th--group'];
+        if (isCollapsed)
+            classes.push('pg-th--group--collapsed');
+        if (group.headerCssClass) {
+            for (const cls of group.headerCssClass.split(' ')) {
+                if (cls.trim())
+                    classes.push(cls.trim());
+            }
+        }
+        const th = createDiv(classes.join(' '));
+        th.setAttribute('role', 'columnheader');
+        th.setAttribute('data-group-id', group.logicalGroupId);
+        th.setAttribute('data-instance-id', group.instanceId);
+        th.setAttribute('aria-expanded', String(!isCollapsed));
+        th.setAttribute('aria-label', group.header);
+        th.setAttribute('tabindex', '0');
+        th.style.left = `${left}px`;
+        th.style.width = `${width}px`;
+        if (group.headerRendererFn) {
+            // Custom renderer — receive a minimal LogicalGroupDef proxy
+            const proxy = {
+                id: group.logicalGroupId,
+                header: group.header,
+                parentId: null,
+                headerCssClass: group.headerCssClass,
+                resizable: group.resizable,
+                collapsedWidth: group.collapsedWidth,
+                headerRendererFn: group.headerRendererFn,
+            };
+            const rendered = group.headerRendererFn({ logicalGroup: proxy, collapsed: isCollapsed, api: null });
+            if (typeof rendered === 'string')
+                th.innerHTML = rendered;
+            else
+                th.appendChild(rendered);
+        }
+        else {
+            this.buildDefaultContent(th, group, isCollapsed);
+        }
+        // Resize handle — appears on hover; distributes width among all group leaves
+        if (group.resizable) {
+            const handle = createDiv('pg-th__resize-handle pg-th__resize-handle--group');
+            handle.setAttribute('aria-hidden', 'true');
+            handle.addEventListener('mousedown', (e) => {
+                e.stopPropagation();
+                e.preventDefault();
+                this.startGroupResize(e, group, width, options);
+            });
+            th.appendChild(handle);
+        }
+        // Mousedown: notify drag handler before threshold check
+        th.addEventListener('mousedown', (e) => {
+            if (e.target.closest('.pg-th__resize-handle'))
+                return;
+            options.onGroupHeaderMouseDown?.(e, group, th);
+        });
+        // Click: toggle collapse (suppressed when drag just finished)
+        th.addEventListener('click', (e) => {
+            if (e.target.closest('.pg-th__resize-handle'))
+                return;
+            if (options.didJustDragFn?.())
+                return;
+            options.onCollapseToggle?.(group.instanceId);
+        });
+        // Right-click: open the group context menu at cursor position.
+        th.addEventListener('contextmenu', (e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            options.onGroupContextMenu?.(e, group, th);
+        });
+        // Keyboard: Enter/Space toggles; Arrow keys expand/collapse directionally
+        th.addEventListener('keydown', (e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault();
+                options.onCollapseToggle?.(group.instanceId);
+            }
+            else if (e.key === 'ArrowLeft' && !isCollapsed) {
+                e.preventDefault();
+                options.onCollapseToggle?.(group.instanceId);
+            }
+            else if (e.key === 'ArrowRight' && isCollapsed) {
+                e.preventDefault();
+                options.onCollapseToggle?.(group.instanceId);
+            }
+        });
+        return th;
+    }
+    buildDefaultContent(th, group, isCollapsed) {
+        const content = createDiv('pg-th__content');
+        const labelEl = createDiv('pg-th__label');
+        labelEl.textContent = group.header;
+        labelEl.title = group.header;
+        content.appendChild(labelEl);
+        th.appendChild(content);
+        const btn = createDiv('pg-th__collapse-btn');
+        btn.setAttribute('tabindex', '-1');
+        btn.setAttribute('aria-label', isCollapsed ? `Expand ${group.header}` : `Collapse ${group.header}`);
+        btn.innerHTML = this.iconRenderer.renderToString(isCollapsed ? 'chevronRight' : 'chevronLeft', 12);
+        th.appendChild(btn);
+    }
+    /**
+     * Start a group-header resize drag.
+     * Computes the new width on each mousemove and fires `onGroupResize`.
+     *
+     * @param e          - Initiating mousedown event.
+     * @param group      - The group being resized.
+     * @param startWidth - Pixel width at drag start.
+     * @param options    - Contains the `onGroupResize` callback.
+     */
+    startGroupResize(e, group, startWidth, options) {
+        const startX = e.clientX;
+        document.body.style.cursor = 'col-resize';
+        document.body.style.userSelect = 'none';
+        const onMove = (ev) => {
+            const newW = Math.max(group.collapsedWidth, startWidth + ev.clientX - startX);
+            options.onGroupResize?.(group.instanceId, newW);
+        };
+        const onUp = (ev) => {
+            const newW = Math.max(group.collapsedWidth, startWidth + ev.clientX - startX);
+            options.onGroupResize?.(group.instanceId, newW);
+            document.body.style.cursor = '';
+            document.body.style.userSelect = '';
+            document.removeEventListener('mousemove', onMove);
+            document.removeEventListener('mouseup', onUp);
+        };
+        document.addEventListener('mousemove', onMove);
+        document.addEventListener('mouseup', onUp);
+    }
+}
+//# sourceMappingURL=display-group-header-builder.js.map

package/column-groups/display-group-header-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-group-header-builder.js","sourceRoot":"","sources":["../../src/column-groups/display-group-header-builder.ts"],"names":[],"mappings":"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"}

package/column-groups/display-group.types.d.ts

@@ -0,0 +1,140 @@
+import type { ColumnDef } from '../types/column.types';
+/**
+ * Immutable definition of a logical column group.
+ * Parsed once from the user-supplied ColumnDef hierarchy and never modified.
+ */
+export interface LogicalGroupDef {
+    /** Unique identifier — defaults to the originating ColumnDef.colId. */
+    readonly id: string;
+    /** Display label for the group header cell. */
+    readonly header: string;
+    /** Parent logical group ID; `null` for root groups. */
+    readonly parentId: string | null;
+    /** Optional CSS class applied to every display instance of this group. */
+    readonly headerCssClass?: string;
+    /** Whether the group header shows a resize handle. @default true */
+    readonly resizable?: boolean;
+    /** Minimum pixel width when the group is in the collapsed-peek state. @default 36 */
+    readonly collapsedWidth?: number;
+    /** When `true`, child columns cannot be individually reordered. @default false */
+    readonly marryChildren?: boolean;
+    /** Custom renderer for the group header cell. */
+    readonly headerRendererFn?: (p: GroupHeaderRendererParams) => string | HTMLElement;
+}
+/** Parameters passed to a custom group header renderer function. */
+export interface GroupHeaderRendererParams {
+    readonly logicalGroup: LogicalGroupDef;
+    readonly collapsed: boolean;
+    readonly api: null;
+}
+/**
+ * A single rendered display instance of a logical group.
+ *
+ * The same logical group can produce **multiple display instances** when its
+ * columns are interleaved with columns from other groups in the current
+ * displayed order.
+ *
+ * @example
+ * ```
+ * ColumnDef: Personal[Name, Email]
+ * Displayed:  [Name, Country, Email]
+ * → two display instances: Personal[Name] and Personal[Email]
+ * ```
+ */
+export interface DisplayGroupNode {
+    readonly kind: 'group';
+    /** Unique per render cycle — must not be persisted across rebuilds. */
+    readonly instanceId: string;
+    /** References the immutable logical group. */
+    readonly logicalGroupId: string;
+    readonly header: string;
+    /** Zero-based depth: 0 = topmost group row, 1 = nested group row, etc. */
+    readonly depth: number;
+    /** Ordered child display nodes — groups and/or leaves. */
+    readonly children: ReadonlyArray<DisplayNode>;
+    /** Left offset in pixels from the panel's scroll origin. */
+    left: number;
+    /** Sum of visible children widths in pixels. */
+    width: number;
+    /** `true` when this instance's logical group is in the collapsed-peek state. */
+    collapsed: boolean;
+    readonly resizable: boolean;
+    readonly collapsedWidth: number;
+    readonly headerCssClass?: string;
+    readonly headerRendererFn?: LogicalGroupDef['headerRendererFn'];
+}
+/** A single rendered leaf column node in the display tree. */
+export interface DisplayLeafNode {
+    readonly kind: 'leaf';
+    readonly colDef: ColumnDef;
+    /** Logical group ID path root-first. Empty array for ungrouped flat columns. */
+    readonly groupPath: ReadonlyArray<string>;
+    left: number;
+    width: number;
+}
+/** Union of all display tree node types. */
+export type DisplayNode = DisplayGroupNode | DisplayLeafNode;
+/** A rendered group header cell — one display group node in a header row. */
+export interface RenderedGroupCell {
+    readonly kind: 'group';
+    readonly node: DisplayGroupNode;
+    readonly left: number;
+    readonly width: number;
+    readonly depth: number;
+}
+/**
+ * A transparent filler cell that occupies group-row space for a column that
+ * has no ancestor group at this depth.
+ *
+ * Styled to match the header background so the column visually spans the
+ * full header height — creating a seamless tall-cell appearance.
+ */
+export interface RenderedFillerCell {
+    readonly kind: 'filler';
+    /** Unique ID used for keying DOM comparisons. */
+    readonly id: string;
+    /**
+     * The leaf column ID this filler represents.
+     * Stamped onto the DOM element as `data-col-id` so that the group-drag
+     * CSS-transform path can apply `--pg-drag-x` offsets to both the filler
+     * cell (in the group row) and the leaf header / body cell in a single rule.
+     */
+    readonly colId: string;
+    readonly left: number;
+    readonly width: number;
+    readonly depth: number;
+}
+/** Union of cell types in a rendered header row. */
+export type RenderedHeaderCell = RenderedGroupCell | RenderedFillerCell;
+/** One horizontal rendered header row at a specific depth level. */
+export interface RenderedHeaderRow {
+    readonly depth: number;
+    readonly cells: ReadonlyArray<RenderedHeaderCell>;
+}
+/**
+ * The complete display header tree produced by `DisplayGroupBuilder`.
+ * Consumed by `DisplayGroupHeaderBuilder` to produce DOM elements.
+ */
+export interface DisplayHeaderTree {
+    /** Root-level display nodes — depth-0 groups and ungrouped flat leaves. */
+    readonly roots: ReadonlyArray<DisplayNode>;
+    /**
+     * Number of group header rows above the leaf row.
+     * - `0` — no groups; header has only the leaf row.
+     * - `N` — N group rows at depths 0..N-1, plus the leaf row below them.
+     */
+    readonly maxGroupDepth: number;
+    /**
+     * Flattened group rows — one per depth level `0..maxGroupDepth-1`.
+     * Each row contains group cells and filler cells sorted by `left`.
+     */
+    readonly groupRows: ReadonlyArray<RenderedHeaderRow>;
+    /** Total pixel width of all visible leaf columns. */
+    readonly totalWidth: number;
+}
+/** Serializable collapse state for one logical group. */
+export interface GroupCollapseState {
+    logicalGroupId: string;
+    collapsed: boolean;
+}
+//# sourceMappingURL=display-group.types.d.ts.map

package/column-groups/display-group.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-group.types.d.ts","sourceRoot":"","sources":["../../src/column-groups/display-group.types.ts"],"names":[],"mappings":"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"}

package/column-groups/display-group.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=display-group.types.js.map

package/column-groups/display-group.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-group.types.js","sourceRoot":"","sources":["../../src/column-groups/display-group.types.ts"],"names":[],"mappings":""}

package/column-groups/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @module column-groups
+ *
+ * Public API surface for the Photon Grid column-group system.
+ *
+ * ```ts
+ * import {
+ *   ColumnGroupModel,
+ *   ColumnGroupHeaderBuilder,
+ *   ColumnGroupStateManager,
+ *   ColumnGroupNodeType,
+ *   ColumnGroupResizeStrategy,
+ * } from 'photon-grid/column-groups';
+ * ```
+ */
+export type { IColumnGroupNode, IColumnLeafNode, ColumnTreeNode, HeaderGroupCell, HeaderGroupRow, HeaderGroupLayoutOptions, GroupHeaderRendererParams, ColumnGroupSerialState, ColumnGroupSystemState, ColumnGroupHeaderCollapsedEvent, ColumnGroupHeaderExpandedEvent, ColumnGroupHeaderCreatedEvent, ColumnGroupHeaderRemovedEvent, } from './column-group.types';
+export { ColumnGroupNodeType, ColumnGroupResizeStrategy } from './column-group.types';
+export { ColumnGroupModel } from './column-group-model';
+export { ColumnGroupHeaderBuilder } from './column-group-header-builder';
+export type { GroupCellBuildOptions } from './column-group-header-builder';
+export { ColumnGroupDragHandler } from './column-group-drag-handler';
+export type { GroupDropPosition, GroupDropTarget } from './column-group-drag-handler';
+export { ColumnGroupStateManager } from './column-group-state-manager';
+export type { ColumnGroupStateDiff } from './column-group-state-manager';
+//# sourceMappingURL=index.d.ts.map

package/column-groups/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/column-groups/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,eAAe,EACf,cAAc,EACd,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACtB,sBAAsB,EACtB,+BAA+B,EAC/B,8BAA8B,EAC9B,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAGtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGxD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,YAAY,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAG3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAGtF,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,YAAY,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC"}

package/column-groups/index.js

@@ -0,0 +1,26 @@
+/**
+ * @module column-groups
+ *
+ * Public API surface for the Photon Grid column-group system.
+ *
+ * ```ts
+ * import {
+ *   ColumnGroupModel,
+ *   ColumnGroupHeaderBuilder,
+ *   ColumnGroupStateManager,
+ *   ColumnGroupNodeType,
+ *   ColumnGroupResizeStrategy,
+ * } from 'photon-grid/column-groups';
+ * ```
+ */
+// ── Enums ────────────────────────────────────────────────────────────────────
+export { ColumnGroupResizeStrategy } from './column-group.types';
+// ── Model ────────────────────────────────────────────────────────────────────
+export { ColumnGroupModel } from './column-group-model';
+// ── Header builder ───────────────────────────────────────────────────────────
+export { ColumnGroupHeaderBuilder } from './column-group-header-builder';
+// ── Drag handler ─────────────────────────────────────────────────────────────
+export { ColumnGroupDragHandler } from './column-group-drag-handler';
+// ── State manager ────────────────────────────────────────────────────────────
+export { ColumnGroupStateManager } from './column-group-state-manager';
+//# sourceMappingURL=index.js.map

package/column-groups/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/column-groups/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAmBH,gFAAgF;AAChF,OAAO,EAAuB,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAEtF,gFAAgF;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,gFAAgF;AAChF,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAGzE,gFAAgF;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAGrE,gFAAgF;AAChF,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC"}

package/column-groups/logical-group-registry.d.ts

@@ -0,0 +1,77 @@
+import type { ColumnDef } from '../types/column.types';
+import type { LogicalGroupDef } from './display-group.types';
+/**
+ * Parses the user-supplied ColumnDef[] hierarchy **once** and builds an
+ * immutable registry of logical groups plus a column-path map.
+ *
+ * This is the "Original Column Tree" in the Display Group Builder architecture.
+ * After `parse()` the registry is effectively frozen — the original column
+ * tree is never mutated by drag, collapse, or any other operation.
+ *
+ * @example
+ * ```ts
+ * const registry = new LogicalGroupRegistry();
+ * registry.parse(options.columns);
+ * // registry.getPath('name') → ['grp_personal']
+ * // registry.getGroup('grp_personal') → LogicalGroupDef
+ * ```
+ */
+export declare class LogicalGroupRegistry {
+    /** Logical group ID → immutable group definition. */
+    private readonly _groups;
+    /**
+     * Leaf column ID → ordered list of ancestor logical group IDs (root → parent).
+     * Ungrouped (flat) columns are mapped to an empty array.
+     */
+    private readonly _paths;
+    private _hasGroups;
+    /**
+     * Parse a ColumnDef[] hierarchy and populate the registry.
+     * Clears any previous state before re-parsing — safe to call multiple times.
+     *
+     * @param columns - Top-level column definitions, which may contain nested
+     *   `.children` arrays representing column groups.
+     */
+    parse(columns: ColumnDef[]): void;
+    /**
+     * `true` when any ColumnDef in the parsed hierarchy contained `.children`.
+     * Used to decide whether group header rows should be rendered.
+     */
+    get hasGroups(): boolean;
+    /** Read-only map from logical group ID to its immutable definition. */
+    get groups(): ReadonlyMap<string, LogicalGroupDef>;
+    /** Read-only map from leaf `colId` to its group path. */
+    get paths(): ReadonlyMap<string, ReadonlyArray<string>>;
+    /**
+     * Returns the group path for a leaf column — an ordered list of ancestor
+     * logical group IDs from root to immediate parent.
+     * Returns an empty array for ungrouped (flat) columns.
+     *
+     * @param colId - Leaf column ID.
+     */
+    getPath(colId: string): ReadonlyArray<string>;
+    /**
+     * Returns the `LogicalGroupDef` for the given group ID, or `undefined` if
+     * the ID is not registered (e.g., a leaf column ID was passed by mistake).
+     *
+     * @param groupId - Logical group ID (equals the originating ColumnDef.colId).
+     */
+    getGroup(groupId: string): LogicalGroupDef | undefined;
+    /**
+     * Returns all leaf column IDs whose group path **includes** the given
+     * logical group ID at any depth.
+     *
+     * Used by the engine to collect all leaves of a group for drag/resize/collapse.
+     *
+     * @param logicalGroupId - Logical group ID to search for.
+     */
+    getLeavesForGroup(logicalGroupId: string): ReadonlyArray<string>;
+    /**
+     * Depth-first walk through the ColumnDef hierarchy.
+     *
+     * @param cols         - Column definitions at the current depth.
+     * @param ancestorPath - Ordered ancestor group IDs from root to current depth.
+     */
+    private walk;
+}
+//# sourceMappingURL=logical-group-registry.d.ts.map

package/column-groups/logical-group-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logical-group-registry.d.ts","sourceRoot":"","sources":["../../src/column-groups/logical-group-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,oBAAoB;IAC/B,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAE9D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4C;IAEnE,OAAO,CAAC,UAAU,CAAS;IAI3B;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,IAAI;IAOjC;;;OAGG;IACH,IAAI,SAAS,IAAI,OAAO,CAA4B;IAEpD,uEAAuE;IACvE,IAAI,MAAM,IAAI,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAyB;IAE3E,yDAAyD;IACzD,IAAI,KAAK,IAAI,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAwB;IAE/E;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC;IAI7C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAItD;;;;;;;OAOG;IACH,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC;IAUhE;;;;;OAKG;IACH,OAAO,CAAC,IAAI;CA2Bb"}

package/column-groups/logical-group-registry.js

@@ -0,0 +1,118 @@
+/**
+ * Parses the user-supplied ColumnDef[] hierarchy **once** and builds an
+ * immutable registry of logical groups plus a column-path map.
+ *
+ * This is the "Original Column Tree" in the Display Group Builder architecture.
+ * After `parse()` the registry is effectively frozen — the original column
+ * tree is never mutated by drag, collapse, or any other operation.
+ *
+ * @example
+ * ```ts
+ * const registry = new LogicalGroupRegistry();
+ * registry.parse(options.columns);
+ * // registry.getPath('name') → ['grp_personal']
+ * // registry.getGroup('grp_personal') → LogicalGroupDef
+ * ```
+ */
+export class LogicalGroupRegistry {
+    constructor() {
+        /** Logical group ID → immutable group definition. */
+        this._groups = new Map();
+        /**
+         * Leaf column ID → ordered list of ancestor logical group IDs (root → parent).
+         * Ungrouped (flat) columns are mapped to an empty array.
+         */
+        this._paths = new Map();
+        this._hasGroups = false;
+    }
+    // ── Public API ────────────────────────────────────────────────────────────
+    /**
+     * Parse a ColumnDef[] hierarchy and populate the registry.
+     * Clears any previous state before re-parsing — safe to call multiple times.
+     *
+     * @param columns - Top-level column definitions, which may contain nested
+     *   `.children` arrays representing column groups.
+     */
+    parse(columns) {
+        this._groups.clear();
+        this._paths.clear();
+        this._hasGroups = false;
+        this.walk(columns, []);
+    }
+    /**
+     * `true` when any ColumnDef in the parsed hierarchy contained `.children`.
+     * Used to decide whether group header rows should be rendered.
+     */
+    get hasGroups() { return this._hasGroups; }
+    /** Read-only map from logical group ID to its immutable definition. */
+    get groups() { return this._groups; }
+    /** Read-only map from leaf `colId` to its group path. */
+    get paths() { return this._paths; }
+    /**
+     * Returns the group path for a leaf column — an ordered list of ancestor
+     * logical group IDs from root to immediate parent.
+     * Returns an empty array for ungrouped (flat) columns.
+     *
+     * @param colId - Leaf column ID.
+     */
+    getPath(colId) {
+        return this._paths.get(colId) ?? [];
+    }
+    /**
+     * Returns the `LogicalGroupDef` for the given group ID, or `undefined` if
+     * the ID is not registered (e.g., a leaf column ID was passed by mistake).
+     *
+     * @param groupId - Logical group ID (equals the originating ColumnDef.colId).
+     */
+    getGroup(groupId) {
+        return this._groups.get(groupId);
+    }
+    /**
+     * Returns all leaf column IDs whose group path **includes** the given
+     * logical group ID at any depth.
+     *
+     * Used by the engine to collect all leaves of a group for drag/resize/collapse.
+     *
+     * @param logicalGroupId - Logical group ID to search for.
+     */
+    getLeavesForGroup(logicalGroupId) {
+        const result = [];
+        for (const [colId, path] of this._paths) {
+            if (path.includes(logicalGroupId))
+                result.push(colId);
+        }
+        return result;
+    }
+    // ── Private ───────────────────────────────────────────────────────────────
+    /**
+     * Depth-first walk through the ColumnDef hierarchy.
+     *
+     * @param cols         - Column definitions at the current depth.
+     * @param ancestorPath - Ordered ancestor group IDs from root to current depth.
+     */
+    walk(cols, ancestorPath) {
+        for (const col of cols) {
+            const children = col.children;
+            if (Array.isArray(children) && children.length > 0) {
+                this._hasGroups = true;
+                const parentId = ancestorPath.length > 0 ? ancestorPath[ancestorPath.length - 1] : null;
+                this._groups.set(col.colId, {
+                    id: col.colId,
+                    header: col.header ?? '',
+                    parentId,
+                    headerCssClass: col.headerCssClass,
+                    resizable: col.resizable,
+                    collapsedWidth: col.collapsedWidth ?? 36,
+                    marryChildren: col.marryChildren,
+                    headerRendererFn: col.groupHeaderRendererFn,
+                });
+                this.walk(children, [...ancestorPath, col.colId]);
+            }
+            else {
+                // Leaf column — record its full group path
+                this._paths.set(col.colId, [...ancestorPath]);
+            }
+        }
+    }
+}
+//# sourceMappingURL=logical-group-registry.js.map