@coinbase/cds-mcp-server 8.17.2 → 8.17.4

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

@@ -0,0 +1,120 @@
+# useEventHandler
+
+Creates event handlers for components based on the EventHandlerProvider configuration. It enables centralized event handling and analytics tracking by mapping component actions to configured handlers.
+
+## Import
+
+```tsx
+import { useEventHandler } from '@coinbase/cds-common/hooks/useEventHandler'
+```
+
+## API
+
+:::warning
+Must be used within an EventHandlerProvider. The provider's configuration determines which events are handled and how they are processed. The provider config should include:
+
+- `actionMapping?: Record<string, string>` - Optional mapping of CDS actions to handler actions
+- `handlers?: Record<EventHandlerComponent, Record<string, (eventData: EventCallbackProps) => void>>` - Event handlers for components
+
+:::
+
+### Parameters
+
+```tsx
+type EventDataEntryTypes = string | number | boolean | null | undefined;
+type EventDataEntry = EventDataEntryTypes | EventDataEntryTypes[];
+type RecursiveMapType<T> = T | Record<string, T>;
+
+type EventHandlerComponent = 'Button';
+type EventHandlerAction = string;
+type EventCustomData = Record<string, RecursiveMapType<EventDataEntry>>;
+
+type EventHandlerCustomConfig = {
+  componentName: string;
+  actions: EventHandlerAction[];
+  data?: EventCustomData;
+};
+
+function useEventHandler(
+  component: EventHandlerComponent,
+  action: EventHandlerAction,
+  eventConfig?: EventHandlerCustomConfig,
+  analyticsId?: string,
+): () => void;
+```
+
+- `component`: The component type to handle events for (currently supports 'Button')
+- `action`: The action type to handle (e.g., 'onClick', 'onHover'). This is a string type that can be mapped to custom handler actions.
+- `eventConfig` (optional): Configuration object for the event:
+  - `componentName`: Name of the component for tracking purposes
+  - `actions`: List of actions to track
+  - `data`: Additional data to pass to the handler
+- `analyticsId` (optional): A unique identifier for analytics tracking that takes precedence over eventConfig
+
+### Returns
+
+```tsx
+type EventCallbackProps = {
+  componentName?: string;
+  analyticsId?: string;
+  data?: EventCustomData;
+};
+
+type Return = () => void;
+```
+
+Returns a callback function that when invoked will trigger the event handling. The function:
+
+- Executes the configured handler for the component and action when called
+- Maps CDS actions to custom handler actions if `actionMapping` is provided in the EventHandlerProvider
+- Returns a no-op function if:
+  - No handlers are configured
+  - No eventConfig actions are provided and no analyticsId is set
+  - The handler for the component doesn't exist
+  - The action is not listed in eventConfig actions (when using eventConfig)
+  - The params object is empty
+
+## Examples
+
+### Usage
+
+```tsx live
+function ExampleWithProvider() {
+  const { show: showToast } = useToast();
+
+  // Example provider configuration with action mapping
+  const config = {
+    actionMapping: {
+      onClick: 'click', // Maps CDS onClick to custom 'click' handler
+    },
+    handlers: {
+      Button: {
+        click: ({ componentName, data }) => {
+          showToast(`Button ${componentName} clicked with data: ${JSON.stringify(data)}`);
+        },
+      },
+    },
+  };
+
+  function ButtonExample() {
+    const eventConfig = {
+      actions: ['click'], // Use mapped action name
+      componentName: 'mapped_button',
+      data: {
+        source: 'action_mapping_example',
+      },
+    };
+
+    const handleButtonClick = useEventHandler('Button', 'onClick', eventConfig);
+
+    return <Button onClick={handleButtonClick}>Click for Mapped Action</Button>;
+  }
+
+  return (
+    <EventHandlerProvider config={config}>
+      <ButtonExample />
+    </EventHandlerProvider>
+  );
+}
+```
+

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

@@ -0,0 +1,75 @@
+# useHasMounted
+
+Returns a boolean indicating if the component has mounted.
+
+## Import
+
+```tsx
+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.
+
+We recommend using `useHasMounted` whenever you use [useBreakpoints](/hooks/useBreakpoints) or any other hooks that rely on the window object to conditionally render content. This combination can be used to prevent cumulative layout shifts (CLS). This is called two pass rendering and ensures that the component has been mounted and the window object is present before painting the DOM.
+
+```jsx
+const { isPhone } = useBreakpoints();
+const hasMounted = useHasMounted();
+
+// in component render
+{
+  hasMounted && isPhone && <TextHeadline as="h3">Welcome {username}!</TextHeadline>;
+}
+```
+
+### Basic usage
+
+```tsx live
+function Example() {
+  const hasMounted = useHasMounted();
+
+  return <TextHeadline>Component has {hasMounted ? 'mounted' : 'not mounted'}</TextHeadline>;
+}
+```
+
+### Preventing Hydration Mismatch
+
+```tsx live
+function Example() {
+  const hasMounted = useHasMounted();
+  const [currentTime, setCurrentTime] = useState('');
+
+  useEffect(() => {
+    // Only run client-side code after mounting
+    if (hasMounted) {
+      setCurrentTime(new Date().toLocaleTimeString());
+    }
+  }, [hasMounted]);
+
+  return <TextHeadline>{hasMounted ? `Current time: ${currentTime}` : 'Loading...'}</TextHeadline>;
+}
+```
+

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

@@ -0,0 +1,58 @@
+# useIsoEffect
+
+A safe way of calling useLayoutEffect only on the client. Does nothing on the server.
+
+## Import
+
+```tsx
+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
+
+```tsx live
+function Example() {
+  const [position, setPosition] = useState({ x: 0, y: 0 });
+
+  useIsoEffect(() => {
+    const updatePosition = (e: MouseEvent) => {
+      setPosition({ x: e.clientX, y: e.clientY });
+    };
+
+    window.addEventListener('mousemove', updatePosition);
+
+    // Cleanup function to remove event listener
+    return () => {
+      window.removeEventListener('mousemove', updatePosition);
+    };
+  }, []); // Empty deps array means this effect runs once on mount
+
+  return (
+    <VStack gap={2}>
+      <TextHeadline>Mouse Position</TextHeadline>
+      <Text>X: {position.x}</Text>
+      <Text>Y: {position.y}</Text>
+    </VStack>
+  );
+}
+```
+

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

@@ -0,0 +1,114 @@
+# useMediaQuery
+
+Subscribes to window.matchMedia changes with SSR support.
+
+## Import
+
+```tsx
+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
+
+Use the `useMediaQuery` hook to call `window.matchMedia` with SSR support. It must be used within a MediaQueryProvider component.
+
+This hook is ideal for conditional rendering based on viewport size, user preferences, or other media features.
+
+It subscribes to a single state shared by all media queries to ensure Suspense works correctly.
+
+[See the MediaQueryProvider docs here →](/components/other/MediaQueryProvider)
+
+:::warning
+Do not use `useMediaQuery` for responsive styles. Use CSS media queries or [the `StyleProps` API](/getting-started/styling#responsive-styles) for responsive styles.
+:::
+
+```tsx live
+() => {
+  const Page = () => {
+    const isMobile = useMediaQuery('(max-width: 767px)');
+    const prefersDarkMode = useMediaQuery('(prefers-color-scheme: dark)');
+    return <JSONCodeBlock json={{ isMobile, prefersDarkMode }} />;
+  };
+
+  const App = () => (
+    <MediaQueryProvider>
+      <Page />
+    </MediaQueryProvider>
+  );
+
+  return <App />;
+};
+```
+
+### SSR support
+
+The `useMediaQuery` hook integrates with the MediaQueryProvider `defaultValues` to provide consistent behavior between server and client rendering.
+
+On the client the native `window.matchMedia` API is used. On the server the hook solves the `window.matchMedia` queries by comparing to the MediaQueryProvider `defaultValues`.
+
+The comparison against `defaultValues` during SSR is limited: it cannot solve highly complex media queries. If a complex query cannot be solved during SSR the hook will simply return `false`, and the query can still be solved by `window.matchMedia` on the client.
+
+:::tip
+You can populate the MediaQueryProvider `defaultValues` with user preferences, cookies, etc. to ensure the correct styles are applied on the server.
+:::
+
+#### Simple queries that can be solved during SSR
+
+- Simple media queries
+- `width`, `min-width`, `max-width`, `height`, `min-height`, and `max-height` with pixel or em units
+- `prefers-contrast` and `prefers-color-scheme`
+- Logical `and` operator
+
+#### Complex queries that cannot be solved during SSR
+
+- Multiple comma-delimited values
+- Logical `not` and `or` operators
+- Mathematical `<=` and `>=` operators
+- Complex or nested queries
+- Other media types or features
+
+[See the MediaQueryProvider SSR docs here &rarr;](/components/other/MediaQueryProvider#ssr-support)
+
+### Complex queries on the client
+
+Complex queries cannot be solved during SSR. They are solved on the client by calling `window.matchMedia`.
+
+```tsx live
+() => {
+  const isPortrait = useMediaQuery('(orientation: portrait)');
+  const isHighDPI = useMediaQuery('(min-resolution: 2dppx)');
+  const isTouch = useMediaQuery('(pointer: coarse)');
+  const isMediumHeight = useMediaQuery('(min-height: 600px) and (max-height: 900px)');
+
+  const complexQuery = useMediaQuery(
+    `((width >= 1200px) and (orientation: landscape)),
+    (width < 560px) or ((width > 768px) and (width < 900px))`,
+  );
+
+  return <JSONCodeBlock json={{ isPortrait, isHighDPI, isTouch, isMediumHeight, complexQuery }} />;
+};
+```
+

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>
+  );
+}
+```
+