@coinbase/cds-mcp-server 8.17.2 → 8.17.4

package/mcp-docs/mobile/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/mobile/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/mobile/hooks/useOverlayContentContext.txt

@@ -0,0 +1,280 @@
+# useOverlayContentContext
+
+A React context and hook for detecting if components are rendered inside overlay containers like modals, drawers, tours, and trays.
+
+## Import
+
+```tsx
+import { OverlayContentContext, useOverlayContentContext } from '@coinbase/cds-common/overlays/OverlayContentContext'
+```
+
+## API
+
+### useOverlayContentContext
+
+Returns the current overlay context information for mobile applications. This hook does not throw an error when used outside a provider, making it safe to use anywhere in your component tree.
+
+#### Return Value
+
+The hook returns an object with the following properties:
+
+- **`isOverlay?: boolean`** - True if inside any overlay component (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
+
+### OverlayContentContext
+
+The React context that provides overlay state information for mobile applications. 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 MyMobileOverlayComponent() {
+  const contextValue = {
+    isModal: true,
+    isDrawer: false,
+    isTour: false,
+    // isOverlay will be automatically derived as true
+  };
+
+  return (
+    <OverlayContentContext.Provider value={contextValue}>
+      {/* Your mobile overlay content */}
+    </OverlayContentContext.Provider>
+  );
+}
+```
+
+### Mobile Considerations
+
+On mobile platforms, overlay contexts are particularly useful for:
+
+- **Touch Handling**: Adjusting touch behaviors based on overlay type
+- **Safe Areas**: Managing safe area insets differently in overlays vs full-screen content
+- **Navigation**: Preventing or modifying navigation gestures in overlay contexts
+- **Accessibility**: Providing appropriate focus management for screen readers
+
+### 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 on mobile. This is useful for conditional rendering and behavior based on the overlay context.
+
+### Basic usage
+
+```tsx
+function ExampleComponent() {
+  const { isOverlay, isModal, isDrawer, isTour } = useOverlayContentContext();
+
+  return (
+    <VStack gap={2}>
+      <Text variant="title3">Overlay Context Information</Text>
+      <Text>Is inside any overlay: {isOverlay ? 'Yes' : 'No'}</Text>
+      <Text>Is inside modal: {isModal ? 'Yes' : 'No'}</Text>
+      <Text>Is inside drawer/tray: {isDrawer ? 'Yes' : 'No'}</Text>
+      <Text>Is inside tour: {isTour ? 'Yes' : 'No'}</Text>
+    </VStack>
+  );
+}
+```
+
+### Real Modal Example
+
+This example shows how the hook works inside an actual mobile modal:
+
+```tsx
+function ModalExample() {
+  const { openModal } = useModal();
+
+  const ExampleComponent = () => {
+    const { isOverlay, isModal, isDrawer, isTour } = useOverlayContentContext();
+
+    return (
+      <VStack gap={2}>
+        <Text variant="title3">Overlay Context Information</Text>
+        <Text>Is inside any overlay: {isOverlay ? 'Yes' : 'No'}</Text>
+        <Text>Is inside modal: {isModal ? 'Yes' : 'No'}</Text>
+        <Text>Is inside drawer/tray: {isDrawer ? 'Yes' : 'No'}</Text>
+        <Text>Is inside tour: {isTour ? 'Yes' : 'No'}</Text>
+      </VStack>
+    );
+  };
+
+  const ModalContent = () => {
+    return (
+      <VStack gap={3}>
+        <Text>This content is rendered inside a mobile modal. Notice the context values:</Text>
+        <VStack gap={2} padding={3} backgroundColor="surface1">
+          <ExampleComponent />
+        </VStack>
+        <Text color="muted" variant="caption">
+          The hook automatically detects it's inside a modal context on mobile!
+        </Text>
+      </VStack>
+    );
+  };
+
+  const handleOpenModal = () => {
+    openModal({
+      children: <ModalContent />,
+      header: 'Mobile Modal with Context',
+    });
+  };
+
+  return (
+    <VStack gap={3}>
+      <VStack gap={2} padding={3} backgroundColor="surface2">
+        <Text variant="title3">Outside Modal</Text>
+        <ExampleComponent />
+      </VStack>
+
+      <Button onPress={handleOpenModal}>Open Modal to See Context Change</Button>
+    </VStack>
+  );
+}
+```
+
+### Using the Context Provider
+
+You can also use the `OverlayContentContext` directly to provide context values:
+
+```tsx
+function ContextProviderExample() {
+  const ExampleComponent = () => {
+    const { isOverlay, isModal, isDrawer, isTour } = useOverlayContentContext();
+
+    return (
+      <VStack gap={2}>
+        <Text variant="title3">Overlay Context Information</Text>
+        <Text>Is inside any overlay: {isOverlay ? 'Yes' : 'No'}</Text>
+        <Text>Is inside modal: {isModal ? 'Yes' : 'No'}</Text>
+        <Text>Is inside drawer/tray: {isDrawer ? 'Yes' : 'No'}</Text>
+        <Text>Is inside tour: {isTour ? 'Yes' : 'No'}</Text>
+      </VStack>
+    );
+  };
+
+  const contextValue = {
+    isModal: true,
+    isDrawer: false,
+    isTour: false,
+  };
+
+  return (
+    <OverlayContentContext.Provider value={contextValue}>
+      <VStack gap={2} padding={3} backgroundColor="surface2">
+        <Text variant="title3">Inside Context Provider</Text>
+        <ExampleComponent />
+      </VStack>
+    </OverlayContentContext.Provider>
+  );
+}
+```
+
+### Conditional Rendering
+
+Use the hook to conditionally render content based on overlay context:
+
+```tsx
+function ConditionalRenderingExample() {
+  const { openModal } = useModal();
+
+  const ConditionalContent = () => {
+    const { isOverlay, isModal } = useOverlayContentContext();
+
+    return (
+      <VStack gap={2}>
+        <Text variant="title3">Conditional Content</Text>
+        {isOverlay ? (
+          <VStack gap={1}>
+            <Text color="positive">✓ This content shows when inside an overlay</Text>
+            {isModal && <Text color="primary">🎯 Specifically inside a modal!</Text>}
+          </VStack>
+        ) : (
+          <Text color="muted">This content shows when not in an overlay</Text>
+        )}
+      </VStack>
+    );
+  };
+
+  const handleOpenConditionalModal = () => {
+    openModal({
+      children: <ConditionalContent />,
+      header: 'Conditional Content Demo',
+    });
+  };
+
+  return (
+    <VStack gap={3}>
+      <VStack gap={2} padding={3} backgroundColor="surface2">
+        <Text variant="title3">Outside Modal</Text>
+        <ConditionalContent />
+      </VStack>
+
+      <Button onPress={handleOpenConditionalModal}>Open Modal to See Different Content</Button>
+    </VStack>
+  );
+}
+```
+
+### Mobile-Specific Behavior
+
+```tsx
+function MobileBehaviorExample() {
+  const { isModal, isDrawer, isTour } = useOverlayContentContext();
+
+  // Adjust touch behavior based on overlay type
+  const getTouchHandler = () => {
+    if (isModal) return handleModalTouch;
+    if (isDrawer) return handleDrawerTouch;
+    if (isTour) return handleTourTouch;
+    return handleDefaultTouch;
+  };
+
+  return (
+    <Pressable onPress={getTouchHandler()}>
+      <VStack gap={2} padding={3}>
+        <Text variant="title3">Touch Behavior</Text>
+        <Text>Touch handling adapts to overlay context</Text>
+      </VStack>
+    </Pressable>
+  );
+}
+```
+
+### Safe Area Adjustments
+
+```tsx
+function SafeAreaExample() {
+  const { isModal, isDrawer } = useOverlayContentContext();
+
+  // Adjust safe area behavior for different overlay types
+  const shouldUseSafeArea = !isModal && !isDrawer;
+
+  return (
+    <VStack gap={2} padding={3} paddingTop={shouldUseSafeArea ? 'safeTop' : 3}>
+      <Text variant="title3">Safe Area Handling</Text>
+      <Text>Safe area behavior adapts to overlay context</Text>
+    </VStack>
+  );
+}
+```
+

package/mcp-docs/mobile/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>
+  );
+}
+```
+