@coinbase/cds-common 8.19.1 → 8.20.0

package/CHANGELOG.md

@@ -8,6 +8,12 @@ All notable changes to this project will be documented in this file.
 
 <!-- template-start -->
 
+## 8.20.0 (11/7/2025 PST)
+
+#### 🚀 Updates
+
+- Add useMultiSelect hook. [[#21](https://github.com/coinbase/cds/pull/21)]
+
 ## 8.19.1 ((11/4/2025, 08:48 AM PST))
 
 This is an artificial version bump with no new change.

package/dts/select/useMultiSelect.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Options for configuring the useMultiSelect hook
+ */
+export type MultiSelectOptions = {
+  /** Initial array of selected values */
+  initialValue: string[] | null;
+};
+/**
+ * API returned by the useMultiSelect hook for managing multi-select state
+ */
+export type MultiSelectApi<T extends string> = {
+  /** Current array of selected values */
+  value: T[];
+  /** Handler for toggling selection of one or more values.
+   * When a single value is passed, it will be added to the selection if it is not already selected.
+   * If the value is already selected, it will be removed from the selection.
+   * When an array of values is passed, all values will be added to the selection.
+   * When null is passed, all values will be removed from the selection.
+   */
+  onChange: (value: string | string[] | null) => void;
+  /** Add one or more values to the selection */
+  addSelection: (value: string | string[]) => void;
+  /** Remove one or more values from the selection */
+  removeSelection: (value: string | string[]) => void;
+  /** Clear all selected values */
+  resetSelection: () => void;
+};
+/**
+ * Hook for managing multi-select state with convenient API methods
+ * @param options - Configuration options including initial value
+ * @returns API object for managing multi-select state
+ */
+export declare const useMultiSelect: <T extends string>({
+  initialValue,
+}: MultiSelectOptions) => MultiSelectApi<T>;
+//# sourceMappingURL=useMultiSelect.d.ts.map

package/dts/select/useMultiSelect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMultiSelect.d.ts","sourceRoot":"","sources":["../../src/select/useMultiSelect.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,uCAAuC;IACvC,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI;IAC7C,uCAAuC;IACvC,KAAK,EAAE,CAAC,EAAE,CAAC;IACX;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,KAAK,IAAI,CAAC;IACpD,8CAA8C;IAC9C,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC;IACjD,mDAAmD;IACnD,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC;IACpD,gCAAgC;IAChC,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,MAAM,EAAE,mBAE9C,kBAAkB,KAAG,cAAc,CAAC,CAAC,CAmDvC,CAAC"}

package/esm/select/useMultiSelect.js

@@ -0,0 +1,67 @@
+import { useCallback, useMemo, useState } from 'react';
+
+/**
+ * Options for configuring the useMultiSelect hook
+ */
+
+/**
+ * API returned by the useMultiSelect hook for managing multi-select state
+ */
+
+/**
+ * Hook for managing multi-select state with convenient API methods
+ * @param options - Configuration options including initial value
+ * @returns API object for managing multi-select state
+ */
+export const useMultiSelect = _ref => {
+  let {
+    initialValue
+  } = _ref;
+  const [value, setValue] = useState(initialValue !== null && initialValue !== void 0 ? initialValue : []);
+  const onChange = useCallback(value => {
+    if (value === null) return setValue([]);
+    setValue(prev => {
+      if (Array.isArray(value)) {
+        const valuesToKeep = prev.filter(v => !value.includes(v));
+        const valuesToAdd = value.filter(v => !prev.includes(v));
+        return [...valuesToKeep, ...valuesToAdd];
+      }
+      if (!prev.includes(value)) return [...prev, value];
+      return prev.filter(v => v !== value);
+    });
+  }, []);
+  const addSelection = useCallback(value => {
+    setValue(prev => {
+      if (Array.isArray(value)) {
+        const newValue = [...prev];
+        for (const v of value) {
+          if (!newValue.includes(v)) newValue.push(v);
+        }
+        return newValue;
+      }
+      if (prev.includes(value)) return prev;
+      return [...prev, value];
+    });
+  }, []);
+  const removeSelection = useCallback(value => {
+    setValue(prev => {
+      if (Array.isArray(value)) return prev.filter(v => !value.includes(v));
+      if (!prev.includes(value)) return prev;
+      return prev.filter(v => v !== value);
+    });
+  }, []);
+  const resetSelection = useCallback(() => {
+    setValue(prev => {
+      if (prev.length === 0) return prev;
+      return [];
+    });
+  }, []);
+  const api = useMemo(() => ({
+    value,
+    onChange,
+    addSelection,
+    removeSelection,
+    resetSelection
+  }), [value, onChange, addSelection, removeSelection, resetSelection]);
+  return api;
+};

package/esm/select/useMultiSelect.test.js

@@ -0,0 +1,280 @@
+import { act, renderHook } from '@testing-library/react';
+import { useMultiSelect } from './useMultiSelect';
+describe('useMultiSelect', () => {
+  describe('initialization', () => {
+    it('should initialize with empty array when initialValue is null', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: null
+      }));
+      expect(result.current.value).toEqual([]);
+    });
+    it('should initialize with provided initialValue', () => {
+      const initialValue = ['option1', 'option2'];
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue
+      }));
+      expect(result.current.value).toEqual(initialValue);
+    });
+    it('should return the correct API shape', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: null
+      }));
+      expect(result.current).toHaveProperty('value');
+      expect(result.current).toHaveProperty('onChange');
+      expect(result.current).toHaveProperty('addSelection');
+      expect(result.current).toHaveProperty('removeSelection');
+      expect(result.current).toHaveProperty('resetSelection');
+    });
+  });
+  describe('onChange', () => {
+    it('should add a single value when it does not exist', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: ['option1']
+      }));
+      act(() => {
+        result.current.onChange('option2');
+      });
+      expect(result.current.value).toEqual(['option1', 'option2']);
+    });
+    it('should remove a single value when it already exists', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: ['option1', 'option2']
+      }));
+      act(() => {
+        result.current.onChange('option2');
+      });
+      expect(result.current.value).toEqual(['option1']);
+    });
+    it('should add multiple values from an array', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: ['option1']
+      }));
+      act(() => {
+        result.current.onChange(['option2', 'option3']);
+      });
+      expect(result.current.value).toEqual(['option1', 'option2', 'option3']);
+    });
+    it('should add new values when array contains existing values and remove existing values', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: ['option1', 'option2']
+      }));
+      act(() => {
+        result.current.onChange(['option2', 'option3']);
+      });
+      expect(result.current.value).toEqual(['option1', 'option3']);
+    });
+    it('should clear value when null is passed', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: ['option1', 'option2']
+      }));
+      act(() => {
+        result.current.onChange(null);
+      });
+      expect(result.current.value).toEqual([]);
+    });
+  });
+  describe('addSelection', () => {
+    it('should add a single value when it does not exist', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: ['option1']
+      }));
+      act(() => {
+        result.current.addSelection('option2');
+      });
+      expect(result.current.value).toEqual(['option1', 'option2']);
+    });
+    it('should not add a single value when it already exists', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: ['option1', 'option2']
+      }));
+      act(() => {
+        result.current.addSelection('option2');
+      });
+      expect(result.current.value).toEqual(['option1', 'option2']);
+    });
+    it('should add multiple values from an array', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: ['option1']
+      }));
+      act(() => {
+        result.current.addSelection(['option2', 'option3']);
+      });
+      expect(result.current.value).toEqual(['option1', 'option2', 'option3']);
+    });
+    it('should not add duplicate values when adding multiple times', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: ['option1', 'option2']
+      }));
+      act(() => {
+        result.current.addSelection(['option2', 'option3']);
+      });
+      expect(result.current.value).toEqual(['option1', 'option2', 'option3']);
+    });
+    it('should handle adding single value to empty selection', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: []
+      }));
+      act(() => {
+        result.current.addSelection(['option1']);
+      });
+      expect(result.current.value).toEqual(['option1']);
+    });
+  });
+  describe('removeSelection', () => {
+    it('should remove a single value when it exists', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: ['option1', 'option2']
+      }));
+      act(() => {
+        result.current.removeSelection('option2');
+      });
+      expect(result.current.value).toEqual(['option1']);
+    });
+    it('should not change value when removing non-existent value', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: ['option1']
+      }));
+      act(() => {
+        result.current.removeSelection('option2');
+      });
+      expect(result.current.value).toEqual(['option1']);
+    });
+    it('should remove multiple values sequentially', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: ['option1', 'option2', 'option3']
+      }));
+      act(() => {
+        result.current.removeSelection(['option1', 'option3']);
+      });
+      expect(result.current.value).toEqual(['option2']);
+    });
+    it('should handle removal of non-existent values', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: ['option1', 'option2']
+      }));
+      act(() => {
+        result.current.removeSelection(['option3', 'option4']);
+      });
+      expect(result.current.value).toEqual(['option1', 'option2']);
+    });
+    it('should handle removal from empty selection', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: []
+      }));
+      act(() => {
+        result.current.removeSelection(['option1']);
+      });
+      expect(result.current.value).toEqual([]);
+    });
+  });
+  describe('resetSelection', () => {
+    it('should clear all values', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: ['option1', 'option2']
+      }));
+      act(() => {
+        result.current.resetSelection();
+      });
+      expect(result.current.value).toEqual([]);
+    });
+    it('should handle reset when already empty', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: []
+      }));
+      act(() => {
+        result.current.resetSelection();
+      });
+      expect(result.current.value).toEqual([]);
+    });
+  });
+  describe('complex scenarios', () => {
+    it('should handle multiple operations in sequence', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: ['option1']
+      }));
+      act(() => {
+        result.current.addSelection('option2');
+      });
+      expect(result.current.value).toEqual(['option1', 'option2']);
+      act(() => {
+        result.current.onChange('option3');
+      });
+      expect(result.current.value).toEqual(['option1', 'option2', 'option3']);
+      act(() => {
+        result.current.removeSelection('option1');
+        result.current.removeSelection('option3');
+      });
+      expect(result.current.value).toEqual(['option2']);
+      act(() => {
+        result.current.addSelection('option4');
+        result.current.addSelection('option5');
+      });
+      expect(result.current.value).toEqual(['option2', 'option4', 'option5']);
+      act(() => {
+        result.current.resetSelection();
+      });
+      expect(result.current.value).toEqual([]);
+    });
+    it('should handle toggling the same value multiple times', () => {
+      const {
+        result
+      } = renderHook(() => useMultiSelect({
+        initialValue: []
+      }));
+      act(() => {
+        result.current.onChange('option1');
+      });
+      expect(result.current.value).toEqual(['option1']);
+      act(() => {
+        result.current.onChange('option1');
+      });
+      expect(result.current.value).toEqual([]);
+      act(() => {
+        result.current.onChange('option1');
+      });
+      expect(result.current.value).toEqual(['option1']);
+    });
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cds-common",
-  "version": "8.19.1",
+  "version": "8.20.0",
   "description": "Coinbase Design System - Common",
   "repository": {
     "type": "git",
@@ -39,8 +39,8 @@
   },
   "dependencies": {
     "@coinbase/cds-icons": "^5.5.1",
-    "@coinbase/cds-illustrations": "^4.26.0",
-    "@coinbase/cds-mcp-server": "^8.19.1",
+    "@coinbase/cds-illustrations": "^4.26.1",
+    "@coinbase/cds-mcp-server": "^8.20.0",
     "@coinbase/cds-utils": "^2.3.4",
     "@modelcontextprotocol/sdk": "^1.13.1",
     "d3-array": "^3.2.4",