@opencorestack/opengridx 3.9.0 → 3.10.0

package/lib/components/Toolbar/FilterPanelWrapper.tsx

@@ -0,0 +1,82 @@
+import ReactDOM from 'react-dom';
+import type { GridColDef, GridFilterModel } from '../../types';
+import { FilterPanel } from '../FilterPanel/FilterPanel';
+import { useGridLocale } from '../DataGrid/gridLocaleContext';
+import { FilterIcon } from './ToolbarIcons';
+import { useToolbarPanel } from './useToolbarPanel';
+
+/** The toolbar's Filters panel: `FilterPanel` with a count, Clear all and Close. */
+export function FilterPanelWrapper({
+    anchorRef,
+    columns,
+    filterModel,
+    onFilterModelChange,
+    onClose
+}: {
+    anchorRef: React.RefObject<HTMLElement | null>;
+    columns: GridColDef[];
+    filterModel: GridFilterModel;
+    onFilterModelChange: (model: GridFilterModel) => void;
+    onClose: () => void;
+}) {
+    const locale = useGridLocale();
+    // Escape closes it; a press outside does not: users type in its inputs, and it has a Close button.
+    const { panelRef, position: pos, portalContainer } = useToolbarPanel(anchorRef, onClose, { closeOnOutsideClick: false });
+
+    const activeFilterCount = filterModel.items?.length ?? 0;
+
+    const handleClearAll = () => {
+        onFilterModelChange({ ...filterModel, items: [], logicOperator: 'and' });
+    };
+
+    const panel = (
+        <div
+            ref={panelRef}
+            className="ogx-toolbar__panel ogx-toolbar__panel--filter"
+            role="dialog"
+            aria-label={locale.toolbarFiltersLabel}
+            style={{ top: pos.top, right: pos.right, left: pos.left, width: 540, maxWidth: 'calc(100vw - 24px)' }}
+        >
+            <div className="ogx-toolbar__panel-header">
+                <span className="ogx-toolbar__panel-title">
+                    <FilterIcon />
+                    {locale.toolbarFilters}
+                    {activeFilterCount > 0 && (
+                        <span className="ogx-toolbar__panel-count">{activeFilterCount}</span>
+                    )}
+                </span>
+                <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+                    {activeFilterCount > 0 && (
+                        <button
+                            type="button"
+                            className="ogx-toolbar__clear-btn"
+                            onClick={handleClearAll}
+                            title={locale.toolbarFiltersClearAllTooltip}
+                        >
+                            {locale.toolbarFiltersClearAll}
+                        </button>
+                    )}
+                    <button
+                        type="button"
+                        className="ogx-toolbar__close-btn"
+                        onClick={onClose}
+                        title={locale.toolbarFiltersCloseTooltip}
+                        aria-label={locale.toolbarFiltersCloseLabel}
+                    >
+                        {locale.toolbarFiltersClose}
+                    </button>
+                </div>
+            </div>
+
+            <div className="ogx-toolbar__panel-body ogx-toolbar__panel-body--filter">
+                <FilterPanel
+                    columns={columns}
+                    filterModel={filterModel}
+                    onFilterModelChange={onFilterModelChange}
+                />
+            </div>
+        </div>
+    );
+
+    return portalContainer ? ReactDOM.createPortal(panel, portalContainer) : null;
+}

package/lib/components/Toolbar/GridToolbar.tsx

@@ -1,18 +1,16 @@
-import React, { useState, useRef, useEffect, useCallback, useLayoutEffect, useContext } from 'react';
-import ReactDOM from 'react-dom';
+import React, { useState, useRef, useEffect, useCallback, useContext } from 'react';
 import type { GridColDef, GridAggregationModel, GridPivotModel, GridFilterModel } from '../../types';
-import { AGGREGATION_FUNCTIONS } from '../../utils/aggregation';
-import type { BuiltInAggFn } from '../../utils/aggregation';
-import { getViewportWidth } from '../../utils/viewport';
-import { getPanelPosition, type GridPanelPosition } from '../../utils/direction';
+import { getOfferedAggregationFunctions } from '../../utils/aggregation';
 import { GridToolbarHostContext } from '../../hooks/core/gridToolbarHostContext';
 import { PivotPanel, PivotIcon } from './PivotPanel';
 import { GlobalSearch } from './GlobalSearch';
-import { ColumnVisibilityPanel } from '../ColumnVisibilityPanel/ColumnVisibilityPanel';
-import { FilterPanel } from '../FilterPanel/FilterPanel';
 import { GridTooltip } from '../Tooltip/Tooltip';
 import { AiSparkleIcon } from '../AiAssistant/GridAiAssistantPanel';
 import { useGridLocale } from '../DataGrid/gridLocaleContext';
+import { SigmaIcon, ViewColumnIcon, FilterIcon } from './ToolbarIcons';
+import { AggregationPanel } from './AggregationPanel';
+import { ColumnsPanelWrapper } from './ColumnsPanelWrapper';
+import { FilterPanelWrapper } from './FilterPanelWrapper';
 
 /** Props passed to a custom toolbar button renderer. */
 export interface ToolbarButtonRenderProps {
@@ -99,379 +97,8 @@ export interface GridToolbarProps {
     aiAssistantLabel?: string;
 }
 
-const BUILT_IN_AGGREGATION_FUNCTIONS = Object.keys(AGGREGATION_FUNCTIONS) as BuiltInAggFn[];
-
-function isBuiltInAggregationFunction(fn: string): fn is BuiltInAggFn {
-    return Object.prototype.hasOwnProperty.call(AGGREGATION_FUNCTIONS, fn);
-}
-
-/**
- * The summary functions offered for a column: its `availableAggregationFunctions` when set,
- * otherwise every built-in one. Names the aggregation engine does not implement are dropped,
- * because choosing one would show the label in the header but never compute a value.
- */
-function getAggregationFunctions(col: GridColDef): BuiltInAggFn[] {
-    if (!col.availableAggregationFunctions) return BUILT_IN_AGGREGATION_FUNCTIONS;
-    return Array.from(new Set(col.availableAggregationFunctions.filter(isBuiltInAggregationFunction)));
-}
-
 type ToolbarPanel = 'summaries' | 'pivot' | 'columns' | 'filters';
 
-function SigmaIcon() {
-    return (
-        <svg
-            width="18" height="18" viewBox="0 0 24 24"
-            fill="none" stroke="currentColor" strokeWidth="2"
-            strokeLinecap="round" strokeLinejoin="round"
-            aria-hidden="true"
-        >
-            <path d="M18 4H6l6 8-6 8h12" />
-        </svg>
-    );
-}
-
-function ViewColumnIcon() {
-    return (
-        <svg focusable="false" aria-hidden="true" viewBox="0 0 24 24" width="18" height="18" fill="none">
-            <rect x="2" y="4" width="20" height="16" rx="2" stroke="currentColor" strokeWidth="1.8" />
-            <rect x="8.5" y="4" width="7" height="16" fill="currentColor" opacity="0.25" />
-            <line x1="8.5" y1="4" x2="8.5" y2="20" stroke="currentColor" strokeWidth="1.8" />
-            <line x1="15.5" y1="4" x2="15.5" y2="20" stroke="currentColor" strokeWidth="1.8" />
-            <line x1="2" y1="9" x2="22" y2="9" stroke="currentColor" strokeWidth="1.2" />
-            <line x1="2" y1="14" x2="22" y2="14" stroke="currentColor" strokeWidth="1.2" />
-        </svg>
-    );
-}
-
-function FilterIcon() {
-    return (
-        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-            <polygon points="22 3 2 3 10 12.46 10 19 14 21 14 12.46 22 3" />
-        </svg>
-    );
-}
-
-type PanelPosition = GridPanelPosition;
-
-function AggregationPanel({
-    anchorRef,
-    aggregationModel,
-    aggregableColumns,
-    onFunctionChange,
-    onClearAll,
-    onClose,
-    activeCount,
-}: {
-    anchorRef: React.RefObject<HTMLElement | null>;
-    aggregationModel: GridAggregationModel;
-    aggregableColumns: GridColDef[];
-    onFunctionChange: (field: string, fn: string) => void;
-    onClearAll: () => void;
-    onClose: () => void;
-    activeCount: number;
-}) {
-    const locale = useGridLocale();
-    const panelRef = useRef<HTMLDivElement>(null);
-    const [pos, setPos] = useState<PanelPosition>({ top: 0, right: 0 });
-    const [portalContainer, setPortalContainer] = useState<Element | null>(null);
-
-    useLayoutEffect(() => {
-        setPortalContainer(anchorRef.current?.closest('.ogx-theme-provider') ?? document.body);
-    }, [anchorRef]);
-
-    const computePos = useCallback((): PanelPosition => getPanelPosition(anchorRef.current, getViewportWidth()), [anchorRef]);
-
-    useEffect(() => {
-        setPos(computePos());
-        const update = () => setPos(computePos());
-        window.addEventListener('scroll', update, true);
-        window.addEventListener('resize', update);
-        return () => {
-            window.removeEventListener('scroll', update, true);
-            window.removeEventListener('resize', update);
-        };
-    }, [computePos]);
-
-    useEffect(() => {
-        function handleClick(e: MouseEvent) {
-            if (
-                panelRef.current && !panelRef.current.contains(e.target as Node) &&
-                anchorRef.current && !anchorRef.current.contains(e.target as Node)
-            ) {
-                onClose();
-            }
-        }
-        document.addEventListener('mousedown', handleClick);
-        return () => document.removeEventListener('mousedown', handleClick);
-    }, [anchorRef, onClose]);
-
-    useEffect(() => {
-        function onKey(e: KeyboardEvent) { if (e.key === 'Escape') onClose(); }
-        document.addEventListener('keydown', onKey);
-        return () => document.removeEventListener('keydown', onKey);
-    }, [onClose]);
-
-    const panel = (
-        <div
-            ref={panelRef}
-            className="ogx-toolbar__panel"
-            role="dialog"
-            aria-label={locale.toolbarSummariesPanelLabel}
-            style={{ top: pos.top, right: pos.right, left: pos.left, width: 400, maxWidth: 'calc(100vw - 24px)' }}
-        >
-            <div className="ogx-toolbar__panel-header">
-                <span className="ogx-toolbar__panel-title">
-                    <SigmaIcon />
-                    {locale.toolbarSummaries}
-                </span>
-                {activeCount > 0 && (
-                    <button
-                        type="button"
-                        className="ogx-toolbar__clear-btn"
-                        onClick={onClearAll}
-                        title={locale.toolbarSummariesClearAllTooltip}
-                    >
-                        {locale.toolbarSummariesClearAll}
-                    </button>
-                )}
-            </div>
-
-            <div className="ogx-toolbar__panel-body">
-                {aggregableColumns.length === 0 ? (
-                    <p className="ogx-toolbar__empty">
-                        {locale.toolbarSummariesEmpty}<br />
-                        {`${locale.toolbarSummariesEmptyHintBefore} `}<code>aggregable: true</code>{` ${locale.toolbarSummariesEmptyHintAfter}`}
-                    </p>
-                ) : (
-                    aggregableColumns.map((col) => {
-                        const currentFn = aggregationModel[col.field] || 'none';
-                        return (
-                            <div key={col.field} className="ogx-toolbar__agg-row">
-                                <span className="ogx-toolbar__agg-label" title={col.field}>
-                                    {col.headerName || col.field}
-                                </span>
-                                <div className="ogx-toolbar__agg-pills">
-                                    {['none', ...getAggregationFunctions(col)].map((fn) => (
-                                        <button
-                                            type="button"
-                                            key={fn}
-                                            className={`ogx-toolbar__pill${currentFn === fn ? ' ogx-toolbar__pill--active' : ''}`}
-                                            onClick={() => onFunctionChange(col.field, fn)}
-                                            aria-pressed={currentFn === fn}
-                                        >
-                                            {locale.toolbarAggregationFunction(fn)}
-                                        </button>
-                                    ))}
-                                </div>
-                            </div>
-                        );
-                    })
-                )}
-            </div>
-        </div>
-    );
-
-    return portalContainer ? ReactDOM.createPortal(panel, portalContainer) : null;
-}
-
-function ColumnsPanelWrapper({
-    anchorRef,
-    columns,
-    visibleColumns,
-    onVisibilityChange,
-    onShowAll,
-    onHideAll,
-    onColumnReorder,
-    onColumnOrderReset,
-    onClose,
-    showNonHideableColumns,
-}: {
-    anchorRef: React.RefObject<HTMLElement | null>;
-    columns: GridColDef[];
-    visibleColumns: Set<string>;
-    onVisibilityChange: (field: string, isVisible: boolean) => void;
-    onShowAll: () => void;
-    onHideAll: () => void;
-    onColumnReorder?: (fromField: string, toField: string) => void;
-    onColumnOrderReset?: () => void;
-    onClose: () => void;
-    showNonHideableColumns?: boolean;
-}) {
-    const locale = useGridLocale();
-    const panelRef = useRef<HTMLDivElement>(null);
-    const [pos, setPos] = useState<PanelPosition>({ top: 0, right: 0 });
-    const [portalContainer, setPortalContainer] = useState<Element | null>(null);
-
-    useLayoutEffect(() => {
-        setPortalContainer(anchorRef.current?.closest('.ogx-theme-provider') ?? document.body);
-    }, [anchorRef]);
-
-    const computePos = useCallback((): PanelPosition => getPanelPosition(anchorRef.current, getViewportWidth()), [anchorRef]);
-
-    useEffect(() => {
-        setPos(computePos());
-        const update = () => setPos(computePos());
-        window.addEventListener('scroll', update, true);
-        window.addEventListener('resize', update);
-        return () => {
-            window.removeEventListener('scroll', update, true);
-            window.removeEventListener('resize', update);
-        };
-    }, [computePos]);
-
-    useEffect(() => {
-        function handleClick(e: MouseEvent) {
-            if (
-                panelRef.current && !panelRef.current.contains(e.target as Node) &&
-                anchorRef.current && !anchorRef.current.contains(e.target as Node)
-            ) {
-                onClose();
-            }
-        }
-        document.addEventListener('mousedown', handleClick);
-        return () => document.removeEventListener('mousedown', handleClick);
-    }, [anchorRef, onClose]);
-
-    useEffect(() => {
-        function onKey(e: KeyboardEvent) { if (e.key === 'Escape') onClose(); }
-        document.addEventListener('keydown', onKey);
-        return () => document.removeEventListener('keydown', onKey);
-    }, [onClose]);
-
-    const panel = (
-        <div
-            ref={panelRef}
-            className="ogx-toolbar__panel"
-            role="dialog"
-            aria-label={locale.toolbarColumnsPanelLabel}
-            style={{ top: pos.top, right: pos.right, left: pos.left, width: 280, padding: 0 }}
-        >
-            <ColumnVisibilityPanel
-                columns={columns}
-                visibleColumns={visibleColumns}
-                onVisibilityChange={onVisibilityChange}
-                onShowAll={onShowAll}
-                onHideAll={onHideAll}
-                onColumnReorder={onColumnReorder}
-                onColumnOrderReset={onColumnOrderReset}
-                showNonHideableColumns={showNonHideableColumns}
-            />
-        </div>
-    );
-
-    return portalContainer ? ReactDOM.createPortal(panel, portalContainer) : null;
-}
-
-function FilterPanelWrapper({
-    anchorRef,
-    columns,
-    filterModel,
-    onFilterModelChange,
-    onClose
-}: {
-    anchorRef: React.RefObject<HTMLElement | null>;
-    columns: GridColDef[];
-    filterModel: GridFilterModel;
-    onFilterModelChange: (model: GridFilterModel) => void;
-    onClose: () => void;
-}) {
-    const locale = useGridLocale();
-    const panelRef = useRef<HTMLDivElement>(null);
-    const [pos, setPos] = useState<PanelPosition>({ top: 0, right: 0 });
-    // Stable ref for onClose — prevents the mousedown effect from
-    // tearing down and re-registering on every filterModel update,
-    // which could fire the close callback during the re-register window.
-    const onCloseRef = useRef(onClose);
-    useLayoutEffect(() => { onCloseRef.current = onClose; }, [onClose]);
-    const [portalContainer, setPortalContainer] = useState<Element | null>(null);
-
-    useLayoutEffect(() => {
-        setPortalContainer(anchorRef.current?.closest('.ogx-theme-provider') ?? document.body);
-    }, [anchorRef]);
-
-    const computePos = useCallback((): PanelPosition => getPanelPosition(anchorRef.current, getViewportWidth()), [anchorRef]);
-
-    useEffect(() => {
-        setPos(computePos());
-        const update = () => setPos(computePos());
-        window.addEventListener('scroll', update, true);
-        window.addEventListener('resize', update);
-        return () => {
-            window.removeEventListener('scroll', update, true);
-            window.removeEventListener('resize', update);
-        };
-    }, [computePos]);
-
-    // Only Escape key closes the filter panel automatically.
-    // Click-outside is intentionally removed: users need to type in filter
-    // inputs without the panel closing. There is an explicit Close button.
-    useEffect(() => {
-        function handleKey(e: KeyboardEvent) {
-            if (e.key === 'Escape') onCloseRef.current();
-        }
-        document.addEventListener('keydown', handleKey);
-        return () => document.removeEventListener('keydown', handleKey);
-    // Empty deps — listener is registered once and uses the stable ref
-    }, []);
-
-    const activeFilterCount = filterModel.items?.length ?? 0;
-
-    const handleClearAll = () => {
-        onFilterModelChange({ ...filterModel, items: [], logicOperator: 'and' });
-    };
-
-    const panel = (
-        <div
-            ref={panelRef}
-            className="ogx-toolbar__panel ogx-toolbar__panel--filter"
-            role="dialog"
-            aria-label={locale.toolbarFiltersLabel}
-            style={{ top: pos.top, right: pos.right, left: pos.left, width: 540, maxWidth: 'calc(100vw - 24px)' }}
-        >
-            <div className="ogx-toolbar__panel-header">
-                <span className="ogx-toolbar__panel-title">
-                    <FilterIcon />
-                    {locale.toolbarFilters}
-                    {activeFilterCount > 0 && (
-                        <span className="ogx-toolbar__panel-count">{activeFilterCount}</span>
-                    )}
-                </span>
-                <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
-                    {activeFilterCount > 0 && (
-                        <button
-                            type="button"
-                            className="ogx-toolbar__clear-btn"
-                            onClick={handleClearAll}
-                            title={locale.toolbarFiltersClearAllTooltip}
-                        >
-                            {locale.toolbarFiltersClearAll}
-                        </button>
-                    )}
-                    <button
-                        type="button"
-                        className="ogx-toolbar__close-btn"
-                        onClick={() => onCloseRef.current()}
-                        title={locale.toolbarFiltersCloseTooltip}
-                        aria-label={locale.toolbarFiltersCloseLabel}
-                    >
-                        {locale.toolbarFiltersClose}
-                    </button>
-                </div>
-            </div>
-
-            <div className="ogx-toolbar__panel-body ogx-toolbar__panel-body--filter">
-                <FilterPanel
-                    columns={columns}
-                    filterModel={filterModel}
-                    onFilterModelChange={onFilterModelChange}
-                />
-            </div>
-        </div>
-    );
-
-    return portalContainer ? ReactDOM.createPortal(panel, portalContainer) : null;
-}
-
 const EMPTY_PIVOT: GridPivotModel = { rowFields: [], columnFields: [], valueFields: [] };
 // Module-level default, so `columns` is the same frozen value on every render (React Compiler).
 const NO_COLUMNS: GridColDef[] = [];
@@ -576,7 +203,7 @@ export function GridToolbar({
     const baseFields = baseColumns ? new Set(baseColumns.map((c) => c.field)) : null;
     const aggregableColumns = columns.filter(
         (c) => c.aggregable !== false && (c.type === 'number' || c.aggregable === true)
-            && getAggregationFunctions(c).length > 0
+            && getOfferedAggregationFunctions(c).length > 0
             && (!baseFields || baseFields.has(c.field))
     );
 

package/lib/components/Toolbar/ToolbarIcons.tsx

@@ -0,0 +1,35 @@
+// Icons of the toolbar buttons and panel titles.
+
+export function SigmaIcon() {
+    return (
+        <svg
+            width="18" height="18" viewBox="0 0 24 24"
+            fill="none" stroke="currentColor" strokeWidth="2"
+            strokeLinecap="round" strokeLinejoin="round"
+            aria-hidden="true"
+        >
+            <path d="M18 4H6l6 8-6 8h12" />
+        </svg>
+    );
+}
+
+export function ViewColumnIcon() {
+    return (
+        <svg focusable="false" aria-hidden="true" viewBox="0 0 24 24" width="18" height="18" fill="none">
+            <rect x="2" y="4" width="20" height="16" rx="2" stroke="currentColor" strokeWidth="1.8" />
+            <rect x="8.5" y="4" width="7" height="16" fill="currentColor" opacity="0.25" />
+            <line x1="8.5" y1="4" x2="8.5" y2="20" stroke="currentColor" strokeWidth="1.8" />
+            <line x1="15.5" y1="4" x2="15.5" y2="20" stroke="currentColor" strokeWidth="1.8" />
+            <line x1="2" y1="9" x2="22" y2="9" stroke="currentColor" strokeWidth="1.2" />
+            <line x1="2" y1="14" x2="22" y2="14" stroke="currentColor" strokeWidth="1.2" />
+        </svg>
+    );
+}
+
+export function FilterIcon() {
+    return (
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <polygon points="22 3 2 3 10 12.46 10 19 14 21 14 12.46 22 3" />
+        </svg>
+    );
+}

package/lib/components/Toolbar/useToolbarPanel.ts

@@ -0,0 +1,71 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { getViewportWidth } from '../../utils/viewport';
+import { getPanelPosition, type GridPanelPosition } from '../../utils/direction';
+
+export interface UseToolbarPanelOptions {
+    /** Close when the user presses the mouse outside the panel and its button. Default: true. */
+    closeOnOutsideClick?: boolean;
+}
+
+export interface UseToolbarPanelResult {
+    panelRef: React.RefObject<HTMLDivElement | null>;
+    /** Where to place the panel: under its button, kept on screen (`getPanelPosition`). */
+    position: GridPanelPosition;
+    /** The element to portal into: the enclosing theme provider (so its tokens apply), else `document.body`. */
+    portalContainer: Element | null;
+}
+
+/**
+ * What every toolbar panel needs: a portal target, a position under its button that follows page
+ * scroll and resize, and closing on Escape (and, by default, on a press outside it). `onClose` is
+ * read through a ref, so the listeners are registered once and a re-render never leaves a window in
+ * which a close could be lost or fired twice.
+ */
+export function useToolbarPanel(
+    anchorRef: React.RefObject<HTMLElement | null>,
+    onClose: () => void,
+    { closeOnOutsideClick = true }: UseToolbarPanelOptions = {},
+): UseToolbarPanelResult {
+    const panelRef = useRef<HTMLDivElement>(null);
+    const [position, setPosition] = useState<GridPanelPosition>({ top: 0, right: 0 });
+    const [portalContainer, setPortalContainer] = useState<Element | null>(null);
+    const onCloseRef = useRef(onClose);
+    useLayoutEffect(() => { onCloseRef.current = onClose; });
+
+    useLayoutEffect(() => {
+        setPortalContainer(anchorRef.current?.closest('.ogx-theme-provider') ?? document.body);
+    }, [anchorRef]);
+
+    const computePosition = useCallback(() => getPanelPosition(anchorRef.current, getViewportWidth()), [anchorRef]);
+
+    useEffect(() => {
+        setPosition(computePosition());
+        const update = () => setPosition(computePosition());
+        window.addEventListener('scroll', update, true);
+        window.addEventListener('resize', update);
+        return () => {
+            window.removeEventListener('scroll', update, true);
+            window.removeEventListener('resize', update);
+        };
+    }, [computePosition]);
+
+    useEffect(() => {
+        if (!closeOnOutsideClick) return undefined;
+        function handleMouseDown(e: MouseEvent) {
+            const target = e.target as Node;
+            if (panelRef.current && !panelRef.current.contains(target) && anchorRef.current && !anchorRef.current.contains(target)) {
+                onCloseRef.current();
+            }
+        }
+        document.addEventListener('mousedown', handleMouseDown);
+        return () => document.removeEventListener('mousedown', handleMouseDown);
+    }, [anchorRef, closeOnOutsideClick]);
+
+    useEffect(() => {
+        function handleKey(e: KeyboardEvent) { if (e.key === 'Escape') onCloseRef.current(); }
+        document.addEventListener('keydown', handleKey);
+        return () => document.removeEventListener('keydown', handleKey);
+    }, []);
+
+    return { panelRef, position, portalContainer };
+}