@coinbase/cds-mcp-server 8.17.2 → 8.17.3

package/mcp-docs/web/components/Tooltip.txt

@@ -0,0 +1,90 @@
+# Tooltip
+
+A component that displays additional information on hover.
+
+## Import
+
+```jsx
+import { Tooltip } from '@coinbase/cds-web/overlays/Tooltip'
+```
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `content` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | Yes | `-` | The content to render within the tooltip. |
+| `autoFocusDelay` | `number` | No | `undefined` | The amount of time in milliseconds to wait before auto-focusing the first focusable element. |
+| `disableAutoFocus` | `boolean` | No | `false` | If true, the focus trap will not automatically shift focus to itself when it opens, and replace it to the last focused element when it closes. |
+| `disableFocusTrap` | `boolean` | No | `-` | Disables the focus trap to allow normal keyboard navigation. |
+| `disablePortal` | `boolean` | No | `false` | - |
+| `disableTypeFocus` | `boolean` | No | `-` | Use for editable Search Input components to ensure focus is correctly applied |
+| `elevation` | `0 \| 1 \| 2` | No | `-` | Determines a components shadow styles. Parent should have overflow set to visible to ensure styles are not clipped. |
+| `focusTabIndexElements` | `boolean` | No | `false` | If true, the focus trap will include all elements with tabIndex values in the list of focusable elements. |
+| `gap` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 0.25 \| 0.5 \| 0.75 \| 1.5` | No | `1` | This value corresponds to how big the gap between the subject and the tooltip is. We do not encourage usage of this prop. But it is enabled for special cases as an escape hatch. |
+| `invertColorScheme` | `boolean` | No | `true` | Invert the themes activeColorScheme for this component |
+| `placement` | `top \| bottom \| left \| right` | No | `top` | Position of tooltip in relation to the subject. |
+| `respectNegativeTabIndex` | `boolean` | No | `false` | If true, the focus trap will respect negative tabIndex values, removing them from the list of focusable elements. |
+| `testID` | `string` | No | `-` | Used to locate this element in unit and end-to-end tests. Under the hood, testID translates to data-testid on Web. On Mobile, testID stays the same - testID |
+| `tooltipId` | `string` | No | `-` | A unique ID used to ensure tooltips are accessible |
+| `visible` | `boolean` | No | `true` | Control whether the tooltip is shown or hidden. |
+| `zIndex` | `number` | No | `4` | Typically only used when disablePortal is set to true to adjust zIndex of tooltip. When using portal this value should remain as default. |
+
+
+## Examples
+
+### Placement
+
+```jsx live
+function TooltipPlacement() {
+  const content = 'This is the tooltip Content';
+  return (
+    <HStack spacingHorizontal={2} gap={2} justifyContent="space-around">
+      <Tooltip content={content}>
+        <Button>Default</Button>
+      </Tooltip>
+      <Tooltip content={content} placement="top">
+        <Button>Top</Button>
+      </Tooltip>
+      <Tooltip content={content} placement="left">
+        <Button>Left</Button>
+      </Tooltip>
+      <Tooltip content={content} placement="right">
+        <Button>Right</Button>
+      </Tooltip>
+      <Tooltip content={content} placement="bottom">
+        <Button>Bottom</Button>
+      </Tooltip>
+    </HStack>
+  );
+}
+```
+
+### Positioning
+
+Sometimes you may want to use a tooltip with an absolute positioned element.
+
+To ensure the tooltip is properly aligned, you should instead set the position prop on the tooltip.
+
+```jsx live
+function TooltipPosition() {
+  const content = 'This is the tooltip Content';
+  return (
+    <VStack gap={2}>
+      <Box position="relative">
+        Set your default display currency.
+        <Tooltip content="I am not centered horizontally">
+          <Icon active color="fg" name="info" paddingStart={1} position="absolute" />
+        </Tooltip>
+      </Box>
+      <Box position="relative">
+        Set your default display currency.
+        <Tooltip content="I am centered horizontally" position="absolute">
+          <Icon active color="fg" name="info" paddingStart={1} />
+        </Tooltip>
+      </Box>
+    </VStack>
+  );
+}
+```
+
+

package/mcp-docs/web/components/Tour.txt

@@ -0,0 +1,180 @@
+# Tour
+
+Creates guided tours of a user interface.
+
+## Import
+
+```jsx
+import { Tour, TourStep } from '@coinbase/cds-web/tour'
+```
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `activeTourStep` | `TourStepValue<T> \| null` | Yes | `-` | - |
+| `onChange` | `(tourStep: TourStepValue<T> \| null) => void` | Yes | `-` | - |
+| `steps` | `TourStepValue<T>[]` | Yes | `-` | - |
+| `TourMaskComponent` | `TourMaskComponent` | No | `DefaultTourMask` | The Component to render as a tour overlay and mask. |
+| `TourStepArrowComponent` | `TourStepArrowComponent` | No | `DefaultTourStepArrow` | The default Component to render for each TourStep arrow element. |
+| `disableAutoScroll` | `boolean` | No | `-` | Disable automatically scrolling to active elements. |
+| `disablePortal` | `boolean` | No | `-` | - |
+| `hideOverlay` | `boolean` | No | `false` | Hide overlay when tour is active |
+| `scrollOptions` | `TourScrollOptions` | No | `{   behavior: 'smooth',   marginX: 100,   marginY: 100, }` | Controls the scrolling behavior and margins when calling element.scrollTo() to scroll to an active TourStep target. |
+| `testID` | `string` | No | `-` | Used to locate this element in unit and end-to-end tests. Under the hood, testID translates to data-testid on Web. On Mobile, testID stays the same - testID |
+| `tourMaskBorderRadius` | `string \| number` | No | `-` | Corner radius for the TourMasks content mask. Uses SVG rect elements rx and ry attributes https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/rx. |
+| `tourMaskPadding` | `string \| number` | No | `-` | Padding to add around the edges of the TourMasks content mask. |
+| `tourStepAutoPlacement` | `{ padding?: Padding; rootBoundary?: RootBoundary \| undefined; elementContext?: ElementContext \| undefined; altBoundary?: boolean \| undefined; crossAxis?: boolean \| undefined; alignment?: Alignment \| null \| undefined; autoAlignment?: boolean \| undefined; allowedPlacements?: Placement[] \| undefined; boundary?: Boundary \| undefined; } \| undefined` | No | `24` | Configures @floating-ui autoPlacement options for Tour Step component. See https://floating-ui.com/docs/autoplacement. |
+| `tourStepOffset` | `number \| Partial<{ mainAxis: number; crossAxis: number; alignmentAxis: number \| null; }> \| Derivable<OffsetValue>` | No | `24` | Configures @floating-ui offset options for Tour Step component. See https://floating-ui.com/docs/offset. |
+| `tourStepShift` | `{ padding?: Padding; rootBoundary?: RootBoundary \| undefined; elementContext?: ElementContext \| undefined; altBoundary?: boolean \| undefined; crossAxis?: boolean \| undefined; mainAxis?: boolean \| undefined; limiter?: { fn: (state: MiddlewareState) => Coords; options?: any; } \| undefined; boundary?: Boundary \| undefined; } \| undefined` | No | `-` | Configures @floating-ui shift options for Tour Step component. See https://floating-ui.com/docs/shift. |
+
+
+## Examples
+
+### Basic usage
+
+```jsx live
+function Example() {
+  const [activeTourStep, setActiveTourStep] = useState(null);
+
+  const StepOne = () => {
+    const [checked, setChecked] = useState(false);
+
+    const { goNextTourStep, stopTour } = useTourContext();
+
+    return (
+      <Coachmark
+        action={
+          <Button compact onClick={goNextTourStep}>
+            Next
+          </Button>
+        }
+        checkbox={
+          <Checkbox checked={checked} onChange={setChecked}>
+            Don&apos;t show again
+          </Checkbox>
+        }
+        content="Add up to 3 lines of body copy. Deliver your message with clarity and impact"
+        onClose={stopTour}
+        title="My first step"
+      />
+    );
+  };
+
+  const StepTwo = () => {
+    const { goNextTourStep, goPreviousTourStep, stopTour } = useTourContext();
+    return (
+      <Coachmark
+        action={
+          <HStack gap={1}>
+            <Button compact onClick={goPreviousTourStep} variant="secondary">
+              Back
+            </Button>
+            <Button compact onClick={goNextTourStep}>
+              Next
+            </Button>
+          </HStack>
+        }
+        content={
+          <VStack gap={2}>
+            <TextCaption as="p" color="fgMuted">
+              50%
+            </TextCaption>
+            <ProgressBar progress={0.5} />
+            <TextBody as="p">
+              Add up to 3 lines of body copy. Deliver your message with clarity and impact
+            </TextBody>
+          </VStack>
+        }
+        media={<RemoteImage height={150} source={ethBackground} width="100%" />}
+        onClose={stopTour}
+        title="My second step"
+      />
+    );
+  };
+
+  const StepThree = () => {
+    const { stopTour, goNextTourStep, goPreviousTourStep } = useTourContext();
+    return (
+      <Coachmark
+        action={
+          <HStack gap={1}>
+            <Button compact onClick={goPreviousTourStep} variant="secondary">
+              Back
+            </Button>
+            <Button compact onClick={stopTour}>
+              Done
+            </Button>
+          </HStack>
+        }
+        content="Add up to 3 lines of body copy. Deliver your message with clarity and impact"
+        title="My third step"
+        width={350}
+      />
+    );
+  };
+
+  const tourSteps = [
+    {
+      id: 'step1',
+      onBeforeActive: () => console.log('step1 before'),
+      Component: StepOne,
+    },
+    {
+      id: 'step2',
+      onBeforeActive: () => console.log('step2 before'),
+      Component: StepTwo,
+    },
+    {
+      id: 'step3',
+      onBeforeActive: () => console.log('step3 before'),
+      Component: StepThree,
+    },
+  ];
+
+  const TourExample = ({ spacerWidthIncrement = 0, spacerHeightIncrement = 500 }) => {
+    const { startTour } = useTourContext();
+
+    const handleClick = useCallback(() => startTour(), [startTour]);
+
+    return (
+      <VStack flexGrow={1} gap={2} justifyContent="space-between">
+        <Button compact onClick={handleClick}>
+          Start tour
+        </Button>
+        <TourStep id="step1">
+          <Box background="bgAlternate" padding={4}>
+            <TextBody as="p">This is step 1</TextBody>
+          </Box>
+        </TourStep>
+        <Box height={spacerHeightIncrement} />
+        <HStack justifyContent="flex-end">
+          <Box flexShrink={0} width={spacerWidthIncrement} />
+          <TourStep id="step2">
+            <Box background="bgAlternate" padding={4} width={150}>
+              <TextBody as="p">This is step 2</TextBody>
+            </Box>
+          </TourStep>
+        </HStack>
+        <Box height={spacerHeightIncrement} />
+        <HStack>
+          <Box flexShrink={0} width={spacerWidthIncrement * 2} />
+          <TourStep id="step3">
+            <VStack background="bgAlternate" padding={4} width={150}>
+              <TextBody as="p">This is step 3</TextBody>
+            </VStack>
+          </TourStep>
+        </HStack>
+      </VStack>
+    );
+  };
+
+  return (
+    <Tour activeTourStep={activeTourStep} onChange={setActiveTourStep} steps={tourSteps}>
+      <TourExample />
+    </Tour>
+  );
+}
+```
+
+

package/mcp-docs/web/components/Tray.txt

@@ -0,0 +1,289 @@
+# Tray
+
+An elevated container pinned to the bottom of the screen.
+
+## Import
+
+```jsx
+import { Tray } from '@coinbase/cds-web/overlays/tray/Tray'
+```
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `onCloseComplete` | `() => void` | Yes | `-` | Action that will happen when tray is dismissed |
+| `closeAccessibilityHint` | `string` | No | `-` | Sets an accessible hint or description for the close button. On web, maps to aria-describedby and lists the id(s) of the element(s) that describe the element on which the attribute is set. On mobile, a string that helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label. |
+| `closeAccessibilityLabel` | `string` | No | `-` | Sets an accessible label for the close button. On web, maps to aria-label and defines a string value that labels an interactive element. On mobile, VoiceOver will read this string when a user selects the associated element. |
+| `focusTabIndexElements` | `boolean` | No | `false` | Allow any element with tabIndex attribute to be focusable in FocusTrap, rather than only focusing specific interactive element types like button. This can be useful when having long content in a Modal. |
+| `footer` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | Optional footer content that will be fixed to the bottom of the tray |
+| `id` | `string` | No | `-` | HTML ID for the tray |
+| `key` | `Key \| null` | No | `-` | - |
+| `onBlur` | `(() => void)` | No | `-` | Callback fired when the overlay is pressed, or swipe to close |
+| `onClose` | `(() => void)` | No | `-` | Action that will happen when tray is dismissed |
+| `onVisibilityChange` | `((context: hidden \| visible) => void)` | No | `-` | Optional callback that, if provided, will be triggered when the Tray is toggled open/ closed If used for analytics, context (visible \| hidden) can be bundled with the event info to track whether the multiselect was toggled into or out of view |
+| `preventDismiss` | `boolean` | No | `-` | Prevents a user from dismissing the tray by pressing the overlay or swiping |
+| `ref` | `((instance: TrayRefProps \| null) => void) \| RefObject<TrayRefProps> \| null` | No | `-` | - |
+| `restoreFocusOnUnmount` | `boolean` | No | `true` | If true, the focus trap will restore focus to the previously focused element when it unmounts.  WARNING: If you disable this, you need to ensure that focus is restored properly so it doesnt end up on the body |
+| `role` | `dialog \| alertdialog` | No | `-` | WAI-ARIA Roles |
+| `title` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | Text or ReactNode for optional Tray title |
+| `verticalDrawerPercentageOfView` | `string` | No | `-` | Allow user of component to define maximum percentage of screen that can be taken up by the Drawer |
+| `zIndex` | `number` | No | `-` | z-index for the tray overlay |
+
+
+## Examples
+
+:::tip Accessibility tip
+
+**Labels**
+
+Trays require an accessibility label, which we set to `title` by default. However, if you don't want to provide a `title` or there's other text that gives the user better context to the tray, then you can pass an element id to `accessibilityLabelledBy`. Alternatively, you may directly provide a contextual label to `accessibilityLabel`.
+
+:::
+
+### Basic usage with Callback
+
+The recommended way to use a `Tray` is by passing a callback as children, which receives a `handleClose` function:
+
+```tsx live
+function BasicTray() {
+  const [visible, setVisible] = useState(false);
+  const handleOpen = () => setVisible(true);
+  const handleClose = () => setVisible(false);
+
+  return (
+    <VStack gap={2}>
+      <Button onClick={handleOpen}>Open Tray</Button>
+      {visible && (
+        <Tray title="Example Title" onCloseComplete={handleClose}>
+          {({ handleClose }) => (
+            <VStack gap={2}>
+              <Text>This is the content of the tray.</Text>
+              <Button onClick={handleClose}>Close</Button>
+            </VStack>
+          )}
+        </Tray>
+      )}
+    </VStack>
+  );
+}
+```
+
+### Using Ref to Control the Tray
+
+:::tip Accessibility tip
+
+**Trigger Focus**
+
+A `ref` to the trigger that opens the tray, along with an `onClosedComplete` method to reset focus on the trigger when the tray closes, needs to be wired up for accessibility (see code example below).
+
+:::
+
+You can also control the Tray using a ref, which provides a `close()` method:
+
+```tsx live
+function TrayWithRef() {
+  const [visible, setVisible] = useState(false);
+  const trayRef = useRef<DrawerRefBaseProps>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+
+  const handleOpen = () => setVisible(true);
+  const handleClose = () => {
+    setVisible(false);
+    triggerRef.current?.focus();
+  };
+
+  return (
+    <VStack gap={2}>
+      <Button ref={triggerRef} onClick={handleOpen}>
+        Open Tray
+      </Button>
+      {visible && (
+        <Tray ref={trayRef} title="Ref Controlled Tray" onCloseComplete={handleClose}>
+          <VStack gap={2}>
+            <Text>Control this tray using the ref.</Text>
+            <Button onClick={() => trayRef.current?.close()}>Close</Button>
+          </VStack>
+        </Tray>
+      )}
+    </VStack>
+  );
+}
+```
+
+### Scrollable Content
+
+Trays with long content will automatically be scrollable.
+
+```tsx live
+function ScrollableTray() {
+  const [visible, setVisible] = useState(false);
+  const handleOpen = () => setVisible(true);
+  const handleClose = () => setVisible(false);
+
+  return (
+    <VStack gap={2}>
+      <Button onClick={handleOpen}>Open Scrollable Tray</Button>
+      {visible && (
+        <Tray title="Scrollable Content" onCloseComplete={handleClose}>
+          {({ handleClose }) => (
+            <VStack gap={2}>
+              <VStack gap={2}>
+                <Text>
+                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
+                  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                </Text>
+                <Text>
+                  Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
+                  fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
+                  culpa qui officia deserunt mollit anim id est laborum.
+                </Text>
+                <Text>
+                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
+                  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                </Text>
+                <Text>
+                  Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
+                  fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
+                  culpa qui officia deserunt mollit anim id est laborum.
+                </Text>
+                <Text>
+                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
+                  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                </Text>
+                <Text>
+                  Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
+                  fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
+                  culpa qui officia deserunt mollit anim id est laborum.
+                </Text>
+                <Text>
+                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
+                  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                </Text>
+                <Text>
+                  Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
+                  fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
+                  culpa qui officia deserunt mollit anim id est laborum.
+                </Text>
+                <Text>
+                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
+                  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                </Text>
+                <Text>
+                  Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
+                  fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
+                  culpa qui officia deserunt mollit anim id est laborum.
+                </Text>
+                <Text>
+                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+                  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
+                  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                </Text>
+                <Text>
+                  Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
+                  fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
+                  culpa qui officia deserunt mollit anim id est laborum.
+                </Text>
+              </VStack>
+              <HStack justifyContent="flex-end">
+                <Button onClick={handleClose}>Close</Button>
+              </HStack>
+            </VStack>
+          )}
+        </Tray>
+      )}
+    </VStack>
+  );
+}
+```
+
+### Non-Dismissible Tray
+
+Trays can be configured to prevent the user from dismissing the tray by clicking close, clicking outside, or pressing ESC.
+
+```tsx live
+function NonDismissibleTray() {
+  const [visible, setVisible] = useState(false);
+  const handleOpen = () => setVisible(true);
+  const handleClose = () => setVisible(false);
+
+  return (
+    <VStack gap={2}>
+      <Button onClick={handleOpen}>Open Non-Dismissible Tray</Button>
+      {visible && (
+        <Tray title="Non-Dismissible Tray" preventDismiss onCloseComplete={handleClose}>
+          {({ handleClose }) => (
+            <VStack gap={2}>
+              <Text>
+                This tray cannot be dismissed, user must click an explicit action button to close
+                it.
+              </Text>
+              <Button onClick={handleClose}>Close</Button>
+            </VStack>
+          )}
+        </Tray>
+      )}
+    </VStack>
+  );
+}
+```
+
+### Multiple Overlay Flow
+
+When transitioning between overlays, ensure proper dismounting using `onCloseComplete`:
+
+```tsx live
+function TrayToModalFlow() {
+  const [isTrayVisible, setIsTrayVisible] = useState(false);
+  const [isModalVisible, setIsModalVisible] = useState(false);
+
+  const openTray = () => setIsTrayVisible(true);
+  const closeTray = () => setIsTrayVisible(false);
+  const openModal = () => setIsModalVisible(true);
+  const closeModal = () => setIsModalVisible(false);
+
+  const handleTrayClose = useCallback(() => {
+    closeTray();
+    openModal();
+  }, []);
+
+  return (
+    <VStack gap={2}>
+      <Button onClick={openTray}>Start Flow</Button>
+      {isTrayVisible && (
+        <Tray title="First Step" onCloseComplete={handleTrayClose}>
+          {({ handleClose }) => (
+            <VStack gap={2}>
+              <Text>Click below to continue to the modal</Text>
+              <Button onClick={handleClose}>Continue to Modal</Button>
+            </VStack>
+          )}
+        </Tray>
+      )}
+      <Modal visible={isModalVisible} onRequestClose={closeModal}>
+        <ModalHeader title="Second Step" />
+        <ModalBody>
+          <VStack gap={2}>
+            <Text>This is the second step in the flow.</Text>
+            <Button onClick={closeModal}>Finish</Button>
+          </VStack>
+        </ModalBody>
+      </Modal>
+    </VStack>
+  );
+}
+```
+
+Note: The Tray component is an elevated container that is pinned to the bottom of the screen and provides a standardized way to present bottom sheets in your web application. Key points:
+
+- Use `onCloseComplete` for cleanup when the tray is dismissed
+- Children can be either a React node or a render function that receives a `handleClose` function
+- The `ref` provides `open()` and `close()` methods for controlling the tray
+- When transitioning between overlays, ensure proper dismounting using lifecycle methods
+
+