@cccsaurora/howler-ui 2.18.0 → 2.19.0-cases.1040

package/components/app/providers/SearchResponseProvider.test.js

@@ -0,0 +1,406 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { act, renderHook } from '@testing-library/react';
+import { useContext } from 'react';
+import SearchResponseProvider, { SearchResponseContext } from './SearchResponseProvider';
+const TEST_PAGE_SIZE = 25;
+const TEST_TOTAL_COUNT = 100;
+const makeWrapper = (initialResponse) => {
+    const Wrapper = ({ children }) => (_jsx(SearchResponseProvider, { idField: "id", initialResponse: initialResponse, children: children }));
+    return Wrapper;
+};
+const renderProvider = (initialResponse) => {
+    return renderHook(() => useContext(SearchResponseContext), {
+        wrapper: makeWrapper(initialResponse)
+    });
+};
+describe('push', () => {
+    it("should add an item to the response if it doesn't exist", () => {
+        const hook = renderProvider({
+            items: [{ id: '0', name: 'existing' }],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 0
+        });
+        act(() => {
+            hook.result.current.push({ id: '1', name: 'test' });
+        });
+        expect(hook.result.current.response).toEqual({
+            items: [
+                { id: '0', name: 'existing' },
+                { id: '1', name: 'test' }
+            ],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT + 1,
+            removeCount: 0
+        });
+    });
+    it('should replace an item in the response if it already exists', () => {
+        const hook = renderProvider({
+            items: [{ id: '0', name: 'old' }],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 0
+        });
+        act(() => {
+            hook.result.current.push({ id: '0', name: 'new' });
+        });
+        expect(hook.result.current.response).toEqual({
+            items: [{ id: '0', name: 'new' }],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 0
+        });
+    });
+    it('should update total but not add item if the response has the maximum number of items', () => {
+        const items = Array.from({ length: TEST_PAGE_SIZE }, (_, i) => ({ id: i.toString(), name: `item${i}` }));
+        const newItem = { id: TEST_PAGE_SIZE.toString(), name: 'test' };
+        const hook = renderProvider({
+            items,
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 0
+        });
+        act(() => {
+            hook.result.current.push(newItem);
+        });
+        expect(hook.result.current.response?.items).not.toContainEqual(newItem);
+        expect(hook.result.current.response).toEqual({
+            items,
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT + 1,
+            removeCount: 0
+        });
+    });
+    it('should decrement removeCount if the item does not exist already', () => {
+        const hook = renderProvider({
+            items: [{ id: '0', name: 'existing' }],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 1
+        });
+        act(() => {
+            hook.result.current.push({ id: '1', name: 'test' });
+        });
+        expect(hook.result.current.response).not.toBeNull();
+        expect(hook.result.current.response.removeCount).toBe(0);
+    });
+    it('should not decrement removeCount if the item already exists', () => {
+        const hook = renderProvider({
+            items: [{ id: '0', name: 'existing' }],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 1
+        });
+        act(() => {
+            hook.result.current.push({ id: '0', name: 'new' });
+        });
+        expect(hook.result.current.response).not.toBeNull();
+        expect(hook.result.current.response.removeCount).toBe(1);
+    });
+    it('should keep response null if it is uninitiated', () => {
+        const hook = renderProvider();
+        act(() => {
+            hook.result.current.push({ id: '0', name: 'test' });
+        });
+        expect(hook.result.current.response).toBeNull();
+    });
+});
+describe('remove', () => {
+    it('should remove an item from the response if it exists', () => {
+        const hook = renderProvider({
+            items: [
+                { id: '0', name: 'item0' },
+                { id: '1', name: 'item1' }
+            ],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 0
+        });
+        act(() => {
+            hook.result.current.remove('0');
+        });
+        expect(hook.result.current.response).toEqual({
+            items: [{ id: '1', name: 'item1' }],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT - 1,
+            removeCount: 1
+        });
+    });
+    it('should ignore the remove if the item does not exist', () => {
+        const hook = renderProvider({
+            items: [{ id: '0', name: 'item' }],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 0
+        });
+        act(() => {
+            hook.result.current.remove('1');
+        });
+        expect(hook.result.current.response).toEqual({
+            items: [{ id: '0', name: 'item' }],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 0
+        });
+    });
+    it('should keep response null if it is uninitiated', () => {
+        const hook = renderProvider();
+        act(() => {
+            hook.result.current.remove('0');
+        });
+        expect(hook.result.current.response).toBeNull();
+    });
+});
+describe('replace', () => {
+    it('should replace an item in the response if it exists', () => {
+        const hook = renderProvider({
+            items: [{ id: '0', name: 'old' }],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 0
+        });
+        act(() => {
+            hook.result.current.replace('0', { id: undefined, name: 'new' });
+        });
+        expect(hook.result.current.response).toEqual({
+            items: [{ id: '0', name: 'new' }],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 0
+        });
+    });
+    it('should ignore the replace if the item does not exist', () => {
+        const hook = renderProvider({
+            items: [{ id: '0', name: 'item' }],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 0
+        });
+        act(() => {
+            hook.result.current.replace('1', { id: undefined, name: 'new' });
+        });
+        expect(hook.result.current.response).not.toContainEqual({ id: '1', name: 'new' });
+        expect(hook.result.current.response).toEqual({
+            items: [{ id: '0', name: 'item' }],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 0
+        });
+    });
+    it('should keep response null if it is uninitiated', () => {
+        const hook = renderProvider();
+        act(() => {
+            hook.result.current.replace('0', { id: '0', name: 'new' });
+        });
+        expect(hook.result.current.response).toBeNull();
+    });
+    it('should throw error if item id does not match the id provided', () => {
+        const hook = renderProvider({
+            items: [{ id: '0', name: 'old' }],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 0
+        });
+        expect(() => act(() => {
+            hook.result.current.replace('0', { id: '1', name: 'new' });
+        })).toThrow(/id does not match/);
+    });
+});
+describe('request', () => {
+    const apiSearchMock = vi.fn();
+    beforeEach(() => {
+        apiSearchMock.mockReset();
+    });
+    it('should update the response with the result of the request', async () => {
+        const hook = renderProvider({
+            items: [{ id: '0', name: 'item' }],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 0
+        });
+        const request = {
+            query: 'test',
+            rows: TEST_PAGE_SIZE,
+            offset: 0
+        };
+        apiSearchMock.mockResolvedValue({
+            items: [{ id: '1', name: 'new' }],
+            offset: request.offset,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT
+        });
+        await act(async () => {
+            await hook.result.current.request(apiSearchMock, request);
+        });
+        expect(apiSearchMock).toHaveBeenCalledWith(request);
+        expect(hook.result.current.response).toEqual({
+            items: [{ id: '1', name: 'new' }],
+            offset: request.offset,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 0
+        });
+    });
+    it.for([
+        { description: 'before', offset: 0 },
+        { description: 'the same as', offset: TEST_PAGE_SIZE }
+    ])('should reset removeCount if the offset is $description the current offset', async ({ offset }) => {
+        const hook = renderProvider({
+            items: [{ id: '0', name: 'item' }],
+            offset: TEST_PAGE_SIZE,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 5
+        });
+        const request = {
+            query: 'test',
+            rows: TEST_PAGE_SIZE,
+            offset: offset
+        };
+        apiSearchMock.mockResolvedValue({
+            items: [{ id: '1', name: 'new' }],
+            offset: request.offset,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT
+        });
+        await act(async () => {
+            await hook.result.current.request(apiSearchMock, request);
+        });
+        expect(apiSearchMock).toHaveBeenCalledWith(request);
+        expect(hook.result.current.response).toEqual({
+            items: [{ id: '1', name: 'new' }],
+            offset: request.offset,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 0
+        });
+    });
+    it('should not reset removeCount if the offset is after the current offset', async () => {
+        const hook = renderProvider({
+            items: [{ id: '0', name: 'item' }],
+            offset: TEST_PAGE_SIZE,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 5
+        });
+        const request = {
+            query: 'test',
+            rows: TEST_PAGE_SIZE,
+            offset: TEST_PAGE_SIZE * 2
+        };
+        apiSearchMock.mockResolvedValue({
+            items: [{ id: '1', name: 'new' }],
+            offset: request.offset,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT
+        });
+        await act(async () => {
+            await hook.result.current.request(apiSearchMock, request);
+        });
+        expect(apiSearchMock).toHaveBeenCalledWith(request);
+        expect(hook.result.current.response).toEqual({
+            items: [{ id: '1', name: 'new' }],
+            offset: request.offset,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 5
+        });
+    });
+    it('should keep response undefined if the request fails', async () => {
+        const hook = renderProvider();
+        const request = {
+            query: 'test',
+            rows: TEST_PAGE_SIZE,
+            offset: 0
+        };
+        apiSearchMock.mockRejectedValue(new Error('Request failed'));
+        await act(async () => {
+            await hook.result.current.request(apiSearchMock, request).catch(() => { });
+        });
+        expect(apiSearchMock).toHaveBeenCalledWith(request);
+        expect(hook.result.current.response).toBeNull();
+    });
+    it('should keep response unchanged if the request fails', async () => {
+        const initialResponse = {
+            items: [{ id: '0', name: 'item' }],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 5
+        };
+        const hook = renderProvider(initialResponse);
+        const request = {
+            query: 'test',
+            rows: TEST_PAGE_SIZE,
+            offset: 0
+        };
+        apiSearchMock.mockRejectedValue(new Error('Request failed'));
+        await act(async () => {
+            await hook.result.current.request(apiSearchMock, request).catch(() => { });
+        });
+        expect(apiSearchMock).toHaveBeenCalledWith(request);
+        expect(hook.result.current.response).toEqual(initialResponse);
+    });
+    it('should throw an error if the request throws an error', async () => {
+        const hook = renderProvider();
+        const request = {
+            query: 'test',
+            rows: TEST_PAGE_SIZE,
+            offset: 0
+        };
+        apiSearchMock.mockRejectedValue(new Error('Request failed'));
+        await expect(act(async () => {
+            await hook.result.current.request(apiSearchMock, request);
+        })).rejects.toThrow('Request failed');
+    });
+});
+describe('getSearchRequestData', () => {
+    it.for([
+        { description: 'no remove count', removeCount: 0 },
+        { description: 'with remove count', removeCount: 5 }
+    ])('should modify offset if it is provided - $description', ({ removeCount }) => {
+        const hook = renderProvider({
+            items: [],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: removeCount
+        });
+        const modifiedRequest = hook.result.current.getSearchRequestData({ offset: TEST_PAGE_SIZE });
+        expect(modifiedRequest.offset).toBe(TEST_PAGE_SIZE - removeCount);
+    });
+    it('should not modify offset if it is not provided', () => {
+        const hook = renderProvider({
+            items: [],
+            offset: 0,
+            rows: TEST_PAGE_SIZE,
+            total: TEST_TOTAL_COUNT,
+            removeCount: 5
+        });
+        const modifiedRequest = hook.result.current.getSearchRequestData({ query: 'value' });
+        expect(modifiedRequest.offset).not.toBeDefined();
+    });
+    it('should not modify offset if response is uninitialised', () => {
+        const hook = renderProvider();
+        const modifiedRequest = hook.result.current.getSearchRequestData({ offset: TEST_PAGE_SIZE });
+        expect(modifiedRequest.offset).toBe(TEST_PAGE_SIZE);
+    });
+});

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/app/providers/ViewProvider.test.js

@@ -151,7 +151,10 @@ describe('ViewContext', () => {
         it('should allow users to edit views', async () => {
             const result = await act(async () => hook.result.current('example_view_id', { query: DEFAULT_QUERY }));
             expect(hput).toHaveBeenCalledOnce();
-            expect(hput).toBeCalledWith('/api/v1/view/example_view_id', { query: DEFAULT_QUERY });
+            const [url, body, ...rest] = vi.mocked(hput).mock.calls[0];
+            expect(url).toBe('/api/v1/view/example_view_id');
+            expect(body).toEqual({ query: DEFAULT_QUERY });
+            expect(rest.every(v => v === undefined)).toBe(true);
             expect(result).toEqual(MOCK_RESPONSES['/api/v1/view/example_view_id']);
         });
     });

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;