@coinbase/cds-mcp-server 8.17.3 → 8.17.4

package/mcp-docs/mobile/getting-started/theming.txt

@@ -0,0 +1,286 @@
+# theming
+
+The theme contains design tokens like colors, fonts, spacing, and more. The ThemeProvider provides access to these values via CSS Variables for web, and React Context for both web and React Native.
+
+import { defaultTheme } from '@coinbase/cds-mobile/themes/defaultTheme';
+import { JSONCodeBlock } from '@site/src/components/page/JSONCodeBlock';
+
+### ThemeProvider component
+
+The ThemeProvider provides the theme context to all child components.
+
+You must pass the `theme` prop to configure the theme, and the `activeColorScheme` prop to set light or dark mode.
+
+[See the ThemeProvider docs here →](/components/other/ThemeProvider)
+
+```tsx
+import { ThemeProvider } from '@coinbase/cds-mobile/system/ThemeProvider';
+import { defaultTheme } from '@coinbase/cds-mobile/themes/defaultTheme';
+
+const App = () => (
+  <ThemeProvider theme={defaultTheme} activeColorScheme="light">
+    {/* Your app components */}
+  </ThemeProvider>
+);
+```
+
+:::tip
+Changing the `activeColorScheme` automatically updates the values returned from the `useTheme` hook.
+:::
+
+#### `useTheme` hook
+
+The `useTheme` hook provides access to the current `theme` and `activeColorScheme`.
+
+The `color` and `spectrum` objects automatically change based on the `activeColorScheme`.
+
+[See the `useTheme` docs here &rarr;](/hooks/useTheme)
+
+```jsx
+const theme = useTheme();
+theme.activeColorScheme; // "light" or "dark"
+theme.spectrum; // Resolves to lightSpectrum or darkSpectrum, depends on activeColorScheme
+theme.color; // Resolves to lightColor or darkColor, depends on activeColorScheme
+theme.color.bgPrimary; // "rgb(0,82,255)" or "rgb(87,139,250)", depends on activeColorScheme
+theme.space[2]; // 16
+theme.borderRadius[200]; // 8
+theme.fontSize.display3; // 40
+```
+
+#### Nested themes
+
+ThemeProviders can be nested to create theme overrides for specific sections.
+
+```jsx
+<ThemeProvider theme={defaultTheme} activeColorScheme="light">
+  {/* Default theme in light color scheme */}
+
+  <ThemeProvider theme={customTheme} activeColorScheme="dark">
+    {/* Custom theme in dark color scheme */}
+  </ThemeProvider>
+</ThemeProvider>
+```
+
+When nesting, you may want to override specific color values from the current theme. Overrides must be conditionally applied because we don't enforce that a theme has both light and dark colors defined.
+
+```jsx
+// Override parts of the parent theme
+const theme = useTheme();
+const customTheme = {
+  ...theme,
+  ...(theme.lightColor &&
+    theme.lightSpectrum && {
+      lightColor: {
+        ...theme.lightColor,
+        bg: `rgb(${theme.lightSpectrum.orange50})`,
+        bgPrimary: `rgb(${theme.lightSpectrum.red20})`,
+        bgSecondary: `rgb(${theme.lightSpectrum.blue50})`,
+      },
+    }),
+  ...(theme.darkColor &&
+    theme.darkSpectrum && {
+      darkColor: {
+        ...theme.darkColor,
+        bg: `rgb(${theme.darkSpectrum.orange50})`,
+        bgPrimary: `rgb(${theme.darkSpectrum.red20})`,
+        bgSecondary: `rgb(${theme.darkSpectrum.blue50})`,
+      },
+    }),
+} as const satisfies Theme;
+```
+
+#### Theme inheritence
+
+Nested ThemeProviders do not automatically inherit the theme from their parent provider. You can manually inherit the theme with the `useTheme` hook.
+
+```jsx
+const Example = () => {
+  // Pass the parent theme down to another ThemeProvider
+  const theme = useTheme();
+  return (
+    <ThemeProvider theme={theme} activeColorScheme={theme.activeColorScheme}>
+      {children}
+    </ThemeProvider>
+  );
+};
+```
+
+#### InvertedThemeProvider component
+
+The InvertedThemeProvider automatically inherits from its parent theme and flips the `activeColorScheme` to the opposite value.
+
+```jsx
+<ThemeProvider theme={defaultTheme} activeColorScheme="light">
+  {/* Default theme in light color scheme */}
+
+  <InvertedThemeProvider>
+    {/* Default theme in inverse (dark) color scheme */}
+  </InvertedThemeProvider>
+</ThemeProvider>
+```
+
+### `ThemeConfig` vs `Theme` type
+
+Use the `ThemeConfig` type when creating a theme, or when passing the `theme` prop to the ThemeProvider.
+
+Use the `Theme` type for the return value of the `useTheme` hook. The `Theme` type includes all the properties of `ThemeConfig` - plus the `activeColorScheme`, `color`, and `spectrum` properties.
+
+[See the `ThemeConfig` type definition here &rarr;](https://github.com/coinbase/cds/blob/master/packages/mobile/src/core/theme.ts#L11)
+
+[See the `Theme` type definition here &rarr;](https://github.com/coinbase/cds/blob/master/packages/mobile/src/core/theme.ts#L50)
+
+:::tip
+Although the `Theme` type includes extra properties, you can still pass the `useTheme` return value directly to the ThemeProvider `theme` prop as shown in the [theme inheritence section.](#theme-inheritence)
+:::
+
+### `spectrum` vs `color` values
+
+The `spectrum` variables are partial `"r,g,b"` strings while `color` variables are complete CSS color values.
+
+Both `color` and `spectrum` behave inversely in light and dark mode.
+
+For example with the `defaultTheme` config, `spectrum.gray0` is white in light mode and black in dark mode. We use `spectrum` variables to define `color` variables, so this same behavior extends to `color`.
+
+The `color` variables have semantic names which describe their application in the UI. You should prefer to use `color` variables instead of `spectrum` variables when styling UI.
+
+```jsx
+const theme = useTheme();
+theme.lightSpectrum.gray0; // "255,255,255"
+theme.darkSpectrum.gray0; // "10,11,13"
+theme.spectrum.gray100; // "255,255,255" or "10,11,13", depends on activeColorScheme
+theme.lightColor.bg; // "rgb(255,255,255)"
+theme.darkColor.bg; // "rgb(10,11,13)"
+theme.color.bg; // "rgb(255,255,255)" or "rgb(10,11,13)", depends on activeColorScheme
+```
+
+:::tip
+Prefer to use semantic `color` variables for UI styles. Direct usage of `spectrum` values should be a rare exception.
+:::
+
+### Creating a theme
+#### Defining colors
+
+We recommend defining `lightSpectrum` and `darkSpectrum` as separate objects. This makes it easier to reference them when defining the `lightColor` and `darkColor` values.
+
+The `lightColor` and `darkColor` values must be raw color strings (hex, rgba, hsl, etc), they cannot contain CSS Variables or CSS functions.
+
+#### The `space` scale
+
+CDS expects that the theme `space` values will be multiples of some base number.
+
+For example, the `defaultTheme` uses `8px` as the base number:
+
+```jsx
+theme.space[0]; // 0
+theme.space[0.25]; // 2
+theme.space[0.5]; // 4
+theme.space[1]; // 8
+theme.space[1.5]; // 12
+theme.space[2]; // 16
+theme.space[3]; // 24
+// etc.
+```
+
+While it is possible to customize the `space` values in any way, deviating from this expectation may produce broken styles.
+
+#### Example new theme
+
+In this example we'll start with the `defaultTheme` and customize a couple values.
+
+```tsx
+import type { ThemeConfig } from '@coinbase/cds-mobile/core/theme';
+import { ThemeProvider } from '@coinbase/cds-mobile/system/ThemeProvider';
+import { defaultTheme } from '@coinbase/cds-mobile/themes/defaultTheme';
+
+// Define lightSpectrum and darkSpectrum as separate objects
+const lightSpectrum = {
+  ...defaultTheme.lightSpectrum,
+  blue60: '8,90,255',
+};
+
+const darkSpectrum = {
+  ...defaultTheme.darkSpectrum,
+  blue60: '65,125,245',
+};
+
+// Use lightSpectrum and darkSpectrum to define the lightColor and darkColor values
+const myTheme = {
+  ...defaultTheme,
+  id: 'my-custom-theme',
+  lightSpectrum,
+  darkSpectrum,
+  lightColor: {
+    ...defaultTheme.lightColor,
+    bgPrimary: `rgb(${lightSpectrum.red60})`,
+  },
+  darkColor: {
+    ...defaultTheme.darkColor,
+    bgPrimary: `rgb(${darkSpectrum.red60})`,
+  },
+} as const satisfies ThemeConfig;
+
+const App = () => (
+  <ThemeProvider theme={myTheme} activeColorScheme="light">
+    {/* Your app components */}
+  </ThemeProvider>
+);
+```
+
+:::tip
+Use the `ThemeConfig` type with TypeScript's `satisfies` keyword to enforce type safety for your theme.
+:::
+
+### `defaultTheme` config
+
+The `defaultTheme` is a good example of a complete `ThemeConfig`. You can use it as an example when developing your own themes.
+
+[See the `defaultTheme` source code here &rarr;](https://github.com/coinbase/cds/blob/master/packages/mobile/src/themes/defaultTheme.ts)
+
+<JSONCodeBlock json={defaultTheme} />
+
+### `ThemeVars` namespace
+
+The `ThemeVars` namespace contains type definitions for all themeable variable names in CDS. It includes any custom theme variables added in `ThemeVarsExtended`.
+
+```tsx
+import type { ThemeVars } from '@coinbase/cds-common/core/theme';
+
+// All theme variables are accessible through ThemeVars
+ThemeVars.Color; // 'fg' | 'bg' | 'bgPrimary' | 'bgSecondary' | ...
+ThemeVars.SpectrumColor; // 'blue60' | 'red40' | 'gray100' | ...
+ThemeVars.SpectrumHue; // 'blue' | 'green' | 'orange' | 'gray' | ...
+ThemeVars.SpectrumHueStep; // 0 | 5 | 10 | 20 | ...
+ThemeVars.Space; // 0 | 0.25 | 0.5 | 1 | 2 | ...
+ThemeVars.BorderWidth; // 0 | 100 | 200 | ...
+ThemeVars.BorderRadius; // 0 | 100 | 200 | ...
+ThemeVars.Font; // 'display1' | 'title1' | 'body' | ...
+ThemeVars.FontFamily; // 'display1' | 'title1' | 'body' | ...
+ThemeVars.FontSize; // 'display1' | 'title1' | 'body' | ...
+ThemeVars.FontWeight; // 'display1' | 'title1' | 'body' | ...
+ThemeVars.LineHeight; // 'display1' | 'title1' | 'body' | ...
+ThemeVars.TextTransform; // 'display1' | 'title1' | 'body' | ...
+ThemeVars.IconSize; // 'xs' | 's' | 'm' | 'l'
+ThemeVars.AvatarSize; // 's' | 'm' | 'l' | 'xl' | ...
+ThemeVars.ControlSize; // 'checkboxSize' | 'radioSize' | ...
+```
+
+### Extending the theme
+
+You can extend the theme by adding custom theme variables. In this example we'll show how to add a custom color variable, but you can extend other types of `ThemeVars` as well.
+
+Start by overriding interfaces in the `ThemeVarsExtended` namespace to add new theme variables. Only the key names are used, the `void` type is just a necessary placeholder.
+
+```jsx
+declare module '@coinbase/cds-common/core/theme' {
+  export namespace ThemeVarsExtended {
+    export interface Color {
+      myCustomColor: void;
+    }
+  }
+}
+```
+
+This adds `myCustomColor` to `ThemeVars.Color` - which enforces that this variable must be defined in your theme to satisfy the `ThemeConfig` type, and allows this variable name to be passed to the `StyleProps` API anywhere that theme colors are accepted.
+
+Now that `myCustomColor` is defined in your theme the `useTheme` hook will include it in the return value.
+

package/mcp-docs/mobile/hooks/useDimensions.txt

@@ -1,5 +1,5 @@
-
 # useDimensions
+
 Measures the screen dimensions and status bar height.
 
 ## Import
@@ -8,6 +8,32 @@ Measures the screen dimensions and status bar height.
 import { useDimensions } from '@coinbase/cds-mobile/hooks/useDimensions'
 ```
 
+## API
+
+### Parameters
+
+None. The hook takes no parameters.
+
+### Returns
+
+Returns an object with the following properties:
+
+```tsx
+type Return = {
+  screenHeight: number;
+  screenWidth: number;
+  statusBarHeight: number;
+};
+```
+
+- `screenHeight`: The total height of the device screen in points (DIP).
+- `screenWidth`: The total width of the device screen in points (DIP).
+- `statusBarHeight`: The height of the device's status bar in points (DIP).
+
+:::tip
+All dimensions are in points (DIP - Density Independent Pixels), not physical pixels. Values automatically update on device orientation changes. The status bar height varies by device type, orientation, and presence of notches or dynamic islands.
+:::
+
 ## Examples
 
 ### Basic usage
@@ -44,4 +70,3 @@ function Example() {
 }
 ```
 
-

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

@@ -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,72 @@ A React context and hook for detecting if components are rendered inside overlay
 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.
@@ -212,4 +278,3 @@ function SafeAreaExample() {
 }
 ```
 
-