@coinbase/cds-mcp-server 8.17.3 → 8.17.4

package/mcp-docs/web/hooks/useHasMounted.txt

@@ -1,5 +1,5 @@
-
 # useHasMounted
+
 Returns a boolean indicating if the component has mounted.
 
 ## Import
@@ -8,6 +8,27 @@ Returns a boolean indicating if the component has mounted.
 import { useHasMounted } from '@coinbase/cds-web/hooks/useHasMounted'
 ```
 
+## API
+
+### Parameters
+
+The `useHasMounted` hook does not accept any parameters.
+
+### Returns
+
+```tsx
+type Return = boolean;
+```
+
+Returns a boolean:
+
+- `true`: Component has mounted and is running in a browser environment
+- `false`: Component hasn't mounted yet or is running in a non-browser environment (e.g., server-side rendering)
+
+:::tip
+This hook is useful for preventing hydration mismatches and ensuring code only runs in the browser environment.
+:::
+
 ## Examples
 
 `useHasMounted` should be used when conditionally rendering components or styles in SSR or SSG environments.
@@ -52,4 +73,3 @@ function Example() {
 }
 ```
 
-

package/mcp-docs/web/hooks/useIsoEffect.txt

@@ -1,5 +1,5 @@
-
 # useIsoEffect
+
 A safe way of calling useLayoutEffect only on the client. Does nothing on the server.
 
 ## Import
@@ -8,6 +8,23 @@ A safe way of calling useLayoutEffect only on the client. Does nothing on the se
 import { useIsoEffect } from '@coinbase/cds-web/hooks/useIsoEffect'
 ```
 
+## API
+
+### Parameters
+
+The `useIsoEffect` hook accepts the same parameters as React's `useEffect` and `useLayoutEffect`:
+
+- `effect: () => (void | (() => void))` - The effect function to run
+- `deps?: any[]` - Optional array of dependencies
+
+### Returns
+
+Returns nothing (void).
+
+:::tip
+This hook automatically uses `useLayoutEffect` when running in the browser and falls back to `useEffect` during server-side rendering. This prevents warnings and ensures proper timing of effects across different environments.
+:::
+
 ## Examples
 
 ### Usage
@@ -39,4 +56,3 @@ function Example() {
 }
 ```
 
-

package/mcp-docs/web/hooks/useMediaQuery.txt

@@ -1,5 +1,5 @@
-
 # useMediaQuery
+
 Subscribes to window.matchMedia changes with SSR support.
 
 ## Import
@@ -8,6 +8,27 @@ Subscribes to window.matchMedia changes with SSR support.
 import { useMediaQuery } from '@coinbase/cds-web/hooks/useMediaQuery'
 ```
 
+## API
+
+### Parameters
+
+The `useMediaQuery` hook accepts a single parameter:
+
+- `query: string` - A CSS media query string to subscribe to. Can include:
+  - **Viewport dimensions**: `(min-width: 768px)`, `(max-width: 767px)`, `(width: 1024px)`
+  - **User preferences**: `(prefers-color-scheme: dark)`, `(prefers-reduced-motion: reduce)`
+  - **Device features**: `(orientation: portrait)`, `(pointer: coarse)`, `(hover: hover)`
+  - **Complex queries**: Combined with `and`, `not`, or `,` operators
+
+### Returns
+
+Returns a `boolean` that indicates whether the media query matches:
+
+- `true` - The media query conditions are currently met
+- `false` - The media query conditions are not met
+- Automatically updates when the media query state changes
+- Uses MediaQueryProvider's default values during server-side rendering
+
 ## Examples
 
 ### Basic usage
@@ -91,4 +112,3 @@ Complex queries cannot be solved during SSR. They are solved on the client by ca
 };
 ```
 
-

package/mcp-docs/web/hooks/useMergeRefs.txt

@@ -0,0 +1,116 @@
+# useMergeRefs
+
+Combines multiple refs into a single ref callback, allowing a component to work with multiple ref instances simultaneously. Useful when you need to combine refs from different sources, such as forwarded refs and internal component state.
+
+## Import
+
+```tsx
+import { useMergeRefs } from '@coinbase/cds-common/hooks/useMergeRefs'
+```
+
+## API
+
+### Parameters
+
+The `useMergeRefs` hook accepts a spread of refs as its parameter:
+
+- `...refs: (React.MutableRefObject<T> | React.LegacyRef<T> | undefined | null)[]` - An array of refs to merge. Can include:
+  - `MutableRefObject` - Object-based refs created with `useRef`
+  - `LegacyRef` - Function-based refs or string refs (legacy)
+  - `undefined` or `null` - Optional refs that might not be provided
+
+### Returns
+
+Returns a `React.RefCallback<T>` function that can be used as a ref:
+
+- The returned callback handles updating all provided refs when the referenced element changes
+- Properly handles both object-based and function-based refs
+- Safely handles undefined or null refs by ignoring them
+
+:::tip
+This hook is particularly useful when working with components that need to combine multiple refs, such as when using both forwarded refs and internal state refs, or when composing components that each require their own ref.
+:::
+
+## Examples
+
+### Basic usage
+
+```tsx live
+function Example() {
+  // Create an internal ref for component logic
+  const internalRef = useRef<HTMLDivElement>(null);
+
+  // Simulating a forwarded ref from parent
+  const Component = forwardRef((props, forwardedRef) => {
+    // Merge the internal ref with the forwarded ref
+    const refs = useMergeRefs(forwardedRef, internalRef);
+
+    return (
+      <Box ref={refs} padding={3} background="bgAlternate" borderRadius={300}>
+        <TextBody>This box uses a merged ref</TextBody>
+      </Box>
+    );
+  });
+
+  return <Component />;
+}
+```
+
+### With Multiple Refs
+
+```tsx live
+function Example() {
+  const firstRef = useRef<HTMLDivElement>(null);
+  const secondRef = useRef<HTMLDivElement>(null);
+  const thirdRef = useRef<HTMLDivElement>(null);
+
+  // Function to check if all refs are properly set
+  const checkRefs = () => {
+    const allRefsSet = firstRef.current && secondRef.current && thirdRef.current;
+    alert(`All refs are ${allRefsSet ? 'set' : 'not set'}`);
+  };
+
+  // Merge all three refs
+  const mergedRefs = useMergeRefs(firstRef, secondRef, thirdRef);
+
+  return (
+    <VStack gap={2}>
+      <Box ref={mergedRefs} padding={3} background="bgAlternate" borderRadius={300}>
+        <TextBody>This element is referenced by three refs</TextBody>
+      </Box>
+      <Button onClick={checkRefs}>Check Refs</Button>
+    </VStack>
+  );
+}
+```
+
+### With Function Ref
+
+```tsx live
+function Example() {
+  const [elementWidth, setElementWidth] = useState<number>(0);
+
+  // Create a function ref that measures the element
+  const functionRef = (element: HTMLDivElement | null) => {
+    if (element) {
+      setElementWidth(element.offsetWidth);
+    }
+  };
+
+  // Create an object ref for other purposes
+  const objectRef = useRef<HTMLDivElement>(null);
+
+  // Merge both types of refs
+  const refs = useMergeRefs(functionRef, objectRef);
+
+  return (
+    <VStack gap={2}>
+      <Box ref={refs} padding={3} background="bgAlternate" borderRadius={300} width="100%">
+        <TextBody>This box uses both function and object refs</TextBody>
+      </Box>
+      <TextBody>Box width: {elementWidth}px</TextBody>
+    </VStack>
+  );
+}
+```
+

package/mcp-docs/web/hooks/useOverlayContentContext.txt

@@ -1,5 +1,5 @@
-
 # useOverlayContentContext
+
 A React context and hook for detecting if components are rendered inside overlay containers like modals, drawers, tours, and trays.
 
 ## Import
@@ -8,6 +8,69 @@ A React context and hook for detecting if components are rendered inside overlay
 import { OverlayContentContext, useOverlayContentContext } from '@coinbase/cds-common/overlays/OverlayContentContext'
 ```
 
+## API
+
+### Parameters
+
+The `useOverlayContentContext` hook accepts no parameters.
+
+### Returns
+
+Returns an `OverlayContentContextValue` object with overlay state information:
+
+- `isOverlay?: boolean` - True if inside any overlay component (automatically derived from other values if not explicitly set)
+- `isModal?: boolean` - True if inside a Modal component
+- `isDrawer?: boolean` - True if inside a Drawer or Tray component
+- `isTour?: boolean` - True if inside a Tour component
+
+All properties are optional and will be `undefined` when outside of overlay contexts.
+
+:::tip
+This hook is safe to use anywhere in your component tree - it does not throw an error when used outside a provider. When `isOverlay` is not explicitly provided, it will be automatically derived as `true` if any of the other overlay type flags are `true`.
+:::
+
+### OverlayContentContext
+
+The React context that provides overlay state information. Can be used directly with `React.useContext` or through the `useOverlayContentContext` hook.
+
+#### Context Value Type
+
+```typescript
+type OverlayContentContextValue = {
+  isOverlay?: boolean;
+  isModal?: boolean;
+  isDrawer?: boolean;
+  isTour?: boolean;
+};
+```
+
+### Provider Usage
+
+```tsx
+import { OverlayContentContext } from '@coinbase/cds-common/overlays/OverlayContentContext';
+
+function MyOverlayComponent() {
+  const contextValue = {
+    isModal: true,
+    isDrawer: false,
+    isTour: false,
+    // isOverlay will be automatically derived as true
+  };
+
+  return (
+    <OverlayContentContext.Provider value={contextValue}>
+      {/* Your overlay content */}
+    </OverlayContentContext.Provider>
+  );
+}
+```
+
+### Automatic Derivation
+
+If `isOverlay` is not explicitly provided in the context value, it will be automatically derived as `true` when any of `isModal`, `isDrawer`, or `isTour` is `true`. This ensures consistent behavior across the system.
+
+**Important**: When adding new overlay types to the `OverlayContentContextValue` type, remember to update the derivation logic in the `useOverlayContentContext` hook.
+
 ## Examples
 
 The `useOverlayContentContext` hook provides information about whether a component is rendered inside various types of overlay containers. This is useful for conditional rendering and styling based on the overlay context.
@@ -214,4 +277,3 @@ function StylingExample() {
 }
 ```
 
-

package/mcp-docs/web/hooks/usePreviousValue.txt

@@ -0,0 +1,74 @@
+# usePreviousValue
+
+Returns the previous value of a given variable, useful for comparing current and previous states in effects or for tracking changes over time.
+
+## Import
+
+```tsx
+import { usePreviousValue } from '@coinbase/cds-common/hooks/usePreviousValue'
+```
+
+## API
+
+### Parameters
+
+The `usePreviousValue` hook accepts a single parameter:
+
+- `value: T` - The value to track. Can be of any type.
+
+### Returns
+
+Returns the previous value of type `T | undefined`:
+
+- Returns `undefined` on the first render
+- Returns the previous value of the tracked value on subsequent renders
+
+:::tip
+This hook is useful for comparing the current value with its previous state, such as in animations, transitions, or when you need to react to value changes. The hook uses a ref to store the previous value, ensuring it persists between renders.
+:::
+
+## Examples
+
+### Basic usage
+
+```tsx live
+function Example() {
+  const [count, setCount] = useState(0);
+  const previousCount = usePreviousValue(count);
+
+  return (
+    <VStack gap={3} alignItems="start">
+      <VStack gap={1}>
+        <TextHeadline>Current count: {count}</TextHeadline>
+        <TextHeadline>Previous count: {previousCount ?? 'None'}</TextHeadline>
+      </VStack>
+      <Button onClick={() => setCount(count + 1)}>Increment</Button>
+    </VStack>
+  );
+}
+```
+
+### With Complex Values
+
+```tsx live
+function Example() {
+  const [user, setUser] = useState({ name: 'John', age: 25 });
+  const previousUser = usePreviousValue(user);
+
+  const updateAge = () => {
+    setUser((prev) => ({ ...prev, age: prev.age + 1 }));
+  };
+
+  return (
+    <VStack gap={3} alignItems="start">
+      <VStack gap={1}>
+        <TextHeadline>Name: {user.name}</TextHeadline>
+        <TextHeadline>Age: {user.age}</TextHeadline>
+        <TextHeadline>Previous age: {previousUser?.age ?? 'None'}</TextHeadline>
+      </VStack>
+      <Button onClick={updateAge}>Add Year</Button>
+    </VStack>
+  );
+}
+```
+

package/mcp-docs/web/hooks/useRefMap.txt

@@ -0,0 +1,178 @@
+# useRefMap
+
+Manages a collection of refs using a key-value map structure, allowing dynamic registration and retrieval of refs by their unique identifiers. Commonly used in components that need to track multiple DOM elements, such as tabs, tours, or complex navigation systems.
+
+## Import
+
+```tsx
+import { useRefMap } from '@coinbase/cds-common/hooks/useRefMap'
+```
+
+## API
+
+### Parameters
+
+The `useRefMap` hook accepts an optional configuration object:
+
+- `options?: RefMapOptions<RefValue>` - Configuration options for the ref map
+  - `initialRefMap?: Record<string, RefValue>` - Optional initial map of refs
+
+The generic type `RefValue` represents the type of values stored in the ref map (typically `HTMLElement` or a specific element type).
+
+### Returns
+
+Returns a `RefMapApi<RefValue>` object with the following properties:
+
+- `refs: Record<string, RefValue>` - The current map of all registered refs
+- `getRef: (id: string) => RefValue | null` - Function to retrieve a ref by its ID
+- `registerRef: (id: string, ref: RefValue) => void` - Function to register a new ref with an ID
+
+:::tip
+This hook is particularly useful when working with components that need to manage multiple refs, such as in tour guides where elements need to be highlighted, or in tab systems where tab panels need to be referenced. The hook maintains a stable reference to the ref map and its utility functions across renders.
+:::
+
+## Examples
+
+### Basic usage
+
+```tsx live
+function Example() {
+  const { registerRef, getRef } = useRefMap<HTMLDivElement>();
+  const toast = useToast();
+
+  const handleClick = () => {
+    // Get the element by its ID and log its dimensions
+    const element = getRef('box1');
+    if (element) {
+      toast.show(`Box dimensions: ${element.offsetWidth}x${element.offsetHeight}`);
+    }
+  };
+
+  return (
+    <VStack gap={2}>
+      <Box
+        ref={(el) => el && registerRef('box1', el)}
+        padding={3}
+        background="bgAlternate"
+        borderRadius={300}
+      >
+        <TextBody>This box is registered with ID 'box1'</TextBody>
+      </Box>
+      <Button onClick={handleClick}>Get Box Dimensions</Button>
+    </VStack>
+  );
+}
+```
+
+### With Multiple Elements
+
+```tsx live
+function Example() {
+  const { registerRef, getRef } = useRefMap<HTMLDivElement>();
+  const [activeId, setActiveId] = useState<string | null>(null);
+
+  const highlightElement = (id: string) => {
+    // Reset previous highlight
+    if (activeId) {
+      const prevElement = getRef(activeId);
+      if (prevElement) {
+        prevElement.style.outline = 'none';
+      }
+    }
+
+    // Highlight new element
+    const element = getRef(id);
+    if (element) {
+      element.style.outline = '2px solid var(--color-fgPrimary)';
+      setActiveId(id);
+    }
+  };
+
+  return (
+    <VStack gap={3}>
+      <HStack gap={2}>
+        <Button onClick={() => highlightElement('box1')}>Highlight Box 1</Button>
+        <Button onClick={() => highlightElement('box2')}>Highlight Box 2</Button>
+        <Button onClick={() => highlightElement('box3')}>Highlight Box 3</Button>
+      </HStack>
+
+      <VStack gap={2}>
+        <Box
+          ref={(el) => el && registerRef('box1', el)}
+          padding={3}
+          background="bgAlternate"
+          borderRadius={300}
+        >
+          <TextBody>Box 1</TextBody>
+        </Box>
+
+        <Box
+          ref={(el) => el && registerRef('box2', el)}
+          padding={3}
+          background="bgAlternate"
+          borderRadius={300}
+        >
+          <TextBody>Box 2</TextBody>
+        </Box>
+
+        <Box
+          ref={(el) => el && registerRef('box3', el)}
+          padding={3}
+          background="bgAlternate"
+          borderRadius={300}
+        >
+          <TextBody>Box 3</TextBody>
+        </Box>
+      </VStack>
+    </VStack>
+  );
+}
+```
+
+### With Initial Refs
+
+```tsx live
+function Example() {
+  // Create initial refs map
+  const box1Ref = useRef<HTMLDivElement>(null);
+  const box2Ref = useRef<HTMLDivElement>(null);
+
+  const initialRefs = {
+    box1: box1Ref.current,
+    box2: box2Ref.current,
+  };
+
+  const { refs, registerRef } = useRefMap<HTMLDivElement>({
+    initialRefMap: initialRefs,
+  });
+
+  const logRefs = () => {
+    console.log('Current refs:', refs);
+  };
+
+  return (
+    <VStack gap={2}>
+      <Box
+        ref={(el) => el && registerRef('box1', el)}
+        padding={3}
+        background="bgAlternate"
+        borderRadius={300}
+      >
+        <TextBody>Box 1</TextBody>
+      </Box>
+
+      <Box
+        ref={(el) => el && registerRef('box2', el)}
+        padding={3}
+        background="bgAlternate"
+        borderRadius={300}
+      >
+        <TextBody>Box 2</TextBody>
+      </Box>
+
+      <Button onClick={logRefs}>Log Refs</Button>
+    </VStack>
+  );
+}
+```
+

package/mcp-docs/web/hooks/useScrollBlocker.txt

@@ -1,5 +1,5 @@
-
 # useScrollBlocker
+
 Block and unblock page scrolling.
 
 ## Import
@@ -8,6 +8,26 @@ Block and unblock page scrolling.
 import { useScrollBlocker } from '@coinbase/cds-web/hooks/useScrollBlocker'
 ```
 
+## API
+
+### Parameters
+
+The `useScrollBlocker` hook does not accept any parameters.
+
+### Returns
+
+```tsx
+type Return = (shouldBlock: boolean) => void;
+```
+
+Returns a function that takes a boolean parameter to control scroll blocking:
+
+- `shouldBlock`: When `true`, blocks page scrolling. When `false`, re-enables scrolling.
+
+:::tip
+This hook is useful for temporarily disabling page scrolling, such as when displaying modals or overlays. It automatically handles scroll bar width compensation to prevent layout shifts.
+:::
+
 ## Examples
 
 ### Basic usage
@@ -60,4 +80,3 @@ function Example() {
 }
 ```
 
-