An open source design system that's fully customizable and agent ready
TypeScript
fix(core): add menu placement options (#2770)
Cindy Zhang2914aabc0075
diff --git a/apps/storybook/stories/DropdownMenu.stories.tsx b/apps/storybook/stories/DropdownMenu.stories.tsxindex 2f8761766d..a95b271ee5 100644--- a/apps/storybook/stories/DropdownMenu.stories.tsx+++ b/apps/storybook/stories/DropdownMenu.stories.tsx@@ -40,6 +40,11 @@ const meta: Meta<typeof XDSDropdownMenu> = {control: 'text',description: 'Custom menu width (number for px or CSS string)',},+ placement: {+ control: 'select',+ options: ['above', 'below', 'start', 'end'],+ description: 'Menu placement relative to trigger',+ },'data-testid': {control: 'text',description: 'Test ID for testing frameworks',@@ -496,3 +501,17 @@ export const CompoundWithDescriptions: Story = {</XDSDropdownMenu>),};++export const PlacementAbove: Story = {+ render: () => (+ <XDSDropdownMenu+ button={{label: 'Bottom toolbar menu'}}+ placement="above"+ items={[+ {label: 'Edit', onClick: () => console.log('Edit')},+ {label: 'Duplicate', onClick: () => console.log('Duplicate')},+ {label: 'Delete', onClick: () => console.log('Delete')},+ ]}+ />+ ),+};diff --git a/apps/storybook/stories/Selector.stories.tsx b/apps/storybook/stories/Selector.stories.tsxindex 6a1dc02278..1f573e3e78 100644--- a/apps/storybook/stories/Selector.stories.tsx+++ b/apps/storybook/stories/Selector.stories.tsx@@ -50,6 +50,12 @@ const meta: Meta<typeof XDSSelector> = {options: ['sm', 'md', 'lg'],description: 'Size variant of the selector',},+ placement: {+ control: 'select',+ options: ['above', 'below', 'start', 'end'],+ description:+ 'Explicit menu placement. Leave unset for selected-item overlay behavior.',+ },isDisabled: {control: 'boolean',description: 'Whether the selector is disabled',@@ -554,3 +560,26 @@ export const ClearableWithStatus: Story = {status: {type: 'warning', message: 'Selection is recommended'},},};++export const PlacementAbove: Story = {+ render: args => {+ const {+ value: argsValue,+ onChange: _onChange,+ changeAction: _changeAction,+ hasClear: _hc,+ ...rest+ } = args;+ const [value, setValue] = useState(argsValue ?? 'Banana');+ return (+ <XDSSelector+ {...rest}+ label="Bottom toolbar selector"+ options={['Apple', 'Banana', 'Cherry', 'Date']}+ value={value}+ onChange={v => setValue(v)}+ placement="above"+ />+ );+ },+};diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjsindex 194bfb31e8..9514e82831 100644--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs@@ -59,6 +59,13 @@ export const docs = {description:'Custom menu width; defaults to matching the trigger button width.',},+ {+ name: 'placement',+ type: "'above' | 'below' | 'start' | 'end'",+ description:+ 'Menu placement relative to the trigger. Defaults below; the layer automatically flips when there is not enough viewport space.',+ default: "'below'",+ },{name: 'onClick',type: '() => void',@@ -184,6 +191,13 @@ export const docsZh = {description:'自定义菜单宽度;默认与触发按钮同宽。',},+ {+ name: 'placement',+ type: "'above' | 'below' | 'start' | 'end'",+ description:+ '菜单相对于触发器的位置。默认在下方;当视口空间不足时图层会自动翻转。',+ default: "'below'",+ },{name: 'onClick',type: '() => void',@@ -278,6 +292,7 @@ export const docsDense = {isMenuOpen: 'controlled open state',onOpenChange: 'callback on open state change',menuWidth: 'custom menu width; default matches trigger button',+ placement: 'menu placement relative to trigger; default below with viewport auto-flip',onClick: 'trigger button click callback',hasChevron: 'show chevron on trigger; false for icon-only triggers',hasAutoFocus: 'auto-focus first item on open; false for showcases',diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsxindex 94bae0d7c3..b2eb76df84 100644--- a/packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx+++ b/packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx@@ -63,6 +63,37 @@ describe('XDSDropdownMenu', () => {expect(screen.getByRole('menu', {hidden: true})).toBeInTheDocument();});+ it('defaults menu placement below', () => {+ render(+ <XDSDropdownMenu+ button={{label: 'Actions'}}+ items={[{label: 'Item 1'}]}+ />,+ );+ const popover = screen+ .getByRole('menu', {hidden: true})+ .closest('[popover]');+ expect(popover?.getAttribute('style')).toContain(+ 'position-area: bottom span-right',+ );+ });++ it('supports explicit menu placement', () => {+ render(+ <XDSDropdownMenu+ button={{label: 'Actions'}}+ placement="above"+ items={[{label: 'Item 1'}]}+ />,+ );+ const popover = screen+ .getByRole('menu', {hidden: true})+ .closest('[popover]');+ expect(popover?.getAttribute('style')).toContain(+ 'position-area: top span-right',+ );+ });+it('has aria-haspopup and aria-expanded attributes', () => {render(<XDSDropdownMenudiff --git a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsxindex f9591bea5d..48aa04e1bd 100644--- a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx+++ b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx@@ -44,9 +44,9 @@ import {} from './XDSDropdownMenuContext';import {useListFocus} from '../hooks/useListFocus';import {layerAnimations} from '../Layer/layerAnimations.stylex';+import type {LayerPlacement} from '../Layer/useXDSLayer';import {spacingVars,- sizeVars,radiusVars,durationVars,easeVars,@@ -74,32 +74,19 @@ const styles = stylex.create({popover: {minWidth: 'anchor-size(width)',},- popoverGap: {+ popoverBlockGap: {marginBlockStart: spacingVars['--spacing-1'],marginBlockEnd: spacingVars['--spacing-1'],},+ popoverInlineGap: {+ marginInlineStart: spacingVars['--spacing-1'],+ marginInlineEnd: spacingVars['--spacing-1'],+ },popoverCustomWidth: (width: string | number) => ({minWidth: typeof width === 'number' ? `${width}px` : width,}),});-/**- * Overlay offset styles: shift the popover up so the first item's text- * aligns with the trigger button's text.- * Formula: -(container_padding + trigger_height)- */-const popoverOverlayStyles = stylex.create({- sm: {- marginBlockStart: `calc(-1 * (${spacingVars['--spacing-1']} + ${sizeVars['--size-element-sm']}))`,- },- md: {- marginBlockStart: `calc(-1 * (${spacingVars['--spacing-1']} + ${sizeVars['--size-element-md']}))`,- },- lg: {- marginBlockStart: `calc(-1 * (${spacingVars['--spacing-1']} + ${sizeVars['--size-element-lg']}))`,- },-});-// =============================================================================// Types// =============================================================================@@ -139,6 +126,13 @@ interface XDSDropdownMenuBaseProps extends XDSBaseProps {menuWidth?: number | string;onClick?: () => void;hasChevron?: boolean;+ /**+ * Position placement relative to the trigger.+ * Uses the same placement values as other XDS layer-based components.+ * @default 'below'+ */+ placement?: LayerPlacement;+/*** Whether to auto-focus the first menu item when the menu opens.* Set to `false` for inline showcases or documentation previews@@ -196,6 +190,7 @@ export function XDSDropdownMenu({menuWidth,onClick,hasChevron = true,+ placement = 'below',hasAutoFocus = true,className,style,@@ -357,6 +352,10 @@ export function XDSDropdownMenu({const popoverXstyle = menuWidth? styles.popoverCustomWidth(menuWidth): styles.popover;+ const popoverGapStyle =+ placement === 'above' || placement === 'below'+ ? styles.popoverBlockGap+ : styles.popoverInlineGap;// Context for compound itemsconst contextValue = useMemo<XDSDropdownMenuContextValue>(@@ -411,13 +410,9 @@ export function XDSDropdownMenu({</XDSDropdownMenuContext></div>,{- placement: 'below',+ placement,alignment: 'start',- xstyle: [- popoverXstyle,- popoverOverlayStyles[menuSize],- layerAnimations.below,- ],+ xstyle: [popoverXstyle, popoverGapStyle, layerAnimations[placement]],},)}</>diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjsindex 5f55f032c8..fed560f769 100644--- a/packages/core/src/Selector/Selector.doc.mjs+++ b/packages/core/src/Selector/Selector.doc.mjs@@ -62,6 +62,12 @@ export const docs = {description: 'Placeholder text for the search input.',default: "'Search...'",},+ {+ name: 'placement',+ type: "'above' | 'below' | 'start' | 'end'",+ description:+ 'Dropdown placement relative to the trigger. Omit for the default selector behavior: align the selected item over the trigger and clamp the menu to the viewport. Set a value to use explicit layer positioning.',+ },{name: 'placeholder',type: 'string',@@ -224,6 +230,12 @@ export const docsZh = {description: '搜索输入的占位文本。',default: "'Search...'",},+ {+ name: 'placement',+ type: "'above' | 'below' | 'start' | 'end'",+ description:+ '下拉层相对于触发器的位置。省略时使用选择器默认行为:将已选项对齐到触发器上并限制在视口内。设置后使用显式图层定位。',+ },{name: 'placeholder',type: 'string',@@ -366,6 +378,7 @@ export const docsDense = {hasClear: 'Shows clear button when value selected. onChange also accepts null on clear.',hasSearch: 'Shows search input for filtering options.',searchPlaceholder: 'Placeholder text for search input.',+ placement: 'Dropdown placement. Omit for selected-item overlay clamped to viewport; set value for explicit layer positioning.',placeholder: 'Placeholder text when no value selected.',size: 'Size variant for selector.',isDisabled: 'Disables selector.',diff --git a/packages/core/src/Selector/XDSSelector.test.tsx b/packages/core/src/Selector/XDSSelector.test.tsxindex f4c7c49939..bfbdc2b84e 100644--- a/packages/core/src/Selector/XDSSelector.test.tsx+++ b/packages/core/src/Selector/XDSSelector.test.tsx@@ -10,7 +10,7 @@*/import {describe, it, expect, vi, beforeEach} from 'vitest';-import {render, screen} from '@testing-library/react';+import {render, screen, waitFor} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {XDSSelector} from './XDSSelector';@@ -46,6 +46,65 @@ const h = {hidden: true} as const;const OPTIONS = ['Apple', 'Banana', 'Cherry'];+function rect({+ top,+ bottom,+ left = 0,+ right = 100,+ width = right - left,+ height = bottom - top,+}: {+ top: number;+ bottom: number;+ left?: number;+ right?: number;+ width?: number;+ height?: number;+}): DOMRect {+ return {+ x: left,+ y: top,+ top,+ bottom,+ left,+ right,+ width,+ height,+ toJSON: () => ({}),+ };+}++function mockSelectorRects() {+ const originalGetBoundingClientRect =+ HTMLElement.prototype.getBoundingClientRect;+ const originalInnerHeight = Object.getOwnPropertyDescriptor(+ window,+ 'innerHeight',+ );+ HTMLElement.prototype.getBoundingClientRect = function () {+ if (this.getAttribute('role') === 'combobox') {+ return rect({top: 160, bottom: 190, height: 30});+ }+ if (this.getAttribute('role') === 'listbox') {+ return rect({top: 190, bottom: 310, height: 120});+ }+ if (this.id.endsWith('-item-1')) {+ return rect({top: 220, bottom: 250, height: 30});+ }+ return originalGetBoundingClientRect.call(this);+ };+ Object.defineProperty(window, 'innerHeight', {+ value: 200,+ configurable: true,+ });+ return () => {+ HTMLElement.prototype.getBoundingClientRect = originalGetBoundingClientRect;+ if (originalInnerHeight) {+ Object.defineProperty(window, 'innerHeight', originalInnerHeight);+ }+ };+}+describe('XDSSelector', () => {it('renders with placeholder when no value', () => {render(@@ -66,6 +125,79 @@ describe('XDSSelector', () => {expect(screen.getByRole('combobox')).toHaveTextContent('Banana');});+ it('supports explicit menu placement', () => {+ render(+ <XDSSelector+ label="Fruit"+ options={OPTIONS}+ value="Banana"+ onChange={() => {}}+ placement="above"+ />,+ );+ const popover = screen+ .getByRole('listbox', {hidden: true})+ .closest('[popover]');+ expect(popover?.getAttribute('style')).toContain(+ 'position-area: top span-right',+ );+ });++ it('clamps the default selected-item overlay to the viewport', async () => {+ const restoreRects = mockSelectorRects();+ const user = userEvent.setup();+ try {+ render(+ <XDSSelector+ label="Fruit"+ options={OPTIONS}+ value="Banana"+ onChange={() => {}}+ />,+ );++ await user.click(screen.getByRole('combobox'));+ const popover = screen+ .getByRole('listbox', {hidden: true})+ .closest('[popover]');+ await waitFor(() => {+ expect(popover?.getAttribute('style')).toContain(+ 'margin-block-start: -110px',+ );+ });+ } finally {+ restoreRects();+ }+ });++ it('does not apply selected-item overlay offset when placement is explicit', async () => {+ const restoreRects = mockSelectorRects();+ const user = userEvent.setup();+ try {+ render(+ <XDSSelector+ label="Fruit"+ options={OPTIONS}+ value="Banana"+ onChange={() => {}}+ placement="above"+ />,+ );++ await user.click(screen.getByRole('combobox'));+ const popover = screen+ .getByRole('listbox', {hidden: true})+ .closest('[popover]');+ await waitFor(() => {+ expect(popover?.getAttribute('style')).not.toContain(+ 'margin-block-start',+ );+ });+ } finally {+ restoreRects();+ }+ });+describe('hasClear', () => {it('shows selected value label when hasClear is enabled', () => {render(diff --git a/packages/core/src/Selector/XDSSelector.tsx b/packages/core/src/Selector/XDSSelector.tsxindex 4d0b8b3015..3444f42a29 100644--- a/packages/core/src/Selector/XDSSelector.tsx+++ b/packages/core/src/Selector/XDSSelector.tsx@@ -37,6 +37,7 @@ import {} from '../Field';import {XDSDivider} from '../Divider';import {layerAnimations} from '../Layer/layerAnimations.stylex';+import type {LayerPlacement} from '../Layer/useXDSLayer';import {XDSSpinner} from '../Spinner';import {colorVars,@@ -175,9 +176,6 @@ const styles = stylex.create({opacity: 0,transition: 'none',},- dropdownOffset: (offset: number) => ({- marginTop: offset,- }),// Popover container (for anchor positioning)popover: {@@ -433,6 +431,16 @@ interface XDSSelectorPropsBase<*/searchPlaceholder?: string;+ /**+ * Position placement relative to the trigger.+ *+ * Omit to use the selector's default selected-item overlay behavior: the+ * selected item is positioned over the trigger and clamped to the viewport.+ * Set a placement to opt into explicit layer positioning (for example,+ * `placement="above"` for bottom-fixed toolbars).+ */+ placement?: LayerPlacement;+/*** Whether the dropdown starts open on mount.* Useful for showcases and previews.@@ -527,6 +535,7 @@ export function XDSSelector<T extends XDSSelectorOptionType>(children,hasSearch = false,searchPlaceholder = 'Search...',+ placement,isDefaultOpen = false,'data-testid': testId,xstyle,@@ -615,19 +624,26 @@ export function XDSSelector<T extends XDSSelectorOptionType>(// eslint-disable-next-line @eslint-react/exhaustive-deps -- mount-only: isDefaultOpen is not reactive}, []);- // Calculate offset to position selected item over trigger+ // Calculate offset to position selected item over trigger. Explicit+ // placement opts out of the selector-specific overlay behavior and uses the+ // standard layer positioning API instead.+ const shouldOverlaySelectedItem = placement == null && !hasSearch;const {offset: rawOffset, isPositioned: rawIsPositioned} =useSelectedItemOffset({- isOpen: popover.isOpen,+ isOpen: popover.isOpen && shouldOverlaySelectedItem,selectedItemIndex,listboxId,listboxRef,triggerRef,});- // Disable macOS overlay positioning when search is active- const selectedItemOffset = hasSearch ? 0 : rawOffset;- const isPositioned = hasSearch ? true : rawIsPositioned;+ const selectedItemOffset = shouldOverlaySelectedItem ? rawOffset : 0;+ const isPositioned = shouldOverlaySelectedItem ? rawIsPositioned : true;+ const popoverPlacement = placement ?? 'below';+ const popoverOffsetStyle: React.CSSProperties | undefined =+ selectedItemOffset > 0+ ? {marginBlockStart: `-${selectedItemOffset}px`}+ : undefined;// Selector behavior (keyboard nav, typeahead, selection)const {@@ -936,15 +952,15 @@ export function XDSSelector<T extends XDSSelectorOptionType>({...stylex.props(styles.dropdown,!isPositioned && styles.dropdownHidden,- styles.dropdownOffset(-selectedItemOffset),)}>{renderOptions()}</div>),{- placement: 'below',+ placement: popoverPlacement,alignment: 'start',- xstyle: [styles.popover, layerAnimations.below],+ xstyle: [styles.popover, layerAnimations[popoverPlacement]],+ style: popoverOffsetStyle,},)}</XDSField>diff --git a/packages/core/src/Selector/hooks.ts b/packages/core/src/Selector/hooks.tsindex 7b7a7faa09..a1a1bc7f9a 100644--- a/packages/core/src/Selector/hooks.ts+++ b/packages/core/src/Selector/hooks.ts@@ -34,11 +34,11 @@ interface UseSelectedItemOffsetResult {* Calculates the offset needed to position the dropdown so that the selected* item appears centered over the trigger button (macOS-style selector).*- * When the offset would push the popover out of the viewport (e.g. the selector- * is near the top of the page), the offset is clamped so the popover stays- * fully visible. If the selected item can't be shown over the trigger without- * going out of bounds, the popover falls back to appearing below the trigger- * with no offset.+ * The desired dropdown top is calculated directly from the trigger center and+ * selected-item center, then clamped to the viewport. This preserves the+ * default "selected item over trigger" behavior while letting the menu slide+ * upward near the bottom edge or downward near the top edge instead of being+ * clipped off-screen.*/export function useSelectedItemOffset({isOpen,@@ -83,47 +83,34 @@ export function useSelectedItemOffset({return;}- // Get positions+ // Get positions. JSDOM returns zero rects by default, but browsers provide+ // real dimensions before paint via layout effect.const listboxRect = listboxRef.current.getBoundingClientRect();const itemRect = targetItem.getBoundingClientRect();const triggerRect = triggerRef.current.getBoundingClientRect();- // Calculate offset to center the item over the trigger- // The listbox is positioned below the trigger by anchor positioning (top of listbox at bottom of trigger)- // We need to move it UP so the selected item's center aligns with trigger's center- //- // Item center relative to listbox top:- const itemCenterInListbox =- itemRect.top - listboxRect.top + itemRect.height / 2;- //- // To center item over trigger, we need to move up by:- // (item center in listbox) + (half trigger height to reach trigger's center from its bottom edge)- const calculatedOffset = itemCenterInListbox + triggerRect.height / 2;-- // Clamp to viewport bounds — don't let the popover go above the screen.- // The popover's top edge after offset = triggerRect.bottom - calculatedOffset.- // We want: top >= 0 (viewport top) and bottom <= viewportHeight.- const popoverTopAfterOffset = triggerRect.bottom - calculatedOffset;const listboxHeight = listboxRect.height;- const popoverBottomAfterOffset = popoverTopAfterOffset + listboxHeight;- const viewportHeight = window.innerHeight;+ if (listboxHeight <= 0) {+ commitPosition(0, true);+ return;+ }- let clampedOffset = calculatedOffset;+ // Item center relative to listbox top. This remains stable even as the+ // popover's top changes between measurements.+ const itemCenterInListbox =+ itemRect.top - listboxRect.top + itemRect.height / 2;+ const triggerCenter = triggerRect.top + triggerRect.height / 2;- if (popoverTopAfterOffset < 0) {- // Would go above viewport — reduce offset so top edge sits at viewport top- clampedOffset = calculatedOffset + popoverTopAfterOffset;- } else if (popoverBottomAfterOffset > viewportHeight) {- // Would go below viewport — reduce offset so bottom edge sits at viewport bottom- clampedOffset =- calculatedOffset - (popoverBottomAfterOffset - viewportHeight);- }+ // Desired top aligns the selected item's center with trigger center.+ const desiredTop = triggerCenter - itemCenterInListbox;+ const viewportHeight = window.innerHeight;+ const maxTop = Math.max(0, viewportHeight - listboxHeight);+ const clampedTop = Math.min(Math.max(desiredTop, 0), maxTop);- // If even the clamped offset is negative or near-zero, fall back to- // showing the popover below the trigger with no overlay offset- if (clampedOffset < 0) {- clampedOffset = 0;- }+ // useXDSLayer positions the popover below the trigger. Apply a negative+ // block-start margin to the layer container so the listbox top moves from+ // triggerRect.bottom to clampedTop.+ const clampedOffset = Math.max(0, triggerRect.bottom - clampedTop);commitPosition(clampedOffset, true);}, [