photon-grid-core 0.0.1

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

@@ -0,0 +1,91 @@
+import type { ColumnDef } from '../types/column.types';
+import type { ColumnStyleManager } from '../renderer/column-style-manager';
+import type { LogicalGroupRegistry } from './logical-group-registry';
+import type { DisplayHeaderTree } from './display-group.types';
+/**
+ * Stateless builder that produces a {@link DisplayHeaderTree} from the current
+ * displayed column order.
+ *
+ * The same builder instance can be reused — call `build()` whenever the
+ * displayed column order, column widths, or collapse state changes.
+ * Because the builder is stateless, `build()` always returns a fresh tree
+ * without any shared mutable state.
+ *
+ * ### Algorithm — O(n) per column
+ *
+ * Walk through visible columns **left to right**, maintaining an `openStack`
+ * of currently-open `DisplayGroupNode` instances:
+ *
+ * 1. Get the column's group path from the registry.
+ * 2. Find the **longest common prefix** between the open stack IDs and the path.
+ * 3. **Close** every group above the common-prefix depth — attach each closed
+ *    node to its parent (or to `roots`), finalising its width.
+ * 4. **Open** new group instances from `commonLen` to `path.length - 1`.
+ * 5. Attach a `DisplayLeafNode` to the deepest open group (or `roots`).
+ * 6. Advance `cursor` by the column's pixel width.
+ *
+ * After the last column, close any remaining open groups.
+ *
+ * Then: compute `maxGroupDepth`, flatten the tree into `RenderedHeaderRow[]`
+ * (one per depth), and return the completed `DisplayHeaderTree`.
+ *
+ * ### Split groups
+ *
+ * When the same logical group's columns are interleaved with another group's
+ * columns in the displayed order, the algorithm naturally creates **multiple
+ * display instances** of that logical group — one per consecutive run.
+ * Each instance has a unique `instanceId` and an independently computed width.
+ */
+export declare class DisplayGroupBuilder {
+    /**
+     * Build the display header tree for a single panel's visible column list.
+     *
+     * @param columns       - Visible columns in display order (left to right).
+     * @param registry      - Logical group registry supplying paths and definitions.
+     * @param collapseState - Per-logical-group collapse flags (from the engine).
+     * @param colStyles     - Column width resolver.
+     * @returns A fully-computed `DisplayHeaderTree` ready for DOM building.
+     */
+    build(columns: ColumnDef[], registry: LogicalGroupRegistry, collapseState: ReadonlyMap<string, boolean>, colStyles: ColumnStyleManager): DisplayHeaderTree;
+    /**
+     * Find the longest common prefix length between the current open stack's
+     * logical group IDs and the incoming column's group path.
+     *
+     * @param stack - Currently open group nodes.
+     * @param path  - Group path for the incoming column.
+     */
+    private commonPrefixLen;
+    /**
+     * Recursively compute the maximum group nesting depth across all nodes.
+     * Returns `0` when there are no group nodes (all columns are flat).
+     *
+     * @param nodes - Display nodes to inspect.
+     */
+    private computeMaxGroupDepth;
+    /**
+     * Flatten the display tree into one {@link RenderedHeaderRow} per group
+     * depth level (rows `0..maxGroupDepth-1`).
+     *
+     * - Group nodes produce `RenderedGroupCell` entries in their depth row.
+     * - Leaf nodes at any level produce `RenderedFillerCell` entries for every
+     *   group-row depth where they have no ancestor group.  This makes flat and
+     *   shallow columns appear to span the full header height.
+     *
+     * Cells within each row are sorted by `left` position before returning.
+     *
+     * @param roots         - Root-level display nodes.
+     * @param maxGroupDepth - Total number of group header rows to produce.
+     */
+    private buildGroupRows;
+    /**
+     * Recursively fill the rows array from display tree nodes.
+     *
+     * @param nodes      - Nodes at the current recursion level.
+     * @param rows       - Output rows array, mutated in place.
+     * @param startDepth - The group-row depth these nodes contribute to.
+     *   Root nodes → `startDepth = 0`.
+     *   Children of a depth-0 group → `startDepth = 1`, etc.
+     */
+    private fillRows;
+}
+//# sourceMappingURL=display-group-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"display-group-builder.d.ts","sourceRoot":"","sources":["../../src/column-groups/display-group-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,KAAK,EAQV,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAG/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,mBAAmB;IAC9B;;;;;;;;OAQG;IACH,KAAK,CACH,OAAO,EAAQ,SAAS,EAAE,EAC1B,QAAQ,EAAO,oBAAoB,EACnC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3C,SAAS,EAAM,kBAAkB,GAChC,iBAAiB;IA4FpB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAWvB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAY5B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,cAAc;IAYtB;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ;CAwCjB"}

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

@@ -0,0 +1,225 @@
+/**
+ * Stateless builder that produces a {@link DisplayHeaderTree} from the current
+ * displayed column order.
+ *
+ * The same builder instance can be reused — call `build()` whenever the
+ * displayed column order, column widths, or collapse state changes.
+ * Because the builder is stateless, `build()` always returns a fresh tree
+ * without any shared mutable state.
+ *
+ * ### Algorithm — O(n) per column
+ *
+ * Walk through visible columns **left to right**, maintaining an `openStack`
+ * of currently-open `DisplayGroupNode` instances:
+ *
+ * 1. Get the column's group path from the registry.
+ * 2. Find the **longest common prefix** between the open stack IDs and the path.
+ * 3. **Close** every group above the common-prefix depth — attach each closed
+ *    node to its parent (or to `roots`), finalising its width.
+ * 4. **Open** new group instances from `commonLen` to `path.length - 1`.
+ * 5. Attach a `DisplayLeafNode` to the deepest open group (or `roots`).
+ * 6. Advance `cursor` by the column's pixel width.
+ *
+ * After the last column, close any remaining open groups.
+ *
+ * Then: compute `maxGroupDepth`, flatten the tree into `RenderedHeaderRow[]`
+ * (one per depth), and return the completed `DisplayHeaderTree`.
+ *
+ * ### Split groups
+ *
+ * When the same logical group's columns are interleaved with another group's
+ * columns in the displayed order, the algorithm naturally creates **multiple
+ * display instances** of that logical group — one per consecutive run.
+ * Each instance has a unique `instanceId` and an independently computed width.
+ */
+export class DisplayGroupBuilder {
+    /**
+     * Build the display header tree for a single panel's visible column list.
+     *
+     * @param columns       - Visible columns in display order (left to right).
+     * @param registry      - Logical group registry supplying paths and definitions.
+     * @param collapseState - Per-logical-group collapse flags (from the engine).
+     * @param colStyles     - Column width resolver.
+     * @returns A fully-computed `DisplayHeaderTree` ready for DOM building.
+     */
+    build(columns, registry, collapseState, colStyles) {
+        const roots = [];
+        const openStack = [];
+        let cursor = 0;
+        /**
+         * Close groups until the stack depth reaches `targetDepth`.
+         * Each closed group is attached to its parent or to `roots`, with its
+         * final width computed as `cursor - node.left`.
+         */
+        const closeDown = (targetDepth) => {
+            while (openStack.length > targetDepth) {
+                const closing = openStack.pop();
+                // Finalise width: everything between its left edge and the cursor
+                closing.width = cursor - closing.left;
+                const parent = openStack.length > 0 ? openStack[openStack.length - 1] : null;
+                if (parent) {
+                    parent.children.push(closing);
+                }
+                else {
+                    roots.push(closing);
+                }
+            }
+        };
+        for (const col of columns) {
+            if (col.visible === false)
+                continue;
+            const path = registry.getPath(col.colId);
+            const colWidth = colStyles.getWidth(col.colId);
+            // Longest common prefix between the current open stack and this column's path
+            const common = this.commonPrefixLen(openStack, path);
+            closeDown(common);
+            // Open new group nodes for depths from `common` to `path.length - 1`.
+            // The stable instanceId uses the FIRST column that opens each group instance
+            // so that collapse/resize state persists across header rebuilds.
+            // Format: "${logicalGroupId}:${firstLeafColId}"
+            for (let d = common; d < path.length; d++) {
+                const groupId = path[d];
+                const def = registry.getGroup(groupId);
+                // col.colId is always the first leaf of a newly-opened instance because
+                // we walk columns left-to-right and a group is only opened once per run.
+                const instanceId = `${groupId}:${col.colId}`;
+                const node = {
+                    kind: 'group',
+                    instanceId,
+                    logicalGroupId: groupId,
+                    header: def?.header ?? groupId,
+                    depth: d,
+                    children: [],
+                    left: cursor,
+                    width: 0, // finalised on close
+                    collapsed: collapseState.get(instanceId) ?? false,
+                    resizable: def?.resizable !== false,
+                    collapsedWidth: def?.collapsedWidth ?? 36,
+                    headerCssClass: def?.headerCssClass,
+                    headerRendererFn: def?.headerRendererFn,
+                };
+                openStack.push(node);
+            }
+            // Create and attach the leaf node
+            const leaf = {
+                kind: 'leaf',
+                colDef: col,
+                groupPath: path,
+                left: cursor,
+                width: colWidth,
+            };
+            const parent = openStack.length > 0 ? openStack[openStack.length - 1] : null;
+            if (parent) {
+                parent.children.push(leaf);
+            }
+            else {
+                roots.push(leaf);
+            }
+            cursor += colWidth;
+        }
+        // Close any groups still open after the last column
+        closeDown(0);
+        const maxGroupDepth = this.computeMaxGroupDepth(roots);
+        const groupRows = maxGroupDepth > 0 ? this.buildGroupRows(roots, maxGroupDepth) : [];
+        return { roots, maxGroupDepth, groupRows, totalWidth: cursor };
+    }
+    // ── Private helpers ───────────────────────────────────────────────────────
+    /**
+     * Find the longest common prefix length between the current open stack's
+     * logical group IDs and the incoming column's group path.
+     *
+     * @param stack - Currently open group nodes.
+     * @param path  - Group path for the incoming column.
+     */
+    commonPrefixLen(stack, path) {
+        const len = Math.min(stack.length, path.length);
+        for (let i = 0; i < len; i++) {
+            if (stack[i].logicalGroupId !== path[i])
+                return i;
+        }
+        return len;
+    }
+    /**
+     * Recursively compute the maximum group nesting depth across all nodes.
+     * Returns `0` when there are no group nodes (all columns are flat).
+     *
+     * @param nodes - Display nodes to inspect.
+     */
+    computeMaxGroupDepth(nodes) {
+        let max = 0;
+        for (const n of nodes) {
+            if (n.kind === 'group') {
+                const childMax = this.computeMaxGroupDepth(n.children);
+                // This group occupies depth n.depth, contributing 1 group row
+                max = Math.max(max, n.depth + 1, childMax);
+            }
+        }
+        return max;
+    }
+    /**
+     * Flatten the display tree into one {@link RenderedHeaderRow} per group
+     * depth level (rows `0..maxGroupDepth-1`).
+     *
+     * - Group nodes produce `RenderedGroupCell` entries in their depth row.
+     * - Leaf nodes at any level produce `RenderedFillerCell` entries for every
+     *   group-row depth where they have no ancestor group.  This makes flat and
+     *   shallow columns appear to span the full header height.
+     *
+     * Cells within each row are sorted by `left` position before returning.
+     *
+     * @param roots         - Root-level display nodes.
+     * @param maxGroupDepth - Total number of group header rows to produce.
+     */
+    buildGroupRows(roots, maxGroupDepth) {
+        const rows = Array.from({ length: maxGroupDepth }, () => []);
+        this.fillRows(roots, rows, 0);
+        return rows.map((cells, depth) => ({
+            depth,
+            cells: cells.slice().sort((a, b) => a.left - b.left),
+        }));
+    }
+    /**
+     * Recursively fill the rows array from display tree nodes.
+     *
+     * @param nodes      - Nodes at the current recursion level.
+     * @param rows       - Output rows array, mutated in place.
+     * @param startDepth - The group-row depth these nodes contribute to.
+     *   Root nodes → `startDepth = 0`.
+     *   Children of a depth-0 group → `startDepth = 1`, etc.
+     */
+    fillRows(nodes, rows, startDepth) {
+        for (const node of nodes) {
+            if (node.kind === 'leaf') {
+                // Leaf at `startDepth` has no ancestor group from `startDepth` onward.
+                // Add filler cells from startDepth to the last group row so the column
+                // visually spans the full multi-row header height.
+                for (let d = startDepth; d < rows.length; d++) {
+                    const filler = {
+                        kind: 'filler',
+                        id: `_filler_${node.colDef.colId}_d${d}`,
+                        colId: node.colDef.colId,
+                        left: node.left,
+                        width: node.width,
+                        depth: d,
+                    };
+                    rows[d].push(filler);
+                }
+                continue;
+            }
+            // Group node — add a cell at its designated depth row
+            if (node.depth < rows.length) {
+                const cell = {
+                    kind: 'group',
+                    node,
+                    left: node.left,
+                    width: node.width,
+                    depth: node.depth,
+                };
+                rows[node.depth].push(cell);
+            }
+            // Recurse into children; they live at depth node.depth + 1
+            this.fillRows(node.children, rows, node.depth + 1);
+        }
+    }
+}
+//# sourceMappingURL=display-group-builder.js.map

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

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

package/column-groups/display-group-drag-handler.d.ts

@@ -0,0 +1,205 @@
+import type { DisplayGroupNode } from './display-group.types';
+/**
+ * Fired by {@link DisplayGroupDragHandler} when the user drops a group at a
+ * new position.
+ *
+ * @param logicalGroupId    - The logical group being moved.
+ * @param sourcePanel       - The panel the drag originated from.
+ * @param targetPanel       - The panel the group is dropped into.
+ * @param insertBeforeColId - First leaf column to the right of the drop target.
+ *   `null` means append at the end of the target panel section.
+ */
+export type GroupMovedCallback = (logicalGroupId: string, sourcePanel: 'left' | null | 'right', targetPanel: 'left' | null | 'right', insertBeforeColId: string | null) => void;
+/**
+ * Callbacks used for real-time (AG Grid-style) group tree preview during drag.
+ *
+ * When provided the drag handler uses a live-rebuild path instead of CSS
+ * transforms: on every slot change the column order is updated in the store so
+ * the header re-renders with the group in its new position before the user drops.
+ */
+export interface GroupPreviewCallbacks {
+    /** Called once when the drag crosses the activation threshold. */
+    onPreviewStart: () => void;
+    /**
+     * Called on every slot change during the drag.
+     * The engine applies the move from the original snapshot so the header
+     * rebuilds with the group at the new position.
+     */
+    onPreviewMove: GroupMovedCallback;
+    /**
+     * Called on mouseup to commit the final preview position.
+     * The store already reflects the correct order — this just clears the snapshot.
+     */
+    onPreviewConfirm: () => void;
+}
+/**
+ * Handles atomic column-group drag and drop.
+ *
+ * ### Rules
+ * - Only **group header cells** (`.pg-th--group`) can be dragged.
+ * - Group children cannot escape their group during drag.
+ * - Drop targets are root-level positions only (before/after other groups or
+ *   flat columns).  Dropping inside another group is not supported.
+ * - Moving across panels changes the `pinned` property of all group leaves.
+ *
+ * ### Visual feedback — two modes
+ * **Live preview** (when `previewCallbacks` is provided):
+ * The column order is updated in the store on every slot change so the header
+ * re-renders in real time — identical to AG Grid behaviour.  CSS transforms are
+ * not used; the rebuilt DOM IS the visual feedback.
+ *
+ * **CSS-transform** (legacy fallback):
+ * `translateX` rules are injected via a `<style>` tag to slide cells without
+ * touching the store.  The final move is committed on mouseup.
+ *
+ * ### Drag activation threshold
+ * A drag is not activated until the pointer moves **5 px** — preventing
+ * accidental drags during collapse-toggle clicks.
+ */
+export declare class DisplayGroupDragHandler {
+    private readonly gridElGetter;
+    private readonly onGroupMoved;
+    private readonly previewCallbacks?;
+    private readonly leavesFor?;
+    private _didJustDrag;
+    private isDragging;
+    private dragGroupId;
+    private sourcePanel;
+    private ghostEl;
+    private indicatorEl;
+    private dragStyleEl;
+    private capturedCells;
+    private dragSourceIdx;
+    /** Last slot key seen in live-preview mode — `"<panel>:<insertBeforeColId|end>"`. */
+    private lastSlotKey;
+    private startX;
+    private startY;
+    private removeMoveUp;
+    /**
+     * @param gridElGetter    - Returns the root `.pg-grid` element (may be null before mount).
+     * @param onGroupMoved    - Committed on mouseup; receives the final group position.
+     * @param previewCallbacks - When provided, switches to the live-rebuild path (store mutations
+     *   on every slot change, same as AG Grid's live column reorder).  When omitted, the handler
+     *   uses CSS transforms instead — smoother and without flicker.
+     * @param leavesFor       - Returns the leaf column IDs for a logical group.  Used by the
+     *   CSS-transform path so that leaf header cells AND body cells animate in sync with the
+     *   group header when the drag slot changes.
+     */
+    constructor(gridElGetter: () => HTMLElement | null, onGroupMoved: GroupMovedCallback, previewCallbacks?: GroupPreviewCallbacks | undefined, leavesFor?: ((groupId: string) => readonly string[]) | undefined);
+    /**
+     * Called from `DisplayGroupHeaderBuilder.onGroupHeaderMouseDown` for each
+     * newly built group header cell.  Wires a threshold-based drag using the
+     * `mousedown` event already delivered by the builder.
+     *
+     * @param e    - The `mousedown` event from the group header cell.
+     * @param node - The display group node this cell represents.
+     * @param el   - The DOM element of the group header cell.
+     */
+    onHeaderMouseDown(e: MouseEvent, node: DisplayGroupNode, el: HTMLElement): void;
+    /**
+     * `true` for ~200 ms after a drag completes.
+     * Used by the header builder to suppress the click event fired after mouseup.
+     */
+    get didJustDrag(): boolean;
+    /**
+     * `true` while a group header drag is currently in progress.
+     * Exposed so the store-watcher in `GridRenderer` can skip the full header
+     * destroy / rebuild cycle during live-preview group drag, preventing flicker.
+     */
+    get isDraggingGroup(): boolean;
+    /**
+     * Tear down all event listeners and remove any remaining drag DOM artifacts.
+     * Must be called when the grid is destroyed or when the header is rebuilt.
+     */
+    destroy(): void;
+    /**
+     * Activate the drag once the movement threshold is exceeded.
+     * Creates the ghost chip, drop indicator, and style element.
+     *
+     * Adds `pg-grid--group-dragging` before live preview updates begin so the
+     * renderer can suppress normal transition effects while column order is being
+     * updated repeatedly under the pointer.
+     */
+    private activateDrag;
+    private onMouseMove;
+    private onMouseUp;
+    /**
+     * Find the leaf column ID that the group should be inserted before.
+     * Inspects the leaf header row in the target panel, finding the first cell
+     * whose horizontal midpoint is to the right of the cursor.
+     *
+     * @param e           - Current cursor position.
+     * @param targetPanel - Panel the drop is over.
+     * @param gridEl      - Root `.pg-grid` element.
+     */
+    private findInsertBeforeColId;
+    /**
+     * Capture all root-level drag slots from the depth-0 group header row.
+     *
+     * Slots include both:
+     * - **Group cells** (`.pg-th--group`): represent a whole logical group.
+     * - **Flat-column filler cells** (`.pg-th--depth-filler`): represent a single
+     *   ungrouped column sitting between/around groups.  Including these as slots
+     *   lets the drag handler detect when the cursor crosses a flat-column boundary
+     *   and animate the flat column (header + body cells) out of the way in real
+     *   time — matching AG Grid's behaviour for mixed grouped/flat layouts.
+     *
+     * Cells are sorted by their `style.left` value because absolutely-positioned
+     * elements may appear in arbitrary DOM insertion order.
+     *
+     * Falls back to the leaf header row when no group rows exist (rare — only when
+     * the grid transitions from grouped to flat while a drag is in progress).
+     *
+     * @param gridEl - Root `.pg-grid` element.
+     * @param panel  - Panel to inspect.
+     */
+    private capturePanelCells;
+    /**
+     * Find the effective drop-slot index from the current cursor x position.
+     * Returns `capturedCells.length` to indicate "append at end".
+     *
+     * @param cursorX - Cursor x position in client coordinates.
+     */
+    private findEffectiveSlot;
+    /**
+     * Apply `--pg-drag-x` and `--pg-drag-transition` rules via the injected `<style>`
+     * element to give a live preview of where the dragged group will land.
+     *
+     * - The **dragged group** and all of its leaf columns snap instantly
+     *   (`--pg-drag-transition: 0ms`) so they track the slot-change in a single frame.
+     * - **Displaced groups** and their leaf columns animate smoothly with the default
+     *   transition duration (180 ms) — matching AG Grid's animated reorder behaviour.
+     * - Body cells (`pg-cell[data-col-id]`) receive the same offset as their header
+     *   counterpart, so the data rows shift in perfect sync with the header.
+     *
+     * Using the `--pg-drag-transition` CSS variable avoids specificity conflicts:
+     * the base CSS in `base-styles.ts` reads the variable and provides the default,
+     * while the per-cell override only needs to set the variable.
+     *
+     * @param effectiveIdx - Drop-slot index from {@link findEffectiveSlot}.
+     * @param gridEl       - Root `.pg-grid` element (used to scope CSS selectors).
+     */
+    private applyTransforms;
+    /**
+     * Reposition the drop-indicator line to show the insertion point.
+     *
+     * @param effectiveIdx - Slot index derived from cursor position.
+     */
+    private updateIndicator;
+    /**
+     * Position the drop-indicator line by looking up the target cell directly in
+     * the live DOM.  Used in live-preview mode where captured cell rects are stale
+     * after each header rebuild.
+     *
+     * @param colId    - The `data-col-id` of the cell to insert before, or `null`
+     *                   to place the indicator at the end of the panel.
+     * @param panel    - The panel the drop is targeting.
+     * @param gridEl   - Root `.pg-grid` element.
+     */
+    private updateIndicatorFromColId;
+    private detectPanelFromElement;
+    private detectPanelAtPoint;
+    private getPanelEl;
+    private cleanupDrag;
+}
+//# sourceMappingURL=display-group-drag-handler.d.ts.map

package/column-groups/display-group-drag-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-group-drag-handler.d.ts","sourceRoot":"","sources":["../../src/column-groups/display-group-drag-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAG9D;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,cAAc,EAAI,MAAM,EACxB,WAAW,EAAO,MAAM,GAAG,IAAI,GAAG,OAAO,EACzC,WAAW,EAAO,MAAM,GAAG,IAAI,GAAG,OAAO,EACzC,iBAAiB,EAAE,MAAM,GAAG,IAAI,KAC7B,IAAI,CAAC;AAEV;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B;;;;OAIG;IACH,aAAa,EAAE,kBAAkB,CAAC;IAClC;;;OAGG;IACH,gBAAgB,EAAE,MAAM,IAAI,CAAC;CAC9B;AAwBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,uBAAuB;IA2BhC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IA7B7B,OAAO,CAAC,YAAY,CAAU;IAC9B,OAAO,CAAC,UAAU,CAAY;IAC9B,OAAO,CAAC,WAAW,CAAsC;IACzD,OAAO,CAAC,WAAW,CAAsC;IACzD,OAAO,CAAC,OAAO,CAA2C;IAC1D,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,aAAa,CAAM;IAC3B,qFAAqF;IACrF,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,YAAY,CAA6B;IAEjD;;;;;;;;;OASG;gBAEgB,YAAY,EAAE,MAAM,WAAW,GAAG,IAAI,EACtC,YAAY,EAAE,kBAAkB,EAChC,gBAAgB,CAAC,EAAE,qBAAqB,YAAA,EACxC,SAAS,CAAC,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,aAAA;IAKrE;;;;;;;;OAQG;IACH,iBAAiB,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI;IAoC/E;;;OAGG;IACH,IAAI,WAAW,IAAI,OAAO,CAA8B;IAExD;;;;OAIG;IACH,IAAI,eAAe,IAAI,OAAO,CAA4B;IAE1D;;;OAGG;IACH,OAAO,IAAI,IAAI;IAQf;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAkCpB,OAAO,CAAC,WAAW;IA8CnB,OAAO,CAAC,SAAS;IAkCjB;;;;;;;;OAQG;IACH,OAAO,CAAC,qBAAqB;IAwB7B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,iBAAiB;IA2CzB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,eAAe;IAmEvB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IA+BvB;;;;;;;;;OASG;IACH,OAAO,CAAC,wBAAwB;IA0ChC,OAAO,CAAC,sBAAsB;IAM9B,OAAO,CAAC,kBAAkB;IAY1B,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,WAAW;CAkBpB"}