Skip to content

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

TypeScript
20.6 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Link.test.tsx
 * @input Uses vitest, @testing-library/react, Link component
 * @output Unit tests for Link component behavior
 * @position Testing; validates Link.tsx implementation
 *
 * SYNC: When Link.tsx changes, update tests to match new behavior
 */

import {describe, it, expect, vi} from 'vitest';
import {fireEvent, render, screen} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {hasPressedArm} from '../__tests__/pressState';
import type {ReactNode} from 'react';
import {LayerContentBoundary} from '../Layer/layerScopedContext';
import {Text} from '../Text/Text';
import {Link} from './Link';
import {LinkProvider} from './LinkProvider';

function CustomLink({
  children,
  ref,
  ...props
}: React.ComponentPropsWithRef<'a'>) {
  return (
    <a ref={ref} data-custom-link {...props}>
      {children}
    </a>
  );
}

describe('Link', () => {
  it('renders children as link text', () => {
    render(<Link href="/test">Click me</Link>);
    expect(screen.getByRole('link', {name: 'Click me'})).toBeInTheDocument();
  });

  it('renders with href attribute', () => {
    render(<Link href="/destination">Link</Link>);
    expect(screen.getByRole('link')).toHaveAttribute('href', '/destination');
  });

  it('renders as a button when href is undefined', () => {
    render(<Link>Action</Link>);
    expect(screen.getByRole('button', {name: 'Action'})).toBeInTheDocument();
  });

  it('renders as a button when href is explicitly undefined', () => {
    render(<Link href={undefined}>Action</Link>);
    expect(screen.getByRole('button', {name: 'Action'})).toBeInTheDocument();
  });

  it('button fallback fires onClick', async () => {
    const user = userEvent.setup();
    const handleClick = vi.fn();
    render(<Link onClick={handleClick}>Click me</Link>);

    await user.click(screen.getByRole('button'));
    expect(handleClick).toHaveBeenCalledTimes(1);
  });

  it('button fallback stays focusable and inert when isDisabled', async () => {
    const user = userEvent.setup();
    const onClick = vi.fn();
    render(
      <Link isDisabled onClick={onClick}>
        Disabled Action
      </Link>,
    );
    const button = screen.getByRole('button');
    expect(button).not.toHaveAttribute('disabled');
    expect(button).toHaveAttribute('aria-disabled', 'true');
    const nativeClick = vi.fn();
    button.addEventListener('click', nativeClick);
    await user.tab();
    expect(button).toHaveFocus();
    await user.keyboard('{Enter} ');
    expect(nativeClick).not.toHaveBeenCalled();
    fireEvent.click(button);
    expect(onClick).not.toHaveBeenCalled();
  });

  it('button fallback has type="button"', () => {
    render(<Link>Action</Link>);
    expect(screen.getByRole('button')).toHaveAttribute('type', 'button');
  });

  it('button fallback supports aria-label via label prop', () => {
    render(
      <Link label="Close dialog">
        <span aria-hidden="true">✕</span>
      </Link>,
    );
    expect(screen.getByRole('button')).toHaveAttribute(
      'aria-label',
      'Close dialog',
    );
  });

  it('does not render aria-label when label is omitted', () => {
    render(<Link href="/test">Visible text</Link>);
    expect(screen.getByRole('link')).not.toHaveAttribute('aria-label');
  });

  it('renders aria-label when label prop is provided', () => {
    render(
      <Link label="Accessible label" href="/test">
        <span aria-hidden="true">🏠</span>
      </Link>,
    );
    expect(screen.getByRole('link')).toHaveAttribute(
      'aria-label',
      'Accessible label',
    );
  });

  it('renders with different color values', () => {
    const {rerender} = render(
      <Link href="/test" color="accent">
        Accent
      </Link>,
    );
    expect(screen.getByRole('link')).toBeInTheDocument();

    rerender(
      <Link href="/test" color="secondary">
        Secondary
      </Link>,
    );
    expect(screen.getByRole('link')).toBeInTheDocument();

    rerender(
      <Link href="/test" color="inherit">
        Inherit
      </Link>,
    );
    expect(screen.getByRole('link')).toBeInTheDocument();
  });

  it('defaults the inner text type to body', () => {
    render(<Link href="/test">Body link</Link>);
    expect(screen.getByText('Body link')).toHaveClass('astryx-text');
    expect(screen.getByText('Body link')).toHaveAttribute('data-type', 'body');
  });

  it('forwards type="inherit" so the link adopts the surrounding text type', () => {
    render(
      <Link href="/test" type="inherit">
        Inline link
      </Link>,
    );
    // The inner Text renders with the `inherit` type, so font-size/line-height
    // inherit from the surrounding text rather than imposing the body type.
    const text = screen.getByText('Inline link');
    expect(text).toHaveClass('astryx-text');
    expect(text).toHaveAttribute('data-type', 'inherit');
    expect(text).not.toHaveAttribute('data-type', 'body');
  });

  it('applies hasUnderline style when true', () => {
    render(
      <Link href="/test" hasUnderline>
        Underlined Link
      </Link>,
    );
    expect(screen.getByRole('link')).toBeInTheDocument();
  });

  it('applies isDisabled state correctly', () => {
    render(
      <Link href="/test" isDisabled>
        Disabled Link
      </Link>,
    );
    // The href-less anchor keeps a Tab stop and an explicit link role.
    const link = screen.getByRole('link', {name: 'Disabled Link'});
    expect(link).toHaveAttribute('aria-disabled', 'true');
    expect(link).toHaveAttribute('tabIndex', '0');
    // Visual classes are preserved in the disabled state.
    expect(link?.className).toContain('astryx-link');
  });

  it('disabled link has no href attribute', () => {
    render(
      <Link href="/test" isDisabled>
        Disabled Link
      </Link>,
    );
    const link = screen.getByText('Disabled Link').closest('a');
    expect(link).not.toBeNull();
    expect(link).not.toHaveAttribute('href');
  });

  it('clicking a disabled link cancels default navigation', () => {
    render(
      <Link href="/test" isDisabled>
        Disabled Link
      </Link>,
    );
    const link = screen.getByText('Disabled Link').closest('a');
    expect(link).not.toBeNull();
    // fireEvent bypasses pointer-events, simulating programmatic/AT
    // activation. It returns false when preventDefault was called, i.e.
    // any default navigation behavior is cancelled.
    const notCancelled = fireEvent.click(link as HTMLAnchorElement);
    expect(notCancelled).toBe(false);
  });

  it('disabled link with onClick fires neither navigation nor the consumer onClick', () => {
    const handleClick = vi.fn();
    const {container} = render(
      <Link href="/test" isDisabled onClick={handleClick}>
        Disabled Link
      </Link>,
    );
    // With onClick present, a disabled Link renders as a disabled <button>
    // (useInteractiveRole excludes a disabled href). Either way the rendered
    // root must carry no live href and never invoke the consumer handler.
    const el = container.firstElementChild as HTMLElement;
    expect(el).not.toHaveAttribute('href');
    fireEvent.click(el);
    expect(handleClick).not.toHaveBeenCalled();
  });

  it('disabled link omits target and rel', () => {
    render(
      <Link href="https://example.com" isDisabled isExternalLink>
        Disabled External
      </Link>,
    );
    const link = screen.getByText('Disabled External').closest('a');
    expect(link).not.toBeNull();
    expect(link).not.toHaveAttribute('target');
    expect(link).not.toHaveAttribute('rel');
  });

  it('disabled link renders a plain anchor, not the custom LinkComponent', () => {
    render(
      <LinkProvider component={CustomLink}>
        <Link href="/custom" as={CustomLink} isDisabled>
          Disabled Custom
        </Link>
      </LinkProvider>,
    );
    const link = screen.getByText('Disabled Custom').closest('a');
    expect(link).not.toBeNull();
    expect(link).not.toHaveAttribute('data-custom-link');
    expect(link).not.toHaveAttribute('href');
  });

  it('renders external link with icon and target="_blank"', () => {
    render(
      <Link href="https://example.com" isExternalLink>
        External Link
      </Link>,
    );
    const link = screen.getByRole('link');
    expect(link).toHaveAttribute('target', '_blank');
    expect(link).toHaveAttribute('rel', 'noopener noreferrer');
    expect(link.querySelector('svg')).toBeInTheDocument();
  });

  it('announces the new-tab context via screen-reader text (obs-4)', () => {
    render(
      <Link href="https://example.com" isExternalLink>
        Docs
      </Link>,
    );
    // The link's accessible name includes the new-tab hint (the icon is
    // decorative).
    expect(
      screen.getByRole('link', {name: 'Docs (opens in new tab)'}),
    ).toBeInTheDocument();
  });

  it('supports a custom newTabLabel for localization', () => {
    render(
      <Link
        href="https://example.com"
        isExternalLink
        newTabLabel="(new window)">
        Docs
      </Link>,
    );
    expect(
      screen.getByRole('link', {name: 'Docs (new window)'}),
    ).toBeInTheDocument();
  });

  it('does not add new-tab text to non-external links', () => {
    render(<Link href="/internal">Internal</Link>);
    expect(screen.getByRole('link', {name: 'Internal'})).toBeInTheDocument();
  });

  it('renders external link with existing rel merged', () => {
    render(
      <Link href="https://example.com" isExternalLink rel="sponsored">
        External Link
      </Link>,
    );
    const link = screen.getByRole('link');
    expect(link).toHaveAttribute('rel', 'sponsored noopener noreferrer');
  });

  it('renders with custom target without isExternalLink', () => {
    render(
      <Link href="/test" target="_parent">
        Parent Link
      </Link>,
    );
    const link = screen.getByRole('link');
    expect(link).toHaveAttribute('target', '_parent');
  });

  it('adds safe rel tokens for explicit target="_blank"', () => {
    render(
      <Link href="/test" target="_blank">
        Blank Link
      </Link>,
    );
    const link = screen.getByRole('link');
    expect(link).toHaveAttribute('target', '_blank');
    expect(link).toHaveAttribute('rel', 'noopener noreferrer');
  });

  it('preserves existing rel tokens for explicit target="_blank"', () => {
    render(
      <Link href="/test" target="_blank" rel="sponsored noopener">
        Blank Link
      </Link>,
    );
    const link = screen.getByRole('link');
    expect(link).toHaveAttribute('rel', 'sponsored noopener noreferrer');
  });

  it('handles click events', async () => {
    const user = userEvent.setup();
    const handleClick = vi.fn((e: React.MouseEvent<HTMLAnchorElement>) => {
      e.preventDefault();
    });
    render(
      <Link href="/test" onClick={handleClick}>
        Click me
      </Link>,
    );

    await user.click(screen.getByRole('link'));
    expect(handleClick).toHaveBeenCalledTimes(1);
  });

  it('forwards ref correctly', () => {
    const ref = vi.fn();
    render(
      <Link href="/test" ref={ref}>
        Test
      </Link>,
    );
    expect(ref).toHaveBeenCalledWith(expect.any(HTMLAnchorElement));
  });

  it('renders standalone link', () => {
    render(
      <Link href="/standalone" isStandalone>
        Standalone Link
      </Link>,
    );
    expect(screen.getByRole('link')).toBeInTheDocument();
  });

  it('renders link with tooltip', () => {
    render(
      <Link href="/settings" tooltip="Configure settings">
        Settings
      </Link>,
    );
    const link = screen.getByRole('link', {name: 'Settings'});
    expect(link).toBeInTheDocument();
  });

  it('renders custom component when as is provided', () => {
    render(
      <Link href="/custom" as={CustomLink}>
        Custom Link
      </Link>,
    );
    const link = screen.getByRole('link', {name: 'Custom Link'});
    expect(link).toHaveAttribute('data-custom-link');
    expect(link).toHaveAttribute('href', '/custom');
  });

  it('renders custom component from LinkProvider', () => {
    render(
      <LinkProvider component={CustomLink}>
        <Link href="/provider">Provider Link</Link>
      </LinkProvider>,
    );
    const link = screen.getByRole('link', {name: 'Provider Link'});
    expect(link).toHaveAttribute('data-custom-link');
  });

  it('as prop overrides LinkProvider', () => {
    function AnotherLink({
      children,
      ref,
      ...props
    }: React.ComponentPropsWithRef<'a'>) {
      return (
        <a ref={ref} data-another-link {...props}>
          {children}
        </a>
      );
    }
    render(
      <LinkProvider component={AnotherLink}>
        <Link href="/override" as={CustomLink}>
          Override Link
        </Link>
      </LinkProvider>,
    );
    const link = screen.getByRole('link', {name: 'Override Link'});
    expect(link).toHaveAttribute('data-custom-link');
    expect(link).not.toHaveAttribute('data-another-link');
  });

  it('renders astryx-* class names for theme targeting', () => {
    render(
      <Link href="/test" color="secondary">
        Themed Link
      </Link>,
    );
    const link = screen.getByRole('link', {name: 'Themed Link'});
    expect(link.className).toContain('astryx-link');
    expect(link).toHaveAttribute('data-color', 'secondary');
  });

  it('keeps the reflected data-color when a caller passes its own', () => {
    const callerProps = {'data-color': 'danger'};
    render(
      <>
        <Link href="/test" color="secondary" {...callerProps}>
          Anchor Link
        </Link>
        <Link color="secondary" onClick={() => {}} {...callerProps}>
          Button Link
        </Link>
        <Link href="/test" color="secondary" isDisabled {...callerProps}>
          Disabled Link
        </Link>
      </>,
    );
    expect(screen.getByRole('link', {name: 'Anchor Link'})).toHaveAttribute(
      'data-color',
      'secondary',
    );
    expect(screen.getByRole('button', {name: 'Button Link'})).toHaveAttribute(
      'data-color',
      'secondary',
    );
    expect(screen.getByRole('link', {name: 'Disabled Link'})).toHaveAttribute(
      'data-color',
      'secondary',
    );
  });
});

describe('pressed state', () => {
  it('paints the pressed overlay behind a link while it is pressed', () => {
    render(<Link href="/docs">Docs</Link>);
    expect(hasPressedArm(screen.getByRole('link', {name: 'Docs'}))).toBe(true);
  });

  it('paints it on the button form too', () => {
    render(<Link onClick={() => {}}>Open</Link>);
    expect(hasPressedArm(screen.getByRole('button', {name: 'Open'}))).toBe(
      true,
    );
  });

  it('does not press a disabled link', () => {
    render(
      <Link href="/docs" isDisabled>
        Docs
      </Link>,
    );
    expect(hasPressedArm(screen.getByText('Docs').closest('a')!)).toBe(false);
  });
});

// =============================================================================
// Display: inside a clamped Text the anchor joins the text's line boxes, so
// the clamp can truncate it. Everywhere else it keeps its inline-flex box.
// Link never reads its children to decide (Link AV1).
// =============================================================================

/**
 * Extracts class-name tokens from a CSS selector (e.g. the selectorText of
 * a CSSStyleRule), so callers can match against an element's classList by
 * exact token rather than by substring. Handles compound selectors
 * (`.a.b:hover`) and comma-separated selector lists (`.a, .b`).
 */
function classTokensFromSelector(selectorText: string): string[] {
  const tokens: string[] = [];
  const classRegex = /\.([-_a-zA-Z0-9]+)/g;
  let match: RegExpExecArray | null;
  while ((match = classRegex.exec(selectorText)) !== null) {
    tokens.push(match[1]);
  }
  return tokens;
}

/**
 * Recursively collects every CSSStyleRule from a rule list, descending into
 * grouping rules (e.g. `@media`) so declarations nested in a condition are
 * not missed.
 */
function collectStyleRules(rules: CSSRuleList, out: CSSStyleRule[]): void {
  for (const rule of Array.from(rules)) {
    if (rule instanceof CSSStyleRule) {
      out.push(rule);
    } else if ('cssRules' in rule && rule.cssRules) {
      collectStyleRules((rule as CSSGroupingRule).cssRules, out);
    }
  }
}

/**
 * Returns the `display` value of every injected CSS rule that targets `el`,
 * matched via the CSSOM (real selector tokens + real class list) rather than
 * substring checks on raw selector/body text — a hashed atomic class like
 * `x1a` can be a substring of an unrelated class like `x1a2b3c4`, so
 * string-based matching can both false-positive and false-negative.
 */
function displayDeclarationsFor(el: Element): string[] {
  const classes = new Set(Array.from(el.classList));
  const styleRules: CSSStyleRule[] = [];
  for (const sheet of Array.from(document.styleSheets)) {
    let rules: CSSRuleList;
    try {
      rules = sheet.cssRules;
    } catch {
      continue;
    }
    collectStyleRules(rules, styleRules);
  }

  const declarations: string[] = [];
  for (const rule of styleRules) {
    const matchesElement = classTokensFromSelector(rule.selectorText).some(
      token => classes.has(token),
    );
    if (!matchesElement) {
      continue;
    }
    const display = rule.style.getPropertyValue('display');
    if (display) {
      declarations.push(display.trim());
    }
  }
  return declarations;
}

describe('Link display', () => {
  const inClamp = (link: ReactNode) => (
    <Text maxLines={2} hasTruncateTooltip={false}>
      Lead text {link} tail text
    </Text>
  );

  it('keeps its inline-flex box outside a clamped Text', () => {
    const {container} = render(<Link href="/docs">Documentation</Link>);
    expect(displayDeclarationsFor(container.querySelector('a')!)).toContain(
      'inline-flex',
    );
  });

  it('keeps its inline-flex box inside a Text that does not clamp', () => {
    const {container} = render(
      <Text>
        <Link href="/docs">Documentation</Link>
      </Text>,
    );
    expect(displayDeclarationsFor(container.querySelector('a')!)).toContain(
      'inline-flex',
    );
  });

  it('is inline inside a clamped Text, so the clamp can truncate it', () => {
    const {container} = render(
      inClamp(<Link href="/docs">Documentation</Link>),
    );
    const anchor = container.querySelector('a')!;
    expect(displayDeclarationsFor(anchor)).toContain('inline');
  });

  it('decides from the clamp, not the children: composed content is inline too', () => {
    const {container} = render(
      inClamp(
        <Link href="/docs">
          <strong>Docs</strong> home
        </Link>,
      ),
    );
    expect(displayDeclarationsFor(container.querySelector('a')!)).toContain(
      'inline',
    );
  });

  it('is inline inside a clamped Text for the external-link form', () => {
    const {container} = render(
      inClamp(
        <Link href="https://example.com" isExternalLink>
          External docs
        </Link>,
      ),
    );
    expect(displayDeclarationsFor(container.querySelector('a')!)).toContain(
      'inline',
    );
  });

  it('keeps its own box inside a clamped Text when it sets display or maxLines', () => {
    const {container} = render(
      inClamp(
        <>
          <Link href="/block" display="block">
            Block
          </Link>
          <Link href="/self" maxLines={1}>
            Self clamped
          </Link>
        </>,
      ),
    );
    for (const anchor of Array.from(container.querySelectorAll('a'))) {
      expect(displayDeclarationsFor(anchor)).not.toContain('inline');
    }
  });

  it('keeps the button form as an inline-flex box inside a clamped Text', () => {
    const {container} = render(
      inClamp(
        <Link onClick={() => {}} role="button">
          Action
        </Link>,
      ),
    );
    expect(
      displayDeclarationsFor(container.querySelector('button')!),
    ).not.toContain('inline');
  });

  it('keeps its own box in a layer opened inside a clamped Text', () => {
    const {container} = render(
      inClamp(
        <LayerContentBoundary>
          <Link href="/docs">In a layer</Link>
        </LayerContentBoundary>,
      ),
    );
    expect(displayDeclarationsFor(container.querySelector('a')!)).not.toContain(
      'inline',
    );
  });
});

describe('Link label color', () => {
  it('lets the label inherit the root color, so a theme styles Link through the link target', () => {
    for (const color of ['accent', 'primary', 'secondary'] as const) {
      const {container, unmount} = render(
        <Link href="/docs" color={color}>
          Docs
        </Link>,
      );
      const anchor = container.querySelector('a')!;
      expect(anchor).toHaveAttribute('data-color', color);
      const label = anchor.querySelector('.astryx-text')!;
      expect(label).toHaveAttribute('data-color', 'inherit');
      unmount();
    }
  });
});