Skip to content

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

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

'use client';

/**
 * @file Outline.tsx
 * @input Uses React, StyleX, Astryx link provider integration, Outline hooks/types
 * @output Exports Outline component and OutlineProps type
 * @position Core implementation; consumed by index.ts
 *
 * A table-of-contents navigation component with:
 * - Sliding indicator track (vertical divider + animated active bar)
 * - Density variant (default/compact)
 * - Scroll-spy active state when uncontrolled
 * - Each link in the normal Tab order (Enter/Space activate)
 * - onNavigateStart / onNavigateEnd callbacks around the smooth scroll
 * - Scroll scoping (offset, scrollContainerRef, hasScrollOnClick)
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/Outline/Outline.doc.mjs
 * - /packages/core/src/Outline/index.ts
 * - /apps/storybook/stories/Outline.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/Outline/ (showcase blocks)
 */

import {useRef} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
  colorVars,
  durationVars,
  easeVars,
  radiusVars,
  spacingVars,
  typeScaleVars,
  fontWeightVars,
} from '../theme/tokens.stylex';
import {useLinkComponent} from '../Link/useLinkComponent';
import {mergeProps} from '../utils';
import type {BaseProps} from '../BaseProps';
import {useScrollSpy} from './useScrollSpy';
import type {OutlineItem} from './types';
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 {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Outline/Outline.generated';

registerEnglishFallback(english);
export type {OutlineItem} from './types';

export interface OutlineProps extends BaseProps<HTMLElement> {
  /** Ref forwarded to the root nav element. */
  ref?: React.Ref<HTMLElement>;

  /** Ordered list of heading items to render. */
  items: OutlineItem[];

  /** ID of the currently active item. When provided, disables built-in scroll-spy. */
  activeId?: string;

  /** Called when the active item changes from scroll-spy or click. */
  onActiveIdChange?: (id: string) => void;

  /** Accessible label for the nav landmark. @default 'Table of contents' */
  label?: string;

  /**
   * Density variant controlling item padding.
   * - 'default': Standard spacing (default)
   * - 'compact': Reduced spacing for dense UIs
   * @default 'default'
   */
  density?: 'default' | 'compact';

  /**
   * Called when navigation to an item begins, before the scroll starts.
   * Receives the item `id`. Pair with `onNavigateEnd` to drive an arrival
   * effect (flash, ring, pulse) on the target heading.
   */
  onNavigateStart?: (id: string) => void;

  /**
   * Called once when navigation to an item resolves — when the smooth scroll
   * settles, or immediately-ish when reduced motion turns it into a jump.
   *
   * Fires exactly once for every `onNavigateStart`, including when the user
   * interrupts the scroll by scrolling manually, so a "navigating" state can
   * never leak. It does not fire if the Outline unmounts mid-scroll.
   */
  onNavigateEnd?: (id: string) => void;

  /**
   * Height in px of a fixed header overlaying the top of the scroll root.
   *
   * Shifts both the activation line *and* the scroll landing by the same
   * amount, so a heading activates exactly where navigating to it puts it —
   * below the header rather than hidden underneath it.
   *
   * It composes with each heading's own `scroll-margin-top` (the header, then
   * the breathing room below it) rather than replacing it. When nothing
   * overlays the content, leave this at 0 and let `scroll-margin-top` do the
   * work — the browser already honors it.
   *
   * @default 0
   */
  offset?: number;

  /**
   * Scroll container to track, instead of auto-detecting the nearest scrollable
   * ancestor. Use this when the content scrolls inside a split pane, modal, or
   * dashboard panel rather than the viewport.
   */
  scrollContainerRef?: React.RefObject<HTMLElement | null>;

  /**
   * Whether activating an item smooth-scrolls to it. Set to false to own the
   * scrolling yourself (virtualized content, a router) — the Outline still
   * updates the active item, the hash, and the navigate callbacks, but performs
   * no scroll and suppresses the anchor's default jump.
   * @default true
   */
  hasScrollOnClick?: boolean;

  /** Test ID for testing frameworks. */
  'data-testid'?: string;
}

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

const styles = stylex.create({
  root: {
    display: 'flex',
    flexDirection: 'row',
    position: 'relative',
    gap: spacingVars['--spacing-0-5'],
    width: '100%',
  },
  track: {
    position: 'relative',
    width: '2px',
    flexShrink: 0,
    order: -1,
  },
  dividerLine: {
    position: 'absolute',
    insetBlockStart: 0,
    insetBlockEnd: 0,
    insetInlineStart: 0,
    width: '2px',
    backgroundColor: colorVars['--color-border'],
    borderRadius: radiusVars['--radius-full'],
    pointerEvents: 'none',
  },
  indicator: {
    position: 'absolute',
    insetInlineStart: 0,
    width: '2px',
    backgroundColor: colorVars['--color-icon-primary'],
    borderRadius: radiusVars['--radius-full'],
    pointerEvents: 'none',
    zIndex: 1,
    positionAnchor: '--outline-active',
    top: 'anchor(--outline-active top, 0px)',
    height: 'anchor-size(--outline-active height, 0px)',
    transitionProperty: 'top, height',
    transitionDuration: durationVars['--duration-fast-min'],
    transitionTimingFunction: easeVars['--ease-standard'],
  },
  activeAnchor: {
    anchorName: '--outline-active',
  },
  list: {
    display: 'flex',
    flexDirection: 'column',
    gap: spacingVars['--spacing-0-5'],
    margin: 0,
    padding: 0,
    listStyle: 'none',
    flex: 1,
    minWidth: 0,
  },
  item: {
    listStyleType: 'none',
    margin: 0,
    padding: 0,
  },
  link: {
    alignItems: 'center',
    borderRadius: radiusVars['--radius-element'],
    boxSizing: 'border-box',
    color: colorVars['--color-text-secondary'],
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    display: 'flex',
    fontWeight: fontWeightVars['--font-weight-normal'],
    position: 'relative',
    textAlign: 'start',
    textDecoration: 'none',
    transitionDuration: durationVars['--duration-fast'],
    transitionProperty: 'background-color, color',
    transitionTimingFunction: easeVars['--ease-standard'],
    width: '100%',
    fontSize: typeScaleVars['--text-body-size'],
    lineHeight: typeScaleVars['--text-body-leading'],
    ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
      '@media (hover: hover)': {
        color: colorVars['--color-text-primary'],
      },
    },
  },
  activeLink: {
    color: colorVars['--color-text-primary'],
    fontWeight: fontWeightVars['--font-weight-semibold'],
  },
  label: {
    overflow: 'hidden',
    textOverflow: 'ellipsis',
    whiteSpace: 'nowrap',
  },
});

const densityStyles = stylex.create({
  compact: {
    paddingBlock: spacingVars['--spacing-1'],
    paddingInlineEnd: spacingVars['--spacing-2'],
  },
  default: {
    paddingBlock: spacingVars['--spacing-2'],
    paddingInlineEnd: spacingVars['--spacing-2'],
  },
});

const indentStyles = stylex.create({
  level1: {paddingInlineStart: spacingVars['--spacing-3']},
  level2: {paddingInlineStart: spacingVars['--spacing-7']},
  level3: {paddingInlineStart: spacingVars['--spacing-11']},
  level4: {paddingInlineStart: spacingVars['--spacing-12']},
});

function getIndentStyle(level: number) {
  // Map heading levels 1-6 to visual indent levels 1-4
  // Level 1 (h1) = indent 1, Level 2 (h2) = indent 1, Level 3 (h3) = indent 2, etc.
  const indentLevel = Math.max(1, Math.min(4, level - 1 || 1));
  switch (indentLevel) {
    case 1:
      return indentStyles.level1;
    case 2:
      return indentStyles.level2;
    case 3:
      return indentStyles.level3;
    default:
      return indentStyles.level4;
  }
}

/**
 * A followed in-page link moves the sequential focus starting point to its
 * target, so the next Tab continues inside that section. Outline cancels the
 * link's default to scroll itself, so it restores that by focusing the target
 * without scrolling (WCAG 2.4.3). A target that is not focusable becomes
 * programmatically focusable only.
 */
function moveFocusTo(id: string) {
  const target = document.getElementById(id);
  if (target == null) {
    return;
  }
  // A target that already takes focus (a link, a button) keeps its place in
  // the Tab order; only one that refuses focus is made focusable by script.
  target.focus({preventScroll: true});
  // A caller's own tabindex is never overwritten.
  if (document.activeElement !== target && !target.hasAttribute('tabindex')) {
    target.setAttribute('tabindex', '-1');
    target.focus({preventScroll: true});
  }
}

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

/**
 * A table-of-contents navigation component for document headings.
 *
 * Outline accepts a flat `items` array and renders anchor links with
 * indentation based on each heading level. Features a sliding indicator
 * track that animates to the active item.
 *
 * When `activeId` is omitted, it tracks scroll position and marks the last
 * heading whose top has passed its activation line — which is exactly where
 * navigating to that heading lands it: `offset` (a fixed header overlaying the
 * scroll root) plus the heading's own `scroll-margin-top`. It defaults to the
 * first item at the top and the last at the bottom.
 *
 * Keyboard: each link is in the normal Tab order, and Enter/Space activate.
 * There is no arrow, Home, or End movement between links.
 *
 * @example
 * ```
 * <Outline
 *   items={[
 *     {id: 'intro', label: 'Introduction', level: 1},
 *     {id: 'features', label: 'Features', level: 2},
 *     {id: 'api', label: 'API Reference', level: 1},
 *   ]}
 * />
 * ```
 *
 * Scoped to a custom scroll container, under a fixed header:
 *
 * @example
 * ```
 * const scrollContainerRef = useRef<HTMLDivElement>(null);
 * <div ref={scrollContainerRef} style={{overflowY: 'auto'}}>...</div>
 * <Outline
 *   items={items}
 *   scrollContainerRef={scrollContainerRef}
 *   offset={64}
 *   onNavigateEnd={id => flashHeading(id)}
 * />
 * ```
 */
export function Outline({
  items,
  activeId,
  onActiveIdChange,
  label: labelFromProps,
  density = 'default',
  onNavigateStart,
  onNavigateEnd,
  offset = 0,
  scrollContainerRef,
  hasScrollOnClick = true,
  xstyle,
  className,
  style,
  ref,
  'data-testid': testId,
  ...props
}: OutlineProps) {
  const pressable = usePressFeedback();
  const t = useComponentTranslator();
  const label = labelFromProps ?? t('@astryx.outline.label');
  const rootRef = useRef<HTMLElement | null>(null);
  const LinkComponent = useLinkComponent();
  const {activeId: resolvedActiveId, scrollTo} = useScrollSpy({
    activeId,
    items,
    onActiveIdChange,
    rootRef,
    offset,
    scrollContainerRef,
    hasScrollOnClick,
    onNavigateStart,
    onNavigateEnd,
  });

  /**
   * The single navigation path, shared by click and keyboard activation:
   * push the hash, then hand off to the scroll-spy's `scrollTo`, which fires
   * the navigate callbacks and moves the indicator when the scroll settles.
   */
  const navigate = (id: string) => {
    if (scrollTo(id)) {
      window.history.pushState(null, '', `#${id}`);
      moveFocusTo(id);
    }
  };

  /** Whether an event carries a modifier chord we must leave to the browser. */
  const hasModifier = (
    event: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>,
  ) => event.metaKey || event.altKey || event.ctrlKey || event.shiftKey;

  const handleClick =
    (id: string) => (event: React.MouseEvent<HTMLElement>) => {
      // Let the browser handle modified clicks (open in new tab, etc.) without
      // touching the active state.
      if (event.defaultPrevented || hasModifier(event)) {
        return;
      }

      // With no target in the DOM — lazily-rendered or virtualized content —
      // there is nothing to scroll to and nothing to make active. Leave the
      // anchor to the browser's native fragment navigation (which still
      // updates the URL) rather than swallowing the click into a dead link.
      if (document.getElementById(id) == null) {
        return;
      }

      // Suppress the anchor's default jump: we own the scroll (or, with
      // `hasScrollOnClick={false}`, deliberately leave it to the consumer).
      event.preventDefault();
      navigate(id);
    };

  const handleKeyDown =
    (id: string) => (event: React.KeyboardEvent<HTMLElement>) => {
      // Enter is a link's native activation and already produces a click.
      // Space is not, so wire it up here to match the button-like affordance.
      if (event.key !== ' ' && event.key !== 'Spacebar') {
        return;
      }
      if (event.defaultPrevented || hasModifier(event)) {
        return;
      }

      // preventDefault does double duty: it stops the page from scrolling, and
      // it tells useScrollSpy this Space is an activation, not a manual scroll.
      event.preventDefault();
      navigate(id);
    };

  return (
    <nav
      {...props}
      ref={useMergedRefs(rootRef, ref)}
      aria-label={label}
      data-testid={testId}
      {...mergeProps(
        themeProps('outline', {density}),
        stylex.props(styles.root, xstyle),
        className,
        style,
      )}>
      <ul {...stylex.props(styles.list)} role="list">
        {items.map(item => {
          const isActive = item.id === resolvedActiveId;

          return (
            <li key={item.id} {...stylex.props(styles.item)} role="listitem">
              <LinkComponent
                href={`#${item.id}`}
                aria-current={isActive ? 'location' : undefined}
                onClick={handleClick(item.id)}
                onKeyDown={handleKeyDown(item.id)}
                {...pressable}
                {...mergeProps(
                  themeProps('outline-item', {
                    active: isActive ? 'active' : null,
                    level: item.level,
                  }),
                  focusOutlineProps.focusVisible(
                    styles.link,
                    interactionOverlayStyles.backgroundColor,
                    densityStyles[density],
                    getIndentStyle(item.level),
                    isActive && styles.activeLink,
                    isActive && styles.activeAnchor,
                  ),
                )}>
                <span {...stylex.props(styles.label)}>{item.label}</span>
              </LinkComponent>
            </li>
          );
        })}
      </ul>

      {/* Track divider. Rendered after the list so the active anchor appears
          earlier in DOM order; `order: -1` keeps the track visually before it. */}
      <div {...stylex.props(styles.track)} aria-hidden="true">
        <span {...stylex.props(styles.dividerLine)} />
      </div>
      <span
        {...mergeProps(
          themeProps('outline-indicator'),
          stylex.props(styles.indicator),
        )}
        aria-hidden="true"
      />
    </nav>
  );
}

Outline.displayName = 'Outline';