Skip to content

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

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

'use client';

/**
 * @file TourStep.tsx
 * @input Uses React, Popover/Button/Text/Heading/Stack from @astryxdesign/core, TourContext
 * @output Exports TourStep component and TourStepProps
 * @position Lab experiment (meta/astryx#4239); a single spotlight step in a Tour
 *
 * A TourStep highlights a target element and renders a callout anchored to it,
 * with a heading, body, optional step progress ("2 of 5"), and back / next /
 * close controls. It registers with the parent `<Tour>` on mount (so step
 * order follows the children) and only renders its callout while it is the
 * active step. Anchoring + the callout surface reuse the core `Popover`
 * (`anchorRef` → the step's target), so positioning, top-layer rendering, and
 * dismiss semantics come from the existing layer system rather than a bespoke
 * implementation.
 *
 * The highlight is drawn as a separate overlay tracking the target's box — the
 * consumer's element is never restyled, so there is no cascade fight with the
 * target's own styles. That overlay is promoted into the browser TOP LAYER
 * (via the popover API, like the rest of the layer system) so it sits above
 * page content without any hardcoded z-index; the callout is promoted after
 * it, so the callout stays above the highlight. Because it is promoted in
 * place (not portaled out of the tree), it stays inside the consumer's Theme
 * subtree and inherits theme tokens — including a scoped/nested theme's accent
 * for the ring. Dimming is an opt-in spotlight cutout (dims around the target,
 * not over it) rather than a flat scrim.
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/lab/src/Tour/Tour.tsx
 * - /packages/lab/src/Tour/TourContext.ts
 * - /packages/lab/src/Tour/Tour.doc.mjs (props table, features)
 * - /packages/lab/src/Tour/Tour.test.tsx (tests for new/changed behavior)
 * - /packages/lab/src/Tour/index.ts (exports if types change)
 */

import {
  useContext,
  useEffect,
  useId,
  useLayoutEffect,
  useRef,
  useState,
  type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {Popover} from '@astryxdesign/core/Popover';
import type {LayerAlignment, LayerPlacement} from '@astryxdesign/core/Layer';
import {Button} from '@astryxdesign/core/Button';
import {Text} from '@astryxdesign/core/Text';
import {Heading} from '@astryxdesign/core/Heading';
import {VStack, HStack} from '@astryxdesign/core/Layout';
import {
  colorVars,
  spacingVars,
  durationVars,
  easeVars,
} from '@astryxdesign/core/theme/tokens.stylex';
import {TourContext} from './TourContext';

// Client-only layout effect (SSR renders no overlay, so this only runs on the
// client). Kept local since core does not export its isomorphic variant.
const useClientLayoutEffect =
  typeof window !== 'undefined' ? useLayoutEffect : useEffect;

// Gap between the target's edge and the highlight ring, in px.
const HIGHLIGHT_PADDING = 4;

interface TargetRect {
  top: number;
  left: number;
  width: number;
  height: number;
  radius: string;
}

const styles = stylex.create({
  content: {
    display: 'flex',
    flexDirection: 'column',
    gap: spacingVars['--spacing-3'],
    // Keep the callout from growing arbitrarily wide with long body copy.
    maxWidth: '320px',
  },
  footer: {
    alignItems: 'center',
    justifyContent: 'space-between',
  },
  // Extra clearance between the target and the callout, so the highlight ring
  // (which extends a few px past the target) is never covered by the callout.
  // Placement-aware: the margin goes on the side of the callout that faces the
  // target. Adds to Popover's own small anchor gap.
  calloutGapBelow: {marginBlockStart: spacingVars['--spacing-2']},
  calloutGapAbove: {marginBlockEnd: spacingVars['--spacing-2']},
  calloutGapStart: {marginInlineEnd: spacingVars['--spacing-2']},
  calloutGapEnd: {marginInlineStart: spacingVars['--spacing-2']},
  // Full-viewport overlay root, promoted into the browser top layer so it sits
  // above all page content with NO z-index. UA popover styles are neutralized
  // so it fills the viewport. Click-through by default (coachmark); interactive
  // only when it dims (to catch backdrop clicks).
  overlayRoot: {
    position: 'fixed',
    inset: 0,
    margin: 0,
    padding: 0,
    borderWidth: 0,
    borderStyle: 'none',
    backgroundColor: 'transparent',
    overflow: 'visible',
    pointerEvents: 'none',
  },
  overlayInteractive: {
    pointerEvents: 'auto',
  },
  // The highlight box, sized to the target. Non-interactive so clicks reach the
  // target (coachmark) or the overlay root (dimmed). The accent ring with a
  // surface-colored gap mirrors the focus-visible outline used across the
  // system.
  highlight: {
    position: 'absolute',
    pointerEvents: 'none',
    boxShadow: `0 0 0 2px ${colorVars['--color-background-surface']}, 0 0 0 4px ${colorVars['--color-accent']}`,
    transitionProperty: 'top, left, width, height',
    transitionDuration: durationVars['--duration-fast'],
    transitionTimingFunction: easeVars['--ease-standard'],
  },
  // Spotlight cutout: a huge box-shadow spread dims the whole viewport EXCEPT
  // this box, so the target reads as lit rather than covered. Layered after the
  // ring so both shadows show. Only applied when the step opts into a backdrop.
  cutout: {
    boxShadow: `0 0 0 2px ${colorVars['--color-background-surface']}, 0 0 0 4px ${colorVars['--color-accent']}, 0 0 0 9999px ${colorVars['--color-overlay']}`,
  },
  hidden: {
    opacity: 0,
  },
});

const calloutGapStyles = {
  below: styles.calloutGapBelow,
  above: styles.calloutGapAbove,
  start: styles.calloutGapStart,
  end: styles.calloutGapEnd,
} as const;

/**
 * The highlight overlay: a top-layer box sized to the target, plus an optional
 * spotlight-cutout dim. Rendered inline (not portaled) so it stays inside the
 * consumer's Theme subtree and inherits theme tokens — the popover API promotes
 * it into the top layer in place. Rendered before the callout so the callout
 * promotes on top of it; promoted once (never re-promoted) so that ordering
 * holds across re-measures.
 */
function TourHighlight({
  rect,
  hasBackdrop,
  onBackdropClick,
}: {
  rect: TargetRect | null;
  hasBackdrop: boolean;
  onBackdropClick: () => void;
}) {
  const ref = useRef<HTMLDivElement>(null);

  useClientLayoutEffect(() => {
    const el = ref.current;
    if (el == null || typeof el.showPopover !== 'function') {
      return;
    }
    el.showPopover();
    return () => {
      if (el.isConnected && typeof el.hidePopover === 'function') {
        el.hidePopover();
      }
    };
  }, []);

  return (
    <div
      ref={ref}
      popover="manual"
      data-testid={hasBackdrop ? 'tour-backdrop' : undefined}
      aria-hidden="true"
      onClick={hasBackdrop ? onBackdropClick : undefined}
      {...stylex.props(
        styles.overlayRoot,
        hasBackdrop && styles.overlayInteractive,
      )}>
      <div
        data-testid="tour-highlight"
        {...stylex.props(
          styles.highlight,
          hasBackdrop && styles.cutout,
          rect == null && styles.hidden,
        )}
        style={
          rect != null
            ? {
                top: rect.top - HIGHLIGHT_PADDING,
                left: rect.left - HIGHLIGHT_PADDING,
                width: rect.width + HIGHLIGHT_PADDING * 2,
                height: rect.height + HIGHLIGHT_PADDING * 2,
                borderRadius: rect.radius,
              }
            : undefined
        }
      />
    </div>
  );
}

export interface TourStepProps {
  /**
   * Ref to the element this step points at. The callout anchors to it (like a
   * Popover trigger); it must be a `<button>` or `[role="button"]` element,
   * matching Popover's `anchorRef` contract. Accepts a ref to any HTMLElement
   * subtype (e.g. `useRef<HTMLButtonElement>(null)`).
   */
  targetRef: React.RefObject<HTMLElement | null>;
  /** Step heading. */
  heading: ReactNode;
  /** Step body content. */
  children?: ReactNode;
  /**
   * Which side of the target the callout sits on.
   * @default 'below'
   */
  placement?: LayerPlacement;
  /**
   * How the callout aligns along the placement side — e.g. with `placement="below"`,
   * `start` left-aligns it under the target, `center` centers it, `end` right-aligns it.
   * @default 'start'
   */
  alignment?: LayerAlignment;
  /** Test id applied to the callout content. */
  'data-testid'?: string;
}

/**
 * A single spotlight step within a `<Tour>`. Renders its callout only while
 * active.
 *
 * @example
 * ```
 * <TourStep targetRef={saveRef} heading="Save your work">
 *   Changes save automatically.
 * </TourStep>
 * ```
 */
export function TourStep({
  targetRef,
  heading,
  children,
  placement = 'below',
  alignment = 'start',
  'data-testid': testId,
}: TourStepProps) {
  const tour = useContext(TourContext);
  const id = useId();
  const isActiveStep = tour != null && tour.activeStepId === id;

  // The active target's viewport box, tracked so the highlight overlay can sit
  // exactly over it. null until measured (or when inactive).
  const [rect, setRect] = useState<TargetRect | null>(null);

  // Register with the controller on mount so the tour learns this step (and
  // its position among siblings). Unregister on unmount.
  useEffect(() => {
    if (tour == null) {
      return;
    }
    return tour.registerStep(id);
  }, [tour, id]);

  // Track the target's box while this step is active. Re-measure on
  // scroll/resize so the highlight stays glued to the target.
  useEffect(() => {
    const el = targetRef.current;
    if (el == null || !isActiveStep) {
      setRect(null);
      return;
    }
    const measure = () => {
      const box = el.getBoundingClientRect();
      setRect({
        top: box.top,
        left: box.left,
        width: box.width,
        height: box.height,
        radius: getComputedStyle(el).borderRadius || '0px',
      });
    };
    measure();
    window.addEventListener('scroll', measure, true);
    window.addEventListener('resize', measure);
    return () => {
      window.removeEventListener('scroll', measure, true);
      window.removeEventListener('resize', measure);
      setRect(null);
    };
  }, [targetRef, isActiveStep]);

  // Outside a <Tour>, or when this isn't the active step, render nothing.
  if (tour == null || !isActiveStep) {
    return null;
  }

  const {
    activeStepIndex,
    stepCount,
    isStepCountShown,
    hasBackdrop,
    onNext,
    onPrevious,
    onDismiss,
  } = tour;

  const isFirstStep = activeStepIndex <= 0;
  const isLastStep = stepCount > 0 && activeStepIndex === stepCount - 1;

  const content = (
    <div {...stylex.props(styles.content)} data-testid={testId}>
      <VStack gap={1}>
        <Heading level={4}>{heading}</Heading>
        {children != null && <Text type="body">{children}</Text>}
      </VStack>
      <HStack gap={2} xstyle={styles.footer}>
        {isStepCountShown && stepCount > 0 ? (
          <Text type="supporting" color="secondary">
            {`${activeStepIndex + 1} of ${stepCount}`}
          </Text>
        ) : (
          <span />
        )}
        <HStack gap={2}>
          {!isFirstStep && (
            <Button
              variant="ghost"
              size="sm"
              label="Back"
              onClick={onPrevious}
            />
          )}
          <Button
            variant="primary"
            size="sm"
            label={isLastStep ? 'Done' : 'Next'}
            onClick={onNext}
          />
        </HStack>
      </HStack>
    </div>
  );

  return (
    <>
      {/* Rendered before the callout so the callout promotes above it in the
          top layer (callout > highlight > page). */}
      <TourHighlight
        rect={rect}
        hasBackdrop={hasBackdrop}
        onBackdropClick={() => onDismiss('backdrop')}
      />
      <Popover
        // Popover types anchorRef as RefObject<HTMLElement>; TourStep accepts a
        // nullable ref for ergonomics (useRef<HTMLButtonElement>(null)). Popover
        // guards a null `.current` internally, so this widening is safe.
        anchorRef={targetRef as React.RefObject<HTMLElement>}
        isOpen
        onOpenChange={open => {
          // Popover reports close from light-dismiss (backdrop) or Escape.
          // Route it to the tour as a dismissal so the whole tour ends, not
          // just this step's popover. Escape and outside-click both surface
          // here.
          if (!open) {
            onDismiss('close');
          }
        }}
        placement={placement}
        alignment={alignment}
        // Size the callout to its content instead of matching the target's
        // width (Popover's default minWidth: anchor-size(width) makes it span a
        // wide target); the content's own maxWidth caps it.
        width="fit-content"
        // Push the callout clear of the highlight ring so the ring is never
        // covered (placement-aware; adds to Popover's own anchor gap).
        xstyle={calloutGapStyles[placement]}
        label={typeof heading === 'string' ? heading : 'Tour step'}
        hasCloseButton
        closeButtonLabel="Close tour"
        content={content}
      />
    </>
  );
}

TourStep.displayName = 'TourStep';