An open source design system that's fully customizable and agent ready
TypeScript
feat(TopNav): add isIconOnly prop to XDSTopNavItem (#1309)
Cindy Zhangd9b7242aff9d
diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjsindex f69920ef70..23ddfd15c9 100644--- a/packages/core/src/TopNav/TopNav.doc.mjs+++ b/packages/core/src/TopNav/TopNav.doc.mjs@@ -132,7 +132,7 @@ export const docs = {accessibility: ['XDSTopNav renders a <nav> element with role="navigation" and aria-label set from the label prop','XDSTopNavItem sets aria-current="page" when isSelected is true',- 'XDSTopNavItem sets aria-label for icon-only items (when icon is provided and no children or label text is visible)',+ 'XDSTopNavItem sets aria-label when isIconOnly is true, keeping the item accessible.','XDSTopNavItem sets aria-disabled and tabIndex=-1 when isDisabled is true','XDSTopNavMenu sets aria-haspopup="true" on the trigger button','XDSTopNavMegaMenu sets aria-haspopup="true" and aria-expanded on the trigger button',@@ -267,7 +267,7 @@ export const docs = {name: 'label',type: 'string',description:- 'Accessible label for the nav item. Used as visible text, or as aria-label for icon-only items.',+ 'Accessible label for the nav item. Rendered as visible text by default. When isIconOnly is true, used as aria-label instead.',required: true,},{@@ -289,17 +289,24 @@ export const docs = {'Whether the nav item is disabled. Sets aria-disabled and prevents interaction.',default: 'false',},+ {+ name: 'isIconOnly',+ type: 'boolean',+ description:+ 'Renders the item as a square icon-only element. When true, label becomes the aria-label and visible text is hidden. Requires icon to be set.',+ default: 'false',+ },{name: 'icon',type: 'ReactNode',description:- 'Optional icon to display before the label. If provided without children, the item becomes icon-only.',+ 'Optional icon to display before the label.',},{name: 'children',type: 'ReactNode',description:- 'Custom content to render instead of the label text. When omitted and an icon is provided, the item becomes icon-only.',+ 'Custom content to render instead of the label text.',},{name: 'as',@@ -1205,7 +1212,7 @@ export const docsDense = {accessibility: ['XDSTopNav renders <nav> w/ role="navigation"+aria-label from label prop.','XDSTopNavItem sets aria-current="page" when isSelected.',- 'XDSTopNavItem sets aria-label for icon-only items (icon provided w/o children or visible label).',+ 'XDSTopNavItem sets aria-label when isIconOnly is true.','XDSTopNavItem sets aria-disabled+tabIndex=-1 when isDisabled.','XDSTopNavMenu sets aria-haspopup="true" on trigger button.','XDSTopNavMegaMenu sets aria-haspopup="true"+aria-expanded on trigger button.',@@ -1239,11 +1246,11 @@ export const docsDense = {name: 'XDSTopNavItem',description: 'Nav link for XDSTopNav startContent; renders as anchor w/ hover+selected states.',propDescriptions: {- label: 'Visible text or aria-label for icon-only items.',+ label: 'Visible text or aria-label when isIconOnly is true.',href: 'Navigation URL.',isSelected: 'Sets aria-current="page"+highlighted styles.',isDisabled: 'Sets aria-disabled, prevents interaction.',- icon: 'Icon before label. W/o children becomes icon-only.',+ icon: 'Icon before label.',children: 'Custom content instead of label text.',as: 'Custom link component. Overrides XDSLinkProvider default. Must accept href, className, style, children.',},diff --git a/packages/core/src/TopNav/XDSTopNav.test.tsx b/packages/core/src/TopNav/XDSTopNav.test.tsxindex f9914b3e9a..fb03592974 100644--- a/packages/core/src/TopNav/XDSTopNav.test.tsx+++ b/packages/core/src/TopNav/XDSTopNav.test.tsx@@ -254,6 +254,20 @@ describe('XDSTopNavItem', () => {expect(screen.getByText('Settings')).toBeInTheDocument();});+ it('hides label and sets aria-label when isIconOnly', () => {+ render(+ <XDSTopNavItem+ label="Settings"+ href="#"+ icon={<span data-testid="icon">⚙️</span>}+ isIconOnly+ />,+ );+ expect(screen.getByTestId('icon')).toBeInTheDocument();+ expect(screen.queryByText('Settings')).not.toBeInTheDocument();+ expect(screen.getByRole('link')).toHaveAttribute('aria-label', 'Settings');+ });+it('handles click events', async () => {const user = userEvent.setup();const handleClick = vi.fn();diff --git a/packages/core/src/TopNav/XDSTopNavItem.tsx b/packages/core/src/TopNav/XDSTopNavItem.tsxindex c2cb4605fd..930bb25e10 100644--- a/packages/core/src/TopNav/XDSTopNavItem.tsx+++ b/packages/core/src/TopNav/XDSTopNavItem.tsx@@ -2,7 +2,7 @@/*** @file XDSTopNavItem.tsx- * @input Uses React, AnchorHTMLAttributes, ReactNode+ * @input Uses React, ReactNode, XDSBaseProps, XDSLinkComponentType* @output Exports XDSTopNavItem component and XDSTopNavItemProps* @position Navigation item component for XDSTopNav startContent*@@ -115,7 +115,8 @@ export interface XDSTopNavItemProps extends XDSBaseProps<HTMLAnchorElement> {as?: XDSLinkComponentType;/*** The accessible label for the nav item.- * Used as visible text, or as aria-label for icon-only items.+ * Rendered as visible text by default. When `isIconOnly` is true,+ * used as aria-label instead.*/label: string;/**@@ -128,15 +129,19 @@ export interface XDSTopNavItemProps extends XDSBaseProps<HTMLAnchorElement> {* @default false*/isDisabled?: boolean;+ /**+ * Renders the item as a square icon-only element.+ * When true, `label` becomes the aria-label and visible text is hidden.+ * Requires `icon` to be set.+ * @default false+ */+ isIconOnly?: boolean;/*** Optional icon to display before the label.- * // TODO: Add isIconOnly prop for consistency with XDSButton (#1257)- * If provided without children, item becomes icon-only.*/icon?: ReactNode;/*** Optional content to render instead of the label.- * If omitted and icon is provided, item becomes icon-only.*/children?: ReactNode;/**@@ -160,7 +165,7 @@ export interface XDSTopNavItemProps extends XDSBaseProps<HTMLAnchorElement> {* <>* <XDSTopNavItem label="Home" href="/" isSelected />* <XDSTopNavItem label="Products" href="/products" />- * <XDSTopNavItem label="Settings" href="/settings" icon={<GearIcon />} />+ * <XDSTopNavItem label="Settings" href="/settings" icon={<GearIcon />} isIconOnly />* </>* }* />@@ -171,6 +176,7 @@ export function XDSTopNavItem({label,isSelected = false,isDisabled = false,+ isIconOnly = false,icon,children,size = 'md',@@ -182,8 +188,6 @@ export function XDSTopNavItem({}: XDSTopNavItemProps) {const LinkComponent = useXDSLinkComponent(as);const renderMode = useXDSTopNavRenderMode();- const isIconOnly = icon != null && children == null && !label;- const showLabel = !isIconOnly;// =========================================================================// Drawer mode — render as a SideNavItem-style vertical list element@@ -192,6 +196,7 @@ export function XDSTopNavItem({return (<LinkComponentref={ref}+ aria-label={isIconOnly ? label : undefined}aria-current={isSelected ? 'page' : undefined}aria-disabled={isDisabled || undefined}tabIndex={isDisabled ? -1 : undefined}@@ -210,7 +215,7 @@ export function XDSTopNavItem({)}{...props}>{icon}- {children ?? label}+ {!isIconOnly && (children ?? label)}</LinkComponent>);}@@ -240,7 +245,7 @@ export function XDSTopNavItem({)}{...props}>{icon}- {showLabel && (children ?? label)}+ {!isIconOnly && (children ?? label)}</LinkComponent>);}