Skip to content

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

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

'use client';

/**
 * @file NavigationStack.tsx
 * @input React and StyleX. Core's compositor animator and UIKit tables come
 *   from Core's internal touch entry and navigationMotion.ts. The math is in
 *   navigationTransition.ts, and the back swipes in NavigationStackTouch.ts.
 *   Each screen scrolls through Core's useScrollableArea, under Lab's scroll
 *   edge effect (internal/useScrollEdgeEffect.ts).
 * @output Exports NavigationStack, a push/pop navigator with UIKit's
 *   transitions and back gestures. NavigationScreen is one screen: its bar
 *   title, back title, end content and content. useNavigationStack pushes,
 *   pops and pops to the root from inside a screen.
 * @position Lab component (packages/lab/src/NavigationStack). It is the
 *   phone presentation of drill-down navigation, UINavigationController's
 *   counterpart.
 *
 * SYNC: When modified, update NavigationStack.doc.mjs,
 * NavigationStack.test.tsx and
 * __tests__/NavigationStack.interaction.browser.spec.ts.
 */

import {
  createContext,
  useCallback,
  useContext,
  useLayoutEffect,
  useMemo,
  useRef,
  useState,
  type ReactElement,
  type ReactNode,
  type SyntheticEvent,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
  focusForLastInput,
  isCoarsePointer,
  isFocusLost,
  isRtlElement,
  resolveMotion,
  solveSpring,
  toSpring,
  useInteractionModalityTracking,
  useTouchPresentation,
  type MotionEngine,
  type SpringDescription,
} from '@astryxdesign/core/internal/touch';
import {useTranslator} from '@astryxdesign/core/i18n';
import {useScrollableArea} from '@astryxdesign/core/hooks';
import {focusOutlineStyles} from '@astryxdesign/core/utils';
import {Icon} from '@astryxdesign/core/Icon';
import {
  colorVars,
  focusVars,
  fontWeightVars,
  spacingVars,
  textSizeVars,
  typeScaleVars,
} from '@astryxdesign/core/theme/tokens.stylex';
import {
  layerVelocities,
  layersAt,
  progressFromScreen,
  programmaticVelocity,
} from './navigationTransition';
import {useBackSwipes, type BackSwipeStack} from './NavigationStackTouch';
import {bars, navigation, springs} from './navigationMotion';
import {useMotionEngine} from '../internal/useMotionEngine';
import {useScrollEdgeEffect} from '../internal/useScrollEdgeEffect';

// =============================================================================
// Types
// =============================================================================

export interface NavigationScreenProps {
  /** The screen's title, shown in the bar and read first on arrival. */
  title: string;
  /**
   * What the back button reads on the screen pushed on top of this one.
   * Defaults to this screen's `title`.
   */
  backTitle?: string;
  /** Content at the end of the bar while this screen is on top. */
  endContent?: ReactNode;
  /**
   * How the title shows: in the bar (`inline`), or `large` above the
   * content. A large title scrolls with the content, as iOS's large titles
   * do. It hands over to the bar's title once it has scrolled under the bar.
   * @default 'inline'
   */
  titleDisplayMode?: 'large' | 'inline';
  /** The screen's content; it scrolls on its own. */
  children?: ReactNode;
}

export interface NavigationStackProps<T> {
  /** The root screen: a NavigationScreen. */
  root: ReactElement<NavigationScreenProps>;
  /** The entries pushed on the root, bottom first. Controlled. */
  path: ReadonlyArray<T>;
  /** Called with the new path when a push, pop or back swipe changes it. */
  onPathChange: (path: T[]) => void;
  /** Renders an entry's screen: a NavigationScreen. */
  renderScreen: (
    entry: T,
    index: number,
  ) => ReactElement<NavigationScreenProps>;
  /**
   * A stable key per entry, so a screen keeps its state while it moves down
   * the stack. Defaults to the entry's position.
   */
  getKey?: (entry: T, index: number) => string | number;
  /** Whether the back swipe pops. @default true */
  isInteractivePopEnabled?: boolean;
  /** Accessible name of the navigator region. */
  label?: string;
  'data-testid'?: string;
}

export interface NavigationStackApi<T = unknown> {
  /**
   * Pushes an entry. The control that started it (the click or key press
   * being handled, or `options.source`) gets focus back when its screen pops.
   */
  push: (entry: T, options?: {source?: Element | null}) => void;
  /** Pops the top screen; nothing at the root. */
  pop: () => void;
  /** Pops back to the root. */
  popToRoot: () => void;
  /** How many screens are pushed on the root. */
  depth: number;
}

// =============================================================================
// Context
// =============================================================================

const NavigationStackContext = createContext<NavigationStackApi | null>(null);

/** The enclosing NavigationStack's push / pop / popToRoot. */
export function useNavigationStack<T = unknown>(): NavigationStackApi<T> {
  const api = useContext(NavigationStackContext);
  if (api == null) {
    throw new Error('useNavigationStack must be used inside a NavigationStack');
  }
  return api as NavigationStackApi<T>;
}

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

const BAR_HEIGHT = 44;

const styles = stylex.create({
  stack: {
    position: 'relative',
    width: '100%',
    height: '100%',
    overflow: 'hidden',
    backgroundColor: colorVars['--color-background-body'],
  },
  // The bar overlays the screens, which scroll under it, as UIKit's content
  // extends under its bar.
  bar: {
    position: 'absolute',
    top: 0,
    insetInline: 0,
    isolation: 'isolate',
    height: BAR_HEIGHT,
    zIndex: 1,
  },
  // The bar's own background and hairline, under every screen's bar layer,
  // which paints its own background over it. iOS 26.2's bar paints neither:
  // under a finger the content shows through until the screen's scroll edge
  // effect veils it. The literal coarse-pointer key is the resolver's touch
  // constant. A mouse keeps both.
  barBackground: {
    position: 'absolute',
    inset: 0,
    zIndex: -2,
    backgroundColor: {
      default: colorVars['--color-background-surface'],
      '@media (pointer: coarse)': 'transparent',
    },
    borderBottomWidth: {
      default: 1,
      '@media (pointer: coarse)': 0,
    },
    borderBottomStyle: 'solid',
    borderBottomColor: colorVars['--color-border'],
  },
  // Each screen's bar moves with its screen, as UIKit's per-screen bar copy
  // does. Under a mouse it has an opaque background of its own
  // (barLayerBackground), so the incoming one covers the outgoing title.
  // Under a finger the bars are clear, so barClip cuts the covered bar at the
  // top card's leading edge.
  barLayer: {
    position: 'absolute',
    inset: 0,
    // Below the back button: WebKit does not promote the static siblings a
    // moving layer crosses, so the moving one goes underneath.
    zIndex: -1,
  },
  // The box that cuts the bar, moved by the stack. The row inside it moves
  // back by as much, so only the cut moves.
  barClip: {
    position: 'absolute',
    inset: 0,
    overflow: 'hidden',
  },
  barRow: {
    position: 'absolute',
    inset: 0,
    display: 'grid',
    gridTemplateColumns: '1fr auto 1fr',
    alignItems: 'center',
    paddingInline: spacingVars['--spacing-4'],
  },
  // A layer's background, above the bar's hairline. It is clear under a
  // finger, as the bar's own background.
  barLayerBackground: {
    position: 'absolute',
    insetInline: 0,
    top: 0,
    bottom: 1,
    zIndex: -1,
    backgroundColor: {
      default: colorVars['--color-background-surface'],
      '@media (pointer: coarse)': 'transparent',
    },
  },
  // The one back button: it stays put while the bars move under it.
  backControl: {
    position: 'absolute',
    insetInlineStart: spacingVars['--spacing-4'],
    top: 0,
    bottom: 0,
    display: 'flex',
    alignItems: 'center',
  },
  barLayerCovered: {
    pointerEvents: 'none',
  },
  barStart: {
    display: 'flex',
    justifyContent: 'flex-start',
    minWidth: 0,
  },
  barTitle: {
    margin: 0,
    minWidth: 0,
    fontSize: textSizeVars['--font-size-lg'],
    fontWeight: fontWeightVars['--font-weight-semibold'],
    whiteSpace: 'nowrap',
    overflow: 'hidden',
    textOverflow: 'ellipsis',
  },
  largeTitle: {
    margin: 0,
    paddingInline: spacingVars['--spacing-4'],
    paddingTop: spacingVars['--spacing-1'],
    paddingBottom: spacingVars['--spacing-2'],
    fontSize: textSizeVars['--font-size-4xl'],
    fontWeight: fontWeightVars['--font-weight-bold'],
    lineHeight: typeScaleVars['--text-display-2-leading'],
    // The scroller clips the sides: the ring draws inside the title.
    outlineOffset: {
      default: 0,
      ':focus-visible': `calc(-1 * ${focusVars['--focus-outline-width']})`,
    },
  },
  barEnd: {
    display: 'flex',
    justifyContent: 'flex-end',
    minWidth: 0,
  },
  // iOS 26: a 44 pt circle holding only the chevron; the previous title
  // is its accessible name, not a label.
  back: {
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    width: 44,
    height: 44,
    padding: 0,
    borderRadius: '50%',
    borderWidth: 1,
    borderStyle: 'solid',
    borderColor: colorVars['--color-border'],
    backgroundColor: colorVars['--color-background-surface'],
    color: colorVars['--color-text-accent'],
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
  },
  backIcon: {
    transform: {
      default: null,
      ':is([dir="rtl"] *)': 'scaleX(-1)',
    },
  },
  cards: {
    position: 'absolute',
    inset: 0,
  },
  card: {
    position: 'absolute',
    inset: 0,
    overflow: 'hidden',
    backgroundColor: colorVars['--color-background-body'],
  },
  scroller: {
    position: 'absolute',
    inset: 0,
    boxSizing: 'border-box',
    paddingTop: BAR_HEIGHT,
    scrollPaddingTop: BAR_HEIGHT,
    // The screen scrolls vertically; a sideways drag is the back swipe's. A
    // horizontal scroller inside the content is its own scroll container
    // and keeps its native sideways scrolling.
    touchAction: 'pan-y pinch-zoom',
    // The card clips anything outside the scroller: the ring draws inside it.
    outlineOffset: {
      default: 0,
      ':focus-visible': `calc(-1 * ${focusVars['--focus-outline-width']})`,
    },
  },
  cardHidden: {
    contentVisibility: 'hidden',
  },
  // The scroll edge sentinel stays at its static position, just above the
  // content. The scroller is its containing block, so it scrolls with the
  // content with no positioned wrapper. On an inline screen it sits outside
  // the content, so the screen's first element keeps :first-child.
  edgeSentinelStatic: {
    insetBlockStart: 'auto',
    insetInlineStart: 'auto',
  },
  // On a large-title screen the sentinel follows the large title in the
  // content and ends where the title ends. So the veil comes on as the bar's
  // title takes over. iOS's veil leaves out an expanded large title. The
  // margin is the sentinel's 10px height.
  edgeSentinelAfterLargeTitle: {
    insetBlockStart: 'auto',
    insetInlineStart: 'auto',
    marginBlockStart: -10,
  },
  dim: {
    position: 'absolute',
    inset: 0,
    opacity: 0,
    pointerEvents: 'none',
  },
  // A bar's dimming ends above the bar's hairline, as its background does:
  // the covered bar would otherwise darken the hairline under it.
  barDim: {
    bottom: 1,
  },
});

// The dimming's black is the UIKit table's alpha, a runtime value StyleX
// cannot read at compile time.
const dynamicStyles = stylex.create({
  dimColor: (alpha: number) => ({
    // eslint-disable-next-line @astryx/no-raw-color -- UIKit's parallax dimming is black at the table's measured alpha in every appearance; it is not a theme colour
    backgroundColor: `rgba(0, 0, 0, ${alpha})`,
  }),
});

// =============================================================================
// Layers
// =============================================================================

/**
 * One screen's animated layers: its card and the dimming over it, and its
 * bar with the same dimming. The bar moves with the card, title and end
 * content included.
 */
interface ScreenLayers {
  card: MotionEngine;
  dim: MotionEngine;
  bar: MotionEngine;
  barDim: MotionEngine;
  /**
   * The bar's clip box and the row inside it, moved apart: the row moves by
   * the opposite of the box. Under a finger the box's edge cuts a covered
   * bar at the top card's leading edge, and the row holds still. Identity
   * everywhere else.
   */
  barClip: MotionEngine;
  barClipContent: MotionEngine;
  titleElement: HTMLElement | null;
  /** The large title above the content, for `titleDisplayMode="large"`. */
  largeTitleElement: HTMLElement | null;
  /** The bar title's text, hidden while the large title shows. */
  titleText: MotionEngine;
}

type Registry = Map<string, Partial<ScreenLayers>>;

interface ScreenModel {
  key: string;
  element: ReactElement<NavigationScreenProps>;
  /** The control that pushed this screen; focus returns to it on the pop. */
  source: Element | null;
}

function CardLayer({
  model,
  registry,
  isTop,
  isCovered,
  isHidden,
  onLargeTitleCollapse,
}: {
  model: ScreenModel;
  registry: Registry;
  isTop: boolean;
  isCovered: boolean;
  isHidden: boolean;
  onLargeTitleCollapse: (key: string, isCollapsed: boolean) => void;
}) {
  const props = model.element.props;
  const isLarge = props.titleDisplayMode === 'large';
  // The large title has collapsed once it has scrolled entirely under the
  // bar: the bar's own title takes over. The title reads the card's scroll
  // position from the moment it attaches. A card hidden two levels down
  // scrolls no more and keeps its last value. A title that detaches drops its
  // collapse. One that attaches reads the scroll position again.
  const largeTitleCallback = useCallback(
    (title: HTMLHeadingElement | null) => {
      const entry = registry.get(model.key) ?? {};
      entry.largeTitleElement = title;
      registry.set(model.key, entry);
      // The title is first in the scroll content, so a change of its height
      // reaches the scroll area's measure. The scroller holds that content.
      const scroller = title?.parentElement?.parentElement ?? null;
      if (title == null || scroller == null) {
        return undefined;
      }
      // The screen scrolls under the bar: the title has gone once its bottom
      // passes the bar's. A title with no layout has not scrolled away.
      const read = () =>
        onLargeTitleCollapse(
          model.key,
          title.offsetHeight > 0 &&
            scroller.scrollTop >=
              title.offsetTop + title.offsetHeight - BAR_HEIGHT,
        );
      read();
      scroller.addEventListener('scroll', read, {passive: true});
      // React runs this in place of a null call when the title detaches.
      return () => {
        scroller.removeEventListener('scroll', read);
        onLargeTitleCollapse(model.key, false);
        const current = registry.get(model.key);
        if (current?.largeTitleElement === title) {
          current.largeTitleElement = null;
        }
      };
    },
    [registry, model.key, onLargeTitleCollapse],
  );
  const card = useMotionEngine();
  const dim = useMotionEngine();
  const scrollerRef = useRef<HTMLDivElement | null>(null);
  // iOS 26: each screen's scroll view carries its own edge effect, so a push
  // or a pop carries each screen's veil with its card. It switches on once
  // the content has moved 10px under the bar, which overlays the scroller.
  // The veil is half strength at the bar's bottom. A hidden screen, two or
  // more levels down, has no layout to measure, so it runs no effect. Once
  // revealed it measures and switches at once.
  const edge = useScrollEdgeEffect({
    enabled: !isHidden,
    root: scrollerRef,
    rootInset: BAR_HEIGHT,
    edge: `${BAR_HEIGHT}px`,
    sentinelXstyle: isLarge
      ? styles.edgeSentinelAfterLargeTitle
      : styles.edgeSentinelStatic,
    springs: bars.scrollEdgeEffect,
  });
  // A forward Tab into the scroller moves on to its first plain link or
  // button.
  const {getViewportProps, getContentProps} = useScrollableArea({
    axis: 'block',
    overscroll: 'contain',
    keyboardAccess: {owner: 'contentOrViewport', label: props.title},
  });
  // The screen's animators register as its card attaches. The callback is
  // stable: a new one each render would detach and reattach the animator,
  // and restart a running transition.
  const cardRef = useCallback(
    (element: HTMLDivElement | null) => {
      card.ref(element);
      const entry = registry.get(model.key) ?? {};
      entry.card = card.animator;
      entry.dim = dim.animator;
      registry.set(model.key, entry);
    },
    [card, registry, model.key, dim.animator],
  );
  return (
    <div
      ref={cardRef}
      data-navigation-screen={model.key}
      data-navigation-top={isTop || undefined}
      inert={isCovered || undefined}
      {...stylex.props(styles.card, isHidden && styles.cardHidden)}>
      <div
        {...getViewportProps<HTMLDivElement>({
          ref: scrollerRef,
          xstyle: [focusOutlineStyles.focusVisible, styles.scroller],
        })}>
        {isLarge ? null : (
          <div {...edge.sentinelProps} data-navigation-scroll-edge-sentinel />
        )}
        <div {...getContentProps<HTMLDivElement>({})}>
          {isLarge ? (
            <>
              <h1
                ref={largeTitleCallback}
                tabIndex={-1}
                {...stylex.props(
                  focusOutlineStyles.focusVisible,
                  styles.largeTitle,
                )}>
                {props.title}
              </h1>
              <div
                {...edge.sentinelProps}
                data-navigation-scroll-edge-sentinel
              />
            </>
          ) : null}
          {props.children}
        </div>
      </div>
      <div {...edge.layerProps} data-navigation-scroll-edge />
      <div
        ref={dim.ref}
        aria-hidden
        {...stylex.props(
          styles.dim,
          dynamicStyles.dimColor(navigation.dimmingAlpha),
        )}
      />
    </div>
  );
}

function BarLayer({
  model,
  registry,
  isCovered,
  isLargeTitleShown,
}: {
  model: ScreenModel;
  registry: Registry;
  isCovered: boolean;
  isLargeTitleShown: boolean;
}) {
  const bar = useMotionEngine();
  const barDim = useMotionEngine();
  const clip = useMotionEngine();
  const clipContent = useMotionEngine();
  // The bar's animators register with it as it attaches. Stable, as the
  // card's: a new callback would detach and reattach the animator.
  const barRef = useCallback(
    (element: HTMLDivElement | null) => {
      bar.ref(element);
      const entry = registry.get(model.key) ?? {};
      entry.bar = bar.animator;
      entry.barDim = barDim.animator;
      entry.barClip = clip.animator;
      entry.barClipContent = clipContent.animator;
      registry.set(model.key, entry);
    },
    [
      bar,
      registry,
      model.key,
      barDim.animator,
      clip.animator,
      clipContent.animator,
    ],
  );
  const titleText = useMotionEngine();
  const wasShownRef = useRef<boolean | null>(null);
  // The bar's title hides while the screen's large title shows, and fades in
  // once the large title has scrolled under the bar. This drives the title's
  // compositor animator, the system it syncs.
  useLayoutEffect(() => {
    const target = {
      opacity: isLargeTitleShown ? 0 : 1,
      y: isLargeTitleShown ? navigation.inlineTitleRise : 0,
    };
    if (wasShownRef.current == null) {
      // First layout: the title is in place at once.
      titleText.animator.set(target);
    } else if (wasShownRef.current !== isLargeTitleShown) {
      titleText.animator.animate(target, {
        spring: springs.navigationBarElements,
      });
    }
    wasShownRef.current = isLargeTitleShown;
  }, [titleText.animator, isLargeTitleShown]);
  // The title is one element (its heading role): the stack focuses it, and
  // the animator rises and fades it. Both register as the title attaches.
  const titleRefs = useCallback(
    (element: HTMLHeadingElement | null) => {
      const entry = registry.get(model.key) ?? {};
      entry.titleElement = element;
      entry.titleText = titleText.animator;
      registry.set(model.key, entry);
      titleText.ref(element);
    },
    [registry, model.key, titleText],
  );
  const props = model.element.props;
  return (
    <div
      ref={barRef}
      data-navigation-bar={model.key}
      inert={isCovered || undefined}
      {...stylex.props(styles.barLayer, isCovered && styles.barLayerCovered)}>
      <div ref={clip.ref} {...stylex.props(styles.barClip)}>
        <div ref={clipContent.ref} {...stylex.props(styles.barRow)}>
          <div
            aria-hidden
            data-navigation-bar-background
            {...stylex.props(styles.barLayerBackground)}
          />
          <div {...stylex.props(styles.barStart)} />
          <h2
            ref={titleRefs}
            tabIndex={-1}
            aria-hidden={isLargeTitleShown || undefined}
            {...stylex.props(styles.barTitle, focusOutlineStyles.focusVisible)}>
            {props.title}
          </h2>
          <div {...stylex.props(styles.barEnd)}>{props.endContent}</div>
          <div
            ref={barDim.ref}
            aria-hidden
            data-navigation-bar-dim
            {...stylex.props(
              styles.dim,
              styles.barDim,
              dynamicStyles.dimColor(navigation.dimmingAlpha),
            )}
          />
        </div>
      </div>
    </div>
  );
}

/**
 * The back button: one for the stack, over the moving bars. Its glass
 * platter shows from a push's first frame; its chevron fades in and out on
 * its own clock (the stack drives both).
 */
function BackControl({
  label,
  onBack,
  isInert,
  control,
  chevron,
}: {
  label: string;
  onBack: () => void;
  isInert: boolean;
  control: (element: HTMLElement | null) => void;
  chevron: (element: HTMLElement | null) => void;
}) {
  // The motion engine takes an HTML element, and the icon's ref reaches its
  // inner SVG. So the animator binds the icon's wrapper, the button's first
  // child.
  const buttonRef = useCallback(
    (button: HTMLButtonElement | null) => {
      const icon = button?.firstElementChild;
      chevron(isHTMLElement(icon) ? icon : null);
    },
    [chevron],
  );
  return (
    <div
      ref={control}
      inert={isInert || undefined}
      {...stylex.props(styles.backControl)}>
      <button
        ref={buttonRef}
        type="button"
        onClick={onBack}
        aria-label={label}
        data-navigation-back
        {...stylex.props(styles.back)}>
        <Icon icon="chevronLeft" color="inherit" xstyle={styles.backIcon} />
      </button>
    </div>
  );
}

// =============================================================================
// Screen
// =============================================================================

/**
 * One screen of a NavigationStack. Its props describe the screen (title,
 * back title, end content, content); the stack lays it out.
 */
export function NavigationScreen(_props: NavigationScreenProps): ReactNode {
  // Rendered by NavigationStack, which reads these props; on its own it is
  // nothing.
  return null;
}
NavigationScreen.displayName = 'NavigationScreen';

// =============================================================================
// Stack
// =============================================================================

interface Transition {
  id: number;
  kind: 'push' | 'pop' | 'none';
  /** The screen on top when the transition ends (push) or leaving (pop). */
  top: string;
  /** The screen under it. */
  under: string | null;
}

/**
 * Whether a value is an element, by its node type. `instanceof` reads the
 * constructors of the window running this module. A stack rendered into
 * another window (an iframe, a picture-in-picture window) does not use them.
 */
function isElement(value: unknown): value is Element {
  return (
    typeof value === 'object' &&
    value != null &&
    (value as Partial<Node>).nodeType === 1
  );
}

function isHTMLElement(value: unknown): value is HTMLElement {
  return (
    isElement(value) && value.namespaceURI === 'http://www.w3.org/1999/xhtml'
  );
}

/** What a press on a control's label or icon gives focus back to. */
const FOCUSABLE_CONTROL =
  'button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"])';

/** The stack's writing direction, as core reads it. */
function writingDirection(element: HTMLElement | null): 'ltr' | 'rtl' {
  return isRtlElement(element) ? 'rtl' : 'ltr';
}

/**
 * A push/pop navigator: UINavigationController's transitions, back button
 * and back swipes, on the compositor.
 *
 * The app owns the path (`path` + `onPathChange`). The stack renders the
 * root screen and one screen per entry, top last. It animates the change
 * whenever the path gains or loses its top entry.
 *
 * Motion is UIKit's, measured on iOS 26.2 (motion/uikit/navigation.ts). A
 * push is a critically damped spring (response 0.3 s) that starts at 8.773
 * widths per second. The card underneath moves at 0.3 of the top card's
 * speed, under a 10 % black dimming. Each screen's bar moves with it.
 * Every layer runs on the compositor (core's animator), so a busy main thread
 * does not stall a push or a pop. The recognizer tracks the back swipe 1:1,
 * from the leading screen edge or, as on iOS 26, from anywhere in the
 * content. The compositor plays its release. The swipe finishes when
 * progress plus 0.35 s of velocity passes half the width. It finishes on a
 * spring (0.3 s, ζ 0.85) that starts at the finger's speed. Nothing waits
 * for a push. A pop during a push turns it around from where it is, and a
 * finger can grab the moving card.
 *
 * The bar is iOS 26's (measured). Each screen has its own opaque bar that
 * moves with its screen. So a pushed title slides in with its screen and
 * covers the one it replaces, which rides the parallax underneath. Under a
 * finger the revealed bar holds still. Back is one 44 pt circle over the
 * bars. It holds only the chevron and takes its name from the screen it
 * returns to. On a push from the root, its platter is there from the first
 * frame, and the chevron fades in a beat later. On a pop to the root, the
 * chevron fades out at once and the platter leaves with the screen. A back
 * swipe leaves it alone until the pop finishes.
 *
 * Under a finger the bars paint no background and no hairline, as iOS 26's
 * do. Each screen carries a scroll edge effect: a veil of the body colour
 * that comes in once the content has moved 10px under the bar. The veil
 * fades for a finger's scroll and rides the screen's card through a push, a
 * pop or a back swipe. The bar a card covers is cut at that card's leading
 * edge. A mouse keeps the bar's surface and hairline.
 *
 * In a browser tab the screen's leading edge is the browser's own back
 * swipe, which iOS Safari keeps. So the stack's edge swipe runs only in a
 * home-screen web app (`navigator.standalone`). The content swipe ignores
 * touches that start in that edge band.
 *
 * Reduced Motion is the animator's. Under a finger the incoming screen fades
 * in where it lands, and the outgoing one fades out in 200 ms. Nothing
 * travels and nothing dims. Under a mouse the change is immediate. A finger's
 * back swipe still tracks it, and what its release starts fades on any
 * pointer.
 *
 * Accessibility: covered screens are `inert`. A push moves focus to the new
 * screen's title; a pop returns it to the control that pushed the screen.
 * The back button is a real button named by the screen it returns to.
 */
export function NavigationStack<T>({
  root,
  path,
  onPathChange,
  renderScreen,
  getKey,
  isInteractivePopEnabled = true,
  label,
  'data-testid': testId,
}: NavigationStackProps<T>) {
  const t = useTranslator();
  const containerRef = useRef<HTMLDivElement | null>(null);
  const cardsRef = useRef<HTMLDivElement>(null);
  const [registry] = useState<Registry>(() => new Map());
  // The last input decides whether a moved focus shows its ring.
  const {ref: trackModality, readModality} = useInteractionModalityTracking();
  const containerCallback = useCallback(
    (element: HTMLDivElement | null) => {
      containerRef.current = element;
      const release = trackModality(element);
      return () => {
        release?.();
        containerRef.current = null;
      };
    },
    [trackModality],
  );
  // Screens whose large title has scrolled under the bar. The ref holds the
  // same set for the handlers and effects below; only the handler changes it.
  const [collapsedTitles, setCollapsedTitles] = useState<ReadonlySet<string>>(
    () => new Set(),
  );
  const collapsedRef = useRef(collapsedTitles);
  const onLargeTitleCollapse = useCallback(
    (key: string, isCollapsed: boolean) => {
      const current = collapsedRef.current;
      if (current.has(key) === isCollapsed) {
        return;
      }
      const next = new Set(current);
      if (isCollapsed) {
        next.add(key);
      } else {
        next.delete(key);
      }
      collapsedRef.current = next;
      setCollapsedTitles(next);
    },
    [],
  );

  // The screens on the path, root first.
  const models = useMemo<ScreenModel[]>(() => {
    const list: ScreenModel[] = [{key: 'root', element: root, source: null}];
    path.forEach((entry, index) => {
      list.push({
        key: `screen-${getKey ? getKey(entry, index) : index}`,
        element: renderScreen(entry, index),
        source: null,
      });
    });
    return list;
  }, [root, path, renderScreen, getKey]);
  const keys = models.map(model => model.key).join('\u0000');

  // Sources of pushes, by screen key (focus returns there on the pop).
  const sourcesRef = useRef(new Map<string, Element | null>());
  // The last control activated inside the stack: what a push it starts came
  // from.
  const lastActivationRef = useRef<{target: Element; at: number} | null>(null);
  // A pending push source handed to push(): applied to the new top.
  const pendingSourceRef = useRef<Element | null | undefined>(undefined);
  // An interactive release in flight: the pop it commits continues from the
  // finger's velocity instead of starting a programmatic pop.
  const releaseRef = useRef<{velocity: number} | null>(null);

  // Derived during render, so a popped screen is still rendered (leaving) in
  // the very commit that drops it from the path.
  const [view, setView] = useState<{
    keys: string;
    models: ScreenModel[];
    leaving: ScreenModel | null;
    transition: Transition;
  }>(() => ({
    keys,
    models,
    leaving: null,
    transition: {
      id: 0,
      kind: 'none',
      top: models.at(-1)?.key ?? 'root',
      under: null,
    },
  }));

  if (view.keys !== keys) {
    const before = view.models;
    const isPrefix = (shorter: ScreenModel[], longer: ScreenModel[]) =>
      shorter.every((model, i) => longer[i]?.key === model.key);
    let transition: Transition;
    let leaving: ScreenModel | null = null;
    if (models.length === before.length + 1 && isPrefix(before, models)) {
      transition = {
        id: view.transition.id + 1,
        kind: 'push',
        top: models[models.length - 1].key,
        under: before[before.length - 1]?.key ?? null,
      };
    } else if (models.length < before.length && isPrefix(models, before)) {
      leaving = before[before.length - 1];
      transition = {
        id: view.transition.id + 1,
        kind: 'pop',
        top: leaving.key,
        under: models[models.length - 1].key,
      };
    } else {
      transition = {
        id: view.transition.id + 1,
        kind: 'none',
        top: models[models.length - 1].key,
        under: null,
      };
    }
    setView({keys, models, leaving, transition});
  } else if (view.models !== models) {
    // Same screens, new elements (the app re-rendered): keep them current.
    setView({...view, models});
  }

  const depth = models.length - 1;
  const rendered = view.leaving ? [...view.models, view.leaving] : view.models;
  const topKey = view.leaving
    ? view.leaving.key
    : (view.models.at(-1)?.key ?? 'root');
  // While a pop runs, the screen it reveals; otherwise the one under the top
  // (a finished pop's `transition.under` is the new top itself).
  const underKey =
    view.leaving != null
      ? view.transition.under
      : (view.models.at(-2)?.key ?? null);

  // ---------------------------------------------------------------------------
  // Transition driver
  // ---------------------------------------------------------------------------

  const runningRef = useRef<{id: number; done: boolean} | null>(null);
  // The clock the last transition's screens run on (their start time), so
  // the back chevron keeps time with them.
  const startedRef = useRef(0);
  // A pop's focus return, waiting for the commit that drops the leaving
  // screen (until then every screen is `inert` and cannot take focus).
  const pendingFocusRef = useRef<{popped: string; revealed: string} | null>(
    null,
  );
  const progressRef = useRef(0);
  // The back button's platter and chevron (one for the stack).
  const backControl = useMotionEngine();
  const backChevron = useMotionEngine();

  const layersOf = useCallback(
    (key: string | null) => (key == null ? null : (registry.get(key) ?? null)),
    [registry],
  );

  // Under a finger the bars are iOS 26's: clear, so a covered bar would show
  // through the card above it. UIKit's covering view cuts the title under it
  // at its leading edge. Here the covered bar's clip box follows the top
  // card's leading edge, and the row inside it holds still. At rest the box
  // is shut. While the cards travel it moves on their spring, or with the
  // finger. The stack reads the touch presentation as each move starts, as
  // the swipes do. A mouse keeps opaque bars and the boxes at identity.
  const clearBarsRef = useRef(false);
  const readClearBars = useCallback(() => {
    clearBarsRef.current = isCoarsePointer(
      containerRef.current?.ownerDocument.defaultView,
    );
    return clearBarsRef.current;
  }, []);
  /**
   * Where the covered bar's box goes so its edge meets the top card's
   * leading edge (the top card at `topX`, the covered bar at `underBarX`).
   */
  const clipXFor = useCallback((topX: number, underBarX: number) => {
    const width = cardsRef.current?.clientWidth ?? 0;
    const sign = writingDirection(containerRef.current) === 'rtl' ? -1 : 1;
    return topX - underBarX - sign * width;
  }, []);
  const setClip = useCallback(
    (key: string | null, x: number) => {
      const layers = layersOf(key);
      layers?.barClip?.set({x});
      layers?.barClipContent?.set({x: -x});
    },
    [layersOf],
  );

  const shownBarsRef = useRef<ReadonlySet<string>>(new Set());
  // A bar that mounts covered parks at the parallax, as `settle` parks a
  // covered screen. A pop that reveals a screen two levels down brings one.
  // Under a finger it is cut away at the top card's leading edge; under a
  // mouse it is whole, under the opaque top bar. A bar that was already shown
  // keeps its place, and the transition moves it. This drives the bars'
  // compositor animators, the system it syncs.
  useLayoutEffect(() => {
    const before = shownBarsRef.current;
    shownBarsRef.current = new Set(
      underKey == null ? [topKey] : [topKey, underKey],
    );
    if (underKey == null || before.has(underKey)) {
      return;
    }
    const values = layersAt(
      0,
      cardsRef.current?.clientWidth ?? 0,
      writingDirection(containerRef.current),
    );
    layersOf(underKey)?.bar?.set({x: values.underX});
    setClip(underKey, readClearBars() ? clipXFor(0, values.underX) : 0);
  }, [topKey, underKey, layersOf, readClearBars, setClip, clipXFor]);

  const {isTouch} = useTouchPresentation();
  const touchSeenRef = useRef(isTouch);
  // The touch presentation can change while a screen is covered (a tablet
  // losing its mouse). The bars' backgrounds follow it at once, so the
  // covered bar's cut follows it too. A running move reads it again as it
  // settles. This drives the bars' compositor animators, the system it syncs.
  useLayoutEffect(() => {
    if (touchSeenRef.current === isTouch) {
      return;
    }
    touchSeenRef.current = isTouch;
    const running = runningRef.current;
    if (underKey == null || (running != null && !running.done)) {
      return;
    }
    const values = layersAt(
      0,
      cardsRef.current?.clientWidth ?? 0,
      writingDirection(containerRef.current),
    );
    setClip(underKey, readClearBars() ? clipXFor(0, values.underX) : 0);
  }, [isTouch, underKey, readClearBars, setClip, clipXFor]);

  /**
   * Writes the layers for progress p (a finger's frame, or a transition's
   * first one; no animation). The top bar moves with its card. Under a
   * finger the revealed bar holds still where it rests, as UIKit's does.
   * `underBar: 'ride'` puts it at its card's parallax instead, where a
   * programmatic pop starts it.
   */
  const setProgress = useCallback(
    (
      p: number,
      top: string,
      under: string | null,
      underBar: 'rest' | 'ride' = 'rest',
    ) => {
      const width = cardsRef.current?.clientWidth ?? 0;
      const direction = writingDirection(containerRef.current);
      const values = layersAt(p, width, direction);
      const topLayers = layersOf(top);
      const underLayers = layersOf(under);
      topLayers?.card?.set({x: values.topX});
      topLayers?.bar?.set({x: values.topX});
      underLayers?.card?.set({x: values.underX});
      const underBarX = underBar === 'ride' ? values.underX : 0;
      underLayers?.bar?.set({x: underBarX});
      underLayers?.dim?.set({opacity: values.dim});
      underLayers?.barDim?.set({opacity: values.dim});
      // Under a finger the covered bar is cut where the top card's leading
      // edge is; under a mouse both bars are whole.
      setClip(top, 0);
      setClip(
        under,
        clearBarsRef.current ? clipXFor(values.topX, underBarX) : 0,
      );
      progressRef.current = p;
    },
    [layersOf, setClip, clipXFor],
  );

  /**
   * Springs the layers to progress `to`. `dp` is the progress velocity to
   * start from (omit it to keep the velocity the layers have on screen).
   */
  const animateProgress = useCallback(
    (
      to: 0 | 1,
      top: string,
      under: string | null,
      spring: SpringDescription,
      dp: number | undefined,
      release: boolean,
      underBar: 'rest' | 'ride',
      startAt?: number,
    ): Promise<boolean> => {
      const width = cardsRef.current?.clientWidth ?? 0;
      const direction = writingDirection(containerRef.current);
      const values = layersAt(to, width, direction);
      const velocity =
        dp == null ? null : layerVelocities(dp, width, direction);
      const at = startAt ?? performance.now();
      const topLayers = layersOf(top);
      const underLayers = layersOf(under);
      const handles = [];
      // Reduced Motion is the animator's; `crossfadeAs` says which card
      // enters (fades in where it lands) and which leaves (fades out in
      // place). A finger's release fades on any pointer (`touchRelease`).
      if (topLayers?.card) {
        handles.push(
          topLayers.card.animate(
            {x: values.topX},
            {spring, velocity: velocity ? {x: velocity.topX} : undefined},
            {
              at,
              touchRelease: release,
              crossfadeAs: to === 0 ? 'entrance' : 'exit',
            },
          ),
        );
        startedRef.current = at;
      }
      // The bars move with their cards (each screen's bar is part of it in
      // UIKit): the incoming one covers the outgoing title.
      if (topLayers?.bar) {
        handles.push(
          topLayers.bar.animate(
            {x: values.topX},
            {spring, velocity: velocity ? {x: velocity.topX} : undefined},
            {at, touchRelease: release},
          ),
        );
      }
      if (underLayers?.bar && underBar === 'ride') {
        handles.push(
          underLayers.bar.animate(
            {x: values.underX},
            {spring, velocity: velocity ? {x: velocity.underX} : undefined},
            {at, touchRelease: release},
          ),
        );
      }
      if (underLayers?.card) {
        handles.push(
          underLayers.card.animate(
            {x: values.underX},
            {spring, velocity: velocity ? {x: velocity.underX} : undefined},
            {
              at,
              touchRelease: release,
              crossfadeAs: to === 1 ? 'entrance' : 'exit',
            },
          ),
        );
      }
      if (clearBarsRef.current) {
        // Under a finger the covered bar's box rides the top card's leading
        // edge on the same spring, from the same start and velocity. The
        // difference of the two bars' curves is the same curve. There is no
        // clamp: an overshoot past rest stays cut. Reduced Motion's
        // cross-fade has no travel: the titles swap at once, as UIKit's do.
        const underBarTo =
          underBar === 'ride'
            ? values.underX
            : (underLayers?.bar?.get('x') ?? 0);
        const clipTo = clipXFor(values.topX, underBarTo);
        setClip(top, 0);
        if (
          (topLayers?.card?.reducedMotion({touchRelease: release}) ?? 'off') !==
          'off'
        ) {
          setClip(under, clipTo);
          if (to === 1) {
            // A pop: the leaving bar goes at once too.
            setClip(top, direction === 'rtl' ? width : -width);
          }
        } else if (underLayers?.barClip && underLayers.barClipContent) {
          const clipVelocity =
            velocity == null
              ? undefined
              : velocity.topX - (underBar === 'ride' ? velocity.underX : 0);
          handles.push(
            underLayers.barClip.animate(
              {x: clipTo},
              {
                spring,
                velocity: clipVelocity == null ? undefined : {x: clipVelocity},
              },
              {at, touchRelease: release},
            ),
            underLayers.barClipContent.animate(
              {x: -clipTo},
              {
                spring,
                velocity: clipVelocity == null ? undefined : {x: -clipVelocity},
              },
              {at, touchRelease: release},
            ),
          );
        }
      } else {
        // Under a mouse both bars are whole, also after a pointer that was
        // coarse left a cut.
        setClip(top, 0);
        setClip(under, 0);
      }
      for (const dim of [underLayers?.dim, underLayers?.barDim]) {
        if (dim == null) {
          continue;
        }
        if (dim.reducedMotion({touchRelease: release}) !== 'off') {
          // A Reduced Motion fade has no dimming: the shade belongs to the
          // slide.
          dim.set({opacity: 0});
        } else {
          handles.push(
            dim.animate(
              {opacity: values.dim},
              {
                spring,
                velocity: velocity ? {opacity: velocity.dim} : undefined,
              },
              {at, touchRelease: release},
            ),
          );
        }
      }
      progressRef.current = to;
      return Promise.all(handles.map(async handle => handle.finished)).then(
        results => results.every(Boolean),
      );
    },
    [layersOf, setClip, clipXFor],
  );

  /**
   * The back button on a push from the root or a pop to it, as UIKit's. On
   * the push the platter is there from the first frame, and the chevron
   * fades in a beat later. On the pop the chevron fades out at once, and the
   * platter leaves with the screen. Both fades are the back-button spring;
   * the push's delay is the navigation table's, as measured.
   */
  const fadeBack = useCallback(
    (kind: 'push' | 'pop', under: string | null, release = false) => {
      const isRoot = under != null && view.models[0]?.key === under;
      const element = containerRef.current;
      const spring = springs.navigationBackButton;
      if (!isRoot) {
        return;
      }
      const delay =
        kind === 'pop'
          ? 0
          : resolveMotion(element, navigation, 'backChevronPushDelayMs');
      if (kind === 'push') {
        backControl.animator.set({opacity: 1});
        backChevron.animator.set({opacity: 0});
      }
      // On the screens' clock, and starting with them. The delay is part of
      // the curve, so the whole fade is one compositor animation. A busy main
      // thread cannot hold it back. In WebKit a start in the future would
      // wait for the main thread.
      const from = kind === 'push' ? 0 : 1;
      const to = kind === 'push' ? 1 : 0;
      const fade = solveSpring(toSpring(resolveMotion(element, spring)), {
        from,
        to,
      });
      const delayS = delay / 1000;
      backChevron.animator.play(
        {
          opacity: {
            duration: delayS + fade.settleTime(0.001),
            at: t => (t < delayS ? from : fade.value(t - delayS)),
            velocity: t => (t < delayS ? 0 : fade.velocity(t - delayS)),
          },
        },
        {at: startedRef.current, touchRelease: release},
      );
    },
    [view.models, backControl.animator, backChevron.animator],
  );

  /** Puts a screen's layers at rest: on top, covered, or off. */
  const settle = useCallback(
    (key: string, role: 'top' | 'covered') => {
      const layers = layersOf(key);
      const width = cardsRef.current?.clientWidth ?? 0;
      const direction = writingDirection(containerRef.current);
      const values = layersAt(0, width, direction);
      if (role === 'top') {
        layers?.card?.set({x: 0, opacity: 1});
        layers?.dim?.set({opacity: 0});
        layers?.bar?.set({x: 0});
        layers?.barDim?.set({opacity: 0});
        // A screen on top shows its whole bar, under any pointer.
        setClip(key, 0);
      } else {
        // Covered: parked at the parallax, under the top screen and its bar.
        layers?.card?.set({x: values.underX, opacity: 1});
        layers?.dim?.set({opacity: 1});
        layers?.bar?.set({x: values.underX});
        layers?.barDim?.set({opacity: 1});
        // Under a finger cut away at the top card's leading edge (the top
        // card at rest); under a mouse whole, parked under the opaque bar.
        // Read again here: the pointer may have changed during the move.
        setClip(key, readClearBars() ? clipXFor(0, values.underX) : 0);
      }
    },
    [layersOf, readClearBars, setClip, clipXFor],
  );

  const focusAfter = useCallback(
    (kind: 'push' | 'pop', key: string, revealed?: string) => {
      const container = containerRef.current;
      // Only move focus when it was in the stack or nowhere: never take it
      // from elsewhere on the page.
      if (container == null || !isFocusLost(container)) {
        return;
      }
      // The moved focus shows its ring by the last input, as Core's overlays
      // do. After a key it shows; after a tap it does not.
      const modality = readModality();
      const focus = (element: HTMLElement) =>
        focusForLastInput(element, {preventScroll: true}, modality);
      if (kind === 'pop') {
        const source = sourcesRef.current.get(key);
        sourcesRef.current.delete(key);
        if (isHTMLElement(source) && source.isConnected) {
          focus(source);
          // A control that can no longer take focus falls through to the
          // title.
          if (source.ownerDocument.activeElement === source) {
            return;
          }
        }
      }
      // Else the screen now on top (the one pushed, or the one revealed): its
      // visible title, the large title while it shows, else the bar's.
      const target = revealed ?? key;
      const layers = layersOf(target);
      const large = layers?.largeTitleElement;
      const title =
        large != null && large.isConnected && !collapsedRef.current.has(target)
          ? large
          : layers?.titleElement;
      if (title != null) {
        focus(title);
      }
    },
    [layersOf, readModality],
  );

  // The committed view, and the back fade that follows it, for the effect
  // below. They sync at each commit, so only a new transition restarts it.
  const transitionInputsRef = useRef({view, fadeBack});
  useLayoutEffect(() => {
    transitionInputsRef.current = {view, fadeBack};
  });
  // Runs the transition the last path change asked for. It drives the
  // screens' and bars' compositor animators, the system it syncs.
  useLayoutEffect(() => {
    const {view, fadeBack} = transitionInputsRef.current;
    const transition = view.transition;
    readClearBars();
    if (transition.kind === 'none') {
      // Settle every screen where it rests.
      view.models.forEach((model, index) => {
        settle(model.key, index === view.models.length - 1 ? 'top' : 'covered');
      });
      backControl.animator.set({opacity: 1});
      backChevron.animator.set({opacity: 1});
      return;
    }
    const {top, under} = transition;
    const id = transition.id;
    const previous = runningRef.current;
    const wasRunning = previous != null && !previous.done;
    runningRef.current = {id, done: false};
    const release = releaseRef.current;
    releaseRef.current = null;
    pendingFocusRef.current = null;
    const at = performance.now();
    let promise: Promise<boolean>;
    if (transition.kind === 'push') {
      if (!wasRunning) {
        setProgress(1, top, under);
      } else {
        // The covered screen continues from where it is; the new one (just
        // mounted, at rest) starts off screen as any push does.
        const values = layersAt(
          1,
          cardsRef.current?.clientWidth ?? 0,
          writingDirection(containerRef.current),
        );
        layersOf(top)?.card?.set({x: values.topX});
        layersOf(top)?.bar?.set({x: values.topX});
      }
      promise = animateProgress(
        0,
        top,
        under,
        springs.navigationPush,
        wasRunning ? undefined : programmaticVelocity('push'),
        false,
        'ride',
      );
      fadeBack('push', under);
    } else if (release != null) {
      promise = animateProgress(
        1,
        top,
        under,
        springs.navigationInteractivePopFinish,
        release.velocity,
        true,
        'rest',
        at,
      );
      fadeBack('pop', under, true);
    } else {
      if (!wasRunning) {
        setProgress(0, top, under, 'ride');
      }
      promise = animateProgress(
        1,
        top,
        under,
        springs.navigationPop,
        wasRunning ? undefined : programmaticVelocity('pop'),
        false,
        'ride',
        at,
      );
      fadeBack('pop', under);
    }
    void promise.then(finished => {
      if (runningRef.current?.id !== id) {
        return;
      }
      runningRef.current = {id, done: true};
      if (!finished) {
        return;
      }
      if (transition.kind === 'pop') {
        setView(current =>
          current.transition.id === id ? {...current, leaving: null} : current,
        );
        if (under != null) {
          settle(under, 'top');
          pendingFocusRef.current = {popped: top, revealed: under};
        }
      } else {
        if (under != null) {
          // The covered screen keeps its place under the top one.
          layersOf(under)?.card?.set({opacity: 1});
        }
        focusAfter('push', top);
      }
    });
    // Only a new transition restarts this; the stack drives the layers
    // imperatively.
  }, [
    view.transition.id,
    animateProgress,
    focusAfter,
    layersOf,
    readClearBars,
    setProgress,
    settle,
    backControl.animator,
    backChevron.animator,
  ]);

  // The pop's focus return, after the commit that dropped the leaving screen
  // (the DOM's focus, the system this effect drives).
  useLayoutEffect(() => {
    const pending = pendingFocusRef.current;
    if (view.leaving == null && pending != null) {
      pendingFocusRef.current = null;
      focusAfter('pop', pending.popped, pending.revealed);
    }
  }, [view.leaving, focusAfter]);

  // ---------------------------------------------------------------------------
  // API
  // ---------------------------------------------------------------------------

  // The committed path and callback, synced at each commit. `push` and `pop`
  // build the next path from what the screen shows, never from a render
  // React discards.
  const pathRef = useRef(path);
  const onPathChangeRef = useRef(onPathChange);
  useLayoutEffect(() => {
    pathRef.current = path;
    onPathChangeRef.current = onPathChange;
  });

  const api = useMemo<NavigationStackApi<T>>(
    () => ({
      push: (entry, options) => {
        const last = lastActivationRef.current;
        const source =
          options?.source !== undefined
            ? options.source
            : last != null && performance.now() - last.at < 1000
              ? last.target
              : null;
        pendingSourceRef.current = source;
        onPathChangeRef.current([...pathRef.current, entry]);
      },
      pop: () => {
        if (pathRef.current.length > 0) {
          onPathChangeRef.current(pathRef.current.slice(0, -1));
        }
      },
      popToRoot: () => {
        if (pathRef.current.length > 0) {
          onPathChangeRef.current([]);
        }
      },
      depth,
    }),
    [depth],
  );

  // Record the source of a push on the screen it pushed.
  useLayoutEffect(() => {
    if (view.transition.kind !== 'push') {
      return;
    }
    if (pendingSourceRef.current !== undefined) {
      sourcesRef.current.set(view.transition.top, pendingSourceRef.current);
      pendingSourceRef.current = undefined;
    }
  }, [view.transition]);

  // The control a push starts from: the last click or key press in the stack,
  // from the container's own capture handlers. A press on a control's label or
  // icon remembers the control itself.
  const rememberActivation = useCallback((event: SyntheticEvent) => {
    const {target} = event;
    if (isElement(target)) {
      // The scroller is focusable while it overflows, but it is not a
      // control. After a push from its plain content, the pop focuses the
      // title.
      const control = target.closest(FOCUSABLE_CONTROL);
      const isScreenScroller =
        control?.parentElement?.hasAttribute('data-navigation-screen') === true;
      lastActivationRef.current = {
        target: control != null && !isScreenScroller ? control : target,
        at: performance.now(),
      };
    }
  }, []);

  // ---------------------------------------------------------------------------
  // Back swipes
  // ---------------------------------------------------------------------------

  const canPop = depth > 0 && view.leaving == null;
  // What the touch layer (NavigationStackTouch.ts) moves: the swipes read
  // and drive the stack through this, each frame's values from the latest
  // render.
  const swipeStackRef = useRef<BackSwipeStack | null>(null);
  const swipeStack: BackSwipeStack = {
    width: () => cardsRef.current?.clientWidth ?? 0,
    direction: () => writingDirection(containerRef.current),
    screens: () => {
      const top = view.models.at(-1)?.key;
      const under = view.models.at(-2)?.key;
      return top == null || under == null ? null : {top, under};
    },
    grab: (top, under) => {
      // Grab whatever is moving: the top card's presentation value is the
      // progress to continue from. A finger's move starts here.
      readClearBars();
      const width = cardsRef.current?.clientWidth ?? 0;
      const x = layersOf(top)?.card?.get('x') ?? 0;
      const direction = writingDirection(containerRef.current);
      for (const key of [top, under]) {
        const layers = layersOf(key);
        layers?.card?.stop();
        layers?.dim?.stop();
        layers?.bar?.stop();
        layers?.barDim?.stop();
        layers?.barClip?.stop();
        layers?.barClipContent?.stop();
      }
      runningRef.current = null;
      return progressFromScreen(x, width, direction);
    },
    setProgress: (p, top, under) => {
      setProgress(p, top, under);
    },
    progress: () => progressRef.current,
    release: (top, under, finish, velocity) => {
      const springBack = (v: number) => {
        const id = (runningRef.current?.id ?? 0) + 0.5;
        runningRef.current = {id, done: false};
        const at = performance.now();
        void animateProgress(
          0,
          top,
          under,
          // Released past its start (rubber-banded), UIKit's return.
          progressRef.current < 0
            ? springs.navigationInteractivePopReturn
            : springs.navigationInteractivePopFinish,
          v,
          true,
          'rest',
          at,
        ).then(finished => {
          if (runningRef.current?.id === id) {
            runningRef.current = {id, done: true};
          }
          if (finished) {
            settle(top, 'top');
            settle(under, 'covered');
          }
        });
      };
      if (!finish) {
        springBack(velocity);
        return;
      }
      // Commit the pop; the transition it triggers continues from here at
      // the finger's speed.
      const release = {velocity};
      const before = pathRef.current;
      releaseRef.current = release;
      onPathChangeRef.current(before.slice(0, -1));
      // An app that keeps its path (guarding unsaved edits, say) gets no
      // pop. By the next frame the release is still waiting, so the cards
      // spring back where they came from.
      const win = containerRef.current?.ownerDocument.defaultView;
      win?.requestAnimationFrame(() => {
        if (releaseRef.current === release && pathRef.current === before) {
          releaseRef.current = null;
          springBack(0);
        }
      });
    },
  };
  useLayoutEffect(() => {
    swipeStackRef.current = swipeStack;
  });
  useBackSwipes(containerRef, cardsRef, swipeStackRef, {
    isEnabled: canPop && isInteractivePopEnabled,
  });

  // ---------------------------------------------------------------------------
  // Render
  // ---------------------------------------------------------------------------

  const backLabelFor = (index: number) => {
    if (index === 0) {
      return null;
    }
    const previous = rendered[index - 1]?.element.props;
    // An empty title names nothing: the catalog's "Back" covers that too.
    return (
      previous?.backTitle ||
      previous?.title ||
      t('@astryx.navigationStack.back')
    );
  };
  // The top screen's back target; while a pop to the root runs, the leaving
  // screen's (its button fades out with it).
  const topBackLabel = backLabelFor(
    rendered.findIndex(model => model.key === topKey),
  );

  return (
    <NavigationStackContext.Provider value={api as NavigationStackApi}>
      <div
        ref={containerCallback}
        role="region"
        aria-label={label}
        data-testid={testId}
        onClickCapture={rememberActivation}
        onKeyDownCapture={rememberActivation}
        {...stylex.props(styles.stack)}>
        <div {...stylex.props(styles.bar)}>
          <div aria-hidden {...stylex.props(styles.barBackground)} />
          {rendered.map(model =>
            model.key === topKey || model.key === underKey ? (
              <BarLayer
                key={model.key}
                model={model}
                registry={registry}
                isCovered={model.key !== topKey || view.leaving != null}
                isLargeTitleShown={
                  model.element.props.titleDisplayMode === 'large' &&
                  !collapsedTitles.has(model.key)
                }
              />
            ) : null,
          )}
          {topBackLabel != null ? (
            <BackControl
              label={topBackLabel}
              onBack={api.pop}
              isInert={view.leaving != null}
              control={backControl.ref}
              chevron={backChevron.ref}
            />
          ) : null}
        </div>
        <div ref={cardsRef} {...stylex.props(styles.cards)}>
          {rendered.map(model => (
            <CardLayer
              key={model.key}
              model={model}
              registry={registry}
              isTop={model.key === topKey && view.leaving == null}
              isCovered={model.key !== topKey || view.leaving != null}
              isHidden={model.key !== topKey && model.key !== underKey}
              onLargeTitleCollapse={onLargeTitleCollapse}
            />
          ))}
        </div>
      </div>
    </NavigationStackContext.Provider>
  );
}

NavigationStack.displayName = 'NavigationStack';