Skip to content

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

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

'use client';

/**
 * @file SegmentedControlItem.tsx
 * @input Uses React, StyleX, SegmentedControlContext
 * @output Exports SegmentedControlItem component and SegmentedControlItemProps type
 * @position Child item; renders as a radio button within the segmented control
 *
 * SYNC: When modified, update:
 * - /packages/core/src/SegmentedControl/useSegmentedSelectionMotion.ts (the title marker)
 * - /packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
 * - /packages/core/src/SegmentedControl/index.ts
 * - /packages/core/src/SegmentedControl/SegmentedControl.test.tsx
 * - /packages/cli/assets/templates/blocks/components/SegmentedControl/ (showcase blocks)
 */

import React, {type ReactNode} from 'react';
import {joinAriaIDs} from '../utils/inputAria';
import {segmentDisabledProps} from '../privateAttributes/segmentDisabled.stylex';
import {segmentTitleProps} from '../privateAttributes/segmentTitle.stylex';
import * as stylex from '@stylexjs/stylex';
import {
  colorVars,
  spacingVars,
  sizeVars,
  durationVars,
  easeVars,
  fontWeightVars,
  shadowVars,
  typeScaleVars,
} from '../theme/tokens.stylex';
import {useSegmentedControlContext} from './SegmentedControlContext';
import type {SegmentedControlSize} from './SegmentedControlContext';
import {mergeProps, composeEventHandlers} from '../utils';
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 {isRenderable} from '../utils/isRenderable';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {useTouchHitArea} from '../utils/touchHitArea';
import {touchHitAreaStyles} from '../internal/touchHitArea.stylex';

export interface SegmentedControlItemProps extends BaseProps<HTMLButtonElement> {
  ref?: React.Ref<HTMLButtonElement>;
  /**
   * Unique value for this segment. Matched against the parent's value.
   */
  value: string;
  /**
   * Accessible label for this segment (required for accessibility).
   * Used as visible text, or as aria-label when isLabelHidden is true.
   */
  label: string;
  /**
   * Whether the label is visually hidden. When true, only the icon is
   * displayed and the label is used as aria-label for accessibility.
   * @default false
   */
  isLabelHidden?: boolean;
  /**
   * Icon element displayed before the label.
   */
  icon?: ReactNode;
  /**
   * Whether this individual item is disabled.
   * @default false
   */
  isDisabled?: boolean;
}

// =============================================================================
// Styles
// =============================================================================

const styles = stylex.create({
  base: {
    position: 'relative',
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    gap: spacingVars['--spacing-1'],
    paddingInline: spacingVars['--spacing-3'],
    backgroundColor: 'transparent',
    borderWidth: 0,
    borderStyle: 'none',
    fontFamily: 'inherit',
    fontSize: typeScaleVars['--text-label-size'],
    lineHeight: typeScaleVars['--text-label-leading'],
    fontWeight: fontWeightVars['--font-weight-medium'],
    color: colorVars['--color-text-secondary'],
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    whiteSpace: 'nowrap',
    // In both layouts a segment may be narrower than its label, so the
    // label's ellipsis can engage when the control is capped by its container.
    minWidth: 0,
    transitionProperty: 'color, background-color, box-shadow',
    transitionDuration: durationVars['--duration-fast'],
    transitionTimingFunction: easeVars['--ease-standard'],
  },
  selected: {
    // Forced colors (Windows High Contrast) strips the painted surface fill
    // and box shadow, which would leave the selected segment with no state
    // indication beyond font weight. Highlight/HighlightText is the platform
    // convention for a selected item (WCAG 1.4.11).
    //
    // forced-color-adjust must be `none` here: the segment is a <button>, and
    // the UA keeps native form-control colors (ButtonFace surface) for it under
    // forced colors, ignoring the authored Highlight fill — the label kept its
    // HighlightText color, giving white text on a white surface. Opting the
    // selected segment out of UA remapping makes both the Highlight surface and
    // the HighlightText label render as authored, restoring figure-ground.
    forcedColorAdjust: 'none',
    color: {
      default: colorVars['--color-text-primary'],
      '@media (forced-colors: active)': 'HighlightText',
    },
    fontWeight: fontWeightVars['--font-weight-semibold'],
    backgroundColor: {
      default: colorVars['--color-background-surface'],
      '@media (forced-colors: active)': 'Highlight',
    },
    boxShadow: shadowVars['--shadow-low'],
  },
  disabled: {
    cursor: 'default',
    color: colorVars['--color-text-disabled'],
  },
  fill: {
    flex: 1,
    minWidth: 0,
    justifyContent: 'center',
  },
  // An icon-only segment has no label to truncate, so it keeps its size.
  iconOnly: {
    flexShrink: 0,
  },
  icon: {
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    flexShrink: 0,
  },
  labelText: {
    overflow: 'hidden',
    textOverflow: 'ellipsis',
    minWidth: 0,
  },
  // Under a finger, script animates the selection change, because the surface
  // slides. A CSS transition would run a second, main-thread version of the
  // same change.
  touchPresentation: {
    transitionProperty: 'none',
  },
});

const CONCENTRIC_RADIUS =
  'max(0px, calc(var(--_segmented-control-radius) - var(--_segmented-control-padding)))';

const sizeStyles = stylex.create({
  sm: {
    height: `calc(${sizeVars['--size-element-sm']} - 4px)`,
    borderRadius: CONCENTRIC_RADIUS,
    paddingInline: spacingVars['--spacing-2'],
    fontSize: typeScaleVars['--text-supporting-size'],
  },
  md: {
    height: `calc(${sizeVars['--size-element-md']} - 4px)`,
    borderRadius: CONCENTRIC_RADIUS,
    paddingInline: spacingVars['--spacing-3'],
  },
  lg: {
    height: `calc(${sizeVars['--size-element-lg']} - 4px)`,
    borderRadius: CONCENTRIC_RADIUS,
    paddingInline: spacingVars['--spacing-3'],
  },
});

const iconSizeStyles = stylex.create({
  sm: {width: '14px', height: '14px'},
  md: {width: '16px', height: '16px'},
  lg: {width: '18px', height: '18px'},
});

/**
 * Individual segment item within an SegmentedControl.
 * Renders as a radio button with visual segment styling.
 *
 * @example
 * ```
 * <SegmentedControlItem value="grid" label="Grid" icon={<GridIcon />} />
 * ```
 */
export function SegmentedControlItem({
  ref,
  value,
  label,
  isLabelHidden = false,
  icon,
  isDisabled = false,
  onClick: onClickProp,
  xstyle,
  'aria-describedby': ariaDescribedByProp,
  ...rest
}: SegmentedControlItemProps) {
  const pressable = usePressFeedback();
  const ctx = useSegmentedControlContext();

  const isSelected = ctx.value === value;
  const isItemDisabled = isDisabled || ctx.isDisabled;
  const size: SegmentedControlSize = ctx.size;
  const isFill = ctx.layout === 'fill';

  // Consumer-first: a consumer onClick can call preventDefault() to opt out of
  // selection; otherwise selection proceeds when enabled and not selected.
  // A disabled segment invokes no caller callback (spec:AST-085 FR2), so the
  // consumer onClick is left out while it is disabled, including the selected
  // segment of a group disabled with a reason, which stays focusable.
  const handleClick = composeEventHandlers(
    isItemDisabled ? undefined : onClickProp,
    () => {
      if (!isItemDisabled && !isSelected) {
        ctx.onChange(value);
      }
    },
  );

  // A disabled segment takes no taps, so it gets no band.
  const hasHitArea = !isItemDisabled;
  const segmentRef = useMergedRefs(ref, useTouchHitArea(hasHitArea));

  const iconElement = isRenderable(icon) ? (
    <span {...stylex.props(styles.icon, iconSizeStyles[size])}>{icon}</span>
  ) : null;

  return (
    <button
      ref={segmentRef}
      {...rest}
      type="button"
      role="radio"
      aria-checked={isSelected}
      aria-disabled={isItemDisabled || undefined}
      aria-label={isLabelHidden ? label : undefined}
      // A caller description, then the group's disabled reason, which
      // describes each segment (FR7).
      aria-describedby={joinAriaIDs(ariaDescribedByProp, ctx.disabledReasonID)}
      data-value={value}
      // The group's fallback Tab stop skips segments disabled on their own.
      {...segmentDisabledProps(isDisabled)}
      {...(!isSelected && !isItemDisabled ? pressable : undefined)}
      // The selected segment holds the Tab stop, disabled or not (spec:AST-085
      // FR1); activation stays blocked by the isItemDisabled guard. With no
      // selected segment, the group places the stop (SegmentedControl FR2).
      tabIndex={isSelected ? 0 : -1}
      onClick={handleClick}
      {...mergeProps(
        themeProps('segmented-control-item', {
          size,
          selected: isSelected ? 'selected' : null,
          disabled: isItemDisabled ? 'disabled' : null,
        }),
        focusOutlineProps.focusVisible(
          styles.base,
          sizeStyles[size],
          isFill && styles.fill,
          isLabelHidden && styles.iconOnly,
          isSelected && styles.selected,
          // The shared hover and pressed overlay, on the segments a press can
          // change: the selected segment keeps its raised surface as it is.
          !isSelected &&
            !isItemDisabled &&
            interactionOverlayStyles.backgroundColor,
          isItemDisabled && styles.disabled,
          hasHitArea && touchHitAreaStyles.layer,
          ctx.isTouchPresentation === true && styles.touchPresentation,
          xstyle,
        ),
      )}>
      {iconElement}
      {!isLabelHidden && (
        <span {...segmentTitleProps} {...stylex.props(styles.labelText)}>
          {label}
        </span>
      )}
    </button>
  );
}

SegmentedControlItem.displayName = 'SegmentedControlItem';