@coinbase/cds-mcp-server 8.17.1 → 8.17.3

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

@@ -0,0 +1,94 @@
+---
+id: mcp-server
+title: MCP Server
+hide_title: true
+---
+
+import { MDXSection } from '@site/src/components/page/MDXSection';
+import { MDXArticle } from '@site/src/components/page/MDXArticle';
+import { ContentHeader } from '@site/src/components/page/ContentHeader';
+
+<ContentHeader
+  title="MCP Server"
+  description="CDS includes an MCP Server that is automatically updated with each new version of our libraries."
+/>
+
+<MDXSection>
+<MDXArticle>
+## What is it?
+
+The CDS MCP Server provides CDS context to LLMs, allowing AI models to understand and work with CDS APIs and components.
+
+From [modelcontextprotocol.io](https://modelcontextprotocol.io/docs/getting-started/intro):
+
+> _MCP is an open protocol that standardizes how applications provide context to large language models (LLMs). MCP provides a standardized way to connect AI models to different data sources and tools. MCP enables you build agents and complex workflows on top of LLMs and connects your models with the world._
+
+</MDXArticle>
+</MDXSection>
+
+<MDXSection>
+<MDXArticle>
+## Basic installation
+
+The CDS MCP server is published in the `@coinbase/cds-mcp-server` package.
+
+This package is automatically included as a dependency of the CDS libraries, ensuring the CDS library and CDS MCP Server versions match. You do not need to install it separately if you are using the CDS libraries.
+
+</MDXArticle>
+<MDXArticle>
+
+### First time setup
+
+Run the setup command to install the CDS MCP Server for Cursor or Claude Code, then enable the MCP server in your agent.
+
+```bash
+npx --package=@coinbase/cds-mcp-server cds-mcp-setup
+```
+
+:::tip
+Make sure to enable the MCP server after installation.<br />
+See the [Cursor docs here](https://cursor.com/docs/context/mcp#using-mcp-in-chat) and the [Claude Code docs here](https://docs.claude.com/en/docs/claude-code/mcp#managing-your-servers) for more information.
+:::
+
+</MDXArticle>
+<MDXArticle>
+
+### Using the MCP server
+
+Once the CDS MCP Server is enabled in your agent, the agent will automatically be able to use the CDS MCP tools to interact with the CDS APIs and components.
+
+Try asking a question like "How can I add an icon to a CDS Button?" or "How can I customize the CDS Stepper component behavior?"
+
+</MDXArticle>
+</MDXSection>
+
+<MDXSection>
+<MDXArticle>
+## Advanced installation
+
+To install the MCP server separately as a standalone package and add it as a dependency to your project, run the following command:
+
+```bash
+npm install @coinbase/cds-mcp-server
+```
+
+Alternatively, if you are using Yarn:
+
+```bash
+yarn add @coinbase/cds-mcp-server
+```
+
+:::tip
+Avoid installing mismatched versions of the CDS libraries and the CDS MCP Server.
+:::
+
+### Executing with npx directly
+
+You can also execute the MCP server with npx directly, but it will not have the associated CDS agent rules installed.
+
+```bash
+npx @coinbase/cds-mcp-server
+```
+
+</MDXArticle>
+</MDXSection>

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

@@ -0,0 +1,25 @@
+---
+id: playground
+title: Playground
+hide_title: true
+---
+
+import { MDXSection } from '@site/src/components/page/MDXSection';
+import { MDXArticle } from '@site/src/components/page/MDXArticle';
+import { ContentHeader } from '@site/src/components/page/ContentHeader';
+import { PlaygroundBanner } from '@site/src/components/page/ComponentBanner/PlaygroundBanner';
+import { ShareablePlayground } from '@site/src/components/page/ShareablePlayground';
+
+<ContentHeader
+  title="Playground"
+  description="Live code playground for testing and sharing CDS components and code examples. All CDS components and hooks and all React exports are available to use in the playground without importing them. You must call render() to render your code."
+  banner={<PlaygroundBanner />}
+/>
+
+<MDXSection>
+<MDXArticle>
+
+<ShareablePlayground />
+
+</MDXArticle>
+</MDXSection>

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

@@ -0,0 +1,33 @@
+
+# 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
+
+```tsx
+import { useBreakpoints } from '@coinbase/cds-web/hooks/useBreakpoints'
+```
+
+## Examples
+
+import { JSONCodeBlock } from '@site/src/components/page/JSONCodeBlock';
+import { useBreakpoints } from '@coinbase/cds-web/hooks/useBreakpoints';
+
+### Basic usage
+
+Use the `useBreakpoints` hook to conditionally render components or component trees based on the current window breakpoint.
+
+[See how breakpoints are defined in the `media` object →](https://github.com/coinbase/cds/blob/master/packages/web/src/styles/media.ts)
+
+:::warning
+Do not use `useBreakpoints` for responsive styles. Use CSS media queries or [the `StyleProps` API](/getting-started/styling#responsive-styles) for responsive styles.
+:::
+
+```tsx live
+() => {
+  const breakpoints = useBreakpoints();
+  return <JSONCodeBlock json={breakpoints} />;
+};
+```
+
+  

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

@@ -0,0 +1,55 @@
+
+# useDimensions
+Measures an element's dimensions using ResizeObserver.
+
+## Import
+
+```tsx
+import { useDimensions } from '@coinbase/cds-web/hooks/useDimensions'
+```
+
+## Examples
+
+### Basic usage
+
+```tsx live
+function Example() {
+  const ref = useRef(null);
+  const { width, height } = useDimensions({ ref });
+
+  return (
+    <Box ref={ref} padding={3} background="bgAlternate" borderRadius={300} width="100%">
+      <TextHeadline>
+        This box is {width}px wide and {height}px tall
+      </TextHeadline>
+    </Box>
+  );
+}
+```
+
+### With Breakpoints
+
+```tsx live
+function Example() {
+  const ref = useRef(null);
+  const { width, currentBreakpoint } = useDimensions({
+    ref,
+    breakpoints: {
+      small: 300,
+      medium: 400,
+      large: 500,
+    },
+  });
+
+  return (
+    <Box ref={ref} padding={3} background="bgAlternate" borderRadius={300} width="100%">
+      <VStack gap={2}>
+        <TextHeadline>Width: {width}px</TextHeadline>
+        <TextHeadline>Current breakpoint: {currentBreakpoint || 'none'}</TextHeadline>
+      </VStack>
+    </Box>
+  );
+}
+```
+
+

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

@@ -0,0 +1,55 @@
+
+# useHasMounted
+Returns a boolean indicating if the component has mounted.
+
+## Import
+
+```tsx
+import { useHasMounted } from '@coinbase/cds-web/hooks/useHasMounted'
+```
+
+## 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,42 @@
+
+# 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'
+```
+
+## 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,94 @@
+
+# useMediaQuery
+Subscribes to window.matchMedia changes with SSR support.
+
+## Import
+
+```tsx
+import { useMediaQuery } from '@coinbase/cds-web/hooks/useMediaQuery'
+```
+
+## 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/useOverlayContentContext.txt

@@ -0,0 +1,217 @@
+
+# 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'
+```
+
+## 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.
+
+### Basic usage
+
+```tsx live
+function ExampleComponent() {
+  const { isOverlay, isModal, isDrawer, isTour } = useOverlayContentContext();
+
+  return (
+    <VStack gap={2}>
+      <TextHeadline>Overlay Context Information</TextHeadline>
+      <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
+
+Click the button below to open a modal and see how the hook behaves inside vs outside:
+
+```tsx live
+function ModalExample() {
+  const [isModalOpen, setIsModalOpen] = useState(false);
+
+  const ExampleComponent = () => {
+    const { isOverlay, isModal, isDrawer, isTour } = useOverlayContentContext();
+
+    return (
+      <VStack gap={2}>
+        <TextHeadline>Overlay Context Information</TextHeadline>
+        <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>
+    );
+  };
+
+  return (
+    <VStack gap={3}>
+      <VStack gap={2} padding={3} background="bgSecondary" borderRadius={400}>
+        <TextHeadline>Outside Modal</TextHeadline>
+        <ExampleComponent />
+      </VStack>
+
+      <Button onClick={() => setIsModalOpen(true)}>Open Modal</Button>
+
+      <Modal visible={isModalOpen} onRequestClose={() => setIsModalOpen(false)}>
+        <ModalHeader closeAccessibilityLabel="Close" title="Modal with Context Hook" />
+        <ModalBody>
+          <VStack gap={3}>
+            <Text>
+              This content is rendered inside a modal. Notice how the context values change:
+            </Text>
+            <VStack gap={2} padding={3} background="bgAlternate" borderRadius={400}>
+              <ExampleComponent />
+            </VStack>
+            <Text color="fgMuted" font="caption">
+              The hook automatically detects it's inside a modal context!
+            </Text>
+          </VStack>
+        </ModalBody>
+      </Modal>
+    </VStack>
+  );
+}
+```
+
+### Using the Context Provider
+
+You can also use the `OverlayContentContext` directly to provide context values:
+
+```tsx live
+function ContextProviderExample() {
+  const ExampleComponent = () => {
+    const { isOverlay, isModal, isDrawer, isTour } = useOverlayContentContext();
+
+    return (
+      <VStack gap={2}>
+        <TextHeadline>Overlay Context Information</TextHeadline>
+        <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} background="bgSecondary" borderRadius={400}>
+        <TextHeadline>Inside Context Provider</TextHeadline>
+        <ExampleComponent />
+      </VStack>
+    </OverlayContentContext.Provider>
+  );
+}
+```
+
+### Conditional Rendering
+
+Use the hook to conditionally render content based on overlay context:
+
+```tsx live
+function ConditionalRenderingExample() {
+  const [isModalOpen, setIsModalOpen] = useState(false);
+
+  const ConditionalContent = () => {
+    const { isOverlay, isModal } = useOverlayContentContext();
+
+    return (
+      <VStack gap={2}>
+        <TextHeadline>Conditional Content</TextHeadline>
+        {isOverlay ? (
+          <VStack gap={1}>
+            <Text color="fgPositive">✓ This content shows when inside an overlay</Text>
+            {isModal && <Text color="fgPrimary">🎯 Specifically inside a modal!</Text>}
+          </VStack>
+        ) : (
+          <Text color="fgMuted">This content shows when not in an overlay</Text>
+        )}
+      </VStack>
+    );
+  };
+
+  return (
+    <VStack gap={3}>
+      <VStack gap={2} padding={3} background="bgSecondary" borderRadius={400}>
+        <TextHeadline>Outside Modal</TextHeadline>
+        <ConditionalContent />
+      </VStack>
+
+      <Button onClick={() => setIsModalOpen(true)}>Open Modal</Button>
+
+      <Modal visible={isModalOpen} onRequestClose={() => setIsModalOpen(false)}>
+        <ModalHeader closeAccessibilityLabel="Close" title="Conditional Content Demo" />
+        <ModalBody>
+          <ConditionalContent />
+        </ModalBody>
+      </Modal>
+    </VStack>
+  );
+}
+```
+
+### Styling Based on Context
+
+```tsx live
+function StylingExample() {
+  const [isModalOpen, setIsModalOpen] = useState(false);
+
+  const StyledContent = () => {
+    const { isModal, isDrawer } = useOverlayContentContext();
+
+    const getBackgroundColor = () => {
+      if (isModal) return 'bgPrimaryWash';
+      if (isDrawer) return 'bgSecondaryWash';
+      return 'bgAlternate';
+    };
+
+    const getStatusText = () => {
+      if (isModal) return 'Modal styling applied! 🎉';
+      if (isDrawer) return 'Drawer styling applied!';
+      return 'Default styling';
+    };
+
+    return (
+      <VStack padding={3} background={getBackgroundColor()} borderRadius={400} gap={2}>
+        <TextHeadline>Dynamic Styling</TextHeadline>
+        <Text>{getStatusText()}</Text>
+        <Text color="fgMuted" font="caption">
+          Background color: {getBackgroundColor()}
+        </Text>
+      </VStack>
+    );
+  };
+
+  return (
+    <VStack gap={3}>
+      <StyledContent />
+
+      <Button onClick={() => setIsModalOpen(true)}>Open Modal</Button>
+
+      <Modal visible={isModalOpen} onRequestClose={() => setIsModalOpen(false)}>
+        <ModalHeader closeAccessibilityLabel="Close" title="Dynamic Styling Demo" />
+        <ModalBody>
+          <StyledContent />
+        </ModalBody>
+      </Modal>
+    </VStack>
+  );
+}
+```
+
+

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

@@ -0,0 +1,63 @@
+
+# useScrollBlocker
+Block and unblock page scrolling.
+
+## Import
+
+```tsx
+import { useScrollBlocker } from '@coinbase/cds-web/hooks/useScrollBlocker'
+```
+
+## Examples
+
+### Basic usage
+
+```tsx live
+function Example() {
+  const blockScroll = useScrollBlocker();
+  const [isBlocked, setIsBlocked] = useState(false);
+
+  const toggleScroll = () => {
+    setIsBlocked(!isBlocked);
+    blockScroll(!isBlocked);
+  };
+
+  return (
+    <VStack gap={3} alignItems="start">
+      <TextHeadline>Scroll is currently {isBlocked ? 'blocked' : 'enabled'}</TextHeadline>
+      <Button onClick={toggleScroll}>{isBlocked ? 'Enable Scroll' : 'Block Scroll'}</Button>
+    </VStack>
+  );
+}
+```
+
+### With Overlay
+
+```tsx live
+function Example() {
+  const blockScroll = useScrollBlocker();
+  const [isOpen, setIsOpen] = useState(false);
+
+  const openModal = () => {
+    setIsOpen(true);
+    blockScroll(true);
+  };
+
+  const closeModal = () => {
+    setIsOpen(false);
+    blockScroll(false);
+  };
+
+  return (
+    <VStack gap={3} alignItems="start">
+      <Button onClick={openModal}>Open Overlay</Button>
+      <Modal visible={isOpen} onRequestClose={closeModal}>
+        <ModalHeader title="Modal Title" />
+        <ModalBody>Modal Content</ModalBody>
+      </Modal>
+    </VStack>
+  );
+}
+```
+
+