@cccsaurora/howler-ui 2.18.0-dev.739 → 2.18.0-dev.748

package/components/app/providers/{HitSearchProvider.test.js → RecordSearchProvider.test.js}

@@ -5,9 +5,9 @@ import { cloneDeep } from 'lodash-es';
 import { setupContextSelectorMock, setupLocalStorageMock } from '@cccsaurora/howler-ui/tests/mocks';
 import { useContextSelector } from 'use-context-selector';
 import { DEFAULT_QUERY, MY_LOCAL_STORAGE_PREFIX, StorageKey } from '@cccsaurora/howler-ui/utils/constants';
-import { HitContext } from './HitProvider';
-import HitSearchProvider, { HitSearchContext } from './HitSearchProvider';
 import { ParameterContext } from './ParameterProvider';
+import { RecordContext } from './RecordProvider';
+import RecordSearchProvider, { RecordSearchContext } from './RecordSearchProvider';
 import { ViewContext } from './ViewProvider';
 vi.mock('api', { spy: true });
 setupContextSelectorMock();
@@ -30,20 +30,21 @@ let mockParameterContext = {
         mockParameterContext.offset = parseInt(offset);
     },
     views: [],
+    indexes: ['hit'],
     addView: vi.fn()
 };
 const originalMockParameterContext = cloneDeep(mockParameterContext);
 const mockHitContext = {
-    hits: {},
-    loadHits: hits => {
-        mockHitContext.hits = {
-            ...mockHitContext.hits,
+    records: {},
+    loadRecords: hits => {
+        mockHitContext.records = {
+            ...mockHitContext.records,
             ...Object.fromEntries(hits.map(hit => [hit.howler.id, hit]))
         };
     }
 };
 const Wrapper = ({ children }) => {
-    return (_jsx(ViewContext.Provider, { value: mockViewContext, children: _jsx(ParameterContext.Provider, { value: mockParameterContext, children: _jsx(HitContext.Provider, { value: mockHitContext, children: _jsx(HitSearchProvider, { children: children }) }) }) }));
+    return (_jsx(ViewContext.Provider, { value: mockViewContext, children: _jsx(ParameterContext.Provider, { value: mockParameterContext, children: _jsx(RecordContext.Provider, { value: mockHitContext, children: _jsx(RecordSearchProvider, { children: children }) }) }) }));
 };
 beforeEach(() => {
     mockParameterContext = cloneDeep(originalMockParameterContext);
@@ -57,38 +58,32 @@ beforeEach(() => {
     let mockSearchParams = new URLSearchParams();
     vi.mocked(useSearchParams).mockReturnValue([mockSearchParams, mockSetParams]);
 });
-describe('HitSearchContext', () => {
+describe('RecordSearchContext', () => {
     it('should initialize with default values', async () => {
-        const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ({
+        const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ({
             displayType: ctx.displayType,
             searching: ctx.searching,
             error: ctx.error,
             response: ctx.response,
-            bundleId: ctx.bundleId,
             fzfSearch: ctx.fzfSearch
         })), { wrapper: Wrapper });
         expect(hook.result.current.displayType).toBe('list');
         expect(hook.result.current.searching).toBe(false);
         expect(hook.result.current.error).toBeNull();
         expect(hook.result.current.response).toBeNull();
-        expect(hook.result.current.bundleId).toBeNull();
         expect(hook.result.current.fzfSearch).toBe(false);
     });
-    it('should set bundleId when on bundles route', () => {
-        mockLocation.pathname = '/bundles/test_bundle_id';
-        mockParams.mockReturnValue({ id: 'test_bundle_id' });
-        const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.bundleId), { wrapper: Wrapper });
-        expect(hook.result.current).toBe('test_bundle_id');
-    });
     it('should initialize queryHistory from localStorage', () => {
         const mockHistory = { 'test:query': new Date().toISOString() };
         mockLocalStorage.setItem(`${MY_LOCAL_STORAGE_PREFIX}.${StorageKey.QUERY_HISTORY}`, JSON.stringify(mockHistory));
-        const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.queryHistory), { wrapper: Wrapper });
+        const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ctx.queryHistory), {
+            wrapper: Wrapper
+        });
         expect(hook.result.current).toEqual(mockHistory);
     });
     describe('setDisplayType', () => {
         it('should update display type', () => {
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ({
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ({
                 displayType: ctx.displayType,
                 setDisplayType: ctx.setDisplayType
             })), { wrapper: Wrapper });
@@ -101,7 +96,7 @@ describe('HitSearchContext', () => {
     });
     describe('setFzfSearch', () => {
         it('should update fzfSearch state', () => {
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ({
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ({
                 fzfSearch: ctx.fzfSearch,
                 setFzfSearch: ctx.setFzfSearch
             })), { wrapper: Wrapper });
@@ -114,7 +109,7 @@ describe('HitSearchContext', () => {
     });
     describe('setQueryHistory', () => {
         it('should update query history', () => {
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ({
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ({
                 queryHistory: ctx.queryHistory,
                 setQueryHistory: ctx.setQueryHistory
             })), { wrapper: Wrapper });
@@ -127,7 +122,7 @@ describe('HitSearchContext', () => {
     });
     describe('search', () => {
         it('should perform a search and update response', async () => {
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ({
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ({
                 search: ctx.search,
                 searching: ctx.searching,
                 response: ctx.response,
@@ -137,13 +132,13 @@ describe('HitSearchContext', () => {
                 hook.result.current.search('test query');
             });
             await waitFor(() => {
-                expect(hpost).toHaveBeenCalledWith('/api/v1/search/hit', expect.objectContaining({
+                expect(hpost).toHaveBeenCalledWith('/api/v2/search/hit', expect.objectContaining({
                     query: expect.stringContaining('test query')
                 }));
             });
         });
         it('should set searching state during search', async () => {
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ({
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ({
                 search: ctx.search,
                 searching: ctx.searching
             })), { wrapper: Wrapper });
@@ -172,7 +167,7 @@ describe('HitSearchContext', () => {
         });
         it('should handle search errors', async () => {
             vi.mocked(hpost).mockRejectedValueOnce(new Error('Search failed'));
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ({
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ({
                 search: ctx.search,
                 error: ctx.error,
                 searching: ctx.searching
@@ -193,7 +188,7 @@ describe('HitSearchContext', () => {
                 total: 10
             };
             vi.mocked(hpost).mockResolvedValueOnce(mockResponse);
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ({
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ({
                 search: ctx.search,
                 response: ctx.response
             })), { wrapper: Wrapper });
@@ -221,27 +216,35 @@ describe('HitSearchContext', () => {
                 expect(hook.result.current.response?.items.length).toBe(2);
             });
         });
-        it('should include bundle filter when on bundles route', async () => {
-            mockLocation.pathname = '/bundles/test_bundle_id';
-            mockParams.mockReturnValue({ id: 'test_bundle_id' });
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.search), { wrapper: Wrapper });
+        it('should not crash when appendResults is true but response is null', async () => {
+            const mockResponse = {
+                items: [{ howler: { id: 'hit1' } }],
+                offset: 0,
+                rows: 1,
+                total: 10
+            };
+            vi.mocked(hpost).mockResolvedValueOnce(mockResponse);
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ({
+                search: ctx.search,
+                response: ctx.response
+            })), { wrapper: Wrapper });
+            // response is null — call search with appendResults=true directly
             act(() => {
-                hook.result.current('test query');
+                hook.result.current.search('test query', true);
             });
             await waitFor(() => {
-                expect(hpost).toHaveBeenCalledWith('/api/v1/search/hit', expect.objectContaining({
-                    query: 'test query',
-                    filters: ['event.created:[now-1w TO now]', 'howler.bundles:test_bundle_id']
-                }));
+                expect(hook.result.current.response).not.toBeNull();
+                expect(hook.result.current.response?.items).toHaveLength(1);
+                expect(hook.result.current.response?.items[0].howler.id).toBe('hit1');
             });
         });
         it('should apply date range filter from span', async () => {
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.search), { wrapper: Wrapper });
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ctx.search), { wrapper: Wrapper });
             act(() => {
                 hook.result.current('test query');
             });
             await waitFor(() => {
-                expect(hpost).toHaveBeenCalledWith('/api/v1/search/hit', expect.objectContaining({
+                expect(hpost).toHaveBeenCalledWith('/api/v2/search/hit', expect.objectContaining({
                     filters: expect.arrayContaining([expect.stringContaining('event.created:')])
                 }));
             });
@@ -250,24 +253,24 @@ describe('HitSearchContext', () => {
             mockParameterContext.span = 'date.range.custom';
             mockParameterContext.startDate = '2025-01-01';
             mockParameterContext.endDate = '2025-12-31';
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.search), { wrapper: Wrapper });
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ctx.search), { wrapper: Wrapper });
             act(() => {
                 hook.result.current('test query');
             });
             await waitFor(() => {
-                expect(hpost).toHaveBeenCalledWith('/api/v1/search/hit', expect.objectContaining({
+                expect(hpost).toHaveBeenCalledWith('/api/v2/search/hit', expect.objectContaining({
                     filters: expect.arrayContaining([expect.stringContaining('event.created:')])
                 }));
             });
         });
         it('should exclude filters ending with * from search', async () => {
             mockParameterContext.filters = ['status:open', 'howler.escalation:*'];
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.search), { wrapper: Wrapper });
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ctx.search), { wrapper: Wrapper });
             act(() => {
                 hook.result.current('test query');
             });
             await waitFor(() => {
-                expect(hpost).toHaveBeenCalledWith('/api/v1/search/hit', expect.objectContaining({
+                expect(hpost).toHaveBeenCalledWith('/api/v2/search/hit', expect.objectContaining({
                     filters: expect.not.arrayContaining([expect.stringContaining('howler.escalation:*')])
                 }));
             });
@@ -280,7 +283,7 @@ describe('HitSearchContext', () => {
                 rows: 0,
                 total: 50
             });
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ({
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ({
                 search: ctx.search
             })), { wrapper: Wrapper });
             act(() => {
@@ -294,7 +297,7 @@ describe('HitSearchContext', () => {
         it('should not search when sort or span is null', async () => {
             mockParameterContext.sort = null;
             mockParameterContext.span = null;
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.search), { wrapper: Wrapper });
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ctx.search), { wrapper: Wrapper });
             act(() => {
                 hook.result.current('test query');
             });
@@ -306,7 +309,7 @@ describe('HitSearchContext', () => {
     });
     describe('automatic search on parameter changes', () => {
         it('should trigger search when filters change', async () => {
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ({
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ({
                 response: ctx.response
             })), { wrapper: Wrapper });
             await waitFor(() => {
@@ -320,23 +323,23 @@ describe('HitSearchContext', () => {
                 expect(hpost).toHaveBeenCalled();
             }, { timeout: 2000 });
         });
-        it('should not trigger search when query is DEFAULT_QUERY and no bundleId', async () => {
+        it('should not trigger search when query is DEFAULT_QUERY', async () => {
             mockParameterContext.query = DEFAULT_QUERY;
-            renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.response), { wrapper: Wrapper });
+            renderHook(() => useContextSelector(RecordSearchContext, ctx => ctx.response), { wrapper: Wrapper });
             await waitFor(() => {
                 expect(hpost).not.toHaveBeenCalled();
             });
         });
         it('should not trigger search when span is custom but dates are missing', async () => {
-            renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.response), { wrapper: Wrapper });
+            renderHook(() => useContextSelector(RecordSearchContext, ctx => ctx.response), { wrapper: Wrapper });
             await waitFor(() => {
                 expect(hpost).not.toHaveBeenCalled();
             });
         });
     });
-    describe('useHitSearchContextSelector', () => {
+    describe('useRecordSearchContextSelector', () => {
         it('should allow selecting specific values from context', async () => {
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ({
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ({
                 searching: ctx.searching,
                 error: ctx.error
             })), { wrapper: Wrapper });
@@ -346,7 +349,7 @@ describe('HitSearchContext', () => {
     });
     describe('edge cases', () => {
         it('should handle concurrent search calls with throttling', async () => {
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.search), { wrapper: Wrapper });
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ctx.search), { wrapper: Wrapper });
             // Make multiple rapid calls
             act(() => {
                 hook.result.current('query1');
@@ -358,8 +361,8 @@ describe('HitSearchContext', () => {
                 expect(hpost).toHaveBeenCalledTimes(1);
             }, { timeout: 2000 });
         });
-        it('should clear response when query becomes DEFAULT_QUERY without viewId or bundleId', async () => {
-            const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.response), { wrapper: Wrapper });
+        it('should clear response when query becomes DEFAULT_QUERY without viewId', async () => {
+            const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ctx.response), { wrapper: Wrapper });
             await waitFor(() => {
                 expect(hook.result.current).toBeDefined();
             }, { timeout: 2000 });
@@ -379,12 +382,12 @@ describe('HitSearchContext', () => {
                     { view_id: 'view_1', query: 'howler.status:open' },
                     { view_id: 'view_2', query: 'howler.priority:high' }
                 ]);
-                const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.search), { wrapper: Wrapper });
+                const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ctx.search), { wrapper: Wrapper });
                 act(() => {
                     hook.result.current('test query');
                 });
                 await waitFor(() => {
-                    expect(hpost).toHaveBeenCalledWith('/api/v1/search/hit', expect.objectContaining({
+                    expect(hpost).toHaveBeenCalledWith('/api/v2/search/hit', expect.objectContaining({
                         query: 'test query',
                         filters: expect.arrayContaining(['howler.status:open', 'howler.priority:high'])
                     }));
@@ -397,12 +400,12 @@ describe('HitSearchContext', () => {
                     { view_id: 'view_2', query: 'howler.priority:high' },
                     { view_id: 'view_3', query: 'howler.analytic:sigma' }
                 ]);
-                const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.search), { wrapper: Wrapper });
+                const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ctx.search), { wrapper: Wrapper });
                 act(() => {
                     hook.result.current('test query');
                 });
                 await waitFor(() => {
-                    expect(hpost).toHaveBeenCalledWith('/api/v1/search/hit', expect.objectContaining({
+                    expect(hpost).toHaveBeenCalledWith('/api/v2/search/hit', expect.objectContaining({
                         query: 'test query',
                         filters: [
                             'event.created:[now-1w TO now]',
@@ -421,7 +424,7 @@ describe('HitSearchContext', () => {
                 mockParameterContext.views = [];
                 const mockSearchParams = new URLSearchParams();
                 vi.mocked(useSearchParams).mockReturnValue([mockSearchParams, mockSetParams]);
-                renderHook(() => useContextSelector(HitSearchContext, () => { }), { wrapper: Wrapper });
+                renderHook(() => useContextSelector(RecordSearchContext, () => { }), { wrapper: Wrapper });
                 await waitFor(() => {
                     expect(mockParameterContext.addView).toBeCalledWith('default_view_id');
                 });
@@ -433,7 +436,7 @@ describe('HitSearchContext', () => {
                 const mockSearchParams = new URLSearchParams();
                 mockSearchParams.append('view', 'existing_view');
                 vi.mocked(useSearchParams).mockReturnValue([mockSearchParams, mockSetParams]);
-                renderHook(() => useContextSelector(HitSearchContext, () => { }), { wrapper: Wrapper });
+                renderHook(() => useContextSelector(RecordSearchContext, () => { }), { wrapper: Wrapper });
                 await waitFor(() => {
                     expect(mockParameterContext.addView).not.toBeCalled();
                 });
@@ -444,7 +447,7 @@ describe('HitSearchContext', () => {
                 mockParameterContext.views = [];
                 const mockSearchParams = new URLSearchParams();
                 vi.mocked(useSearchParams).mockReturnValue([mockSearchParams, mockSetParams]);
-                renderHook(() => useContextSelector(HitSearchContext, () => { }), { wrapper: Wrapper });
+                renderHook(() => useContextSelector(RecordSearchContext, () => { }), { wrapper: Wrapper });
                 await waitFor(() => {
                     expect(mockSetParams).not.toHaveBeenCalled();
                 });
@@ -454,12 +457,12 @@ describe('HitSearchContext', () => {
             it('should not break when view ID does not exist', async () => {
                 mockParameterContext.views = ['non_existent_view'];
                 mockViewContext.getCurrentViews = vi.fn(() => Promise.resolve([null]));
-                const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.search), { wrapper: Wrapper });
+                const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ctx.search), { wrapper: Wrapper });
                 act(() => {
                     hook.result.current('test query');
                 });
                 await waitFor(() => {
-                    expect(hpost).toHaveBeenCalledWith('/api/v1/search/hit', expect.objectContaining({
+                    expect(hpost).toHaveBeenCalledWith('/api/v2/search/hit', expect.objectContaining({
                         query: expect.stringContaining('test query'),
                         filters: ['event.created:[now-1w TO now]']
                     }));
@@ -471,12 +474,12 @@ describe('HitSearchContext', () => {
                     { view_id: 'view_1', query: 'howler.status:open' },
                     { view_id: 'view_2', query: 'howler.priority:high' }
                 ]);
-                const hook = renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.search), { wrapper: Wrapper });
+                const hook = renderHook(() => useContextSelector(RecordSearchContext, ctx => ctx.search), { wrapper: Wrapper });
                 act(() => {
                     hook.result.current('test query');
                 });
                 await waitFor(() => {
-                    expect(hpost).toHaveBeenCalledWith('/api/v1/search/hit', expect.objectContaining({
+                    expect(hpost).toHaveBeenCalledWith('/api/v2/search/hit', expect.objectContaining({
                         query: 'test query',
                         filters: ['event.created:[now-1w TO now]', 'howler.status:open', 'howler.priority:high']
                     }));
@@ -487,7 +490,7 @@ describe('HitSearchContext', () => {
             it('should not trigger search when views is empty and query is DEFAULT_QUERY', async () => {
                 mockParameterContext.query = DEFAULT_QUERY;
                 mockParameterContext.views = [];
-                renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.response), { wrapper: Wrapper });
+                renderHook(() => useContextSelector(RecordSearchContext, ctx => ctx.response), { wrapper: Wrapper });
                 await waitFor(() => {
                     expect(hpost).not.toHaveBeenCalled();
                 });
@@ -495,7 +498,7 @@ describe('HitSearchContext', () => {
             it('should trigger search when views.length > 0 even with DEFAULT_QUERY', async () => {
                 mockParameterContext.query = DEFAULT_QUERY;
                 mockParameterContext.views = ['view_1'];
-                renderHook(() => useContextSelector(HitSearchContext, ctx => ctx.response), { wrapper: Wrapper });
+                renderHook(() => useContextSelector(RecordSearchContext, ctx => ctx.response), { wrapper: Wrapper });
                 await waitFor(() => {
                     expect(hpost).toHaveBeenCalled();
                 });

package/components/app/providers/UserListProvider.js

@@ -1,11 +1,15 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import api from '@cccsaurora/howler-ui/api';
 import useMyApi from '@cccsaurora/howler-ui/components/hooks/useMyApi';
-import { createContext, useCallback, useState } from 'react';
+import { createContext, useCallback, useEffect, useRef, useState } from 'react';
 export const UserListContext = createContext(null);
 const UserListProvider = ({ children }) => {
     const { dispatchApi } = useMyApi();
     const [users, setUsers] = useState({});
+    const usersRef = useRef(users);
+    usersRef.current = users;
+    const pendingIds = useRef(new Set());
+    const debounceTimer = useRef(null);
     const searchUsers = useCallback(async (query) => {
         const newUsers = (await dispatchApi(api.search.user.post({ query, rows: 1000 }), {
             throwError: false,
@@ -17,14 +21,30 @@ const UserListProvider = ({ children }) => {
             ...newUsers
         }));
     }, [dispatchApi]);
-    const fetchUsers = useCallback(async (ids) => {
-        ids.delete('Unknown');
-        const idsToGet = Array.from(ids.values()).filter(id => !Object.keys(users).includes(id));
-        if (idsToGet.length <= 0) {
-            return;
+    const fetchUsers = useCallback((ids) => {
+        const nextIds = new Set(ids);
+        nextIds.delete('Unknown');
+        nextIds.forEach(id => pendingIds.current.add(id));
+        if (debounceTimer.current) {
+            clearTimeout(debounceTimer.current);
         }
-        await searchUsers(`id:${[...idsToGet].join(' OR ')}`);
-    }, [searchUsers, users]);
+        debounceTimer.current = setTimeout(async () => {
+            const idsToGet = Array.from(pendingIds.current).filter(id => !Object.keys(usersRef.current).includes(id));
+            pendingIds.current = new Set();
+            debounceTimer.current = null;
+            if (idsToGet.length <= 0) {
+                return;
+            }
+            await searchUsers(`id:${idsToGet.join(' OR ')}`);
+        }, 200);
+    }, [searchUsers]);
+    useEffect(() => {
+        return () => {
+            if (debounceTimer.current) {
+                clearTimeout(debounceTimer.current);
+            }
+        };
+    }, []);
     return _jsx(UserListContext.Provider, { value: { users, fetchUsers, searchUsers }, children: children });
 };
 export default UserListProvider;

package/components/elements/ContextMenu.d.ts

@@ -0,0 +1,56 @@
+import { type SxProps } from '@mui/material';
+import type { ElementType, FC, MouseEventHandler, PropsWithChildren, ReactNode } from 'react';
+export type ContextMenuDivider = {
+    kind: 'divider';
+    id: string;
+    sx?: SxProps;
+};
+export type ContextMenuLeafItem = {
+    kind: 'item';
+    id: string;
+    icon?: ReactNode;
+    label: ReactNode;
+    disabled?: boolean;
+    onClick?: () => void;
+    /** When provided the item renders as a router Link instead of a button. */
+    to?: string;
+};
+export type ContextMenuSubItem = {
+    key: string;
+    label: ReactNode;
+    disabled?: boolean;
+    onClick?: () => void;
+};
+export type ContextMenuSubmenuItem = {
+    kind: 'submenu';
+    /**
+     * Identifier for this submenu. Used to derive:
+     *  - the MenuItem's DOM id (`${id}-menu-item`)
+     *  - the submenu Paper's DOM id (`${id}-submenu`)
+     */
+    id: string;
+    icon?: ReactNode;
+    label: ReactNode;
+    disabled?: boolean;
+    items: ContextMenuSubItem[];
+};
+export type ContextMenuEntry = ContextMenuDivider | ContextMenuLeafItem | ContextMenuSubmenuItem;
+interface ContextMenuProps {
+    items: ContextMenuEntry[];
+    /** Called after the menu opens, with the triggering event. */
+    onOpen?: MouseEventHandler<HTMLElement>;
+    /** Called when the menu closes. */
+    onClose?: () => void;
+    /** Wraps children + menu in this element. Defaults to Box. */
+    Component?: ElementType;
+    /** id applied to the wrapper element */
+    id?: string;
+}
+/**
+ * Generic context menu component that renders a MUI Menu from a declarative
+ * items structure supporting leaf items, dividers, and single-level submenus.
+ *
+ * Submenus appear on hover and are positioned to avoid screen overflow.
+ */
+declare const ContextMenu: FC<PropsWithChildren<ContextMenuProps>>;
+export default ContextMenu;

package/components/elements/ContextMenu.js

@@ -0,0 +1,109 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { KeyboardArrowRight } from '@mui/icons-material';
+import { Box, Divider, Fade, ListItemIcon, ListItemText, Menu, MenuItem, MenuList, Paper, useTheme } from '@mui/material';
+import { useCallback, useEffect, useState } from 'react';
+import { Link } from 'react-router-dom';
+/**
+ * The margin at the bottom of the screen by which a submenu should be inverted.
+ * If hovering within this many pixels of the bottom, the submenu renders upward.
+ */
+const CONTEXTMENU_MARGIN = 350;
+/**
+ * Generic context menu component that renders a MUI Menu from a declarative
+ * items structure supporting leaf items, dividers, and single-level submenus.
+ *
+ * Submenus appear on hover and are positioned to avoid screen overflow.
+ */
+const ContextMenu = ({ items, onOpen, onClose, Component = Box, id, children }) => {
+    const theme = useTheme();
+    const [show, setShow] = useState({});
+    const [anchorEl, setAnchorEl] = useState(null);
+    const [transformProps, setTransformProps] = useState({});
+    const handleClose = useCallback(() => {
+        setAnchorEl(null);
+        onClose?.();
+    }, [onClose]);
+    const handleContextMenu = useCallback(event => {
+        if (anchorEl) {
+            event.preventDefault();
+            handleClose();
+            return;
+        }
+        event.preventDefault();
+        if (window.innerHeight - event.clientY < 300) {
+            setTransformProps({
+                position: 'fixed',
+                bottom: `${window.innerHeight - event.clientY}px !important`,
+                top: 'unset !important',
+                left: `${event.clientX}px !important`
+            });
+        }
+        else {
+            setTransformProps({
+                position: 'fixed',
+                top: `${event.clientY}px !important`,
+                left: `${event.clientX}px !important`
+            });
+        }
+        setAnchorEl(event.target);
+        onOpen?.(event);
+    }, [anchorEl, handleClose, onOpen]);
+    /**
+     * Calculates positioning styles for a submenu based on the parent element's
+     * position relative to the viewport bottom.
+     */
+    const calculateSubMenuStyles = useCallback((parent) => {
+        const baseStyles = { position: 'absolute', maxHeight: '300px', overflow: 'auto' };
+        const defaultStyles = { ...baseStyles, top: 0, left: '100%' };
+        if (!parent) {
+            return defaultStyles;
+        }
+        const parentBounds = parent.getBoundingClientRect();
+        if (window.innerHeight - parentBounds.y < CONTEXTMENU_MARGIN) {
+            return { ...baseStyles, bottom: 0, left: '100%' };
+        }
+        return defaultStyles;
+    }, []);
+    // Reset submenu visibility whenever the menu is closed
+    useEffect(() => {
+        if (!anchorEl) {
+            setShow({});
+        }
+    }, [anchorEl]);
+    return (_jsxs(Component, { id: id, onContextMenu: handleContextMenu, children: [children, _jsx(Menu, { id: "record-menu", open: !!anchorEl, anchorEl: anchorEl, onClose: handleClose, slotProps: {
+                    paper: {
+                        sx: {
+                            ...transformProps,
+                            overflow: 'visible !important'
+                        },
+                        elevation: 2
+                    }
+                }, MenuListProps: {
+                    dense: true,
+                    sx: {
+                        minWidth: '250px',
+                        paddingY: '0 !important',
+                        '& > :first-child': {
+                            borderTopLeftRadius: theme.shape.borderRadius,
+                            borderTopRightRadius: theme.shape.borderRadius
+                        },
+                        '& > :last-child': {
+                            borderBottomLeftRadius: theme.shape.borderRadius,
+                            borderBottomRightRadius: theme.shape.borderRadius
+                        }
+                    }
+                }, anchorOrigin: { vertical: 'top', horizontal: 'left' }, onClick: handleClose, children: items.map(entry => {
+                    if (entry.kind === 'divider') {
+                        return _jsx(Divider, { sx: { my: '0 !important' } }, entry.id);
+                    }
+                    if (entry.kind === 'item') {
+                        if (entry.to) {
+                            return (_jsxs(MenuItem, { component: Link, to: entry.to, disabled: entry.disabled, children: [entry.icon && _jsx(ListItemIcon, { children: entry.icon }), _jsx(ListItemText, { children: entry.label })] }, entry.id));
+                        }
+                        return (_jsxs(MenuItem, { disabled: entry.disabled, onClick: entry.onClick, children: [entry.icon && _jsx(ListItemIcon, { children: entry.icon }), _jsx(ListItemText, { children: entry.label })] }, entry.id));
+                    }
+                    const { id: entryId, icon, label, disabled, items: subItems } = entry;
+                    return (_jsxs(MenuItem, { id: `${entryId}-menu-item`, sx: { position: 'relative' }, onMouseEnter: ev => setShow(_show => ({ ..._show, [entryId]: ev.target })), onMouseLeave: () => setShow(_show => ({ ..._show, [entryId]: null })), disabled: disabled, children: [icon && _jsx(ListItemIcon, { children: icon }), _jsx(ListItemText, { sx: { flex: 1 }, children: label }), !disabled && _jsx(KeyboardArrowRight, { fontSize: "small", sx: { color: 'text.secondary', mr: -1 } }), _jsx(Fade, { in: !!show[entryId], unmountOnExit: true, children: _jsx(Paper, { id: `${entryId}-submenu`, sx: calculateSubMenuStyles(show[entryId]), elevation: 2, children: _jsx(MenuList, { sx: { p: 0, borderTopLeftRadius: 0 }, dense: true, role: "group", children: subItems.map(subItem => (_jsx(MenuItem, { onClick: subItem.onClick, disabled: subItem.disabled, children: _jsx(ListItemText, { children: subItem.label }) }, subItem.key))) }) }) })] }, entryId));
+                }) })] }));
+};
+export default ContextMenu;