Skip to content

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

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

'use client';

/**
 * @file SelectableCard.tsx
 * @input Uses Card, useClickableContainer, StyleX
 * @output Exports SelectableCard component and SelectableCardProps
 * @position Interactive card for toggle selection
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/SelectableCard/SelectableCard.doc.mjs (props table, features)
 * - /packages/core/src/SelectableCard/index.ts (exports if types change)
 * - /apps/storybook/stories/SelectableCard.stories.tsx (storybook stories)
 * - /packages/cli/assets/templates/blocks/components/Card/SelectableCardShowcase.tsx (showcase block)
 * - /packages/cli/assets/templates/blocks/components/Card/SelectableCardMulti.tsx (block)
 * - /packages/cli/assets/templates/blocks/components/Card/SelectableCardElevated.tsx (block)
 *
 * Composes Card for all visual styling. Adds selection state with
 * an inset box-shadow (zero layout jitter) and useClickableContainer
 * for safe nested interactive elements.
 *
 * A hidden <input type="checkbox"> inside the card provides the accessible
 * role, label, and checked state — the card surface itself has no role/tabIndex.
 * Space toggles it natively; Enter is wired up as an additional toggle key.
 * Inside a single-choice group (Lab's SelectableCardGroup, through an internal
 * context) the input is a radio: the card selects and never deselects itself.
 *
 * For static display, use Card.
 * For navigation or action cards, use ClickableCard.
 */

import {
  type ReactNode,
  type MouseEvent,
  type KeyboardEvent,
  useRef,
  useCallback,
  use,
  type Ref,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {colorVars, durationVars, easeVars} from '../theme/tokens.stylex';
import type {Elevation, SizeValue, SpacingStep} from '../utils/types';
import {isImeKeyEvent, 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 {closestLayerRoot} from '../privateAttributes/layerRoot.stylex';
import type {BaseProps} from '../BaseProps';
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 {SelectableCardInputContext} from './selectableCardInput';
// =============================================================================
// Styles — selection + interaction; Card handles the rest
// =============================================================================

// 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: {
    // Declared here, on the element that carries the `astryx-selectable-card`
    // target, so a theme has something to override — the ring for a variant
    // only the theme knows about reads it (see selectedUnknown).
    '--selectable-card-ring-color': colorVars['--color-accent'],
    position: 'relative',
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    transitionProperty: {
      default: 'box-shadow, border-color',
      // Under reduced motion a selection's ring and border change 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'],
    },
  },
  // 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,
      borderRadius: 'inherit',
      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,
      },
    },
  },
  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,
  },
  // Selection indicator — an inset ring drawn via the card's --_card-ring
  // shadow slot (zero layout jitter) plus a borderColor change on the card's
  // own border for a cohesive look. Routing the ring through --_card-ring
  // (rather than box-shadow directly) lets it compose with the card's
  // elevation instead of clobbering it.
  selected: {
    borderColor: colorVars['--color-accent'],
    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-accent']}`,
  },
  selectedBlue: {
    borderColor: colorVars['--color-border-blue'],
    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-blue']}`,
  },
  selectedCyan: {
    borderColor: colorVars['--color-border-cyan'],
    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-cyan']}`,
  },
  selectedGray: {
    borderColor: colorVars['--color-border-gray'],
    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-gray']}`,
  },
  selectedGreen: {
    borderColor: colorVars['--color-border-green'],
    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-green']}`,
  },
  selectedOrange: {
    borderColor: colorVars['--color-border-orange'],
    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-orange']}`,
  },
  selectedPink: {
    borderColor: colorVars['--color-border-pink'],
    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-pink']}`,
  },
  selectedPurple: {
    borderColor: colorVars['--color-border-purple'],
    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-purple']}`,
  },
  selectedRed: {
    borderColor: colorVars['--color-border-red'],
    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-red']}`,
  },
  selectedTeal: {
    borderColor: colorVars['--color-border-teal'],
    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-teal']}`,
  },
  selectedYellow: {
    borderColor: colorVars['--color-border-yellow'],
    '--_card-ring': `inset 0 0 0 2px ${colorVars['--color-border-yellow']}`,
  },
  // A theme-added variant paints with colours the component cannot know, so no
  // token is guaranteed to contrast with it — an accent ring disappears against
  // an accent fill, and an outset one is no better. The theme that supplied the
  // fill is the only thing that can pick a ring, so it gets a lever beside it;
  // the var defaults to the accent, keeping every built-in unchanged.
  selectedUnknown: {
    '--_card-ring': 'inset 0 0 0 2px var(--selectable-card-ring-color)',
  },
});

const selectedStyleForVariant = (variant: CardVariant) => {
  switch (variant) {
    case 'default':
    case 'transparent':
    case 'muted':
      return styles.selected;
    case 'blue':
      return styles.selectedBlue;
    case 'cyan':
      return styles.selectedCyan;
    case 'gray':
      return styles.selectedGray;
    case 'green':
      return styles.selectedGreen;
    case 'orange':
      return styles.selectedOrange;
    case 'pink':
      return styles.selectedPink;
    case 'purple':
      return styles.selectedPurple;
    case 'red':
      return styles.selectedRed;
    case 'teal':
      return styles.selectedTeal;
    case 'yellow':
      return styles.selectedYellow;
    // CardVariant is open — a theme can add a variant this switch has never
    // seen, and it still has to look selected.
    default:
      return styles.selectedUnknown;
  }
};

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

export interface SelectableCardProps extends Omit<BaseProps, 'onChange'> {
  /** 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.
   */
  label: string;

  /**
   * Controlled selection state.
   * When true, the card shows an inset accent border indicating selection.
   */
  isSelected: boolean;

  /**
   * Selection change handler.
   * Called with the new selection state when the card is toggled.
   */
  onChange: (isSelected: boolean) => void;

  /**
   * Set to true to disable the card.
   * Disabled cards remain focusable (tabIndex 0) with aria-disabled
   * so screen reader users can discover them.
   */
  isDisabled?: boolean;

  /** Content to render inside the card. */
  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.
   * The selection ring composes on top, so a selected card keeps its shadow.
   * @default 'none'
   */
  elevation?: Elevation;

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

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

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

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

/**
 * Call a caller's click handler during capture, before the layer's own
 * handlers, without letting it change what those handlers see. Its
 * stopPropagation() would keep the press from the control inside the layer,
 * so it does nothing here. Its preventDefault() would mark the event handled
 * for those controls (a Button skips its clickAction), so it is applied to
 * the native event only after the press has bubbled to the document, where it
 * still cancels the browser's default action.
 */
function callBeforeLayerHandlers(
  handler: (event: MouseEvent<HTMLElement>) => void,
  event: MouseEvent<HTMLElement>,
): void {
  const {stopPropagation, preventDefault} = event;
  let isDefaultPreventedByCaller = false;
  event.stopPropagation = () => {};
  event.preventDefault = () => {
    isDefaultPreventedByCaller = true;
  };
  try {
    handler(event);
  } finally {
    event.stopPropagation = stopPropagation;
    event.preventDefault = preventDefault;
  }
  if (isDefaultPreventedByCaller) {
    const nativeEvent = event.nativeEvent;
    const doc = event.currentTarget.ownerDocument;
    const cancelDefault = (bubbled: Event) => {
      doc.removeEventListener(nativeEvent.type, cancelDefault);
      if (bubbled === nativeEvent) {
        nativeEvent.preventDefault();
      }
    };
    doc.addEventListener(nativeEvent.type, cancelDefault);
  }
}

/**
 * A card that toggles between selected and unselected states.
 *
 * Composes Card for visual styling and adds selection state with
 * an inset box-shadow (zero layout jitter vs plain Card). Supports
 * hover, pressed, focus, and disabled states.
 *
 * A visually-hidden <input type="checkbox"> inside the card provides
 * the accessible role, label, and checked state. The card surface
 * is a plain <div> — no role or tabIndex on the container.
 *
 * @compositionHint Use for multi-select card groups, managing selection
 * state externally in a Set. Not for single-select: each card is a
 * checkbox, so assistive technology announces a multi-select group.
 * For navigation/action cards, use ClickableCard instead.
 *
 * @example
 * ```
 * <SelectableCard
 *   label="Option A"
 *   isSelected={selected.has('a')}
 *   onChange={isSelected => toggle('a', isSelected)}>
 *   <Text type="body" weight="bold">Option A</Text>
 * </SelectableCard>
 * ```
 */
export function SelectableCard({
  label,
  isSelected,
  onChange,
  onClick: onClickProp,
  onMouseUp: onMouseUpProp,
  onPointerDown: onPointerDownProp,
  isDisabled = false,
  children,
  padding,
  variant = 'default',
  elevation = 'none',
  width,
  height,
  maxWidth,
  ref,
  xstyle: xstyleProp,
  className: classNameProp,
  style,
  ...props
}: SelectableCardProps) {
  const pressable = usePressFeedback();
  const containerRef = useRef<HTMLDivElement | null>(null);
  const interactiveRef = useRef<HTMLInputElement | null>(null);

  // A group can make the input a radio. A radio only selects: a native radio
  // stays checked when it is clicked again.
  const groupInput = use(SelectableCardInputContext);
  const isRadio = groupInput?.type === 'radio';
  const requestChange = useCallback(() => {
    if (!isRadio) {
      onChange(!isSelected);
    } else if (!isSelected) {
      onChange(true);
    }
  }, [isRadio, isSelected, onChange]);

  const handleClick = useCallback(
    (_event: MouseEvent<HTMLElement>) => {
      if (!isDisabled) {
        requestChange();
      }
    },
    [isDisabled, requestChange],
  );

  // A native checkbox or radio reacts to Space but not to Enter. This handler
  // adds Enter. Space is not handled here, because it would act twice.
  const handleKeyDown = useCallback(
    (event: KeyboardEvent<HTMLInputElement>) => {
      if (isImeKeyEvent(event.nativeEvent)) {
        return;
      }
      if (isDisabled) {
        if (event.key === ' ' || event.key === 'Enter') {
          event.preventDefault();
        }
        return;
      }
      if (event.key === 'Enter') {
        event.preventDefault();
        requestChange();
      }
    },
    [isDisabled, requestChange],
  );

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

  const composedOnClick = onClickProp
    ? (e: MouseEvent<HTMLElement>) => {
        onClick(e);
        onClickProp(e);
      }
    : onClick;

  // Until the next minor, a click inside an open layer within the card still
  // reaches the caller's onClick. The layer root stops that click before the
  // bubble phase, so it is delivered here, during capture. It never toggles.
  // Remove at the next minor, when that click stops reaching onClick.
  const handleLayerClickCapture = onClickProp
    ? (e: MouseEvent<HTMLElement>) => {
        const target = e.target;
        if (!(target instanceof Element)) {
          return;
        }
        const layerRoot = closestLayerRoot(target);
        if (layerRoot == null || layerRoot.contains(e.currentTarget)) {
          return;
        }
        callBeforeLayerHandlers(onClickProp, e);
      }
    : undefined;

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

  return (
    <Card
      ref={useMergedRefs(ref, containerRef)}
      {...(isDisabled ? undefined : pressable)}
      width={width}
      height={height}
      maxWidth={maxWidth}
      padding={padding}
      variant={variant}
      elevation={elevation}
      {...mergeProps(
        themeProps('selectable-card', {
          variant,
          selected: isSelected ? 'true' : 'false',
        }),
        focusOutlineProps.focusWithin(),
        classNameProp,
        style,
      )}
      xstyle={
        [
          styles.interactive,
          isSelected && selectedStyleForVariant(variant),
          !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 && styles.disabled,
          xstyleProp,
        ] as unknown as StyleXStyles
      }
      onClick={!isDisabled ? composedOnClick : undefined}
      onMouseUp={!isDisabled ? composedOnMouseUp : undefined}
      onPointerDown={
        !isDisabled
          ? chainEventHandlers(onPointerDown, onPointerDownProp)
          : onPointerDownProp
      }
      {...props}
      onClickCapture={
        !isDisabled && handleLayerClickCapture
          ? (e: MouseEvent<HTMLDivElement>) => {
              handleLayerClickCapture(e);
              props.onClickCapture?.(e);
            }
          : props.onClickCapture
      }>
      <input
        ref={interactiveRef}
        type={isRadio ? 'radio' : 'checkbox'}
        name={groupInput?.name}
        value={groupInput?.value}
        // Radios group by name and form owner, so every radio card leaves
        // the form together and the group stays one tab stop. The group
        // submits its choice itself. A disabled checkbox card submits
        // nothing, so it leaves the form too.
        form={
          groupInput != null && (groupInput.type === 'radio' || isDisabled)
            ? ''
            : undefined
        }
        checked={isSelected}
        aria-label={label}
        aria-disabled={isDisabled ? 'true' : undefined}
        onChange={() => {
          if (isDisabled) {
            return;
          }
          requestChange();
        }}
        onKeyDown={handleKeyDown}
        {...stylex.props(styles.srOnly)}
      />
      {children}
    </Card>
  );
}

SelectableCard.displayName = 'SelectableCard';