Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): forward pass-through props on seven components (#5563)

Cindy Zhangd1807b87c8c6
diff --git a/.changeset/baseprops-passthrough-forwarding.md b/.changeset/baseprops-passthrough-forwarding.md
new file mode 100644
index 0000000000..647881ad07
--- /dev/null
+++ b/.changeset/baseprops-passthrough-forwarding.md
@@ -0,0 +1,13 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Seven components now forward the pass-through props promised by `BaseProps`
+
+`MetadataListItem`, `NavHeadingMenu`, `Timestamp`, `Token`, `TopNavMegaMenu`, `TopNavMenu`, and `TypeaheadItem` now forward neutral `aria-*`, `id`, `tabIndex`, event-handler, and `data-*` props to their rendered DOM element. Styling still merges through `mergeProps`, contract-owned attributes retain precedence, and owned handlers compose through `composeEventHandlers` with the caller first.
+
+`MetadataListItem` targets its wrapper `<div>` when stacked and its `<dt>` when inline. A `TypeaheadItem` backed by caller-supplied `item.element` remains unchanged and does not receive forwarded props because that value may not be a cloneable element.
+
+This completes [#5254](https://github.com/facebook/astryx/issues/5254) after [#5288](https://github.com/facebook/astryx/pull/5288) by @lexs landed `List` and `Markdown` first, followed by [#5493](https://github.com/facebook/astryx/pull/5493) by @gonzoblasco for `TreeList`.
+
+@cixzhang
diff --git a/packages/core/src/MetadataList/MetadataList.test.tsx b/packages/core/src/MetadataList/MetadataList.test.tsx
index 992afb0535..ac668d7581 100644
--- a/packages/core/src/MetadataList/MetadataList.test.tsx
+++ b/packages/core/src/MetadataList/MetadataList.test.tsx
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-import {describe, it, expect} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {MetadataList} from './MetadataList';
import {MetadataListItem} from './MetadataListItem';
@@ -223,3 +223,76 @@ describe('MetadataListItem', () => {
expect(wrapper?.querySelector('dd')).toBeInTheDocument();
});
});
+
+describe('MetadataListItem pass-through props', () => {
+ it('forwards pass-through props to the item element', () => {
+ render(
+ <MetadataList>
+ <MetadataListItem
+ label="Owner"
+ aria-label="Owner field"
+ id="owner"
+ data-source="crm"
+ data-testid="item">
+ Alice
+ </MetadataListItem>
+ </MetadataList>,
+ );
+ const item = screen.getByTestId('item-label');
+ expect(item).toHaveAttribute('aria-label', 'Owner field');
+ expect(item).toHaveAttribute('id', 'owner');
+ expect(item).toHaveAttribute('data-source', 'crm');
+ });
+
+ it('forwards pass-through props in the stacked layout', () => {
+ render(
+ <MetadataList orientation="horizontal">
+ <MetadataListItem label="Owner" id="owner-stacked" data-testid="item">
+ Alice
+ </MetadataListItem>
+ </MetadataList>,
+ );
+ expect(screen.getByTestId('item')).toHaveAttribute('id', 'owner-stacked');
+ });
+});
+
+describe('MetadataListItem pass-through target', () => {
+ it('lands pass-through props on the <dt> in the inline layout, where the ref also goes', () => {
+ const handleClick = vi.fn();
+ render(
+ <MetadataList>
+ <MetadataListItem
+ label="Owner"
+ onClick={handleClick}
+ data-testid="item">
+ Alice
+ </MetadataListItem>
+ </MetadataList>,
+ );
+
+ const label = screen.getByTestId('item-label');
+ expect(label.tagName).toBe('DT');
+ fireEvent.click(label);
+ expect(handleClick).toHaveBeenCalledOnce();
+
+ fireEvent.click(screen.getByTestId('item-value'));
+ expect(handleClick).toHaveBeenCalledOnce();
+ });
+
+ it('lands them on the wrapper in the stacked layout, so both halves are covered', () => {
+ const handleClick = vi.fn();
+ render(
+ <MetadataList orientation="horizontal">
+ <MetadataListItem
+ label="Owner"
+ onClick={handleClick}
+ data-testid="item">
+ Alice
+ </MetadataListItem>
+ </MetadataList>,
+ );
+
+ fireEvent.click(screen.getByText('Alice'));
+ expect(handleClick).toHaveBeenCalledOnce();
+ });
+});
diff --git a/packages/core/src/MetadataList/MetadataListItem.tsx b/packages/core/src/MetadataList/MetadataListItem.tsx
index 6bfffa953e..5dbb1a3737 100644
--- a/packages/core/src/MetadataList/MetadataListItem.tsx
+++ b/packages/core/src/MetadataList/MetadataListItem.tsx
@@ -144,6 +144,7 @@ export function MetadataListItem({
style,
'data-testid': testId,
ref,
+ ...rest
}: MetadataListItemProps) {
const ctx = use(MetadataListContext);
const labelPosition = ctx?.labelConfig.position ?? 'start';
@@ -170,7 +171,8 @@ export function MetadataListItem({
stylex.props(styles.stackedWrapper, xstyle),
className,
style,
- )}>
+ )}
+ {...rest}>
<dt {...stylex.props(styles.stackedLabel)}>{labelContent}</dt>
<dd {...stylex.props(styles.stackedValue)}>{children}</dd>
</div>
@@ -188,7 +190,8 @@ export function MetadataListItem({
stylex.props(styles.label, xstyle),
className,
style,
- )}>
+ )}
+ {...rest}>
{labelContent}
</dt>
<dd
diff --git a/packages/core/src/NavMenu/NavHeadingMenu.test.tsx b/packages/core/src/NavMenu/NavHeadingMenu.test.tsx
index b52eb72079..37704cf802 100644
--- a/packages/core/src/NavMenu/NavHeadingMenu.test.tsx
+++ b/packages/core/src/NavMenu/NavHeadingMenu.test.tsx
@@ -321,3 +321,33 @@ describe('context forwarding', () => {
expect(closeMenu).toHaveBeenCalledOnce();
});
});
+
+describe('NavHeadingMenu pass-through props', () => {
+ it('forwards pass-through props to the menu element', () => {
+ render(
+ <NavHeadingMenu aria-label="Products" id="products" data-source="nav">
+ <NavHeadingMenuItem label="First" />
+ </NavHeadingMenu>,
+ );
+ const menu = screen.getByRole('menu');
+ expect(menu).toHaveAttribute('aria-label', 'Products');
+ expect(menu).toHaveAttribute('id', 'products');
+ expect(menu).toHaveAttribute('data-source', 'nav');
+ });
+
+ it('runs a caller onKeyDown alongside the menu keyboard model', async () => {
+ const user = userEvent.setup();
+ const onKeyDown = vi.fn();
+ render(
+ <NavHeadingMenu onKeyDown={onKeyDown}>
+ <NavHeadingMenuItem label="First" />
+ <NavHeadingMenuItem label="Second" />
+ </NavHeadingMenu>,
+ );
+ const items = screen.getAllByRole('menuitem');
+ items[0].focus();
+ await user.keyboard('{ArrowDown}');
+ expect(onKeyDown).toHaveBeenCalled();
+ expect(items[1]).toHaveFocus();
+ });
+});
diff --git a/packages/core/src/NavMenu/NavHeadingMenu.tsx b/packages/core/src/NavMenu/NavHeadingMenu.tsx
index 710d8dc798..4bd5751e83 100644
--- a/packages/core/src/NavMenu/NavHeadingMenu.tsx
+++ b/packages/core/src/NavMenu/NavHeadingMenu.tsx
@@ -15,7 +15,7 @@
import React, {useCallback, useMemo, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {spacingVars} from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
+import {composeEventHandlers, mergeProps} from '../utils';
import type {BaseProps} from '../BaseProps';
import {useListFocus} from '../hooks/useListFocus';
import {useTypeahead} from '../hooks/useTypeahead';
@@ -96,6 +96,8 @@ export function NavHeadingMenu({
className,
style: styleProp,
'data-testid': testId,
+ onKeyDown: onKeyDownProp,
+ ...rest
}: NavHeadingMenuProps) {
const closeCtx = useNavHeadingCloseContext();
const closeMenu = closeCtx?.closeMenu;
@@ -164,15 +166,16 @@ export function NavHeadingMenu({
<NavHeadingMenuContext value={ctx}>
<div
ref={useMergedRefs(ref, listRef)}
- role="menu"
- onKeyDown={listKeyDown}
data-testid={testId}
{...mergeProps(
themeProps('nav-heading-menu', {size}),
stylex.props(styles.root, sizeStyles[size], xstyle),
className,
inlineStyle,
- )}>
+ )}
+ {...rest}
+ role="menu"
+ onKeyDown={composeEventHandlers(onKeyDownProp, listKeyDown)}>
{children}
</div>
</NavHeadingMenuContext>
diff --git a/packages/core/src/Timestamp/Timestamp.test.tsx b/packages/core/src/Timestamp/Timestamp.test.tsx
index cf337bb40f..689945e85a 100644
--- a/packages/core/src/Timestamp/Timestamp.test.tsx
+++ b/packages/core/src/Timestamp/Timestamp.test.tsx
@@ -1323,3 +1323,43 @@ describe('Timestamp', () => {
});
});
});
+
+describe('Timestamp pass-through props', () => {
+ it('forwards pass-through props to the time element', () => {
+ render(
+ <Timestamp
+ value="2024-01-15T10:30:00Z"
+ format="date_time"
+ aria-label="Published"
+ id="published-at"
+ data-source="cms"
+ data-testid="stamp"
+ />,
+ );
+ const time = screen.getByTestId('stamp');
+ expect(time.tagName).toBe('TIME');
+ expect(time).toHaveAttribute('aria-label', 'Published');
+ expect(time).toHaveAttribute('id', 'published-at');
+ expect(time).toHaveAttribute('data-source', 'cms');
+ });
+
+ it('keeps its own spelled-out label on a relative timestamp', () => {
+ render(
+ <Timestamp
+ value={Date.now()}
+ format="relative"
+ aria-label="Caller label"
+ data-source="cms"
+ data-testid="stamp"
+ />,
+ );
+ const stamp = screen.getByTestId('stamp');
+ expect({
+ ariaLabel: stamp.getAttribute('aria-label'),
+ dataSource: stamp.getAttribute('data-source'),
+ }).toEqual({
+ ariaLabel: expect.not.stringMatching(/^Caller label$/),
+ dataSource: 'cms',
+ });
+ });
+});
diff --git a/packages/core/src/Timestamp/Timestamp.tsx b/packages/core/src/Timestamp/Timestamp.tsx
index 6518bd5849..85e2c1df25 100644
--- a/packages/core/src/Timestamp/Timestamp.tsx
+++ b/packages/core/src/Timestamp/Timestamp.tsx
@@ -419,6 +419,7 @@ export function Timestamp({
style,
ref,
'data-testid': testId,
+ ...rest
}: TimestampProps) {
const t = useTranslator();
const locale = useLocale();
@@ -530,15 +531,16 @@ export function Timestamp({
<time
ref={mergedTimeRef}
dateTime={isoString}
+ data-testid={testId}
+ {...stylex.props(styles.time)}
+ {...rest}
// `ariaLabelText` is '' only for an invalid date, which bails out
// before rendering — but keep the guard local: an empty aria-label
// must be omitted entirely (not rendered as aria-label="") so AT
// falls back to reading the visible <time> content.
- aria-label={
- isRelativeFormat(effectiveFormat) && ariaLabelText !== ''
- ? ariaLabelText
- : undefined
- }
+ {...(isRelativeFormat(effectiveFormat) && ariaLabelText !== ''
+ ? {'aria-label': ariaLabelText}
+ : {})}
// The hover card is anchored here with focusTrigger="always", which
// attaches focus listeners but does not itself make the anchor
// focusable. A bare <time> is not focusable, so without a tab stop
@@ -547,9 +549,7 @@ export function Timestamp({
// gratuitous tab stops otherwise. The card carries its own
// dashed-underline hover indication as the affordance, so the anchor
// needs no separate focus outline.
- tabIndex={showTooltip ? 0 : undefined}
- data-testid={testId}
- {...stylex.props(styles.time)}>
+ {...(showTooltip ? {tabIndex: 0} : {})}>
{displayText}
</time>
</Text>
diff --git a/packages/core/src/Token/Token.test.tsx b/packages/core/src/Token/Token.test.tsx
index 44530863c6..758c11b8f6 100644
--- a/packages/core/src/Token/Token.test.tsx
+++ b/packages/core/src/Token/Token.test.tsx
@@ -521,3 +521,98 @@ describe('Token focus outline', () => {
expect(container.tagName).toBe('SPAN');
});
});
+
+describe('Token pass-through props', () => {
+ it('forwards pass-through props to the token element', () => {
+ render(
+ <Token
+ label="Design"
+ aria-label="Design tag"
+ id="design-token"
+ data-source="filters"
+ data-testid="token"
+ />,
+ );
+ const token = screen.getByTestId('token');
+ expect(token).toHaveAttribute('aria-label', 'Design tag');
+ expect(token).toHaveAttribute('id', 'design-token');
+ expect(token).toHaveAttribute('data-source', 'filters');
+ });
+
+ it('forwards pass-through props on the clickable and link variants', () => {
+ const {rerender} = render(
+ <Token
+ label="Design"
+ onClick={() => {}}
+ id="clickable"
+ data-testid="token"
+ />,
+ );
+ expect(screen.getByTestId('token')).toHaveAttribute('id', 'clickable');
+
+ rerender(
+ <Token label="Design" href="/tags" id="link" data-testid="token" />,
+ );
+ expect(screen.getByTestId('token')).toHaveAttribute('id', 'link');
+ });
+
+ it('keeps its own label when the label is visually hidden', () => {
+ render(
+ <Token
+ label="Design"
+ isLabelHidden
+ aria-label="Caller label"
+ data-source="filters"
+ data-testid="token"
+ />,
+ );
+ const token = screen.getByTestId('token');
+ expect({
+ ariaLabel: token.getAttribute('aria-label'),
+ dataSource: token.getAttribute('data-source'),
+ }).toEqual({ariaLabel: 'Design', dataSource: 'filters'});
+ });
+});
+
+describe('Token — owned handlers on the link+remove container', () => {
+ it("composes a caller's onMouseUp with the container's link delegation", () => {
+ const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null);
+ const handleMouseUp = vi.fn();
+ render(
+ <Token
+ label="Tag"
+ href="/test"
+ onRemove={() => {}}
+ onMouseUp={handleMouseUp}
+ icon={<span data-testid="icon">★</span>}
+ />,
+ );
+
+ fireEvent.mouseUp(screen.getByTestId('icon'), {button: 1});
+
+ expect(handleMouseUp).toHaveBeenCalledOnce();
+ expect(openSpy).toHaveBeenCalledWith('/test', '_blank', 'noopener');
+ openSpy.mockRestore();
+ });
+
+ it("does not fire the container's delegation when disabled, but still forwards the caller's onMouseUp", () => {
+ const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null);
+ const handleMouseUp = vi.fn();
+ render(
+ <Token
+ label="Tag"
+ href="/test"
+ onRemove={() => {}}
+ onMouseUp={handleMouseUp}
+ isDisabled
+ icon={<span data-testid="icon">★</span>}
+ />,
+ );
+
+ fireEvent.mouseUp(screen.getByTestId('icon'), {button: 1});
+
+ expect(handleMouseUp).toHaveBeenCalledOnce();
+ expect(openSpy).not.toHaveBeenCalled();
+ openSpy.mockRestore();
+ });
+});
diff --git a/packages/core/src/Token/Token.tsx b/packages/core/src/Token/Token.tsx
index 23fef90e91..bdb3419d01 100644
--- a/packages/core/src/Token/Token.tsx
+++ b/packages/core/src/Token/Token.tsx
@@ -307,6 +307,7 @@ export function Token({
style,
'data-testid': testId,
ref,
+ ...rest
}: TokenProps) {
const t = useTranslator();
const LinkComponent = useLinkComponent();
@@ -344,8 +345,8 @@ export function Token({
const sharedProps = {
'data-testid': testId,
- 'aria-label': isLabelHidden ? label : undefined,
- 'aria-description': description,
+ ...(isLabelHidden ? {'aria-label': label} : {}),
+ ...(description != null ? {'aria-description': description} : {}),
};
if (role === 'link') {
@@ -354,8 +355,6 @@ export function Token({
<LinkComponent
ref={ref as React.Ref<HTMLAnchorElement>}
href={href as string}
- aria-disabled={isDisabled || undefined}
- {...sharedProps}
{...mergeProps(
themeProps('token', {color, size}),
focusOutlineProps.focusVisible(
@@ -368,7 +367,10 @@ export function Token({
),
className,
style,
- )}>
+ )}
+ {...rest}
+ {...(isDisabled ? {'aria-disabled': true} : {})}
+ {...sharedProps}>
{content}
</LinkComponent>
);
@@ -400,7 +402,6 @@ export function Token({
{label}
</span>
}
- {...sharedProps}
{...mergeProps(
themeProps('token', {color, size}),
focusOutlineProps.focusWithin(
@@ -414,6 +415,8 @@ export function Token({
className,
style,
)}
+ {...rest}
+ {...sharedProps}
/>
);
}
@@ -431,7 +434,6 @@ export function Token({
<span
ref={ref}
onClick={isDisabled ? undefined : handleContainerClick}
- {...sharedProps}
{...mergeProps(
themeProps('token', {color, size}),
focusOutlineProps.focusWithin(
@@ -444,7 +446,9 @@ export function Token({
),
className,
style,
- )}>
+ )}
+ {...rest}
+ {...sharedProps}>
{icon}
<button
type="button"
@@ -468,7 +472,6 @@ export function Token({
return (
<span
ref={ref}
- {...sharedProps}
{...mergeProps(
themeProps('token', {color, size}),
stylex.props(
@@ -480,7 +483,9 @@ export function Token({
),
className,
style,
- )}>
+ )}
+ {...rest}
+ {...sharedProps}>
{content}
</span>
);
diff --git a/packages/core/src/Token/TokenLink.tsx b/packages/core/src/Token/TokenLink.tsx
index bc4a455822..9a0b9d637e 100644
--- a/packages/core/src/Token/TokenLink.tsx
+++ b/packages/core/src/Token/TokenLink.tsx
@@ -29,6 +29,7 @@ import type {ReactNode, CSSProperties, Ref, HTMLAttributes} from 'react';
import {useRef} from 'react';
import {useClickableContainer} from '../hooks/useClickableContainer';
import type {LinkComponentType} from '../Link/types';
+import {composeEventHandlers} from '../utils';
import {useMergedRefs} from '../hooks/useMergedRefs';
export interface TokenLinkProps extends HTMLAttributes<HTMLElement> {
@@ -72,6 +73,8 @@ export function TokenLink({
icon,
endContent,
removeButton,
+ onClick: onClickProp,
+ onMouseUp: onMouseUpProp,
...containerProps
}: TokenLinkProps) {
const containerRef = useRef<HTMLElement | null>(null);
@@ -87,9 +90,15 @@ export function TokenLink({
return (
<span
ref={useMergedRefs(ref, containerRef)}
- onClick={isDisabled ? undefined : onClick}
- onMouseUp={isDisabled ? undefined : onMouseUp}
- {...containerProps}>
+ {...containerProps}
+ onClick={
+ isDisabled ? onClickProp : composeEventHandlers(onClickProp, onClick)
+ }
+ onMouseUp={
+ isDisabled
+ ? onMouseUpProp
+ : composeEventHandlers(onMouseUpProp, onMouseUp)
+ }>
{icon}
<LinkComponent
ref={linkRef as Ref<HTMLAnchorElement>}
diff --git a/packages/core/src/TopNav/TopNavMegaMenu.test.tsx b/packages/core/src/TopNav/TopNavMegaMenu.test.tsx
index 09500f4e58..584f015e60 100644
--- a/packages/core/src/TopNav/TopNavMegaMenu.test.tsx
+++ b/packages/core/src/TopNav/TopNavMegaMenu.test.tsx
@@ -860,3 +860,107 @@ describe('TopNavMegaMenu — drawer focus ring', () => {
expectSharedFocusRing(screen.getByRole('link', {name: /Analytics/}));
});
});
+
+describe('TopNavMegaMenu pass-through props', () => {
+ it('forwards pass-through props to the trigger button', () => {
+ render(
+ <TopNavMegaMenu
+ label="Products"
+ aria-label="Products mega menu"
+ id="mega-trigger"
+ data-source="nav"
+ />,
+ );
+ const trigger = screen.getByRole('button', {name: 'Products mega menu'});
+ expect(trigger).toHaveAttribute('id', 'mega-trigger');
+ expect(trigger).toHaveAttribute('data-source', 'nav');
+ });
+
+ it('forwards pass-through props to the drawer trigger', () => {
+ render(
+ <TopNavRenderContext value="drawer">
+ <TopNavMegaMenu label="Products" id="mega-drawer" data-source="nav" />
+ </TopNavRenderContext>,
+ );
+ const trigger = screen.getByRole('button', {name: /Products/});
+ expect(trigger).toHaveAttribute('id', 'mega-drawer');
+ expect(trigger).toHaveAttribute('data-source', 'nav');
+ });
+});
+
+describe('TopNavMegaMenu — owned handlers on the trigger', () => {
+ beforeAll(installPopoverApiMock);
+ afterAll(restorePopoverApiMock);
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it("composes a caller's onClick with the trigger's own open behavior", async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(
+ <TopNavMegaMenu
+ label="Products"
+ items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+ onClick={handleClick}
+ />,
+ );
+
+ const trigger = screen.getByRole('button', {name: 'Products'});
+ await user.click(trigger);
+
+ expect(handleClick).toHaveBeenCalledOnce();
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it("composes a caller's hover handlers with the trigger's hover-open behavior", async () => {
+ vi.useFakeTimers({shouldAdvanceTime: true});
+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});
+ const handleMouseEnter = vi.fn();
+ const handleMouseLeave = vi.fn();
+ render(
+ <TopNavMegaMenu
+ label="Products"
+ items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+ onMouseEnter={handleMouseEnter}
+ onMouseLeave={handleMouseLeave}
+ />,
+ );
+
+ const trigger = screen.getByRole('button', {name: 'Products'});
+ await user.hover(trigger);
+ act(() => {
+ vi.advanceTimersByTime(200);
+ });
+ expect(handleMouseEnter).toHaveBeenCalledOnce();
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+ await user.unhover(trigger);
+ act(() => {
+ vi.advanceTimersByTime(400);
+ });
+ expect(handleMouseLeave).toHaveBeenCalledOnce();
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it("composes a caller's onClick with the drawer section toggle", async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(
+ <TopNavRenderContext value="drawer">
+ <TopNavMegaMenu
+ label="Products"
+ items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+ onClick={handleClick}
+ />
+ </TopNavRenderContext>,
+ );
+
+ const trigger = screen.getByRole('button', {name: /Products/});
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+ await user.click(trigger);
+ expect(handleClick).toHaveBeenCalledOnce();
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+});
diff --git a/packages/core/src/TopNav/TopNavMegaMenu.tsx b/packages/core/src/TopNav/TopNavMegaMenu.tsx
index 7125c8bcb7..8bb6dfbcbd 100644
--- a/packages/core/src/TopNav/TopNavMegaMenu.tsx
+++ b/packages/core/src/TopNav/TopNavMegaMenu.tsx
@@ -53,7 +53,7 @@ import {usePopover} from '../Popover/usePopover';
import {useMenuHover} from '../hooks/useMenuHover';
import {Grid} from '../Grid/Grid';
import {Icon} from '../Icon';
-import {mergeProps} from '../utils';
+import {mergeProps, composeEventHandlers} from '../utils';
import type {BaseProps} from '../BaseProps';
import {navItemStyles} from '../NavItem/navItemStyles.stylex';
import {useTopNavSlot} from './TopNavContext';
@@ -336,6 +336,7 @@ export function TopNavMegaMenu({
delay = 150,
hideDelay = 250,
onOpenChange,
+ ...rest
}: TopNavMegaMenuProps) {
const renderMode = useTopNavRenderMode();
@@ -350,7 +351,14 @@ export function TopNavMegaMenu({
// Drawer mode — inline collapsible
// =========================================================================
if (renderMode === 'drawer') {
- return <DrawerMegaMenu label={label} items={items} featured={featured} />;
+ return (
+ <DrawerMegaMenu
+ label={label}
+ items={items}
+ featured={featured}
+ {...rest}
+ />
+ );
}
// =========================================================================
@@ -365,6 +373,7 @@ export function TopNavMegaMenu({
delay={delay}
hideDelay={hideDelay}
onOpenChange={onOpenChange}
+ {...rest}
/>
);
}
@@ -387,6 +396,13 @@ function DefaultMegaMenu({
delay = 150,
hideDelay = 250,
onOpenChange,
+ xstyle,
+ className,
+ style,
+ onClick: onClickProp,
+ onMouseEnter: onMouseEnterProp,
+ onMouseLeave: onMouseLeaveProp,
+ ...rest
}: TopNavMegaMenuProps) {
const slot = useTopNavSlot();
const triggerButtonRef = useRef<HTMLButtonElement | null>(null);
@@ -454,14 +470,27 @@ function DefaultMegaMenu({
<button
ref={useMergedRefs(triggerButtonRef, setTriggerEl, ref)}
type="button"
+ {...rest}
{...popover.triggerProps}
{...hoverTriggerProps}
+ onClick={composeEventHandlers(onClickProp, hoverTriggerProps.onClick)}
+ onMouseEnter={composeEventHandlers(
+ onMouseEnterProp,
+ hoverTriggerProps.onMouseEnter,
+ )}
+ onMouseLeave={composeEventHandlers(
+ onMouseLeaveProp,
+ hoverTriggerProps.onMouseLeave,
+ )}
{...mergeProps(
themeProps('top-nav-mega-menu'),
focusOutlineProps.focusVisible(
styles.trigger,
popover.isOpen && styles.triggerOpen,
+ xstyle,
),
+ className,
+ style,
)}>
{label}
<Icon
@@ -513,7 +542,13 @@ function DrawerMegaMenu({
label,
items,
featured,
-}: Pick<TopNavMegaMenuProps, 'label' | 'items' | 'featured'>) {
+ xstyle,
+ className,
+ style,
+ onClick: onClickProp,
+ ...rest
+}: Pick<TopNavMegaMenuProps, 'label' | 'items' | 'featured'> &
+ BaseProps<HTMLButtonElement>) {
const [isExpanded, setIsExpanded] = useState(false);
const menuId = `mega-menu-${label.toLowerCase().replace(/\s+/g, '-')}`;
@@ -522,7 +557,10 @@ function DrawerMegaMenu({
{/* Header toggle — same pattern as TopNavMenu drawer */}
<button
type="button"
- onClick={() => setIsExpanded(v => !v)}
+ {...rest}
+ onClick={composeEventHandlers(onClickProp, () =>
+ setIsExpanded(v => !v),
+ )}
aria-expanded={isExpanded}
aria-controls={`${menuId}-items`}
{...mergeProps(
@@ -530,7 +568,10 @@ function DrawerMegaMenu({
focusOutlineProps.focusVisible(
navItemStyles.item,
styles.drawerHeader,
+ xstyle,
),
+ className,
+ style,
)}>
{label}
<Icon
diff --git a/packages/core/src/TopNav/TopNavMenu.test.tsx b/packages/core/src/TopNav/TopNavMenu.test.tsx
index 4c1f541a0c..f84af66003 100644
--- a/packages/core/src/TopNav/TopNavMenu.test.tsx
+++ b/packages/core/src/TopNav/TopNavMenu.test.tsx
@@ -10,7 +10,7 @@
*/
import {describe, it, expect, vi} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {render, screen, fireEvent, act} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import * as stylex from '@stylexjs/stylex';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
@@ -212,3 +212,135 @@ describe('TopNavMenu — drawer focus ring', () => {
expectSharedFocusRing(screen.getByRole('link', {name: /Analytics/}));
});
});
+
+describe('TopNavMenu pass-through props', () => {
+ it('forwards pass-through props to the trigger button', () => {
+ render(
+ <TopNavMenu
+ label="Products"
+ items={mockItems}
+ aria-label="Products menu"
+ id="products-trigger"
+ data-source="nav"
+ />,
+ );
+ const trigger = screen.getByRole('button', {name: 'Products menu'});
+ expect(trigger).toHaveAttribute('id', 'products-trigger');
+ expect(trigger).toHaveAttribute('data-source', 'nav');
+ });
+
+ it('forwards pass-through props to the drawer trigger', () => {
+ render(
+ <TopNavRenderContext value="drawer">
+ <TopNavMenu
+ label="Products"
+ items={mockItems}
+ id="products-drawer"
+ data-source="nav"
+ />
+ </TopNavRenderContext>,
+ );
+ const trigger = screen.getByRole('button', {name: /Products/});
+ expect(trigger).toHaveAttribute('id', 'products-drawer');
+ expect(trigger).toHaveAttribute('data-source', 'nav');
+ });
+
+ it('keeps its own popup wiring when a caller passes the same attributes', () => {
+ render(
+ <TopNavMenu
+ label="Products"
+ items={mockItems}
+ aria-haspopup="dialog"
+ aria-expanded
+ data-source="nav"
+ />,
+ );
+ const trigger = screen.getByRole('button', {name: 'Products'});
+ expect({
+ hasPopup: trigger.getAttribute('aria-haspopup'),
+ isExpanded: trigger.getAttribute('aria-expanded'),
+ dataSource: trigger.getAttribute('data-source'),
+ }).toEqual({hasPopup: 'true', isExpanded: 'false', dataSource: 'nav'});
+ });
+});
+
+describe('TopNavMenu — owned handlers on the trigger', () => {
+ it("composes a caller's onClick with the trigger's own open behavior", async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(
+ <TopNavMenu label="Products" items={mockItems} onClick={handleClick} />,
+ );
+
+ const trigger = screen.getByRole('button', {name: 'Products'});
+ await user.click(trigger);
+
+ expect(handleClick).toHaveBeenCalledOnce();
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it("composes a caller's hover handlers with the trigger's hover wiring", async () => {
+ vi.useFakeTimers({shouldAdvanceTime: true});
+ const user = userEvent.setup({advanceTimers: vi.advanceTimersByTime});
+ const handleMouseEnter = vi.fn();
+ const handleMouseLeave = vi.fn();
+ render(
+ <TopNavMenu
+ label="Products"
+ items={mockItems}
+ onMouseEnter={handleMouseEnter}
+ onMouseLeave={handleMouseLeave}
+ />,
+ );
+
+ const trigger = screen.getByRole('button', {name: 'Products'});
+ await user.hover(trigger);
+ act(() => {
+ vi.advanceTimersByTime(200);
+ });
+ expect(handleMouseEnter).toHaveBeenCalledOnce();
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+ await user.unhover(trigger);
+ act(() => {
+ vi.advanceTimersByTime(400);
+ });
+ expect(handleMouseLeave).toHaveBeenCalledOnce();
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ vi.useRealTimers();
+ });
+
+ it("composes a caller's onClick with the drawer section toggle", async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(
+ <TopNavRenderContext value="drawer">
+ <TopNavMenu label="Products" items={mockItems} onClick={handleClick} />
+ </TopNavRenderContext>,
+ );
+
+ const trigger = screen.getByRole('button', {name: /Products/});
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+ await user.click(trigger);
+ expect(handleClick).toHaveBeenCalledOnce();
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('still forwards hover handlers the drawer trigger does not own', async () => {
+ const user = userEvent.setup();
+ const handleMouseEnter = vi.fn();
+ render(
+ <TopNavRenderContext value="drawer">
+ <TopNavMenu
+ label="Products"
+ items={mockItems}
+ onMouseEnter={handleMouseEnter}
+ />
+ </TopNavRenderContext>,
+ );
+
+ await user.hover(screen.getByRole('button', {name: /Products/}));
+ expect(handleMouseEnter).toHaveBeenCalledOnce();
+ });
+});
diff --git a/packages/core/src/TopNav/TopNavMenu.tsx b/packages/core/src/TopNav/TopNavMenu.tsx
index 8e4b64cf90..ff393631b8 100644
--- a/packages/core/src/TopNav/TopNavMenu.tsx
+++ b/packages/core/src/TopNav/TopNavMenu.tsx
@@ -29,7 +29,7 @@ import {useMenuHover} from '../hooks/useMenuHover';
import {useListFocus} from '../hooks/useListFocus';
import {useTypeahead} from '../hooks/useTypeahead';
import {Icon} from '../Icon';
-import {mergeProps} from '../utils';
+import {mergeProps, composeEventHandlers} from '../utils';
import {useMergedRefs} from '../hooks/useMergedRefs';
import type {BaseProps} from '../BaseProps';
import {navItemStyles} from '../NavItem/navItemStyles.stylex';
@@ -332,6 +332,13 @@ export function TopNavMenu({
items,
delay = 150,
hideDelay = 200,
+ xstyle,
+ className,
+ style,
+ onClick: onClickProp,
+ onMouseEnter: onMouseEnterProp,
+ onMouseLeave: onMouseLeaveProp,
+ ...rest
}: TopNavMenuProps) {
const renderMode = useTopNavRenderMode();
const {closeMobileNav} = useAppShellMobile();
@@ -440,12 +447,22 @@ export function TopNavMenu({
<div {...stylex.props(drawerStyles.section)}>
<button
type="button"
- onClick={() => setDrawerExpanded(v => !v)}
+ {...rest}
+ onMouseEnter={onMouseEnterProp}
+ onMouseLeave={onMouseLeaveProp}
+ onClick={composeEventHandlers(onClickProp, () =>
+ setDrawerExpanded(v => !v),
+ )}
aria-expanded={drawerExpanded}
aria-controls={`${menuId}-items`}
- {...focusOutlineProps.focusVisible(
- navItemStyles.item,
- drawerStyles.header,
+ {...mergeProps(
+ focusOutlineProps.focusVisible(
+ navItemStyles.item,
+ drawerStyles.header,
+ xstyle,
+ ),
+ className,
+ style,
)}>
{label}
<Icon
@@ -504,14 +521,27 @@ export function TopNavMenu({
<button
ref={setTriggerRef}
type="button"
+ {...rest}
{...popover.triggerProps}
{...triggerProps}
+ onClick={composeEventHandlers(onClickProp, triggerProps.onClick)}
+ onMouseEnter={composeEventHandlers(
+ onMouseEnterProp,
+ triggerProps.onMouseEnter,
+ )}
+ onMouseLeave={composeEventHandlers(
+ onMouseLeaveProp,
+ triggerProps.onMouseLeave,
+ )}
{...mergeProps(
themeProps('top-nav-menu'),
focusOutlineProps.focusVisible(
styles.trigger,
popover.isOpen && styles.triggerOpen,
+ xstyle,
),
+ className,
+ style,
)}>
{label}
<Icon
diff --git a/packages/core/src/Typeahead/TypeaheadItem.test.tsx b/packages/core/src/Typeahead/TypeaheadItem.test.tsx
new file mode 100644
index 0000000000..7dc592847b
--- /dev/null
+++ b/packages/core/src/Typeahead/TypeaheadItem.test.tsx
@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TypeaheadItem.test.tsx
+ * @input Uses vitest, @testing-library/react, TypeaheadItem
+ * @output Unit tests for TypeaheadItem
+ * @position Testing; validates TypeaheadItem.tsx implementation
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {TypeaheadItem} from './TypeaheadItem';
+
+describe('TypeaheadItem', () => {
+ it('forwards pass-through props to the item element', () => {
+ render(
+ <TypeaheadItem
+ item={{id: '1', label: 'Alice'}}
+ aria-label="Alice, engineer"
+ id="result-1"
+ data-source="directory"
+ data-testid="item"
+ />,
+ );
+ const item = screen.getByTestId('item');
+ expect(item).toHaveAttribute('aria-label', 'Alice, engineer');
+ expect(item).toHaveAttribute('id', 'result-1');
+ expect(item).toHaveAttribute('data-source', 'directory');
+ });
+
+ it('merges a caller className with its own classes', () => {
+ render(
+ <TypeaheadItem
+ item={{id: '1', label: 'Alice'}}
+ className="caller-class"
+ data-testid="item"
+ />,
+ );
+ const item = screen.getByTestId('item');
+ expect(item.className).toContain('caller-class');
+ expect(item.className).toContain('astryx-typeahead-item');
+ });
+});
diff --git a/packages/core/src/Typeahead/TypeaheadItem.tsx b/packages/core/src/Typeahead/TypeaheadItem.tsx
index 85e6827548..5225970b1e 100644
--- a/packages/core/src/Typeahead/TypeaheadItem.tsx
+++ b/packages/core/src/Typeahead/TypeaheadItem.tsx
@@ -132,7 +132,11 @@ export function TypeaheadItem<T extends SearchableItem>({
icon,
description,
isDisabled = false,
+ group: _group,
xstyle,
+ className,
+ style,
+ ...rest
}: TypeaheadItemProps<T>) {
// If item has a pre-rendered element, use it
if (item.element) {
@@ -145,7 +149,10 @@ export function TypeaheadItem<T extends SearchableItem>({
{...mergeProps(
themeProps('typeahead-item'),
stylex.props(styles.container, isDisabled && styles.disabled, xstyle),
- )}>
+ className,
+ style,
+ )}
+ {...rest}>
{icon}
<div {...stylex.props(styles.content)}>
<span {...stylex.props(styles.label)}>{item.label}</span>