@cccsaurora/howler-ui 2.18.0-dev.648 → 2.18.0-dev.667

package/components/hooks/useLocalStorage.test.d.ts

@@ -0,0 +1 @@
+export {};

package/components/hooks/useLocalStorage.test.js

@@ -0,0 +1,137 @@
+/// <reference types="vitest" />
+import { renderHook } from '@testing-library/react';
+import { setupLocalStorageMock } from '@cccsaurora/howler-ui/tests/mocks';
+import { describe, expect, it, vi } from 'vitest';
+import useLocalStorage from './useLocalStorage';
+const mockLocalStorage = setupLocalStorageMock();
+beforeEach(() => {
+    mockLocalStorage.clear();
+    vi.mocked(mockLocalStorage.setItem).mockClear();
+    vi.mocked(mockLocalStorage.removeItem).mockClear();
+});
+describe('useLocalStorage (no prefix)', () => {
+    describe('get', () => {
+        it('returns null when key is absent', () => {
+            const { result } = renderHook(() => useLocalStorage());
+            expect(result.current.get('testkey')).toBeNull();
+        });
+        it('returns the parsed value when key exists', () => {
+            mockLocalStorage.setItem('testkey', JSON.stringify(42));
+            const { result } = renderHook(() => useLocalStorage());
+            expect(result.current.get('testkey')).toBe(42);
+        });
+        it('returns null when the raw value is not valid JSON', () => {
+            mockLocalStorage.setItem('testkey', 'not-json{');
+            const { result } = renderHook(() => useLocalStorage());
+            expect(result.current.get('testkey')).toBeNull();
+        });
+    });
+    describe('set', () => {
+        it('serializes and writes a value', () => {
+            const { result } = renderHook(() => useLocalStorage());
+            result.current.set('testkey', { a: 1 });
+            expect(mockLocalStorage.setItem).toHaveBeenCalledWith('testkey', JSON.stringify({ a: 1 }));
+        });
+        it('written value can be read back', () => {
+            const { result } = renderHook(() => useLocalStorage());
+            result.current.set('testkey', 'hello');
+            expect(result.current.get('testkey')).toBe('hello');
+        });
+    });
+    describe('remove', () => {
+        it('removes the key', () => {
+            const { result } = renderHook(() => useLocalStorage());
+            result.current.set('testkey', 'val');
+            result.current.remove('testkey');
+            expect(mockLocalStorage.removeItem).toHaveBeenCalledWith('testkey');
+            expect(result.current.has('testkey')).toBe(false);
+        });
+        it('removes with a raw key when withPrefix=true', () => {
+            const { result } = renderHook(() => useLocalStorage('myprefix'));
+            result.current.remove('raw.key', true);
+            expect(mockLocalStorage.removeItem).toHaveBeenCalledWith('raw.key');
+        });
+    });
+    describe('has', () => {
+        it('returns false when key is absent', () => {
+            const { result } = renderHook(() => useLocalStorage());
+            expect(result.current.has('testkey')).toBe(false);
+        });
+        it('returns true when key exists', () => {
+            const { result } = renderHook(() => useLocalStorage());
+            result.current.set('testkey', 0);
+            expect(result.current.has('testkey')).toBe(true);
+        });
+    });
+    describe('keys', () => {
+        it('returns an empty array when storage is empty', () => {
+            const { result } = renderHook(() => useLocalStorage());
+            expect(result.current.keys()).toEqual([]);
+        });
+        it('returns all stored keys', () => {
+            const { result } = renderHook(() => useLocalStorage());
+            result.current.set('a', 1);
+            result.current.set('b', 2);
+            expect(result.current.keys()).toEqual(expect.arrayContaining(['a', 'b']));
+        });
+    });
+    describe('items', () => {
+        it('returns key-value pairs for all stored items', () => {
+            const { result } = renderHook(() => useLocalStorage());
+            result.current.set('x', 10);
+            result.current.set('y', 20);
+            const items = result.current.items();
+            expect(items).toEqual(expect.arrayContaining([
+                { key: 'x', value: 10 },
+                { key: 'y', value: 20 }
+            ]));
+        });
+    });
+    describe('clear', () => {
+        it('removes all keys when no prefix is set', () => {
+            const { result } = renderHook(() => useLocalStorage());
+            result.current.set('a', 1);
+            result.current.set('b', 2);
+            result.current.clear();
+            expect(result.current.keys()).toEqual([]);
+        });
+    });
+});
+describe('useLocalStorage (with prefix)', () => {
+    const PREFIX = 'ns';
+    describe('get / set', () => {
+        it('writes the key under the prefix', () => {
+            const { result } = renderHook(() => useLocalStorage(PREFIX));
+            result.current.set('item', 'val');
+            expect(mockLocalStorage.setItem).toHaveBeenCalledWith('ns.item', JSON.stringify('val'));
+        });
+        it('reads the key under the prefix', () => {
+            mockLocalStorage.setItem('ns.item', JSON.stringify('val'));
+            const { result } = renderHook(() => useLocalStorage(PREFIX));
+            expect(result.current.get('item')).toBe('val');
+        });
+        it('does not read a key stored without the prefix', () => {
+            mockLocalStorage.setItem('item', JSON.stringify('val'));
+            const { result } = renderHook(() => useLocalStorage(PREFIX));
+            expect(result.current.get('item')).toBeNull();
+        });
+    });
+    describe('remove', () => {
+        it('removes the key under the prefix', () => {
+            const { result } = renderHook(() => useLocalStorage(PREFIX));
+            result.current.remove('item');
+            expect(mockLocalStorage.removeItem).toHaveBeenCalledWith('ns.item');
+        });
+    });
+    describe('clear', () => {
+        it('only removes keys that start with the prefix', () => {
+            const { result } = renderHook(() => useLocalStorage(PREFIX));
+            result.current.set('item', 1);
+            mockLocalStorage.setItem('other.item', JSON.stringify(2));
+            vi.mocked(mockLocalStorage.removeItem).mockClear();
+            result.current.clear();
+            expect(mockLocalStorage.removeItem).toHaveBeenCalledWith('ns.item');
+            expect(mockLocalStorage.removeItem).not.toHaveBeenCalledWith('other.item');
+        });
+    });
+});

package/components/hooks/useParamState.d.ts

@@ -0,0 +1,6 @@
+type Primitive = string | number | boolean | null;
+declare const useParamState: {
+    <T extends Primitive>(key: string, defaultValue?: T, list?: false): [T, (value: T) => void];
+    <T extends Exclude<Primitive, null>>(key: string, defaultValue: T, list: true): [T[], (value: T[]) => void];
+};
+export default useParamState;

package/components/hooks/useParamState.js

@@ -0,0 +1,48 @@
+import { useCallback, useState } from 'react';
+import { useSearchParams } from 'react-router-dom';
+const parseValue = (raw, defaultValue) => {
+    if (raw === null)
+        return defaultValue;
+    if (typeof defaultValue === 'boolean')
+        return (raw === 'true');
+    if (typeof defaultValue === 'number') {
+        const n = Number(raw);
+        return (isNaN(n) ? defaultValue : n);
+    }
+    return raw;
+};
+const serializeValue = (value) => {
+    if (value === null || value === undefined)
+        return '';
+    return String(value);
+};
+// Scalar mode
+const useParamState = (key, defaultValue = null, list = false) => {
+    const [searchParams, setSearchParams] = useSearchParams();
+    const [value, setValue] = useState(() => {
+        if (list) {
+            const raws = searchParams.getAll(key);
+            return raws.map(r => parseValue(r, defaultValue));
+        }
+        return parseValue(searchParams.get(key), defaultValue);
+    });
+    const setter = useCallback((newValue) => {
+        setValue(newValue);
+        setSearchParams(prev => {
+            const next = new URLSearchParams(prev);
+            next.delete(key);
+            if (list) {
+                newValue.forEach(item => next.append(key, serializeValue(item)));
+            }
+            else {
+                const scalar = newValue;
+                if (scalar !== defaultValue && scalar !== null && scalar !== undefined) {
+                    next.set(key, serializeValue(scalar));
+                }
+            }
+            return next;
+        }, { replace: true });
+    }, [key, defaultValue, list, setSearchParams]);
+    return [value, setter];
+};
+export default useParamState;

package/components/hooks/useParamState.test.d.ts

@@ -0,0 +1 @@
+export {};

package/components/hooks/useParamState.test.js

@@ -0,0 +1,167 @@
+/// <reference types="vitest" />
+import { act, renderHook } from '@testing-library/react';
+import { createElement } from 'react';
+import { MemoryRouter, useSearchParams } from 'react-router-dom';
+import { describe, expect, it } from 'vitest';
+import useParamState from './useParamState';
+// Creates a MemoryRouter wrapper using createElement to avoid JSX in a .ts file
+const makeWrapper = (search = '') => {
+    // eslint-disable-next-line react/function-component-definition
+    return ({ children }) => createElement(MemoryRouter, { initialEntries: [search ? `/?${search}` : '/'] }, children);
+};
+// Composite hook: exposes the param state AND the live URL params for URL-level assertions
+const useParamStateWithUrl = (key, defaultValue) => {
+    const [value, setValue] = useParamState(key, defaultValue);
+    const [params] = useSearchParams();
+    return { value, setValue, params };
+};
+describe('useParamState', () => {
+    describe('scalar mode – initialization', () => {
+        it('returns the default value when the param is absent from the URL', () => {
+            const { result } = renderHook(() => useParamState('tab', 'dashboard'), { wrapper: makeWrapper() });
+            expect(result.current[0]).toBe('dashboard');
+        });
+        it('returns null when no default is provided and the param is absent', () => {
+            const { result } = renderHook(() => useParamState('tab'), { wrapper: makeWrapper() });
+            expect(result.current[0]).toBeNull();
+        });
+        it('reads a string value present in the URL', () => {
+            const { result } = renderHook(() => useParamState('tab', 'dashboard'), {
+                wrapper: makeWrapper('tab=settings')
+            });
+            expect(result.current[0]).toBe('settings');
+        });
+        it('coerces a URL string to a number when defaultValue is a number', () => {
+            const { result } = renderHook(() => useParamState('page', 0), { wrapper: makeWrapper('page=3') });
+            expect(result.current[0]).toBe(3);
+        });
+        it('returns the default number when the URL value is non-numeric', () => {
+            const { result } = renderHook(() => useParamState('page', 0), {
+                wrapper: makeWrapper('page=notanumber')
+            });
+            expect(result.current[0]).toBe(0);
+        });
+        it("coerces 'true' string to boolean true when defaultValue is boolean", () => {
+            const { result } = renderHook(() => useParamState('active', false), {
+                wrapper: makeWrapper('active=true')
+            });
+            expect(result.current[0]).toBe(true);
+        });
+        it("coerces 'false' string to boolean false when defaultValue is boolean", () => {
+            const { result } = renderHook(() => useParamState('active', true), {
+                wrapper: makeWrapper('active=false')
+            });
+            expect(result.current[0]).toBe(false);
+        });
+    });
+    describe('scalar mode – setter', () => {
+        it('updates the in-state value', () => {
+            const { result } = renderHook(() => useParamState('tab', 'dashboard'), { wrapper: makeWrapper() });
+            act(() => result.current[1]('settings'));
+            expect(result.current[0]).toBe('settings');
+        });
+        it('writes the new value to the URL', () => {
+            const { result } = renderHook(() => useParamStateWithUrl('tab', 'dashboard'), { wrapper: makeWrapper() });
+            act(() => result.current.setValue('settings'));
+            expect(result.current.params.get('tab')).toBe('settings');
+        });
+        it('removes the param from the URL when set to the default value', () => {
+            const { result } = renderHook(() => useParamStateWithUrl('tab', 'dashboard'), {
+                wrapper: makeWrapper('tab=settings')
+            });
+            act(() => result.current.setValue('dashboard'));
+            expect(result.current.params.has('tab')).toBe(false);
+        });
+        it('removes the param from the URL when set to null', () => {
+            const { result } = renderHook(() => useParamStateWithUrl('tab', null), {
+                wrapper: makeWrapper('tab=settings')
+            });
+            act(() => result.current.setValue(null));
+            expect(result.current.params.has('tab')).toBe(false);
+        });
+        it('serializes a number to the URL', () => {
+            const { result } = renderHook(() => useParamStateWithUrl('page', 0), { wrapper: makeWrapper() });
+            act(() => result.current.setValue(5));
+            expect(result.current.params.get('page')).toBe('5');
+        });
+        it('removes the param when a number is set back to its default', () => {
+            const { result } = renderHook(() => useParamStateWithUrl('page', 0), { wrapper: makeWrapper('page=3') });
+            act(() => result.current.setValue(0));
+            expect(result.current.params.has('page')).toBe(false);
+        });
+        it('serializes boolean true to the URL', () => {
+            const { result } = renderHook(() => useParamStateWithUrl('active', false), { wrapper: makeWrapper() });
+            act(() => result.current.setValue(true));
+            expect(result.current.params.get('active')).toBe('true');
+        });
+        it('removes boolean param when set back to its default', () => {
+            const { result } = renderHook(() => useParamStateWithUrl('active', false), {
+                wrapper: makeWrapper('active=true')
+            });
+            act(() => result.current.setValue(false));
+            expect(result.current.params.has('active')).toBe(false);
+        });
+        it('does not clobber unrelated URL params when writing', () => {
+            const { result } = renderHook(() => useParamStateWithUrl('tab', 'dashboard'), {
+                wrapper: makeWrapper('sort=asc')
+            });
+            act(() => result.current.setValue('settings'));
+            expect(result.current.params.get('sort')).toBe('asc');
+        });
+    });
+    describe('list mode – initialization', () => {
+        it('returns an empty array when no list params are present', () => {
+            const { result } = renderHook(() => useParamState('tag', 'x', true), { wrapper: makeWrapper() });
+            expect(result.current[0]).toEqual([]);
+        });
+        it('reads multiple values from the URL', () => {
+            const { result } = renderHook(() => useParamState('tag', 'x', true), {
+                wrapper: makeWrapper('tag=a&tag=b&tag=c')
+            });
+            expect(result.current[0]).toEqual(['a', 'b', 'c']);
+        });
+    });
+    describe('list mode – setter', () => {
+        it('updates the in-state array value', () => {
+            const { result } = renderHook(() => useParamState('tag', '', true), { wrapper: makeWrapper() });
+            act(() => result.current[1](['alpha', 'beta']));
+            expect(result.current[0]).toEqual(['alpha', 'beta']);
+        });
+        it('writes multiple values as repeated URL params', () => {
+            const { result } = renderHook(() => {
+                const [value, setValue] = useParamState('tag', '', true);
+                const [params] = useSearchParams();
+                return { value, setValue, params };
+            }, { wrapper: makeWrapper() });
+            act(() => result.current.setValue(['x', 'y', 'z']));
+            expect(result.current.params.getAll('tag')).toEqual(['x', 'y', 'z']);
+        });
+        it('clears all repeated params when set to an empty array', () => {
+            const { result } = renderHook(() => {
+                const [value, setValue] = useParamState('tag', '', true);
+                const [params] = useSearchParams();
+                return { value, setValue, params };
+            }, { wrapper: makeWrapper('tag=a&tag=b') });
+            act(() => result.current.setValue([]));
+            expect(result.current.params.getAll('tag')).toEqual([]);
+        });
+        it('replaces existing params entirely on update', () => {
+            const { result } = renderHook(() => {
+                const [value, setValue] = useParamState('tag', '', true);
+                const [params] = useSearchParams();
+                return { value, setValue, params };
+            }, { wrapper: makeWrapper('tag=old1&tag=old2') });
+            act(() => result.current.setValue(['new1']));
+            expect(result.current.params.getAll('tag')).toEqual(['new1']);
+        });
+        it('does not clobber unrelated URL params when writing list values', () => {
+            const { result } = renderHook(() => {
+                const [value, setValue] = useParamState('tag', '', true);
+                const [params] = useSearchParams();
+                return { value, setValue, params };
+            }, { wrapper: makeWrapper('sort=asc') });
+            act(() => result.current.setValue(['x']));
+            expect(result.current.params.get('sort')).toBe('asc');
+        });
+    });
+});

package/package.json

@@ -101,7 +101,7 @@
     "internal-slot": "1.0.7"
   },
   "type": "module",
-  "version": "2.18.0-dev.648",
+  "version": "2.18.0-dev.667",
   "exports": {
     "./i18n": "./i18n.js",
     "./index.css": "./index.css",