Skip to content

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

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

'use client';

/**
 * @file InfoTip.tsx
 * @input Uses React, StyleX, useTooltip, Icon, useComponentTranslator, the
 *   shared touch hit area, color/spacing/radius/duration/ease tokens
 * @output Exports InfoTip component, InfoTipProps, InfoTipSize types
 * @position Core implementation; consumed by index.ts, tested by
 *   InfoTip.test.tsx; `@astryxdesign/lab` re-exports it, deprecated
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/InfoTip/InfoTip.doc.mjs (props table, features)
 * - /docs/specs/components/InfoTip/InfoTip.spec.md (contract)
 * - /packages/core/src/InfoTip/InfoTip.test.tsx (tests for new/changed behavior)
 * - /packages/core/src/InfoTip/index.ts (exports if types change)
 * - /packages/cli/assets/templates/blocks/components/InfoTip/ (showcase and example blocks)
 */

import {
  useCallback,
  useState,
  type MouseEvent,
  type PointerEvent,
  type ReactNode,
  type Ref,
} from 'react';
import * as stylex from '@stylexjs/stylex';

import type {BaseProps} from '../BaseProps';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {Icon, type IconSize} from '../Icon/Icon';
import {stopInReactTree} from '../Layer/layerClickBoundary';
import {useTooltip} from '../Tooltip/useTooltip';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/InfoTip/InfoTip.generated';
import {
  colorVars,
  durationVars,
  easeVars,
  radiusVars,
  spacingVars,
} from '../theme/tokens.stylex';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import {mergeProps} from '../utils/mergeProps';
import {useTouchHitArea} from '../utils/touchHitArea';
import {touchHitAreaStyles} from '../internal/touchHitArea.stylex';

registerEnglishFallback(english);

/**
 * Size of the info icon. Maps 1:1 to Icon sizes
 * (xsm: 12px, sm: 16px, md: 20px, lg: 24px).
 */
export type InfoTipSize = IconSize;

export interface InfoTipProps extends Pick<
  BaseProps,
  'xstyle' | 'className' | 'style'
> {
  /** Ref forwarded to the info button. */
  ref?: Ref<HTMLButtonElement>;
  /**
   * The help the button reveals. Short, noninteractive text; for links or
   * buttons, use HoverCard.
   */
  content: ReactNode;
  /**
   * Accessible name of the button.
   * @default A translated "More information"
   */
  label?: string;
  /**
   * Size of the info icon.
   * @default 'sm'
   */
  size?: InfoTipSize;
}

const styles = stylex.create({
  trigger: {
    position: 'relative',
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    verticalAlign: 'middle',
    padding: spacingVars['--spacing-0-5'],
    margin: 0,
    borderStyle: 'none',
    backgroundColor: 'transparent',
    borderRadius: radiusVars['--radius-full'],
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    color: {
      default: colorVars['--color-icon-secondary'],
      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
        default: null,
        '@media (hover: hover)': colorVars['--color-icon-primary'],
      },
    },
    transitionProperty: 'color',
    transitionDuration: durationVars['--duration-fast'],
    transitionTimingFunction: easeVars['--ease-standard'],
  },
});

/**
 * An info icon that reveals help: a small "i" button. Hover and keyboard
 * focus preview the help. A click, tap, Enter, or Space pins it open until
 * Escape, a second press, a press outside, or focus leaving. Use it next to
 * labels, values, and metrics for permission notes, metric definitions, and
 * field help.
 *
 * InfoTip is a named button that toggles `useTooltip`'s `show()` and `hide()`:
 * the hook previews, holds, announces, and closes the help. The info icon
 * resolves from the icon registry, so themes can replace it.
 *
 * @example
 * ```
 * <InfoTip content="Editors can change this field; viewers cannot." />
 * <InfoTip content="30-day rolling average." label="About this metric" />
 * ```
 */
export function InfoTip({
  content,
  label,
  size = 'sm',
  ref,
  xstyle,
  className,
  style,
}: InfoTipProps): ReactNode {
  const t = useComponentTranslator();
  const hitAreaRef = useTouchHitArea(true);
  // Whether a press pinned the help. A hover or focus preview is not pinned.
  const [isPinned, setIsPinned] = useState(false);
  // Whether the help shows, pinned or previewed: the button names it in
  // `aria-controls` only then.
  const [isShown, setIsShown] = useState(false);
  const handleShow = useCallback(() => setIsShown(true), []);
  // Every close ends the pin: a second press, Escape, a press outside, or
  // focus leaving.
  const handleHide = useCallback(() => {
    setIsShown(false);
    setIsPinned(false);
  }, []);
  const tooltip = useTooltip({onShow: handleShow, onHide: handleHide});
  const mergedRef = useMergedRefs(ref, hitAreaRef, tooltip.ref);

  // A primary mouse or pen press on a preview calls show() first. The hook's
  // press-to-close then leaves it open. The click pins it.
  const handlePointerDownCapture = useCallback(
    (event: PointerEvent<HTMLButtonElement>) => {
      if (
        event.button !== 0 ||
        event.pointerType === 'touch' ||
        isPinned ||
        !isShown
      ) {
        return;
      }
      tooltip.show();
    },
    [isPinned, isShown, tooltip],
  );

  // A click, tap, Enter, or Space pins the help, and the next one closes it.
  // The press stops at the button: a clickable row, card, or label around it
  // does nothing, and document listeners still see it.
  const handleClick = useCallback(
    (event: MouseEvent<HTMLButtonElement>) => {
      stopInReactTree(event);
      event.preventDefault();
      if (isPinned) {
        tooltip.hide();
        return;
      }
      tooltip.show();
      setIsPinned(true);
    },
    [isPinned, tooltip],
  );

  // No Escape handler of its own. The tooltip's entry in the shared dismissal
  // stack takes Escape, so one press never closes both the help and an
  // enclosing Dialog.
  return (
    <>
      <button
        ref={mergedRef}
        type="button"
        aria-label={label ?? t('@astryx.infoTip.label')}
        aria-describedby={tooltip.describedBy}
        aria-expanded={isPinned}
        aria-controls={isShown ? tooltip.describedBy : undefined}
        onPointerDownCapture={handlePointerDownCapture}
        onClick={handleClick}
        {...mergeProps(
          stylex.props(
            focusOutlineStyles.focusVisible,
            styles.trigger,
            touchHitAreaStyles.layer,
            xstyle,
          ),
          className,
          style,
        )}>
        <Icon icon="info" size={size} />
      </button>
      {tooltip.renderTooltip(content)}
    </>
  );
}

InfoTip.displayName = 'InfoTip';