An open source design system that's fully customizable and agent ready
TypeScript
feat(Link): render button when href is undefined (#2507)
Cindy Zhang259eaedbb6e0
diff --git a/apps/storybook/stories/Link.stories.tsx b/apps/storybook/stories/Link.stories.tsxindex 97cf5e7327..e46377a546 100644--- a/apps/storybook/stories/Link.stories.tsx+++ b/apps/storybook/stories/Link.stories.tsx@@ -129,11 +129,8 @@ export const Standalone: Story = {export const InlineWithText: Story = {render: () => (<XDSText type="body">- Read the{' '}- <XDSLink href="/docs">- documentation- </XDSLink>{' '}- for more information about using XDS components.+ Read the <XDSLink href="/docs">documentation</XDSLink> for more+ information about using XDS components.</XDSText>),};@@ -154,10 +151,7 @@ export const AllVariants: Story = {<XDSLink href="/primary" color="primary" isStandalone>Primary</XDSLink>- <XDSLink- href="/secondary"- color="secondary"- isStandalone>+ <XDSLink href="/secondary" color="secondary" isStandalone>Secondary</XDSLink><XDSLink href="/inherit" color="inherit" isStandalone>@@ -165,37 +159,21 @@ export const AllVariants: Story = {</XDSLink></div><div style={{display: 'flex', gap: '16px', alignItems: 'center'}}>- <XDSLink- href="/underlined"- hasUnderline- isStandalone>+ <XDSLink href="/underlined" hasUnderline isStandalone>With underline</XDSLink>- <XDSLink- href="https://example.com"- isExternalLink- isStandalone>+ <XDSLink href="https://example.com" isExternalLink isStandalone>External</XDSLink>- <XDSLink- href="/tooltip"- tooltip="Helpful info"- isStandalone>+ <XDSLink href="/tooltip" tooltip="Helpful info" isStandalone>With tooltip</XDSLink></div><div style={{display: 'flex', gap: '16px', alignItems: 'center'}}>- <XDSLink- href="/disabled"- isDisabled- isStandalone>+ <XDSLink href="/disabled" isDisabled isStandalone>Disabled active</XDSLink>- <XDSLink- href="/disabled"- color="secondary"- isDisabled- isStandalone>+ <XDSLink href="/disabled" color="secondary" isDisabled isStandalone>Disabled secondary</XDSLink></div>@@ -211,16 +189,10 @@ export const ExternalLinks: Story = {flexDirection: 'column',gap: '8px',}}>- <XDSLink- href="https://github.com"- isExternalLink- isStandalone>+ <XDSLink href="https://github.com" isExternalLink isStandalone>GitHub</XDSLink>- <XDSLink- href="https://developer.mozilla.org"- isExternalLink- isStandalone>+ <XDSLink href="https://developer.mozilla.org" isExternalLink isStandalone>MDN Web Docs</XDSLink><XDSLink@@ -259,3 +231,157 @@ export const LinksWithTooltips: Story = {</div>),};++export const ButtonFallback: Story = {+ args: {+ children: 'Click me (no href)',+ onClick: () => alert('Clicked!'),+ },+ parameters: {+ docs: {+ description: {+ story:+ 'When `href` is undefined, XDSLink renders a `<button>` with reset styles. ' ++ 'Visually identical to a link, but semantically correct for actions that do not navigate.',+ },+ },+ },+};++export const ButtonFallbackDisabled: Story = {+ args: {+ children: 'Disabled action',+ isDisabled: true,+ },+ parameters: {+ docs: {+ description: {+ story:+ 'The button fallback supports the `isDisabled` prop with native `disabled` attribute.',+ },+ },+ },+};++export const ButtonFallbackVariants: Story = {+ render: () => (+ <div+ style={{+ display: 'flex',+ flexDirection: 'column',+ gap: '12px',+ maxWidth: '600px',+ }}>+ <div style={{display: 'flex', gap: '16px', alignItems: 'center'}}>+ <XDSLink onClick={() => {}} isStandalone>+ Active (default)+ </XDSLink>+ <XDSLink onClick={() => {}} color="primary" isStandalone>+ Primary+ </XDSLink>+ <XDSLink onClick={() => {}} color="secondary" isStandalone>+ Secondary+ </XDSLink>+ <XDSLink onClick={() => {}} color="inherit" isStandalone>+ Inherit+ </XDSLink>+ </div>+ <div style={{display: 'flex', gap: '16px', alignItems: 'center'}}>+ <XDSLink onClick={() => {}} hasUnderline isStandalone>+ With underline+ </XDSLink>+ <XDSLink onClick={() => {}} tooltip="Action tooltip" isStandalone>+ With tooltip+ </XDSLink>+ <XDSLink onClick={() => {}} isDisabled isStandalone>+ Disabled+ </XDSLink>+ </div>+ </div>+ ),+ parameters: {+ docs: {+ description: {+ story:+ 'Button fallback supports all visual variants (color, underline, tooltip, disabled) — ' ++ 'visually indistinguishable from a regular link.',+ },+ },+ },+};++export const ButtonFallbackInline: Story = {+ render: () => (+ <XDSText type="body">+ You can <XDSLink onClick={() => alert('Undo!')}>undo this action</XDSLink>{' '}+ if you change your mind.+ </XDSText>+ ),+ parameters: {+ docs: {+ description: {+ story:+ 'Button fallback works inline within text, just like a regular link. ' ++ 'Inspect the DOM — it renders a `<button>` not an `<a>`.',+ },+ },+ },+};++export const LinkVsButtonComparison: Story = {+ render: () => (+ <div+ style={{+ display: 'flex',+ flexDirection: 'column',+ gap: '16px',+ maxWidth: '600px',+ }}>+ <XDSText type="large" size="sm">+ Link (with href) vs Button (without href)+ </XDSText>+ <div style={{display: 'flex', gap: '24px', alignItems: 'center'}}>+ <div+ style={{+ display: 'flex',+ flexDirection: 'column',+ gap: '4px',+ alignItems: 'center',+ }}>+ <XDSLink href="/destination" isStandalone>+ I navigate+ </XDSLink>+ <XDSText type="body" size="sm" color="secondary">+ {'<a href="/destination">'}+ </XDSText>+ </div>+ <div+ style={{+ display: 'flex',+ flexDirection: 'column',+ gap: '4px',+ alignItems: 'center',+ }}>+ <XDSLink onClick={() => alert('Action!')} isStandalone>+ I act+ </XDSLink>+ <XDSText type="body" size="sm" color="secondary">+ {'<button type="button">'}+ </XDSText>+ </div>+ </div>+ <XDSText type="body" size="sm" color="secondary">+ Both look the same — but inspect the DOM to see the semantic difference.+ </XDSText>+ </div>+ ),+ parameters: {+ docs: {+ description: {+ story:+ 'Side-by-side comparison showing that links and button fallbacks are visually identical. ' ++ 'The only difference is in the rendered DOM element.',+ },+ },+ },+};diff --git a/packages/core/src/Link/XDSLink.test.tsx b/packages/core/src/Link/XDSLink.test.tsxindex 312c28c9d5..049db2c849 100644--- a/packages/core/src/Link/XDSLink.test.tsx+++ b/packages/core/src/Link/XDSLink.test.tsx@@ -38,6 +38,48 @@ describe('XDSLink', () => {expect(screen.getByRole('link')).toHaveAttribute('href', '/destination');});+ it('renders as a button when href is undefined', () => {+ render(<XDSLink>Action</XDSLink>);+ expect(screen.getByRole('button', {name: 'Action'})).toBeInTheDocument();+ });++ it('renders as a button when href is explicitly undefined', () => {+ render(<XDSLink href={undefined}>Action</XDSLink>);+ expect(screen.getByRole('button', {name: 'Action'})).toBeInTheDocument();+ });++ it('button fallback fires onClick', async () => {+ const user = userEvent.setup();+ const handleClick = vi.fn();+ render(<XDSLink onClick={handleClick}>Click me</XDSLink>);++ await user.click(screen.getByRole('button'));+ expect(handleClick).toHaveBeenCalledTimes(1);+ });++ it('button fallback supports isDisabled', () => {+ render(<XDSLink isDisabled>Disabled Action</XDSLink>);+ const button = screen.getByRole('button');+ expect(button).toBeDisabled();+ });++ it('button fallback has type="button"', () => {+ render(<XDSLink>Action</XDSLink>);+ expect(screen.getByRole('button')).toHaveAttribute('type', 'button');+ });++ it('button fallback supports aria-label via label prop', () => {+ render(+ <XDSLink label="Close dialog">+ <span aria-hidden="true">✕</span>+ </XDSLink>,+ );+ expect(screen.getByRole('button')).toHaveAttribute(+ 'aria-label',+ 'Close dialog',+ );+ });+it('does not render aria-label when label is omitted', () => {render(<XDSLink href="/test">Visible text</XDSLink>);expect(screen.getByRole('link')).not.toHaveAttribute('aria-label');diff --git a/packages/core/src/Link/XDSLink.tsx b/packages/core/src/Link/XDSLink.tsxindex cd626f4693..d5c6d7ad23 100644--- a/packages/core/src/Link/XDSLink.tsx+++ b/packages/core/src/Link/XDSLink.tsx@@ -73,6 +73,17 @@ const styles = stylex.create({':focus-visible': '2px',},},+ /**+ * Reset styles for rendering as a <button> when href is undefined.+ * Strips all native button chrome so it looks identical to a link.+ */+ buttonReset: {+ backgroundColor: 'transparent',+ borderStyle: 'none',+ padding: 0,+ pointerEvents: 'auto',+ position: 'relative',+ },hasUnderline: {textDecoration: 'underline',},@@ -112,13 +123,16 @@ const linkColorStyles = stylex.create({},});-export interface XDSLinkProps extends XDSBaseProps<HTMLAnchorElement> {+export interface XDSLinkProps extends XDSBaseProps<+ HTMLAnchorElement | HTMLButtonElement+> {/** Ref forwarded to the root element */- ref?: React.Ref<HTMLAnchorElement>;+ ref?: React.Ref<HTMLAnchorElement | HTMLButtonElement>;/*** Custom component to render instead of `<a>`.* Overrides the provider-level default set by XDSLinkProvider.* Must accept href, className, style, and children props.+ * Only used when href is provided.*/as?: XDSLinkComponentType;/**@@ -130,6 +144,8 @@ export interface XDSLinkProps extends XDSBaseProps<HTMLAnchorElement> {label?: string;/*** Link destination URL.+ * When undefined, renders as a `<button>` with link styling+ * for semantic correctness and accessibility.*/href?: string;/**@@ -169,9 +185,10 @@ export interface XDSLinkProps extends XDSBaseProps<HTMLAnchorElement> {*/referrerPolicy?: React.HTMLAttributeReferrerPolicy;/**- * Click handler. Fires before navigation.+ * Click handler. Fires before navigation (when href is set),+ * or as the primary action (when href is undefined).*/- onClick?: React.MouseEventHandler<HTMLAnchorElement>;+ onClick?: React.MouseEventHandler<HTMLAnchorElement | HTMLButtonElement>;/*** Tooltip text to display on hover.*/@@ -263,30 +280,11 @@ export function XDSLink({relFromProps,);- const linkElement = (- <LinkComponent- ref={ref}- href={href}- target={target}- rel={rel}- onClick={onClick}- aria-label={label || undefined}- aria-disabled={isDisabled || undefined}- tabIndex={isDisabled ? -1 : undefined}- {...mergeProps(- xdsClassName('link', {color}),- stylex.props(- styles.base,- linkColorStyles[color],- hasUnderline && styles.hasUnderline,- isStandalone && styles.standalone,- isDisabled && styles.disabled,- xstyle,- ),- className,- style,- )}- {...props}>+ // When href is undefined, render as a <button> for semantic correctness+ const renderAsButton = href == null;++ const sharedContent = (+ <><XDSTexttype={type}size={size}@@ -296,12 +294,76 @@ export function XDSLink({maxLines={maxLines}>{children}</XDSText>- {isExternalLink && (+ {isExternalLink && !renderAsButton && (<XDSIcon icon="externalLink" size="xsm" color="inherit" />)}- </LinkComponent>+ </>);+ let linkElement: React.ReactElement;++ if (renderAsButton) {+ linkElement = (+ <button+ ref={ref as React.Ref<HTMLButtonElement>}+ type="button"+ onClick={+ onClick+ }+ aria-label={label || undefined}+ aria-disabled={isDisabled || undefined}+ tabIndex={isDisabled ? -1 : undefined}+ disabled={isDisabled}+ {...mergeProps(+ xdsClassName('link', {color}),+ stylex.props(+ styles.base,+ styles.buttonReset,+ linkColorStyles[color],+ hasUnderline && styles.hasUnderline,+ isStandalone && styles.standalone,+ isDisabled && styles.disabled,+ xstyle,+ ),+ className,+ style,+ )}+ {...(props)}>+ {sharedContent}+ </button>+ );+ } else {+ linkElement = (+ <LinkComponent+ ref={ref as React.Ref<HTMLAnchorElement>}+ href={href}+ target={target}+ rel={rel}+ onClick={+ onClick+ }+ aria-label={label || undefined}+ aria-disabled={isDisabled || undefined}+ tabIndex={isDisabled ? -1 : undefined}+ {...mergeProps(+ xdsClassName('link', {color}),+ stylex.props(+ styles.base,+ linkColorStyles[color],+ hasUnderline && styles.hasUnderline,+ isStandalone && styles.standalone,+ isDisabled && styles.disabled,+ xstyle,+ ),+ className,+ style,+ )}+ {...props}>+ {sharedContent}+ </LinkComponent>+ );+ }+// Wrap with tooltip if providedif (tooltip) {return (