An open source design system that's fully customizable and agent ready
TypeScript
docs: update Button and DropdownMenu docs for isIconOnly prop (#1261)
Cindy Zhangceb8c273cd91
diff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjsindex d063e7d894..35e17c8fbe 100644--- a/packages/core/src/Button/Button.doc.mjs+++ b/packages/core/src/Button/Button.doc.mjs@@ -23,7 +23,7 @@ export const docs = {name: 'label',type: 'string',description:- 'Accessible label; used as aria-label for icon-only buttons.',+ 'Accessible label. Rendered as visible text by default; used as aria-label when isIconOnly is true.',required: true,},{@@ -75,19 +75,26 @@ export const docs = {name: 'icon',type: 'ReactNode',description:- 'Icon element. When provided without children the button renders as a square icon-only button.',+ 'Icon element rendered before the label text.',+ },+ {+ name: 'isIconOnly',+ type: 'boolean',+ description:+ 'When true, renders as a square icon-only button with label as aria-label. Requires icon.',+ default: 'false',},{name: 'children',type: 'ReactNode',description:- 'Button content. When provided alongside icon, the text is rendered next to the icon.',+ 'Optional visible content. When provided, rendered instead of label as the visible text.',},{name: 'endContent',type: 'ReactElement<XDSIconProps> | ReactElement<XDSBadgeProps>',description:- 'Trailing icon or badge rendered after the label. Only accepts <XDSIcon> or <XDSBadge>. Ignored for icon-only buttons. Color is inherited from the button variant.',+ 'Trailing icon or badge rendered after the label. Ignored when isIconOnly is true. Color is inherited from the button variant.',},{name: 'tooltip',@@ -127,16 +134,15 @@ export const docs = {},{label: 'Icon-only button',- code: `// Pass \`icon\` without \`children\` β \`label\` becomes the aria-label-<XDSButton label="Settings" icon={<GearIcon />} variant="ghost" />`,+ code: '<XDSButton label="Settings" icon={<GearIcon />} variant="ghost" isIconOnly />',},{label: 'Icon-only with emoji content',- code: '<XDSButton label="Select rocket emoji" icon={<span>π</span>} variant="ghost" size="sm" />',+ code: '<XDSButton label="Select rocket emoji" icon={<span>π</span>} variant="ghost" size="sm" isIconOnly />',},{label: 'Icon + visible label',- code: '<XDSButton label="Edit" icon={<PencilIcon />}>Edit</XDSButton>',+ code: '<XDSButton label="Edit" icon={<PencilIcon />} />',},{label: 'endContent β badge after label',@@ -144,19 +150,17 @@ export const docs = {},{label: 'endContent β icon, label, and badge',- code: '<XDSButton label="Edit" icon={<PencilIcon />} endContent={<XDSBadge label="New" />}>Edit</XDSButton>',+ code: '<XDSButton label="Edit" icon={<PencilIcon />} endContent={<XDSBadge label="New" />} />',},{label: 'endContent β settings with badge',- code: `<XDSButton label="Settings" icon={<GearIcon />} endContent={<XDSBadge label="New" />}>- Settings-</XDSButton>`,+ code: '<XDSButton label="Settings" icon={<GearIcon />} endContent={<XDSBadge label="New" />} />',},],accessibility: ['Renders a native <button> element for correct semantics and keyboard support',- 'Icon-only buttons (icon without children) set aria-label from the label prop',+ 'Icon-only buttons (isIconOnly={true}) set aria-label from the label prop','Loading state sets aria-busy and announces "Loading" via a role="status" live region','Content is hidden from assistive tech during loading via aria-hidden','When tooltip is present and button is disabled, uses aria-disabled instead of native disabled to keep the button focusable for keyboard tooltip access',@@ -181,8 +185,8 @@ export const docs = {'Hover/active states use backgroundImage with linear-gradient to layer overlay colors on top of the base background.','Destructive variant uses colorTokens.negative for its focus outline color.','endContent is wrapped in a <span> with color: inherit so icons/badges match the button text color across all variants.',- 'When icon is provided without children, the button becomes icon-only: it renders as a perfect square (aspectRatio: 1/1), and label is used as aria-label (not rendered visually). Works with any ReactNode as the icon β SVG components, emoji, or text.',- 'endContent is ignored for icon-only buttons (when icon is provided without children) to preserve the square aspect ratio.',+ 'When isIconOnly is true, the button renders as a perfect square (aspectRatio: 1/1), and label is used as aria-label (not rendered visually). Works with any ReactNode as the icon β SVG components, emoji, or text.',+ 'endContent is ignored when isIconOnly is true to preserve the square aspect ratio.','Prefer XDSButton over <div onClick> or <span onClick> for accessibility β it provides keyboard navigation, focus management, and screen reader support.','Icon-only buttons are suitable for toolbars, action grids, and compact controls.','onClick fires before onClickAction; calling preventDefault in onClick prevents onClickAction from running.',@@ -434,7 +438,7 @@ export const docsDense = {],accessibility: ['Native <button> for correct semantics + keyboard support.',- 'Icon-only buttons set aria-label from label prop.',+ 'Icon-only buttons (isIconOnly) set aria-label from label prop.','Loading sets aria-busy + announces via role="status" live region.','Content hidden from AT during loading via aria-hidden.','Tooltip+disabled uses aria-disabled to stay focusable.',@@ -447,8 +451,8 @@ export const docsDense = {'hover/active use backgroundImage linear-gradient overlay on base bg','destructive variant uses colorTokens.negative for focus outline','endContent wrapped in <span> w/ color:inherit, matches button text across variants',- 'icon w/o children=icon-only: square (aspectRatio:1/1), label=aria-label, any ReactNode as icon',- 'endContent ignored for icon-only to preserve square ratio',+ 'isIconOnly=true: square (aspectRatio:1/1), label=aria-label, any ReactNode as icon',+ 'endContent ignored when isIconOnly to preserve square ratio','prefer XDSButton over <div onClick> for a11y: keyboard nav, focus management, screen reader','icon-only suits toolbars, action grids, compact controls','onClick fires before onClickAction; preventDefault in onClick stops onClickAction',@@ -456,7 +460,7 @@ export const docsDense = {'disabled clears backgroundImage:none to prevent hover tint leaking through opacity',],propDescriptions: {- label: 'accessible label; aria-label for icon-only buttons',+ label: 'accessible label; visible text by default, aria-label when isIconOnly',variant: 'visual style variant',size: 'size variant',type: 'HTML button type; defaults to "button"',@@ -464,9 +468,10 @@ export const docsDense = {value: 'HTML value for form submission',form: 'associates button with form element by ID',isLoading: 'shows spinner+disables interaction; announces via live region',- icon: 'icon element; w/o children renders square icon-only button',- children: 'w/ icon, text rendered next to icon',- endContent: 'trailing icon/badge after label; accepts XDSIcon or XDSBadge; ignored for icon-only; color inherited',+ icon: 'icon element rendered before label text',+ isIconOnly: 'when true, renders square icon-only button; label becomes aria-label',+ children: 'optional visible content; rendered instead of label when provided',+ endContent: 'trailing icon/badge after label; ignored when isIconOnly; color inherited',tooltip: 'tooltip on hover',onClick: 'standard click handler; fires before onClickAction',onClickAction: 'async click handler; shows loading while promise pending',diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjsindex a2224e5668..225ed18420 100644--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs@@ -116,7 +116,7 @@ export const docs = {],notes: ['Uses `useXDSLayer` with `mode: "context"` for CSS anchor positioning',- 'Uses `XDSButton` internally β chevron is passed via `endContent` and auto-hidden for icon-only buttons',+ 'Uses `XDSButton` internally β chevron is passed via `endContent` and auto-hidden when `isIconOnly` is true','Items are tracked via the `items` prop to enable keyboard navigation','Light dismiss is enabled by default (clicking outside closes menu)',],diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsxindex 255d289cd4..379bee092f 100644--- a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx+++ b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx@@ -243,8 +243,7 @@ function getSelectableItems(* Props for customizing the dropdown button.* Extends XDSButtonProps but omits onClick since it's managed internally.*- * When `icon` is set without `children`, renders as an icon-only button- * (square, with `label` as aria-label). Pass `children` to get icon + visible text.+ * Set `isIconOnly` to render as an icon-only button (square, with `label` as aria-label).*/export type XDSDropdownMenuButtonProps = Omit<XDSButtonProps, 'onClick'>;@@ -287,8 +286,7 @@ export interface XDSDropdownMenuProps {/*** Whether to show a chevron indicator on the trigger button.- * Automatically hidden for icon-only buttons (when `button.icon` is set- * without `button.endContent`).+ * Automatically hidden for icon-only buttons (when `button.isIconOnly` is true).* @default true*/hasChevron?: boolean;diff --git a/packages/core/src/TopNav/XDSTopNavItem.tsx b/packages/core/src/TopNav/XDSTopNavItem.tsxindex c3dcf930ed..c2cb4605fd 100644--- a/packages/core/src/TopNav/XDSTopNavItem.tsx+++ b/packages/core/src/TopNav/XDSTopNavItem.tsx@@ -130,6 +130,7 @@ export interface XDSTopNavItemProps extends XDSBaseProps<HTMLAnchorElement> {isDisabled?: 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;