@coinbase/cds-mcp-server 8.17.2 → 8.17.4

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

@@ -0,0 +1,279 @@
+# 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
+
+### Parameters
+
+The `useOverlayContentContext` hook accepts no parameters.
+
+### Returns
+
+Returns an `OverlayContentContextValue` object with overlay state information:
+
+- `isOverlay?: boolean` - True if inside any overlay component (automatically 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
+
+All properties are optional and will be `undefined` when outside of overlay contexts.
+
+:::tip
+This hook is safe to use anywhere in your component tree - it does not throw an error when used outside a provider. When `isOverlay` is not explicitly provided, it will be automatically derived as `true` if any of the other overlay type flags are `true`.
+:::
+
+### OverlayContentContext
+
+The React context that provides overlay state information. 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 MyOverlayComponent() {
+  const contextValue = {
+    isModal: true,
+    isDrawer: false,
+    isTour: false,
+    // isOverlay will be automatically derived as true
+  };
+
+  return (
+    <OverlayContentContext.Provider value={contextValue}>
+      {/* Your overlay content */}
+    </OverlayContentContext.Provider>
+  );
+}
+```
+
+### 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. 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/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>
+  );
+}
+```
+

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

@@ -0,0 +1,178 @@
+# useRefMap
+
+Manages a collection of refs using a key-value map structure, allowing dynamic registration and retrieval of refs by their unique identifiers. Commonly used in components that need to track multiple DOM elements, such as tabs, tours, or complex navigation systems.
+
+## Import
+
+```tsx
+import { useRefMap } from '@coinbase/cds-common/hooks/useRefMap'
+```
+
+## API
+
+### Parameters
+
+The `useRefMap` hook accepts an optional configuration object:
+
+- `options?: RefMapOptions<RefValue>` - Configuration options for the ref map
+  - `initialRefMap?: Record<string, RefValue>` - Optional initial map of refs
+
+The generic type `RefValue` represents the type of values stored in the ref map (typically `HTMLElement` or a specific element type).
+
+### Returns
+
+Returns a `RefMapApi<RefValue>` object with the following properties:
+
+- `refs: Record<string, RefValue>` - The current map of all registered refs
+- `getRef: (id: string) => RefValue | null` - Function to retrieve a ref by its ID
+- `registerRef: (id: string, ref: RefValue) => void` - Function to register a new ref with an ID
+
+:::tip
+This hook is particularly useful when working with components that need to manage multiple refs, such as in tour guides where elements need to be highlighted, or in tab systems where tab panels need to be referenced. The hook maintains a stable reference to the ref map and its utility functions across renders.
+:::
+
+## Examples
+
+### Basic usage
+
+```tsx live
+function Example() {
+  const { registerRef, getRef } = useRefMap<HTMLDivElement>();
+  const toast = useToast();
+
+  const handleClick = () => {
+    // Get the element by its ID and log its dimensions
+    const element = getRef('box1');
+    if (element) {
+      toast.show(`Box dimensions: ${element.offsetWidth}x${element.offsetHeight}`);
+    }
+  };
+
+  return (
+    <VStack gap={2}>
+      <Box
+        ref={(el) => el && registerRef('box1', el)}
+        padding={3}
+        background="bgAlternate"
+        borderRadius={300}
+      >
+        <TextBody>This box is registered with ID 'box1'</TextBody>
+      </Box>
+      <Button onClick={handleClick}>Get Box Dimensions</Button>
+    </VStack>
+  );
+}
+```
+
+### With Multiple Elements
+
+```tsx live
+function Example() {
+  const { registerRef, getRef } = useRefMap<HTMLDivElement>();
+  const [activeId, setActiveId] = useState<string | null>(null);
+
+  const highlightElement = (id: string) => {
+    // Reset previous highlight
+    if (activeId) {
+      const prevElement = getRef(activeId);
+      if (prevElement) {
+        prevElement.style.outline = 'none';
+      }
+    }
+
+    // Highlight new element
+    const element = getRef(id);
+    if (element) {
+      element.style.outline = '2px solid var(--color-fgPrimary)';
+      setActiveId(id);
+    }
+  };
+
+  return (
+    <VStack gap={3}>
+      <HStack gap={2}>
+        <Button onClick={() => highlightElement('box1')}>Highlight Box 1</Button>
+        <Button onClick={() => highlightElement('box2')}>Highlight Box 2</Button>
+        <Button onClick={() => highlightElement('box3')}>Highlight Box 3</Button>
+      </HStack>
+
+      <VStack gap={2}>
+        <Box
+          ref={(el) => el && registerRef('box1', el)}
+          padding={3}
+          background="bgAlternate"
+          borderRadius={300}
+        >
+          <TextBody>Box 1</TextBody>
+        </Box>
+
+        <Box
+          ref={(el) => el && registerRef('box2', el)}
+          padding={3}
+          background="bgAlternate"
+          borderRadius={300}
+        >
+          <TextBody>Box 2</TextBody>
+        </Box>
+
+        <Box
+          ref={(el) => el && registerRef('box3', el)}
+          padding={3}
+          background="bgAlternate"
+          borderRadius={300}
+        >
+          <TextBody>Box 3</TextBody>
+        </Box>
+      </VStack>
+    </VStack>
+  );
+}
+```
+
+### With Initial Refs
+
+```tsx live
+function Example() {
+  // Create initial refs map
+  const box1Ref = useRef<HTMLDivElement>(null);
+  const box2Ref = useRef<HTMLDivElement>(null);
+
+  const initialRefs = {
+    box1: box1Ref.current,
+    box2: box2Ref.current,
+  };
+
+  const { refs, registerRef } = useRefMap<HTMLDivElement>({
+    initialRefMap: initialRefs,
+  });
+
+  const logRefs = () => {
+    console.log('Current refs:', refs);
+  };
+
+  return (
+    <VStack gap={2}>
+      <Box
+        ref={(el) => el && registerRef('box1', el)}
+        padding={3}
+        background="bgAlternate"
+        borderRadius={300}
+      >
+        <TextBody>Box 1</TextBody>
+      </Box>
+
+      <Box
+        ref={(el) => el && registerRef('box2', el)}
+        padding={3}
+        background="bgAlternate"
+        borderRadius={300}
+      >
+        <TextBody>Box 2</TextBody>
+      </Box>
+
+      <Button onClick={logRefs}>Log Refs</Button>
+    </VStack>
+  );
+}
+```
+

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

@@ -0,0 +1,82 @@
+# useScrollBlocker
+
+Block and unblock page scrolling.
+
+## Import
+
+```tsx
+import { useScrollBlocker } from '@coinbase/cds-web/hooks/useScrollBlocker'
+```
+
+## API
+
+### Parameters
+
+The `useScrollBlocker` hook does not accept any parameters.
+
+### Returns
+
+```tsx
+type Return = (shouldBlock: boolean) => void;
+```
+
+Returns a function that takes a boolean parameter to control scroll blocking:
+
+- `shouldBlock`: When `true`, blocks page scrolling. When `false`, re-enables scrolling.
+
+:::tip
+This hook is useful for temporarily disabling page scrolling, such as when displaying modals or overlays. It automatically handles scroll bar width compensation to prevent layout shifts.
+:::
+
+## 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>
+  );
+}
+```
+