@cccsaurora/howler-ui 2.19.0-dev.836 → 2.19.0-dev.842

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 });
@@ -229,7 +224,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 });
@@ -243,27 +238,13 @@ describe('HitSearchContext', () => {
                 expect(hook.result.current.response?.items[0].howler.id).toBe('hit1');
             });
         });
-        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 });
-            act(() => {
-                hook.result.current('test query');
-            });
-            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']
-                }));
-            });
-        });
         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:')])
                 }));
             });
@@ -272,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:*')])
                 }));
             });
@@ -302,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(() => {
@@ -316,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');
             });
@@ -328,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(() => {
@@ -342,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 });
@@ -368,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');
@@ -380,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 });
@@ -401,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'])
                     }));
@@ -419,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]',
@@ -443,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');
                 });
@@ -455,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();
                 });
@@ -466,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();
                 });
@@ -476,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]']
                     }));
@@ -493,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']
                     }));
@@ -509,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();
                 });
@@ -517,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/SocketProvider.d.ts

@@ -48,9 +48,18 @@ interface SocketContextType {
      */
     reconnect: () => void;
     /**
-     * Helper function to tell if the socket is open
+     * Helper to tell if the socket is open
      */
-    isOpen: () => boolean;
+    open: boolean;
+    /**
+     * A map of entity IDs to their current viewers.
+     */
+    viewers: Record<string, string[]>;
+    /**
+     * Fetch the current viewers for an entity via REST, then keep in sync via socket.
+     * @param entityId The entity ID to fetch viewers for
+     */
+    fetchViewers: (entityId: string) => Promise<void>;
 }
 export declare const SocketContext: import("react").Context<SocketContextType>;
 declare const SocketProvider: React.FC<PropsWithChildren>;

package/components/app/providers/SocketProvider.js

@@ -1,11 +1,12 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 /* eslint-disable no-console */
 import api from '@cccsaurora/howler-ui/api';
+import useMyApi from '@cccsaurora/howler-ui/components/hooks/useMyApi';
 import useMyLocalStorage from '@cccsaurora/howler-ui/components/hooks/useMyLocalStorage';
-import { createContext, useCallback, useEffect, useRef, useState } from 'react';
+import { createContext, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { StorageKey } from '@cccsaurora/howler-ui/utils/constants';
 import { getStored, setAxiosCache, setStored } from '@cccsaurora/howler-ui/utils/sessionStorage';
-import { isHitUpdate } from '@cccsaurora/howler-ui/utils/socketUtils';
+import { isHitUpdate, isViewersUpdate } from '@cccsaurora/howler-ui/utils/socketUtils';
 /**
  * Enum to help track the status of the Websocket, since the corresponding websocket enums are directly on the object
  */
@@ -19,6 +20,7 @@ export var Status;
 export const SocketContext = createContext(null);
 const SocketProvider = ({ children }) => {
     const { get } = useMyLocalStorage();
+    const { dispatchApi } = useMyApi();
     // In order to persist the connection through state changes, we use a ref
     const socket = useRef();
     // Due to react setState race conditions, listeners are also stored in a ref
@@ -31,6 +33,8 @@ const SocketProvider = ({ children }) => {
     const [retry, setRetry] = useState(true);
     // Track the number of failed attempts when connecting to the server
     const [failedAttempts, setFailedAttempts] = useState(0);
+    // Track active viewers per entity ID
+    const [viewers, setViewers] = useState({});
     const onClose = useCallback(e => {
         // https://www.rfc-editor.org/rfc/rfc6455:
         // 1006 is a reserved value and MUST NOT be set as a status code in a
@@ -183,7 +187,7 @@ const SocketProvider = ({ children }) => {
     const addListener = useCallback((key, callback) => {
         // If a listener with the same key already exists, remove it.
         if (listeners.current[key]) {
-            socket.current?.removeEventListener('message', listeners[key]);
+            socket.current?.removeEventListener('message', listeners.current[key]);
         }
         // We wrap the callback so that all the listeners don't need to JSON.parse the data
         const wrapped = ev => {
@@ -200,6 +204,9 @@ const SocketProvider = ({ children }) => {
                     api_status_code: parsedData.status
                 });
             }
+            if (isViewersUpdate(parsedData)) {
+                setViewers(prev => ({ ...prev, [parsedData.id]: parsedData.viewers }));
+            }
             callback(parsedData);
         };
         socket.current?.addEventListener('message', wrapped);
@@ -219,8 +226,14 @@ const SocketProvider = ({ children }) => {
         }
         socket.current?.send(data);
     }, [status]);
-    const isOpen = useCallback(() => status === Status.OPEN, [status]);
+    const open = useMemo(() => status === Status.OPEN, [status]);
     const reconnect = useCallback(() => setRetry(true), []);
-    return (_jsx(SocketContext.Provider, { value: { addListener, removeListener, emit, status, reconnect, isOpen }, children: children }));
+    const fetchViewers = useCallback(async (entityId) => {
+        const result = await dispatchApi(api.socket.viewers.get(entityId), { throwError: false });
+        if (result) {
+            setViewers(prev => ({ ...prev, [entityId]: result }));
+        }
+    }, [dispatchApi]);
+    return (_jsx(SocketContext.Provider, { value: { addListener, removeListener, emit, status, reconnect, open, viewers, fetchViewers }, children: children }));
 };
 export default SocketProvider;

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;