Skip to content

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

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

'use client';

/**
 * @file CommentPin.tsx
 * @input Ordered participants (grouped pins show at most three circles),
 *   total and unread represented thread counts (unread shows as a dot), a
 *   size on the element-size
 *   scale, controlled selected/dimmed/resolved/disabled state, and button DOM
 *   props
 * @output Exports the avatar-first CommentPin button and its public types
 * @position Lab collaboration primitive for annotation anchors over content or
 *   in content margins; callers own grouping, coordinates, and opened content
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/lab/src/CommentPin/CommentPin.doc.mjs
 * - /docs/specs/components/CommentPin/CommentPin.spec.md
 * - /packages/lab/src/CommentPin/CommentPin.test.tsx
 * - /packages/lab/src/CommentPin/index.ts
 * - /apps/storybook/stories/CommentPin.stories.tsx
 * - /packages/lab/blocks/CommentPinShowcase.tsx
 */

import * as stylex from '@stylexjs/stylex';
import type {BaseProps} from '@astryxdesign/core';
import {Avatar, type AvatarSize} from '@astryxdesign/core/Avatar';
import {AvatarGroup, AvatarGroupOverflow} from '@astryxdesign/core/AvatarGroup';
import {
  useDevWarning,
  useMergedRefs,
  usePressFeedback,
} from '@astryxdesign/core/hooks';
import {Icon, type IconSize} from '@astryxdesign/core/Icon';
import {StatusDot} from '@astryxdesign/core/StatusDot';
import {
  borderVars,
  colorVars,
  fontWeightVars,
  shadowVars,
  sizeVars,
  spacingVars,
  typeScaleVars,
  typographyVars,
} from '@astryxdesign/core/theme/tokens.stylex';
import {useTooltip} from '@astryxdesign/core/Tooltip';
import {
  focusOutlineProps,
  interactionOverlayStyles,
  mergeProps,
  themeProps,
} from '@astryxdesign/core/utils';

/** Pin heights on the shared element-size scale: 28, 32, or 36px. */
export type CommentPinSize = 'sm' | 'md' | 'lg';

/** Identity data for one representative shown inside a CommentPin. */
export interface CommentPinParticipant {
  /** Stable identity used to remove duplicate representatives. */
  id: string;
  /** Display name used by Avatar for image fallback initials. */
  name: string;
  /** Optional image source passed to Avatar. */
  avatarSrc?: string;
}

export interface CommentPinProps extends Omit<
  BaseProps<HTMLButtonElement>,
  'children'
> {
  /** Ref forwarded to the marker button. */
  ref?: React.Ref<HTMLButtonElement>;
  /**
   * Accessible action name and visual hover/focus tooltip.
   * Include grouped, unread, or resolved context when it changes the action's
   * meaning.
   */
  label: string;
  /**
   * Ordered participants, lead first. A single marker shows the first. A
   * grouped marker shows distinct IDs as an AvatarGroup of at most three
   * circles: every participant when three or fewer are distinct, otherwise the
   * first two plus an ellipsis overflow circle. Pass every distinct
   * participant so the overflow appears only when more than three people
   * participate.
   */
  participants: readonly [CommentPinParticipant, ...CommentPinParticipant[]];
  /**
   * Pin height on the element-size scale: `sm` 28px, `md` 32px, `lg` 36px,
   * with 22px, 24px, and 28px participant circles.
   * @default 'sm'
   */
  size?: CommentPinSize;
  /**
   * Total number of threads represented by this marker. Values above one use
   * the grouped presentation and show the exact total.
   * @default 1
   */
  threadCount?: number;
  /**
   * Number of represented threads with unread activity. When above zero, an
   * accent status dot appears at the end of the pin: after the thread total,
   * or after the participant on a single pin. Values above `threadCount` are
   * capped.
   * @default 0
   */
  unreadCount?: number;
  /** Whether this pin is the currently selected annotation target. */
  isSelected?: boolean;
  /**
   * Whether another pin is selected in the host. Dims this pin without
   * disabling it, so it remains available to switch selection.
   */
  isDimmed?: boolean;
  /**
   * Whether every thread represented by this pin is resolved. A resolved pin
   * renders nothing unless it is selected, so resolved discussion leaves the
   * content while a thread the reader opened keeps its anchor.
   */
  isResolved?: boolean;
  /** Whether activation is unavailable. */
  isDisabled?: boolean;
}

const styles = stylex.create({
  root: {
    appearance: 'none',
    boxSizing: 'border-box',
    position: 'relative',
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    flexShrink: 0,
    verticalAlign: 'middle',
    transformOrigin: {
      default: 'left bottom',
      ':is([dir="rtl"] *)': 'right bottom',
    },
    margin: 0,
    borderWidth: borderVars['--border-width'],
    borderStyle: 'solid',
    borderColor: 'transparent',
    // Speech-bubble silhouette: a fixed 2px logical bottom-start corner; the
    // other three corners are half the pin's height (see `sizeStyles`). The
    // literal is intentional: no radius token is 2px, and themes may change
    // `--radius-inner`, which would soften the anchor cue. Logical longhands
    // mirror the corner in RTL by construction.
    borderEndStartRadius: '2px',
    backgroundColor: colorVars['--color-background-popover'],
    backgroundImage: 'none',
    boxShadow: shadowVars['--shadow-med'],
    color: colorVars['--color-text-secondary'],
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    fontFamily: typographyVars['--font-family-body'],
    fontSize: typeScaleVars['--text-supporting-size'],
    fontWeight: fontWeightVars['--font-weight-semibold'],
    lineHeight: typeScaleVars['--text-supporting-leading'],
    whiteSpace: 'nowrap',
    userSelect: 'none',
  },
  withCount: {
    justifyContent: 'flex-start',
    gap: spacingVars['--spacing-1'],
  },
  selected: {
    // Native buttons keep ButtonFace/ButtonText under forced colors unless the
    // selected state opts out of UA remapping; author both sides together.
    forcedColorAdjust: 'none',
    opacity: 1,
    // The border stays transparent so the selection reads as exactly one 2px
    // accent outline: the box-shadow ring below, drawn outside the pin.
    borderColor: {
      default: 'transparent',
      '@media (forced-colors: active)': 'Highlight',
    },
    backgroundColor: {
      default: colorVars['--color-background-popover'],
      '@media (forced-colors: active)': 'Highlight',
    },
    // A solid 2px accent outline outside the pin, layered with its resting
    // medium elevation. A box-shadow ring shifts no layout, follows the
    // speech-bubble corners, and leaves the shared focus outline (offset
    // farther out) as a separate cue.
    boxShadow: {
      default: `0 0 0 2px ${colorVars['--color-accent']}, ${shadowVars['--shadow-med']}`,
      '@media (forced-colors: active)': 'none',
    },
    color: {
      default: colorVars['--color-text-secondary'],
      '@media (forced-colors: active)': 'HighlightText',
    },
  },
  dimmed: {
    opacity: {
      default: 0.4,
      '@media (forced-colors: active)': 1,
    },
  },
  disabled: {
    cursor: 'default',
    opacity: {
      default: 0.45,
      '@media (forced-colors: active)': 1,
    },
  },
  // An aria-disabled button gets no system disabled paint in forced colors;
  // GrayText is the platform's disabled affordance there. Defaults repeat the
  // base values, since StyleX merges per property. Only unselected pins take
  // it — the selected treatment keeps its forced-colors Highlight, so a
  // selected disabled pin stays prominent (ORD4).
  disabledUnselected: {
    borderColor: {
      default: 'transparent',
      '@media (forced-colors: active)': 'GrayText',
    },
    color: {
      default: colorVars['--color-text-secondary'],
      '@media (forced-colors: active)': 'GrayText',
    },
  },
  avatarRail: {
    display: 'inline-flex',
    alignItems: 'center',
    flexShrink: 0,
  },
  // AvatarGroup draws every face inside a 2px surface ring. Sitting the first
  // ring in the start padding keeps the faces themselves as far from the start
  // edge as from the top and bottom, as on a single pin.
  groupedRail: {
    marginInlineStart: -2,
  },
  // AvatarGroupOverflow pads its content for multi-digit `+N` pills; the
  // ellipsis inside this pin stays a circle the size of its sibling Avatars.
  overflowCircle: {
    paddingInline: 0,
  },
  // The thread total and then the unread dot follow the participants. The
  // end padding gives whichever comes last room before the pin's edge, so a
  // number or dot never crowds it.
  trailing: {
    display: 'inline-flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-1'],
    paddingInlineEnd: spacingVars['--spacing-1'],
  },
  count: {
    color: 'inherit',
    fontVariantNumeric: 'tabular-nums',
  },
  // StatusDot paints its plate with a background, which forced colors would
  // erase; there it takes the pin's own text color, so it shows in every state.
  unreadDot: {
    forcedColorAdjust: 'none',
    color: {
      default: colorVars['--color-on-accent'],
      '@media (forced-colors: active)': 'inherit',
    },
    backgroundColor: {
      default: colorVars['--color-accent'],
      '@media (forced-colors: active)': 'currentColor',
    },
  },
});

// Each size pairs an element-size height with a participant circle diameter
// (see AVATAR_SIZE). The padding is the inset that centers that circle in the
// height, applied on every side: the avatars and overflow sit the same
// distance from all four edges. The three round corners are half the height,
// which is fully round: the 9999px full-radius token would make the browser
// scale every corner down to fit the box (the CSS corner-overlap rule) and
// shrink the 2px anchor corner to nothing.
const sizeStyles = stylex.create({
  sm: {
    minWidth: sizeVars['--size-element-sm'],
    height: sizeVars['--size-element-sm'],
    padding: `calc((${sizeVars['--size-element-sm']} - 22px) / 2 - ${borderVars['--border-width']})`,
    borderStartStartRadius: `calc(${sizeVars['--size-element-sm']} / 2)`,
    borderStartEndRadius: `calc(${sizeVars['--size-element-sm']} / 2)`,
    borderEndEndRadius: `calc(${sizeVars['--size-element-sm']} / 2)`,
  },
  md: {
    minWidth: sizeVars['--size-element-md'],
    height: sizeVars['--size-element-md'],
    padding: `calc((${sizeVars['--size-element-md']} - 24px) / 2 - ${borderVars['--border-width']})`,
    borderStartStartRadius: `calc(${sizeVars['--size-element-md']} / 2)`,
    borderStartEndRadius: `calc(${sizeVars['--size-element-md']} / 2)`,
    borderEndEndRadius: `calc(${sizeVars['--size-element-md']} / 2)`,
  },
  lg: {
    minWidth: sizeVars['--size-element-lg'],
    height: sizeVars['--size-element-lg'],
    padding: `calc((${sizeVars['--size-element-lg']} - 28px) / 2 - ${borderVars['--border-width']})`,
    borderStartStartRadius: `calc(${sizeVars['--size-element-lg']} / 2)`,
    borderStartEndRadius: `calc(${sizeVars['--size-element-lg']} / 2)`,
    borderEndEndRadius: `calc(${sizeVars['--size-element-lg']} / 2)`,
  },
});

/**
 * Participant circle diameter per pin size, matching the literals in
 * `sizeStyles`. Avatar renders any pixel size; its typed scale lists neither
 * 22 nor 28, hence the cast.
 */
const AVATAR_SIZE: Record<CommentPinSize, AvatarSize> = {
  sm: 22 as AvatarSize,
  md: 24,
  lg: 28 as AvatarSize,
};

/** The overflow ellipsis per pin size. */
const OVERFLOW_ICON_SIZE: Record<CommentPinSize, IconSize> = {
  sm: 'xsm',
  md: 'xsm',
  lg: 'sm',
};

function takeDistinctParticipants(
  participants: readonly CommentPinParticipant[],
  limit: number,
): CommentPinParticipant[] {
  const result: CommentPinParticipant[] = [];
  const seen = new Set<string>();

  for (const participant of participants) {
    if (seen.has(participant.id)) {
      continue;
    }
    seen.add(participant.id);
    result.push(participant);
    if (result.length === limit) {
      break;
    }
  }

  return result;
}

function isValidThreadCount(threadCount: number): boolean {
  return (
    Number.isFinite(threadCount) &&
    Number.isInteger(threadCount) &&
    threadCount >= 1
  );
}

function isValidUnreadCount(unreadCount: number): boolean {
  return (
    Number.isFinite(unreadCount) &&
    Number.isInteger(unreadCount) &&
    unreadCount >= 0
  );
}

/** Grouped pins never show more than this many circles, overflow included. */
const MAX_GROUP_CIRCLES = 3;

/**
 * Avatar-first annotation anchor for one thread or a caller-defined group.
 *
 * The caller owns grouping, representative selection, coordinates, collision
 * handling, and the content opened by activation. Absolute placement maps the
 * host anchor to the pin's logical bottom-start corner. The pin only owns its
 * compact button surface and controlled visual states. `size` sets its height
 * on the element-size scale.
 *
 * @example
 * ```
 * <CommentPin
 *   label="Open annotation from Ada"
 *   participants={[{id: 'ada', name: 'Ada Lovelace'}]}
 *   onClick={() => openThread('thread-1')}
 * />
 * ```
 *
 * @example
 * ```
 * <CommentPin
 *   label="Open 6 grouped annotations from Ada, Lin, and 3 others, 2 unread"
 *   participants={[ada, lin, mira, noah, sam]}
 *   threadCount={6}
 *   unreadCount={2}
 *   isSelected
 *   onClick={() => openCluster('cluster-1')}
 * />
 * ```
 */
export function CommentPin({
  label,
  participants,
  size = 'sm',
  threadCount = 1,
  unreadCount = 0,
  isSelected = false,
  isDimmed = false,
  isResolved = false,
  isDisabled = false,
  ref,
  xstyle,
  className,
  style,
  ...rest
}: CommentPinProps): React.ReactNode {
  const resolvedSize: CommentPinSize =
    size === 'md' || size === 'lg' ? size : 'sm';
  const avatarSize = AVATAR_SIZE[resolvedSize];
  const validThreadCount = isValidThreadCount(threadCount);
  const resolvedThreadCount = validThreadCount ? threadCount : 1;
  const isGrouped = resolvedThreadCount > 1;
  const validUnreadCount = isValidUnreadCount(unreadCount);
  const resolvedUnreadCount = validUnreadCount
    ? Math.min(unreadCount, resolvedThreadCount)
    : 0;
  const hasUnread = resolvedUnreadCount > 0;

  // Grouped pins cap at MAX_GROUP_CIRCLES circles: every distinct participant
  // when they fit, otherwise one fewer Avatar plus an ellipsis overflow circle.
  const distinctParticipants = takeDistinctParticipants(
    participants,
    isGrouped ? Number.POSITIVE_INFINITY : 1,
  );
  const hasOverflow =
    isGrouped && distinctParticipants.length > MAX_GROUP_CIRCLES;
  const visibleParticipants = hasOverflow
    ? distinctParticipants.slice(0, MAX_GROUP_CIRCLES - 1)
    : distinctParticipants;
  const overflowCount =
    distinctParticipants.length - visibleParticipants.length;

  useDevWarning(
    'CommentPin',
    '`participants` should contain at least one participant. Pass the lead participant for a single thread or every distinct participant for a group.',
    participants.length === 0,
  );
  useDevWarning(
    'CommentPin',
    '`threadCount` must be a finite positive integer. Invalid values fall back to 1.',
    !validThreadCount,
  );
  useDevWarning(
    'CommentPin',
    '`unreadCount` must be a finite non-negative integer no greater than `threadCount`. Invalid values are ignored and larger values are capped.',
    !validUnreadCount || unreadCount > resolvedThreadCount,
  );
  useDevWarning(
    'CommentPin',
    '`label` must be a non-empty accessible action name.',
    label.trim() === '',
  );

  const pressFeedback = usePressFeedback();
  const hasTooltip = !isDisabled && label.trim() !== '';
  const tooltip = useTooltip({
    placement: 'above',
    isEnabled: hasTooltip,
  });
  const mergedRef = useMergedRefs(ref, hasTooltip ? tooltip.ref : undefined);

  // Resolved discussion leaves the content. A selected pin stays, so a thread
  // the reader opened (or resolved from its popover) keeps its anchor until
  // the host clears the selection.
  if (isResolved && !isSelected) {
    return null;
  }

  const avatarParticipants =
    visibleParticipants.length > 0
      ? visibleParticipants
      : [{id: '__anonymous__', name: '', avatarSrc: undefined}];

  const marker = (
    <button
      {...rest}
      {...pressFeedback}
      ref={mergedRef}
      type="button"
      aria-label={label}
      aria-pressed={isSelected}
      // A disabled pin keeps its tab stop and is announced as disabled through
      // aria-disabled instead of the native attribute (spec:AST-085 FR1). The
      // activation guards below keep it inert (FR2); focus is kept when the
      // pin becomes disabled while focused (FR4), and the shared focus outline
      // still paints, dimmed with the rest of the pin (FR6).
      aria-disabled={isDisabled ? 'true' : undefined}
      onClick={e => {
        if (isDisabled) {
          // A natively disabled element dispatched no click at all, so an
          // aria-disabled pin must not reach the caller's handler, and the
          // click must not leak to a clickable ancestor (annotation surface)
          // the native attribute never let it reach either (FR2).
          e.preventDefault();
          e.stopPropagation();
          return;
        }
        rest.onClick?.(e);
      }}
      // The keyboard paths to activation are Enter and Space; other keys still
      // reach caller handlers, as on an enabled pin (FR2).
      onKeyDown={e => {
        if (isDisabled && (e.key === 'Enter' || e.key === ' ')) {
          e.preventDefault();
          e.stopPropagation();
          return;
        }
        rest.onKeyDown?.(e);
      }}
      {...mergeProps(
        themeProps('comment-pin', {
          size: resolvedSize,
          grouped: isGrouped ? 'grouped' : null,
          unread: hasUnread ? 'unread' : null,
          selected: isSelected ? 'selected' : null,
          dimmed: isDimmed ? 'dimmed' : null,
          resolved: isResolved ? 'resolved' : null,
          disabled: isDisabled ? 'disabled' : null,
        }),
        focusOutlineProps.focusVisible(
          styles.root,
          sizeStyles[resolvedSize],
          interactionOverlayStyles.backgroundImage,
          (isGrouped || hasUnread) && styles.withCount,
          isDimmed && !isSelected && styles.dimmed,
          isSelected && styles.selected,
          isDisabled && styles.disabled,
          isDisabled && !isSelected && styles.disabledUnselected,
          xstyle,
        ),
        className,
        style,
      )}>
      <span
        aria-hidden="true"
        {...stylex.props(styles.avatarRail, isGrouped && styles.groupedRail)}>
        {isGrouped ? (
          <AvatarGroup size={avatarSize}>
            {avatarParticipants.map(participant => (
              <Avatar
                key={participant.id}
                name={participant.name}
                src={participant.avatarSrc}
                tooltip={false}
              />
            ))}
            {overflowCount > 0 ? (
              <AvatarGroupOverflow
                count={overflowCount}
                xstyle={styles.overflowCircle}>
                <Icon
                  icon="moreHorizontal"
                  size={OVERFLOW_ICON_SIZE[resolvedSize]}
                />
              </AvatarGroupOverflow>
            ) : null}
          </AvatarGroup>
        ) : (
          avatarParticipants.map(participant => (
            <Avatar
              key={participant.id}
              name={participant.name}
              src={participant.avatarSrc}
              size={avatarSize}
              tooltip={false}
            />
          ))
        )}
      </span>
      {hasUnread || isGrouped ? (
        <span aria-hidden="true" {...stylex.props(styles.trailing)}>
          {isGrouped ? (
            <span {...stylex.props(styles.count)}>{resolvedThreadCount}</span>
          ) : null}
          {hasUnread ? (
            // Decorative: the button's label carries the unread context.
            <StatusDot variant="accent" label="" xstyle={styles.unreadDot} />
          ) : null}
        </span>
      ) : null}
    </button>
  );

  return (
    <>
      {marker}
      {hasTooltip ? tooltip.renderTooltip(label) : null}
    </>
  );
}

CommentPin.displayName = 'CommentPin';