@coinbase/cds-mcp-server 8.17.3 → 8.17.5

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

@@ -0,0 +1,426 @@
+# 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 { JSONCodeBlock } from '@site/src/components/page/JSONCodeBlock';
+import { defaultTheme } from '@coinbase/cds-web/themes/defaultTheme';
+import { createThemeCssVars } from '@coinbase/cds-web/core/createThemeCssVars';
+### ThemeProvider component
+
+The ThemeProvider provides the theme context to all child components, and automatically generates CSS Variables for dynamic theming.
+
+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-web/system/ThemeProvider';
+import { defaultTheme } from '@coinbase/cds-web/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 and from CSS Variables.
+:::
+
+#### `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; // "2.5rem"
+```
+
+:::tip
+For best performance, prefer to use CSS Variables instead of the `useTheme` hook whenever possible.
+:::
+
+#### ThemeProvider CSS Variables
+
+CSS Variables are created for every value in the theme.
+
+For best performance, prefer to use CSS Variables instead of the `useTheme` hook whenever possible.
+
+```jsx
+const theme = useTheme();
+theme.color.bgPrimary; // --color-bgPrimary
+theme.lightColor.bgPrimary; // --lightColor-bgPrimary
+theme.darkColor.bgPrimary; // --darkColor-bgPrimary
+theme.spectrum.blue10; // --blue10
+theme.lightSpectrum.blue10; // --light-blue10
+theme.darkSpectrum.blue10; // --dark-blue10
+theme.space[2]; // --space-2
+theme.space[0.25]; // --space-0_25
+theme.borderRadius[400]; // --borderRadius-400
+theme.fontSize.body; // --fontSize-body
+```
+
+You can see all the CSS Variables for the `defaultTheme` below.
+
+<JSONCodeBlock json={createThemeCssVars(defaultTheme)} />
+
+#### ThemeProvider classnames
+
+The ThemeProvider renders with CSS classnames based on the `activeColorScheme` and the theme's `id`.
+
+This allows you to style components based on the `activeColorScheme` or the theme's `id`.
+
+```jsx
+// Renders with a .cds-default class and a .light class
+<ThemeProvider theme={defaultTheme} activeColorScheme="light" />
+```
+
+#### 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/web/src/core/theme.ts#L4)
+
+[See the `Theme` type definition here &rarr;](https://github.com/coinbase/cds/blob/master/packages/web/src/core/theme.ts#L43)
+
+:::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-web/core/theme';
+import { ThemeProvider } from '@coinbase/cds-web/system/ThemeProvider';
+import { defaultTheme } from '@coinbase/cds-web/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/web/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, and the ThemeProvider will create CSS Variables for this value just like every other `ThemeVars.Color`.
+
+Next define the corresponding static classnames for your new theme variables via the `initializeCDS` function `extendStyleProps` options. These static classnames should use the CSS Variable that will be created by the ThemeProvider.
+
+:::tip
+Call the `initializeCDS` function only once in your app entry point, before your app renders.
+:::
+
+Web StyleProps support responsive syntax, so you must provide 4 unique classnames per style prop: one each for `base`, `phone`, `tablet`, and `desktop`. Use the [CDS media object](/getting-started/styling/#responsive-styles) to use the same responsive breakpoints as CDS.
+
+```jsx
+import { initializeCDS } from '@coinbase/cds-web/styles/config';
+
+initializeCDS({
+  extendStyleProps: {
+    // Specify the ThemeVars interface name that you extended
+    Color: {
+      // Specify the new theme variable name that you added
+      myCustomColor: {
+        // Configure the necessary static classNames for the new theme variable
+        background: {
+          base: 'background-myCustomColor',
+          phone: 'background-myCustomColor-phone',
+          tablet: 'background-myCustomColor-tablet',
+          desktop: 'background-myCustomColor-desktop',
+        },
+        color: {
+          base: 'color-myCustomColor',
+          phone: 'color-myCustomColor-phone',
+          tablet: 'color-myCustomColor-tablet',
+          desktop: 'color-myCustomColor-desktop',
+        },
+        borderColor: {
+          base: 'borderColor-myCustomColor',
+          phone: 'borderColor-myCustomColor-phone',
+          tablet: 'borderColor-myCustomColor-tablet',
+          desktop: 'borderColor-myCustomColor-desktop',
+        },
+      },
+    },
+  },
+});
+```
+
+With the classnames defined as follows:
+
+```css
+.background-myCustomColor {
+  background-color: var(--color-myCustomColor);
+}
+
+.background-myCustomColor-phone {
+  @media (max-width: 767px) {
+    background-color: var(--color-myCustomColor);
+  }
+}
+
+.background-myCustomColor-tablet {
+  @media (min-width: 768px) and (max-width: 1279px) {
+    background-color: var(--color-myCustomColor);
+  }
+}
+
+.background-myCustomColor-desktop {
+  @media (min-width: 1280px) {
+    background-color: var(--color-myCustomColor);
+  }
+}
+
+/* etc for color and borderColor */
+```
+
+Or, using CSS-in-JS:
+
+```tsx
+import { css } from '@linaria/core';
+import { media } from '@coinbase/cds-web/styles/media';
+
+const myCustomColor = {
+  background: {
+    base: css`
+      background-color: var(--color-myCustomColor);
+    `,
+    phone: css`
+      @media ${media.phone} {
+        background-color: var(--color-myCustomColor);
+      }
+    `,
+    tablet: css`
+      @media ${media.tablet} {
+        background-color: var(--color-myCustomColor);
+      }
+    `,
+    desktop: css`
+      @media ${media.desktop} {
+        background-color: var(--color-myCustomColor);
+      }
+    `,
+  },
+  // etc for color and borderColor
+};
+```
+

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

@@ -1,5 +1,5 @@
-
 # useBreakpoints
+
 Returns an object with a boolean for each breakpoint of the window. Useful for conditionally rendering components or component trees based on the current window breakpoint.
 
 ## Import
@@ -8,6 +8,35 @@ Returns an object with a boolean for each breakpoint of the window. Useful for c
 import { useBreakpoints } from '@coinbase/cds-web/hooks/useBreakpoints'
 ```
 
+## API
+
+import { media } from '@coinbase/cds-web/styles/media';
+
+### Parameters
+
+The `useBreakpoints` hook does not accept any parameters. It must be used within a MediaQueryProvider component.
+
+### Returns
+
+Returns an object with a boolean for each breakpoint of the window.
+
+- `isPhone`: {media.phone}
+- `isPhonePortrait`: {media.phonePortrait}
+- `isPhoneLandscape`: {media.phoneLandscape}
+- `isTablet`: {media.tablet}
+- `isTabletPortrait`: {media.tabletPortrait}
+- `isTabletLandscape`: {media.tabletLandscape}
+- `isDesktop`: {media.desktop}
+- `isDesktopSmall`: {media.desktopSmall}
+- `isDesktopLarge`: {media.desktopLarge}
+- `isExtraWide`: {media.extraWide}
+
+[See how breakpoints are defined in the `media` object →](https://github.com/coinbase/cds/blob/master/packages/web/src/styles/media.ts)
+
+:::tip
+Multiple breakpoint values can be true at the same time.
+:::
+
 ## Examples
 
 import { JSONCodeBlock } from '@site/src/components/page/JSONCodeBlock';
@@ -30,4 +59,3 @@ Do not use `useBreakpoints` for responsive styles. Use CSS media queries or [the
 };
 ```
 
-  

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

@@ -1,5 +1,5 @@
-
 # useDimensions
+
 Measures an element's dimensions using ResizeObserver.
 
 ## Import
@@ -8,6 +8,66 @@ Measures an element's dimensions using ResizeObserver.
 import { useDimensions } from '@coinbase/cds-web/hooks/useDimensions'
 ```
 
+## API
+
+### Parameters
+
+The hook accepts an optional configuration object with the following properties:
+
+#### Options
+
+```tsx
+type Options<T extends HTMLElement> = {
+  ref?: RefObject<T> | null;
+  useBorderBoxSize?: boolean;
+  breakpoints?: Record<string, number>;
+  updateOnBreakpointChange?: boolean;
+  shouldUpdate?: (state: State) => boolean;
+  onResize?: (event: Event<T>) => void;
+  polyfill?: any;
+};
+```
+
+- `ref` (optional): A React ref to observe. If not provided, the hook will create one.
+- `useBorderBoxSize` (optional): Whether to use border-box size measurement instead of content-box. Defaults to `false`.
+- `breakpoints` (optional): An object mapping breakpoint names to width values.
+- `updateOnBreakpointChange` (optional): Whether to update state only when breakpoint changes. Defaults to `false`.
+- `shouldUpdate` (optional): A function to conditionally control state updates.
+- `onResize` (optional): Callback fired when the observed element resizes.
+- `polyfill` (optional): A ResizeObserver polyfill for unsupported browsers.
+
+### Returns
+
+Returns an object with the following properties:
+
+```tsx
+type Return<T> = {
+  ref: RefObject<T>;
+  currentBreakpoint: string;
+  width: number;
+  height: number;
+  x: number;
+  y: number;
+  entry?: ResizeObserverEntry;
+  observe: (element: T | null) => void;
+  unobserve: () => void;
+};
+```
+
+- `ref`: React ref to attach to the element to observe.
+- `currentBreakpoint`: Current active breakpoint based on element width. Empty if no breakpoints defined.
+- `width`: Width of the observed element in pixels.
+- `height`: Height of the observed element in pixels.
+- `x`: X-coordinate of the element relative to the viewport.
+- `y`: Y-coordinate of the element relative to the viewport.
+- `entry`: Raw ResizeObserver entry object.
+- `observe`: Function to start observing an element.
+- `unobserve`: Function to stop observing the current element.
+
+:::tip
+This hook uses the ResizeObserver API to track element dimensions. A polyfill may be required for older browsers.
+:::
+
 ## Examples
 
 ### Basic usage
@@ -52,4 +112,3 @@ function Example() {
 }
 ```
 
-

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