feat: PopoverPanel + Dropdown deprecation by adrienzheng-cb · Pull Request #566 · coinbase/cds

adrienzheng-cb · 2026-03-30T23:03:13Z

What changed? Why?

Popover (internal)

Replace Popper.js positioning with @floating-ui/react-dom: useFloating, autoUpdate,
offset (skid/gap), flip + shift + limitShift for fixed placements, and autoPlacement
for placement values that start with "auto".
Wrap the component in forwardRef and merge the consumer ref with the Floating UI
reference ref (useMergeRefs).
Add optional style and className on the subject (trigger) root.

PopoverPanel / PopoverPanelContent

Add PopoverPanel: trigger + floating or phone modal layout, content as node or
(closePopover) => node, optional enableMobileModal, sizing (panelWidth, min/max
width/height), showOverlay, contentPosition, ref with openPopover/closePopover.
Add PopoverPanelContent: animated VStack surface for the panel body.
Wire useComponentConfig for PopoverPanel and PopoverPanelContent; register both in
core/componentConfig.ts.
Export from packages/web overlays barrel and new package entry @coinbase/cds-web/popover
(package.json exports).
Add Storybook stories, unit tests, and Docusaurus (docgen, examples, props table,
styles explorer, sidebar, webMetadata).

useResponsivePanelMaxHeight (renamed from useResponsiveHeight in popover)

New module overlays/popover/useResponsivePanelMaxHeight.ts (canonical hook for
PopoverPanel).
Rename the hook to useResponsivePanelMaxHeight; return value is panelMaxHeight
(was dropdownHeight in the shared logic).
Rename the measured bounds argument to panelBounds (was dropdownBounds) for panel
sizing; keep the same viewport / calc(100vh - …) responsive behavior.
Support ResponsiveProp with resolveResponsiveMaxHeight aligned to
phone/tablet/desktop breakpoints via useBreakpoints.
Legacy packages/web/src/dropdown/useResponsiveHeight.ts remains for Dropdown only,
with the original non-responsive maxHeight API; deprecate in favor of importing
useResponsivePanelMaxHeight from @coinbase/cds-web/popover (removal v10) and add a
short comment that new behavior lives under overlays/popover.

Dropdown deprecation

Deprecate Dropdown, DropdownContent, DropdownProps-related types, and docs
Dropdown webMetadata warning: use PopoverPanel / PopoverPanelContent instead
(expected removal v10).

Other

ModalWrapper: when hideOverlay is true, render a transparent fixed VStack that still
receives overlay press so dismiss works without a visible Overlay.
Jest: extend @floating-ui/react-dom mock with limitShift.

Breaking / migration notes for consumers

Popover: possible subtle positioning and DOM structure differences vs Popper; new
ref and subject style/className are additive.
Dropdown: deprecated; migrate to PopoverPanel.
Popover-adjacent hook: prefer useResponsivePanelMaxHeight from @coinbase/cds-web/popover;
dropdown/useResponsiveHeight is legacy and deprecated.

UI changes

storybook
docs

Screen.Recording.2026-04-02.at.1.15.52.AM.mov

Testing

How has it been tested?

Testing instructions

Illustrations/Icons Checklist

Required if this PR changes files under packages/illustrations/** or packages/icons/**

verified visreg changes with Terran (include link to visreg run/approval)
all illustration/icons names have been reviewed by Dom and/or Terran

Change management

type=routine
risk=low
impact=sev5

automerge=false

cb-ekuersch

Before we can recommend switching to Popover we should at least:

audit Popover to make sure it can handle any/all use cases that Dropdown can. Any storybook stories from Dropdown should be able to be effortlessly migrated to Popover stories
add docsite pages for Popover

cb-heimdall · 2026-04-02T15:11:23Z

✅ Heimdall Review Status

Requirement Status More Info

Reviews

✅ 1/1

Denominator calculation

Show calculation

1 if user is bot 0

1 if user is external 0

2 if repo is sensitive 0

From .codeflow.yml 1

Additional review requirements

Show calculation

Max	0

0

From CODEOWNERS 1

Global minimum 0

Max 1

1

1 if commit is unverified 0

Sum 1

CODEOWNERS ✅ See below

⚠️ Ignored Reviews (2)

Reviewer	Reason
cb-ekuersch	Old or outdated review
cb-ekuersch	Review missing MFA

✅ `CODEOWNERS`

Code Owner Status Calculation

ui-systems-eng-team

✅ 1/1

Denominator calculation

Additional CODEOWNERS Requirement

Show calculation

Sum	0

0

From CODEOWNERS 1

Sum 1

adrienzheng-cb · 2026-04-02T15:53:03Z

-import React, { memo, useCallback, useMemo } from 'react';
+import React, { forwardRef, memo, useCallback, useMemo } from 'react';
 import { zIndex } from '@coinbase/cds-common/tokens/zIndex';
+import { useMergeRefs } from '@coinbase/cds-common/hooks/useMergeRefs';


will replace with mergeRefs after merging into v9

adrienzheng-cb · 2026-04-02T15:54:06Z

+  type Placement as FloatingPlacement,
+  shift,
+  useFloating,
+} from '@floating-ui/react-dom';


originally replacing with popper with floating UI in popover was done in v9 feature branch, but moved it here since we needed to have PopoverPanel before v9 and Popover is affected

non-breaking since all props are the same

adrienzheng-cb · 2026-04-02T16:12:25Z

+  /** Can optionally pass a maxHeight.
+   * @default 300
+   */
+  maxPanelHeight?: React.CSSProperties['maxHeight'];


maxPanelWidth/Height instead of maxHeight to make it clear to which element dimension is set

adrienzheng-cb · 2026-04-02T19:06:17Z

                    onClick={!disableOverlayPress ? onOverlayPress : undefined}
                    testID="modal-overlay"
                  />
+                ) : (


adding this here so Modal without overlay can still be closed when clicking outside

Would moving this to the parent <Box> be a better alternative? Or does that not work?

I tried that at first, but the problem with that was clicking inside the dialog would also close the modal since the parent Box wraps both the overlay and the dialog.

adrienzheng-cb · 2026-04-02T19:07:09Z

+/**
+ * @deprecated Import `useResponsiveHeight` from `@coinbase/cds-web/popover` instead. This will be removed in a future major release.
+ * @deprecationExpectedRemoval v10
+ */


added a replacement under popover directory. the replacement handle can handle maxHeight with responsive value

adrienzheng-cb · 2026-04-02T19:07:54Z

  onBlur?: (event?: React.FocusEvent) => void;
  /** Callback fired when a mouse down event is fired on the subject */
  onMouseDown?: (event: React.MouseEvent) => void;
+  /**


added style can className support to Popover

maximo-macchi-cb

Currently reviewed new PopoverPanel components in web. Will finish review tomorrow but saving here just in case.

maximo-macchi-cb · 2026-04-13T22:18:36Z

+  title: 'Components/Overlay/PopoverPanel',
+  component: PopoverPanel,
+  parameters: {
+    a11y: { test: 'off' },


Why are a11y tests being disabled? I enabled them locally and in the Storybook UI and CLI all tests pass

oh my bad. I re-enabled it

maximo-macchi-cb · 2026-04-13T22:21:54Z

+    /**
+     * Width of the panel as a percentage string or number converted to pixels.
+     */
+    panelWidth?: PopoverPanelContentBaseProps['width'];
+    /** Minimum width of the panel as a percentage string or number converted to pixels. */
+    minPanelWidth?: PopoverPanelContentBaseProps['minWidth'];
+    /** Maximum width of the panel as a percentage string or number converted to pixels. */
+    maxPanelWidth?: PopoverPanelContentBaseProps['maxWidth'];
+    /** Height of the panel as a percentage string or number converted to pixels. */
+    panelHeight?: PopoverPanelContentBaseProps['height'];


Small nit: since our other height / width props only are named as "height" and "width" I think it'd be easier for engineers to pick up on by keeping the naming convention consistent

Suggested change

/**

* Width of the panel as a percentage string or number converted to pixels.

*/

panelWidth?: PopoverPanelContentBaseProps['width'];

/** Minimum width of the panel as a percentage string or number converted to pixels. */

minPanelWidth?: PopoverPanelContentBaseProps['minWidth'];

/** Maximum width of the panel as a percentage string or number converted to pixels. */

maxPanelWidth?: PopoverPanelContentBaseProps['maxWidth'];

/** Height of the panel as a percentage string or number converted to pixels. */

panelHeight?: PopoverPanelContentBaseProps['height'];

/**

* Width of the panel as a percentage string or number converted to pixels.

*/

width?: PopoverPanelContentBaseProps['width'];

/** Minimum width of the panel as a percentage string or number converted to pixels. */

minWidth?: PopoverPanelContentBaseProps['minWidth'];

/** Maximum width of the panel as a percentage string or number converted to pixels. */

maxWidth?: PopoverPanelContentBaseProps['maxWidth'];

/** Height of the panel as a percentage string or number converted to pixels. */

height?: PopoverPanelContentBaseProps['height'];

I added the panel prefix on purpose so it is clear that they define dimensions of the popover panel not the popover trigger.

maximo-macchi-cb · 2026-04-13T22:32:33Z

+        // eslint-disable-next-line jsx-a11y/click-events-have-key-events
+        <div
+          className={cx(block ? blockCss : triggerContainerCss, classNames?.triggerContainer)}
+          onBlur={onBlur}
+          onClick={disabled ? undefined : onOpen}
+          style={styles?.triggerContainer}
+        >


Even though this is meant for mobile devices, this could still render in a web browser on a desktop where the browser's window width is small, right? Two suggestions for this:

An onKeyDown handler should be added here

A prop for accessibilityRole with default value of "button" should be added to the prop API and used here

Suggested change

// eslint-disable-next-line jsx-a11y/click-events-have-key-events

<div

className={cx(block ? blockCss : triggerContainerCss, classNames?.triggerContainer)}

onBlur={onBlur}

onClick={disabled ? undefined : onOpen}

style={styles?.triggerContainer}

>

<div

accessibilityRole={accessibilityRole}

className={cx(block ? blockCss : triggerContainerCss, classNames?.triggerContainer)}

onBlur={onBlur}

onClick={disabled ? undefined : onOpen}

// onKeyDown could handle the key event then call onOpen

onKeyDown={disabled ? undefined : onKeyDown}

style={styles?.triggerContainer}

>

the panel already opens when pressing enter while focusing on the children at the moment without onKeyDown and since this component handles the open and close logic internally and does not take onKeyDown prop, we don't need to pass onKeydown here.

for accessibilityRole, the child is most likely a button already, if we add additional role to the trigger wrapper here, then we end up with nested buttons.

I will mention in the docs that they should use always interactive element as the child(trigger) of PopoverPanel

maximo-macchi-cb · 2026-04-13T22:33:26Z

+            hideOverlay={!showOverlay}
+            onClick={handleCaptureEvents}
+            onOverlayPress={onClose}
+            testID="popover-panel-modal"


We should make the testID a prop with default of "popover-panel-modal" so customers can configure this as they'd like

added the testID prop but did not assign the default id because we are actually not using it and since this is a new component so no one else is selecting the component using this id.

maximo-macchi-cb · 2026-04-13T22:35:54Z

+            <FocusTrap
+              onEscPress={onClose}
+              respectNegativeTabIndex={respectNegativeTabIndex}
+              restoreFocusOnUnmount={restoreFocusOnUnmount}
+            >


I think adding the following props from FocusTrapBaseProps would be beneficial for customers to configure:

disableAutoFocus

includeTriggerInFocusTrap

focusTabIndexElements

autoFocusDelay

maximo-macchi-cb · 2026-04-13T22:44:02Z

+        background="bg"
+        borderRadius={400}
+        className={cx(popoverPanelContentClassName, className)}
+        elevation={2}
+        minWidth={minWidth}
+        overflow="auto"


Shouldn't these be configurable? At least background, borderRadius, and overflow

cb-ekuersch

Looking good, but I have a couple of quesitons:

What are the long term plans for the two popover directories: src/overlays/popover and src/popover?
Are we planning to keep supporting Popover on its own? I thought PopoverPanel was meant to completely replace it rather than compose it

cb-ekuersch · 2026-04-14T13:10:06Z

  PageHeader?: ConfigResolver<PageHeaderBaseProps>;
  Pagination?: ConfigResolver<PaginationBaseProps>;
+  PopoverPanel?: ConfigResolver<PopoverPanelBaseProps>;
+  PopoverPanelContent?: ConfigResolver<PopoverPanelContentBaseProps>;


Customers never explicitly render a PopoverPanelContent component. It is an implementation detail of the content prop. I recommend we don't add "hidden" components to the component theme config

got it. I'm gonna remove TooltipContent from the component theme config for consistency then.

cb-ekuersch · 2026-04-14T13:30:45Z

+}
+
+export const Default: Story = {
+  render: () => <DefaultStory />,


i think there is a shorter way to define these, take a moment to review: https://storybook.js.org/blog/storybook-csf3-is-here/

You can have a default export that defines a render and then export objects that change the props/args. Not sure if that setup would help you at all here

removed this redundant code
exporting the DefaultStory component would do it.

cb-ekuersch · 2026-04-14T13:31:51Z

+import { DefaultThemeProvider } from '../../../utils/test';
+import { PopoverPanel, type PopoverPanelRef } from '../PopoverPanel';
+
+jest.mock('react-use-measure');


nit: i wonder if we should just centralize the mock of this if its always necessary to set up, similar to what we did for floating ui

good suggestion! I will address this in a separate pr since we have a lot of tests that mock this hook.

cb-ekuersch · 2026-04-14T13:33:28Z

 export * from './overlay/Overlay';
 export * from './popover/Popover';
+export * from './popover/PopoverPanel';
+export * from './popover/PopoverPanelContent';


do we really want to to encourage direct use by putting it in the barrel file? It seems like this component is more an implementation detail; a true sub-component

good catch. I removed the PopoverPanelContent and made it strictly internal

cb-ekuersch · 2026-04-14T13:34:32Z

+
+export type PopoverPanelBaseProps = Pick<
+  PopoverBaseProps,
+  | 'children'


put children on props, not base props

cb-ekuersch · 2026-04-14T13:34:50Z

+  | 'controlledElementAccessibilityProps'
+  | 'respectNegativeTabIndex'
+> &
+  SharedProps &


nit: put full types first in set

cb-ekuersch · 2026-04-14T13:35:37Z

+
+export type PopoverPanelProps = PopoverPanelBaseProps & {
+  style?: React.CSSProperties;
+  styles?: {


use styles and classnames helper - maybe try the skill Hunter added to see how it performs

cb-ekuersch · 2026-04-14T13:36:46Z

+  visible: boolean;
+};
+
+export const POPOVER_PANEL_MAX_HEIGHT = 300;


it might make more sense to encapsulate this in the module for the max height hook

I ended up removing the max height hook. it is no longer necessary because floating-ui can already handle that for us.

cb-ekuersch · 2026-04-14T13:37:07Z

+  placement: 'bottom-start',
+};
+
+function usePopoverPanelImperativeHandle(


nit: is this separate hook necessary?

it is separate because we use it both in Mobile(Modal) and FloatingPopoverPanel sub components.

maximo-macchi-cb

Review fully done! Left a couple additional comments

maximo-macchi-cb · 2026-04-14T15:42:14Z

 );

+/**
+ * @deprecated Use PopoverPanel instead. This will be removed in a future major release.


Select should be mentioned here too. Dropdown was very similar to Select. So while PopoverPanel may satisfy some customer's needs, others may be wanting a Select-like component and Select / SelectChip would be better for that than PopoverPanel

updated all deprecation messages to recommend Select for selectable use case

maximo-macchi-cb · 2026-04-14T15:46:42Z

                    onClick={!disableOverlayPress ? onOverlayPress : undefined}
                    testID="modal-overlay"
                  />
+                ) : (


Would moving this to the parent <Box> be a better alternative? Or does that not work?

- Add PopoverPanel, PopoverPanelContent, tests, stories, and @coinbase/cds-web/popover export - Document PopoverPanel (docgen, sidebar, component docs) - Deprecate Dropdown, DropdownProps-related types, and DropdownContent for removal in v10 - Popover: forwardRef with mergeRefs for Floating UI reference; flatten to one root div; add style/className to PopoverProps - Re-export PopoverPanel from overlays index; add Dropdown docs warning

fix ModalWrapper not closing when clicked outside without overlay

adrienzheng-cb · 2026-04-16T20:32:22Z

@cb-ekuersch

What are the long term plans for the two popover directories: src/overlays/popover and src/popover?

Good catch! I removed the src/popover directory. It was added by mistake. PopoverPanel and Popover are only exported from overlays now.

Are we planning to keep supporting Popover on its own? I thought PopoverPanel was meant to completely replace it rather than compose it

yes, we still need to support Popover on its own because I have seen consumers using this component in many places and implemented their own PopoverPanel/Dropdown logic on top of it.

adrienzheng-cb requested a review from cb-ekuersch March 30, 2026 23:03

cb-ekuersch reviewed Mar 30, 2026

View reviewed changes

adrienzheng-cb force-pushed the adrien/deprecate-dropdown branch from ca7a9d9 to 1bcca8d Compare April 2, 2026 04:49

adrienzheng-cb marked this pull request as draft April 2, 2026 04:50

adrienzheng-cb force-pushed the adrien/deprecate-dropdown branch from 102cbda to 4f73334 Compare April 2, 2026 15:11

adrienzheng-cb changed the base branch from cds-v9 to master April 2, 2026 15:11

adrienzheng-cb had a problem deploying to production April 2, 2026 15:43 — with GitHub Actions Error

github-actions bot added packages:web apps:docs labels Apr 2, 2026

adrienzheng-cb changed the title ~~chore: deprecate Dropdown~~ feat: PopoverPanel + Dropdown deprecation Apr 2, 2026

adrienzheng-cb had a problem deploying to production April 2, 2026 15:56 — with GitHub Actions Error

adrienzheng-cb temporarily deployed to production April 2, 2026 16:10 — with GitHub Actions Inactive

adrienzheng-cb force-pushed the adrien/deprecate-dropdown branch from 5246936 to 5aa2102 Compare April 2, 2026 18:59

adrienzheng-cb had a problem deploying to production April 2, 2026 18:59 — with GitHub Actions Error

adrienzheng-cb force-pushed the adrien/deprecate-dropdown branch from 5aa2102 to e99745a Compare April 2, 2026 19:00

adrienzheng-cb had a problem deploying to production April 2, 2026 19:00 — with GitHub Actions Error

adrienzheng-cb commented Apr 2, 2026

View reviewed changes

adrienzheng-cb had a problem deploying to production April 2, 2026 19:20 — with GitHub Actions Error

adrienzheng-cb requested review from cb-ekuersch and hcopp April 2, 2026 19:22

adrienzheng-cb marked this pull request as ready for review April 2, 2026 19:25

adrienzheng-cb temporarily deployed to production April 2, 2026 19:26 — with GitHub Actions Inactive

adrienzheng-cb temporarily deployed to production April 2, 2026 19:47 — with GitHub Actions Inactive

maximo-macchi-cb self-requested a review April 13, 2026 20:03

maximo-macchi-cb reviewed Apr 13, 2026

View reviewed changes

cb-ekuersch reviewed Apr 14, 2026

View reviewed changes

maximo-macchi-cb reviewed Apr 14, 2026

View reviewed changes

adrienzheng-cb added 2 commits April 15, 2026 17:50

update jsdocs and peer dependency

0808ea9

fix ModalWrapper not closing when clicked outside without overlay

adrienzheng-cb added 3 commits April 15, 2026 17:50

lint

89ee509

update jsdocs

990709f

placement type update

37c0cb1

adrienzheng-cb force-pushed the adrien/deprecate-dropdown branch from f1e9bd2 to 37c0cb1 Compare April 15, 2026 21:50

adrienzheng-cb temporarily deployed to production April 15, 2026 21:50 — with GitHub Actions Inactive

address pr comments

ad315f8

adrienzheng-cb had a problem deploying to production April 16, 2026 20:11 — with GitHub Actions Error

update docs

968d0f8

adrienzheng-cb requested review from cb-ekuersch and maximo-macchi-cb April 16, 2026 20:26

adrienzheng-cb had a problem deploying to production April 16, 2026 20:26 — with GitHub Actions Error

Merge branch 'master' into adrien/deprecate-dropdown

512a164

adrienzheng-cb had a problem deploying to production April 16, 2026 20:36 — with GitHub Actions Error

fix broken links

9253465

adrienzheng-cb had a problem deploying to production April 16, 2026 20:39 — with GitHub Actions Error

update Popover jsdocs

3232208

adrienzheng-cb had a problem deploying to production April 16, 2026 20:49 — with GitHub Actions Error

release

73e61b9

github-actions bot added packages:common packages:mobile packages:mcp-server labels Apr 16, 2026

adrienzheng-cb temporarily deployed to production April 16, 2026 20:58 — with GitHub Actions Inactive

cb-ekuersch approved these changes Apr 16, 2026

View reviewed changes

Merge branch 'master' into adrien/deprecate-dropdown

f37dda7

adrienzheng-cb temporarily deployed to production April 16, 2026 21:59 — with GitHub Actions Inactive

adrienzheng-cb requested a review from cb-ekuersch April 16, 2026 22:00

cb-ekuersch approved these changes Apr 16, 2026

View reviewed changes

adrienzheng-cb merged commit 35d5eb4 into master Apr 16, 2026
33 of 34 checks passed

adrienzheng-cb deleted the adrien/deprecate-dropdown branch April 16, 2026 22:20

Conversation

adrienzheng-cb commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed? Why?

Popover (internal)

PopoverPanel / PopoverPanelContent

useResponsivePanelMaxHeight (renamed from useResponsiveHeight in popover)

Dropdown deprecation

Other

Breaking / migration notes for consumers

UI changes

Testing

How has it been tested?

Testing instructions

Illustrations/Icons Checklist

Change management

Uh oh!

cb-ekuersch left a comment

Choose a reason for hiding this comment

Uh oh!

cb-heimdall commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Heimdall Review Status

⚠️ Ignored Reviews (2)

✅ CODEOWNERS

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maximo-macchi-cb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cb-ekuersch left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adrienzheng-cb commented Mar 30, 2026 •

edited

Loading

cb-heimdall commented Apr 2, 2026 •

edited

Loading

✅ `CODEOWNERS`