Skip to content

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

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

'use client';

/**
 * @file TokenLink.tsx
 * @input Rendered token pieces (icon, label, endContent, remove button) plus
 *   container/link styling props and the resolved LinkComponent
 * @output Exports TokenLink, the interactive container for the href+onRemove Token variant
 * @position Internal to Token; keeps Token.tsx presentational
 *
 * Token is a presentational component (see
 * /internal/eslint-plugin-astryx/presentational-component.js) and must not use
 * refs or effects. When a Token has both `href` and `onRemove`, the remove
 * <button> must be a sibling of the link (nesting a button inside an anchor is
 * invalid HTML — WCAG 4.1.2), so the surface becomes a clickable container that
 * delegates to an inner link. That delegation needs refs, so it lives here.
 *
 * useClickableContainer gives the container middle-click and cmd/ctrl-click
 * open-in-new-tab behavior for the link, ignores clicks on nested interactive
 * elements (the remove button), and skips activation during text selection.
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/Token/Token.tsx (renders TokenLink for the href+onRemove case)
 * - /packages/core/src/Token/Token.test.tsx (tests for delegated behavior)
 */

import type {
  ReactNode,
  CSSProperties,
  Ref,
  HTMLAttributes,
  MouseEventHandler,
} 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';
import {disabledInteractionProps} from '../utils/disabledInteraction';
export interface TokenLinkProps extends HTMLAttributes<HTMLElement> {
  /** Ref forwarded to the container element. */
  ref?: Ref<HTMLElement>;
  /** Link URL. */
  href: string;
  /** Whether the token is disabled. */
  isDisabled: boolean;
  /**
   * Caller `onClick`, attached to the inner link. A plain click on the
   * container surface is delegated to the link, so this runs once per
   * plain-click activation of the link or the surface. A Cmd/Ctrl-click or
   * middle click on the surface opens the link in a new tab and skips it.
   */
  onLinkClick?: MouseEventHandler<HTMLElement>;
  /** Resolved link component (native `<a>` or a router link). */
  LinkComponent: LinkComponentType;
  /** `stylex.props()` output applied to the invisible inner link. */
  linkStyleProps: {className?: string; style?: CSSProperties};
  /** Visible (or visually hidden) label node rendered inside the link. */
  labelContent: ReactNode;
  /** Optional leading icon. */
  icon?: ReactNode;
  /** Content rendered after the label, before the remove button. */
  endContent?: ReactNode;
  /** The remove button node, rendered as a sibling of the link. */
  removeButton: ReactNode;
  /** Allow data-* attributes (e.g. data-testid, theme targets) on the container. */
  [dataAttr: `data-${string}`]: unknown;
}

/**
 * Interactive container for a Token that is both a link and removable.
 *
 * Renders a `<span>` wrapping an invisible inner link and the remove button as
 * siblings. useClickableContainer delegates clicks on the surface to the link
 * (including middle-click / cmd+click to open in a new tab) while the remove
 * button keeps handling its own clicks.
 */
export function TokenLink({
  ref,
  href,
  isDisabled,
  onLinkClick,
  LinkComponent,
  linkStyleProps,
  labelContent,
  icon,
  endContent,
  removeButton,
  onClick: onClickProp,
  onMouseUp: onMouseUpProp,
  onPointerDown: onPointerDownProp,
  ...containerProps
}: TokenLinkProps) {
  const containerRef = useRef<HTMLElement | null>(null);
  const linkRef = useRef<HTMLElement | null>(null);

  const {onClick, onMouseUp, onPointerDown} = useClickableContainer({
    containerRef,
    interactiveRef: linkRef,
    href,
    disabled: isDisabled,
  });

  return (
    <span
      ref={useMergedRefs(ref, containerRef)}
      {...containerProps}
      onClick={
        isDisabled ? onClickProp : composeEventHandlers(onClickProp, onClick)
      }
      onMouseUp={
        isDisabled
          ? onMouseUpProp
          : composeEventHandlers(onMouseUpProp, onMouseUp)
      }
      onPointerDown={
        isDisabled
          ? onPointerDownProp
          : composeEventHandlers(onPointerDownProp, onPointerDown)
      }>
      {icon}
      {isDisabled ? (
        // A disabled link stays a focusable link with no destination, as a
        // disabled Link does (spec:AST-085 FR1, FR5; component:Link FR5).
        <a
          ref={linkRef as Ref<HTMLAnchorElement>}
          role="link"
          aria-disabled={true}
          tabIndex={0}
          {...linkStyleProps}
          {...disabledInteractionProps()}>
          {labelContent}
        </a>
      ) : (
        <LinkComponent
          ref={linkRef as Ref<HTMLAnchorElement>}
          href={href}
          onClick={onLinkClick}
          {...linkStyleProps}>
          {labelContent}
        </LinkComponent>
      )}
      {endContent}
      {removeButton}
    </span>
  );
}

TokenLink.displayName = 'TokenLink';