Skip to content

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

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

'use client';

/**
 * @file ClickableCard.tsx
 * @input Uses Card, useClickableContainer, StyleX
 * @output Exports ClickableCard component and ClickableCardProps
 * @position Interactive card for navigation or action targets
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/ClickableCard/ClickableCard.doc.mjs (props table, features)
 * - /packages/core/src/ClickableCard/index.ts (exports if types change)
 * - /apps/storybook/stories/ClickableCard.stories.tsx (storybook stories)
 * - /packages/cli/assets/templates/blocks/components/Card/ClickableCardShowcase.tsx (showcase block)
 * - /packages/cli/assets/templates/blocks/components/Card/ClickableCardWithNestedButton.tsx (block)
 * - /packages/cli/assets/templates/blocks/components/Card/ClickableCardElevated.tsx (block)
 *
 * Composes Card for all visual styling (radius, padding, variants,
 * container tokens, theming). Adds an interactive wrapper with
 * useClickableContainer for safe nested interactive elements.
 *
 * A hidden <button> or <a> inside the card provides the accessible role,
 * label, and focus ring — the card surface itself has no role/tabIndex.
 * This gives screen readers a real interactive element to announce while
 * keeping the visual hover/active overlay on the full card.
 *
 * For static display, use Card.
 * For toggle selection, use SelectableCard.
 */

import {
  type ReactNode,
  type MouseEvent,
  useCallback,
  useRef,
  type Ref,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {
  borderVars,
  colorVars,
  durationVars,
  easeVars,
} from '../theme/tokens.stylex';
import type {SizeValue, SpacingStep, Elevation} from '../utils/types';
import {mergeProps} from '../utils';
import {chainEventHandlers} from '../utils/chainEventHandlers';
import {Card} from '../Card/Card';
import type {CardVariant} from '../Card/Card';
import {useClickableContainer} from '../hooks/useClickableContainer';
import type {BaseProps} from '../BaseProps';
import {useLinkComponent} from '../Link/useLinkComponent';
import {themeProps} from '../utils/themeProps';
import {focusOutlineProps} from '../utils/focusOutline.stylex';
import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
import {usePressFeedback} from '../hooks/usePressFeedback';

import {useMergedRefs} from '../hooks/useMergedRefs';
import {disabledInteractionProps} from '../utils/disabledInteraction';
// =============================================================================
// Styles — only the interactive layer, Card handles everything else
// =============================================================================

// The touch press's paint, declared by the shared overlay styles on the
// element the controller writes to (`pressedAlpha`) at the press's strength,
// 1 while on and 1 → 0 over the release, and inherited resolved by the
// `::after` that paints it. See interactionOverlay.stylex.ts.
const pressedOverlayImage = 'var(--_press-paint-image)';
/** Written by the press controller while it paints a press. */
const PRESSED_ON = '[data-astryx-press="on"]';
/** Written by the press controller for the press's release. */
const PRESSED_FADING = '[data-astryx-press="fading"]';

const styles = stylex.create({
  interactive: {
    position: 'relative',
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    textDecoration: 'none',
    color: 'inherit',
  },
  // Hover and pressed overlay. Hover is guarded by @media (hover: hover) so
  // touch devices don't show a stuck hover state; the press has two arms,
  // `:active` for a mouse and `data-astryx-press` for the press controller.
  overlay: {
    // The `::after` layer paints the hover and mouse states as its colour,
    // `--_press-overlay`, which their arms set on the element itself (same
    // enabled guard as the shared overlay utility). The press the controller
    // paints (a finger's, and on a touch-first device a mouse's or a key's)
    // is the same layer's image, keyed on the `data-astryx-press` attribute
    // the controller writes. Every arm of that press is a plain property of
    // the `::after`, which outranks the layer's own defaults in a layered
    // stylesheet and a flat one alike. A custom property's attribute arm
    // does not: a layered build emits the property's default outside the
    // priority layers its attribute arms land in, and the default wins.
    '--_press-overlay': {
      default: 'transparent',
      ':where(:not(:disabled,[aria-disabled="true"]))': {
        default: null,
        ':active': {
          default: colorVars['--color-overlay-pressed'],
          '@media (pointer: coarse)': 'transparent',
        },
        '@media (hover: hover)': {
          default: null,
          ':hover:where(:not(:disabled,[aria-disabled="true"]))':
            colorVars['--color-overlay-hover'],
          ':active': colorVars['--color-overlay-pressed'],
        },
      },
    },
    '::after': {
      content: '""',
      position: 'absolute',
      inset: 0,
      pointerEvents: 'none',
      // A press the controller paints shows on its first frame and fades on
      // its strength's own animation, so the colour it replaces drops out at
      // once rather than crossfading: no transition while it paints. The
      // mouse states keep the fast fade.
      transitionProperty: {
        default: 'background-color',
        [PRESSED_ON]: 'none',
        [PRESSED_FADING]: 'none',
        // Under reduced motion a colour changes at once. Only opacity may
        // still fade on a touch screen.
        '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
          'opacity',
      },
      transitionDuration: {
        default: durationVars['--duration-fast'],
        // Under reduced motion a fine pointer gets no transition. A touch
        // screen's fade keeps the exit tokens, within 200 ms.
        '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
          '0s',
        // The 200 ms bound copies reducedMotionFadeConsts.duration. That
        // module is internal, and a swizzled component imports only exported
        // paths. reducedMotionValues.test.ts keeps the copies equal.
        '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': `min(${durationVars['--duration-exit']}, 200ms)`,
      },
      transitionTimingFunction: {
        default: easeVars['--ease-standard'],
        '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
          easeVars['--ease-exit'],
      },
      // While the controller paints, the colour yields to the image: a
      // touchscreen beside a fine pointer still matches `:active` under a
      // finger, and the press would otherwise paint twice.
      backgroundColor: {
        default: 'var(--_press-overlay)',
        [PRESSED_ON]: 'transparent',
        [PRESSED_FADING]: 'transparent',
      },
      // The press at its strength, which the card's `pressedAlpha` arms own:
      // 1 on the first frame of a believed press, then 1 → 0 over the
      // release. The `::after` inherits the resolved paint and repaints with
      // it on every frame of the fade. Read only inside this element's own
      // arms, so a pressed ancestor's strength never paints here.
      backgroundImage: {
        default: null,
        [PRESSED_ON]: pressedOverlayImage,
        [PRESSED_FADING]: pressedOverlayImage,
      },
    },
  },
  // Borderless variants (everything except `default`): drop the transparent
  // 1px border Card applies. The overlay is inset to the padding box — inside
  // that border — so a transparent border strip stays untinted on hover and
  // reads as a faint ring. With no border, the overlay covers the full box
  // edge-to-edge and the ring disappears.
  borderless: {
    borderWidth: 0,
  },
  // Bordered variant (`default`): draw the 1px border *within* the padding by
  // subtracting the border width from every side. Total inset (border +
  // padding) then equals the borderless variants' padding, so content geometry
  // and outer dimensions stay identical across all variants. The border rests
  // at the subtle token and emphasizes on hover.
  bordered: {
    borderColor: colorVars['--color-border'],
    paddingInlineStart: `calc(var(--container-padding-inline-start) - ${borderVars['--border-width']})`,
    paddingInlineEnd: `calc(var(--container-padding-inline-end) - ${borderVars['--border-width']})`,
    paddingBlockStart: `calc(var(--container-padding-block-start) - ${borderVars['--border-width']})`,
    paddingBlockEnd: `calc(var(--container-padding-block-end) - ${borderVars['--border-width']})`,
    transitionProperty: {
      default: 'border-color',
      // Under reduced motion the border's colour changes at once.
      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
        'opacity',
    },
    transitionDuration: {
      default: durationVars['--duration-fast'],
      // Under reduced motion a fine pointer gets no transition. A touch
      // screen's opacity fade, such as a disabled card's dimming, takes
      // 200 ms at most.
      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
        '0s',
      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': `min(${durationVars['--duration-exit']}, 200ms)`,
    },
    transitionTimingFunction: {
      default: easeVars['--ease-standard'],
      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
        easeVars['--ease-exit'],
    },
  },
  // Emphasize the bordered variant's border on hover. Guarded by
  // @media (hover: hover) so touch devices don't get a stuck hover state.
  borderedHoverOnPointer: {
    '@media (hover: hover)': {
      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
        borderColor: colorVars['--color-border-emphasized'],
      },
    },
  },
  disabled: {
    cursor: 'default',
    opacity: 0.5,
  },
  srOnly: {
    position: 'absolute',
    width: '1px',
    height: '1px',
    padding: 0,
    margin: '-1px',
    overflow: 'hidden',
    clip: 'rect(0, 0, 0, 0)',
    whiteSpace: 'nowrap',
    borderWidth: 0,
  },
});

// =============================================================================
// Props
// =============================================================================

export interface ClickableCardProps extends BaseProps {
  /** Ref forwarded to the root element. */
  ref?: Ref<HTMLDivElement>;

  /**
   * Accessibility label for the card.
   * Used as `aria-label` — provides the accessible name for screen readers.
   * When the card has visible text that serves as its label, prefer
   * passing that text here so the screen reader announcement matches.
   */
  label: string;

  /**
   * Click handler. Fires when the card surface is clicked
   * (not when nested interactive elements are clicked).
   */
  onClick?: (event: MouseEvent<HTMLElement>) => void;

  /**
   * Navigation URL. When provided, clicking the card navigates to this URL.
   * Ctrl/Cmd+click opens in a new tab.
   */
  href?: string;

  /**
   * Link target for href navigation.
   * @default '_self'
   */
  target?: string;

  /**
   * Set to true to disable the card.
   * Disabled cards keep their tab stop and expose aria-disabled; activation is
   * blocked, and disabled link cards render no live destination.
   */
  isDisabled?: boolean;

  /**
   * Content to render inside the card.
   * Can include nested interactive elements (buttons, links) — they will
   * work independently from the card's click/navigation behavior.
   */
  children?: ReactNode;

  /**
   * Internal padding of the card using the spacing scale.
   * @default 4 (16px)
   */
  padding?: SpacingStep;

  /**
   * Background color variant.
   * @default 'default'
   */
  variant?: CardVariant;

  /**
   * Resting elevation — the shadow depth the card sits at. Often raised to
   * signal that the whole card is clickable.
   * @default 'none'
   */
  elevation?: Elevation;

  /** Width of the card. */
  width?: SizeValue;

  /** Height of the card. */
  height?: SizeValue;

  /** Maximum width of the card. */
  maxWidth?: SizeValue;
}

// =============================================================================
// Component
// =============================================================================

/**
 * An interactive card that acts as a single navigation or action target.
 *
 * Composes Card for visual styling and adds an interactive layer
 * with useClickableContainer. Nested interactive elements (buttons,
 * links, inputs) work independently — clicking them does NOT trigger
 * the card's onClick or navigation.
 *
 * A visually-hidden <button> or <a> inside the card provides the
 * accessible role and label. The card surface is a plain <div> —
 * no role or tabIndex on the container.
 *
 * @compositionHint Use for cards that navigate to a detail page or trigger an action.
 * For toggle selection cards, use SelectableCard instead.
 * Nest Button or other interactive elements freely inside — they won't conflict.
 *
 * @example
 * ```
 * <ClickableCard label="Settings" href="/settings">
 *   <Text type="body" weight="bold">Settings</Text>
 *   <Text type="supporting" color="secondary">Manage your preferences</Text>
 * </ClickableCard>
 * ```
 *
 * @example
 * ```
 * <ClickableCard label="Open modal" onClick={() => setShowModal(true)}>
 *   <Text type="body">Click anywhere to open</Text>
 *   <Button label="Other action" onClick={handleOther} />
 * </ClickableCard>
 * ```
 */
export function ClickableCard({
  label,
  onClick: onClickProp,
  onMouseUp: onMouseUpProp,
  onPointerDown: onPointerDownProp,
  href,
  target,
  isDisabled = false,
  children,
  padding,
  variant = 'default',
  elevation = 'none',
  width,
  height,
  maxWidth,
  ref,
  xstyle: xstyleProp,
  className: classNameProp,
  style,
  ...props
}: ClickableCardProps) {
  const pressable = usePressFeedback();
  const containerRef = useRef<HTMLDivElement | null>(null);
  const interactiveRef = useRef<HTMLElement | null>(null);
  const restoreFocusRef = useRef(false);
  // The isDisabled value of the link that just detached: a link card that
  // flips it replaces its hidden link (router component and plain anchor),
  // and only that replacement takes focus back.
  const detachedDisabledRef = useRef<boolean | null>(null);

  // A focused link remounts when isDisabled changes: the replacement takes
  // focus back, without scrolling, if focus fell to the page. Any other
  // detach and attach (a hidden Activity or Suspense boundary revealed
  // again) leaves focus where the person put it.
  const setInteractiveRef = useCallback(
    (node: HTMLElement | null) => {
      if (node == null) {
        const previous = interactiveRef.current;
        restoreFocusRef.current =
          previous != null && previous === previous.ownerDocument.activeElement;
        detachedDisabledRef.current = isDisabled;
        interactiveRef.current = null;
        return;
      }
      interactiveRef.current = node;
      const isFlip =
        detachedDisabledRef.current != null &&
        detachedDisabledRef.current !== isDisabled;
      const active = node.ownerDocument.activeElement;
      const hasFallen = active == null || active === node.ownerDocument.body;
      if (restoreFocusRef.current && isFlip && hasFallen) {
        node.focus({preventScroll: true});
      }
      restoreFocusRef.current = false;
      detachedDisabledRef.current = null;
    },
    [isDisabled],
  );

  const LinkComponent = useLinkComponent();

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

  const handleMouseUp = onMouseUpProp
    ? (e: MouseEvent<HTMLElement>) => {
        onMouseUp(e);
        onMouseUpProp(e);
      }
    : onMouseUp;

  const isLink = href != null;

  // Disabled links have no href, so bypass the router and render an anchor.
  const LinkRoot = isDisabled ? 'a' : LinkComponent;

  // Only the `default` variant has a visible border. Card draws a transparent
  // 1px border on every other variant purely to avoid layout jitter; we drop
  // it here so the hover overlay covers the full box with no untinted ring.
  const hasBorder = variant === 'default';

  return (
    <Card
      ref={useMergedRefs(ref, containerRef)}
      {...(isDisabled ? undefined : pressable)}
      width={width}
      height={height}
      maxWidth={maxWidth}
      padding={padding}
      variant={variant}
      elevation={elevation}
      {...mergeProps(
        themeProps('clickable-card', {variant}),
        focusOutlineProps.focusWithin(),
        classNameProp,
        style,
      )}
      xstyle={
        [
          styles.interactive,
          hasBorder ? styles.bordered : styles.borderless,
          !isDisabled && styles.overlay,
          // The touch press's strength and release, on the element the
          // controller writes to; the `::after` above paints off it.
          !isDisabled && interactionOverlayStyles.pressedAlpha,
          !isDisabled && hasBorder && styles.borderedHoverOnPointer,
          isDisabled && styles.disabled,
          xstyleProp,
        ] as unknown as StyleXStyles
      }
      onClick={!isDisabled ? onClick : undefined}
      onMouseUp={!isDisabled ? handleMouseUp : undefined}
      onPointerDown={
        !isDisabled
          ? chainEventHandlers(onPointerDown, onPointerDownProp)
          : onPointerDownProp
      }
      {...props}>
      {isLink ? (
        <LinkRoot
          ref={setInteractiveRef}
          href={isDisabled ? undefined : href}
          target={isDisabled ? undefined : target}
          role={isDisabled ? 'link' : undefined}
          {...(isDisabled ? disabledInteractionProps() : null)}
          aria-label={label}
          aria-disabled={isDisabled || undefined}
          // A disabled card keeps its Tab stop (spec:AST-085 FR1).
          tabIndex={0}
          {...stylex.props(styles.srOnly)}
        />
      ) : (
        <button
          ref={setInteractiveRef}
          type="button"
          aria-label={label}
          aria-disabled={isDisabled || undefined}
          onClick={onClickProp}
          // Focusable while disabled (FR1), but inert (FR2).
          {...(isDisabled ? disabledInteractionProps() : null)}
          {...stylex.props(styles.srOnly)}
        />
      )}
      {children}
    </Card>
  );
}

ClickableCard.displayName = 'ClickableCard';