Skip to content

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

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

'use client';

import React from 'react';

/**
 * @file AppShell.tsx
 * @input Uses React, Theme-resolved breakpoints, Layout, navigation slots, and StyleX
 * @output Exports AppShell component and AppShellProps with SSR-safe mobile layout
 * @position Page shell for an application — the top-level wrapper for any app.
 *   Composes Layout internally to provide header, sideNav, and main content areas.
 *   Use for any app that needs a top nav, side navigation, and scrollable content.
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/AppShell/AppShell.doc.mjs
 * - /packages/core/src/AppShell/index.ts
 * - /packages/core/src/AppShell/AppShell.test.tsx
 * - /apps/storybook/stories/AppShell.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/AppShell/ (showcase blocks)
 */

import {
  isValidElement,
  useCallback,
  useEffect,
  useId,
  useMemo,
  useRef,
  useState,
  type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
  colorVars,
  focusVars,
  fontWeightVars,
  radiusVars,
  spacingVars,
  typeScaleVars,
} from '../theme/tokens.stylex';
import {Layout} from '../Layout/Layout';
import {LayoutHeader} from '../Layout/LayoutHeader';
import {LayoutPanel} from '../Layout/LayoutPanel';
import {LayoutContent} from '../Layout/LayoutContent';
import {LayoutAreaContext} from '../Layout/LayoutAreaContext';
import {LayoutDividerContext} from '../Layout/LayoutDividerContext';
import {
  DEFAULT_LAYOUT_SLOTS,
  LayoutSlotsContext,
} from '../Layout/LayoutSlotsContext';
import {layoutReset} from '../Layout/layoutReset';
import {MobileNavToggle} from '../MobileNav/MobileNavToggle';
import {MAX_CLOSE_DELAY_MS as MOBILE_NAV_MAX_CLOSE_DELAY_MS} from '../MobileNav/MobileNav';
import {SideNavRenderContext} from '../SideNav/SideNavRenderContext';
import {SideNavShellContext, type SideNavShell} from '../SideNav/railMotion';
import {useAnimatedLayout} from '../hooks/useAnimatedLayout';
import {
  holdLayoutSwap,
  landLayoutGlide,
  layoutMotionFor,
  layoutStartFor,
  playLayoutFrames,
  playLayoutSwap,
  reportLayoutChange,
  type LayoutChange,
  type LayoutSwap,
} from '../motion/animatedLayout';
import {TopNavRenderContext} from '../TopNav/TopNavRenderContext';
import {TopNavMobileContentContext} from '../TopNav/TopNavMobileContentContext';
import {AppShellMobileContext} from './AppShellMobileContext';
import {AppShellNestingContext, useAppShellMainId} from './useAppShellMainId';
import type {AppShellMobileContextValue} from './AppShellMobileContext';
import type {SpacingStep} from '../utils/types';
import type {BaseProps} from '../BaseProps';
import {mergeProps, isRenderable} from '../utils';
import {
  focusOutlineProps,
  focusOutlineStyles,
} from '../utils/focusOutline.stylex';
import {useMediaQuery} from '../hooks/useMediaQuery';
import {matchesMediaQuery} from '../utils/coarsePointer';
import {observeResize} from '../utils/sharedResizeObserver';
import {themeProps} from '../utils/themeProps';
import {useThemeDefinition} from '../theme/useTheme';
import {
  DEFAULT_WIDTH_BREAKPOINTS,
  type WidthBreakpointName,
} from '../theme/themeAdaptations';
import type {AppShellVariantMap} from './index';

import {useMergedRefs} from '../hooks/useMergedRefs';
import {attachScrollKeyboardDelegation} from '../hooks/scrollKeyboardDelegation';
import {observeMainOverflow} from './observeMainOverflow';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/AppShell/AppShell.generated';

registerEnglishFallback(english);
const HasActivity = typeof React.Activity !== 'undefined';
const ActivityWrapper = HasActivity
  ? ({
      mode,
      children,
    }: {
      mode: 'visible' | 'hidden';
      children: React.ReactNode;
    }) => <React.Activity mode={mode}>{children}</React.Activity>
  : ({children}: {mode: string; children: React.ReactNode}) => <>{children}</>;

// =============================================================================
// Constants
// =============================================================================

/**
 * Extra time, on top of MobileNav's own worst-case close delay, that
 * AppShell waits before flipping its `Activity` boundary to `'hidden'`.
 *
 * React's `Activity` hides its subtree with `display: none !important`
 * synchronously in the same commit as the mode flip, and re-runs the
 * cleanup of every effect inside it — which would otherwise clear
 * MobileNav's own scheduled `dialog.close()` before it fires, or cut off
 * its slide-out CSS transition before it plays (#5701). Waiting strictly
 * longer than MobileNav's own cap, rather than the same duration, means
 * this never turns into a race decided by browser timer-firing order.
 */
const ACTIVITY_HIDE_BUFFER_MS = 50;

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

/**
 * SideNav breakpoint options. Named points resolve through the nearest Theme;
 * without an active theme they use Astryx's default width-breakpoint map.
 */
export type AppShellBreakpoint = WidthBreakpointName | 'none';

/**
 * Navigation background style:
 * - `wash`: Nav areas use wash background, no dividers
 * - `surface`: Nav areas use surface background, no dividers
 * - `section`: Dividers between nav and content (classic look)
 * - `elevated`: Wash nav background with elevated surface content + border radius
 * @default 'elevated'
 */

/**
 * Navigation background style. Extensible via module augmentation of AppShellVariantMap.
 */
export type AppShellVariant = keyof AppShellVariantMap;

/**
 * Configuration object for mobile navigation behavior.
 * Used when you need to customize the auto mobile nav without replacing it entirely.
 */
export interface MobileNavConfig {
  /**
   * Whether to auto-render the hamburger toggle.
   * When false, use `<MobileNavToggle />` to place it yourself.
   * @default true
   */
  hasToggle?: boolean;

  /**
   * Controlled open state. When provided, AppShell doesn't manage
   * mobile nav state internally.
   */
  isOpen?: boolean;

  /**
   * Callback when the mobile nav drawer open state changes.
   */
  onOpenChange?: (isOpen: boolean) => void;

  /**
   * Custom drawer content. Replaces the auto-generated drawer.
   * Can be an `<MobileNav>` for full drawer config (title, width, side)
   * or raw children.
   */
  content?: ReactNode;

  /**
   * Named Theme width point below which mobile nav activates. `sm`, `md`,
   * `lg`, `xl`, and `2xl` resolve through the nearest Theme's effective
   * `adaptations.widthBreakpoints`; equality belongs to the wider layout.
   * Use `none` to disable automatic mobile mode.
   * @default 'md'
   */
  breakpoint?: AppShellBreakpoint;

  /**
   * SSR hint: whether the initial render should assume mobile layout.
   * Seeds the breakpoint state so the server-rendered HTML matches
   * the client on mobile devices, avoiding a layout flash. Ignored when
   * `breakpoint` is `none`, which is always non-mobile.
   *
   * Derive from the User-Agent header or a device-detection cookie
   * in a server component, then pass down.
   *
   * @default false
   */
  defaultIsMobile?: boolean;
}

export interface AppShellProps extends BaseProps<HTMLDivElement> {
  /** Ref forwarded to the root element */
  ref?: React.Ref<HTMLDivElement>;
  /**
   * Navigation background style controlling how nav areas contrast with content.
   * - `wash`: Nav uses wash background, no dividers
   * - `surface`: Nav uses surface background, no dividers
   * - `section`: Dividers between nav and content (classic look)
   * - `elevated`: Wash nav with elevated surface content area + border radius
   * @default 'elevated'
   */
  variant?: AppShellVariant;

  /**
   * Optional banner slot for system-wide announcements.
   * Renders above the top nav and scrolls away with the page in auto mode.
   */
  banner?: ReactNode;

  /**
   * Main content area (rendered as `<main>`).
   */
  children: ReactNode;

  /**
   * Padding for the main content area using the spacing scale.
   * Set based on the dominant content pattern for the page:
   * - `4` (16px) — standard padding for forms, settings, text-heavy pages
   * - `0` — no padding, for dashboards, maps, tables that need edge-to-edge
   * Override individual sections with `<Section padding={...}>`.
   * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
   */
  contentPadding?: SpacingStep;

  /**
   * Height behavior:
   * - `fill`: Shell fills viewport, content scrolls internally (default)
   * - `auto`: Shell grows with content, page scrolls as a whole
   * @default 'fill'
   */
  height?: 'fill' | 'auto';

  /**
   * Mobile navigation configuration.
   *
   * Accepts three shapes:
   * - **`false`** — Disable mobile nav entirely.
   * - **`MobileNavConfig` object** — Configure auto behavior (toggle, controlled state, custom content).
   * - **`ReactNode`** — Full escape hatch: provide your own `<MobileNav>` (you own everything).
   *
   * When omitted, AppShell automatically generates a mobile drawer with
   * sideNav content (and TopNav items in the future) below the breakpoint.
   *
   * @example
   * ```
   * <AppShell topNav={...} sideNav={...} />
   * <AppShell mobileNav={{ isOpen, onOpenChange }} />
   * <AppShell mobileNav={{ hasToggle: false }}>
   *   <MobileNavToggle />
   * </AppShell>
   * <AppShell mobileNav={<MobileNav header="Menu">...</MobileNav>} />
   * <AppShell mobileNav={false} />
   * ```
   */
  mobileNav?: false | MobileNavConfig | ReactNode;

  /**
   * Side navigation — typically an SideNav.
   *
   * Pass `undefined` (or omit) when a page has no side navigation.
   * Do NOT pass a component that renders `null` — AppShell treats any
   * renderable value as "sidenav exists".
   *
   * **Next.js parallel routes:** Conditionally pass the slot based on
   * the current route rather than relying on a `default.tsx` that
   * returns `null`:
   *
   * @example
   * ```
   * const SIDEBAR_ROUTES = ['/dashboard', '/settings'];
   * function Layout({ children, sidebar }) {
   *   const hasSidebar = SIDEBAR_ROUTES.some(r => pathname.startsWith(r));
   *   return (
   *     <AppShell
   *       sideNav={hasSidebar ? sidebar : undefined}
   *       mobileNav={hasSidebar ? { breakpoint: 'md' } : false}>
   *       {children}
   *     </AppShell>
   *   );
   * }
   * ```
   */
  sideNav?: ReactNode;

  /**
   * Top navigation — typically an TopNav.
   * Same contract as `sideNav` — pass `undefined` when there's no top nav.
   */
  topNav?: ReactNode;
}

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

const styles = stylex.create({
  root: {
    display: 'flex',
    flexDirection: 'column',
    position: 'relative',
    overflow: 'clip',
  },
  variantWash: {
    backgroundColor: colorVars['--color-background-body'],
  },
  variantSurface: {
    backgroundColor: colorVars['--color-background-surface'],
  },
  variantSection: {
    backgroundColor: colorVars['--color-background-surface'],
  },
  variantElevated: {
    backgroundColor: colorVars['--color-background-body'],
  },
  rootFill: {
    height: '100dvh',
  },
  rootAuto: {
    minHeight: '100dvh',
  },
  skipLink: {
    // Visually hidden by default, visible on focus (keyboard navigation)
    position: {
      default: 'absolute',
      ':focus': 'fixed',
    },
    width: {
      default: '1px',
      ':focus': 'auto',
    },
    height: {
      default: '1px',
      ':focus': 'auto',
    },
    paddingBlock: {
      default: 0,
      ':focus': spacingVars['--spacing-2'],
    },
    paddingInline: {
      default: 0,
      ':focus': spacingVars['--spacing-4'],
    },
    margin: {
      default: '-1px',
      ':focus': 0,
    },
    overflow: {
      default: 'hidden',
      ':focus': 'visible',
    },
    clipPath: {
      default: 'inset(50%)',
      ':focus': 'none',
    },
    whiteSpace: {
      default: 'nowrap',
      ':focus': 'normal',
    },
    borderWidth: 0,
    // Focus styles
    top: {
      default: 0,
      ':focus': spacingVars['--spacing-2'],
    },
    insetInlineStart: {
      default: 0,
      ':focus': spacingVars['--spacing-2'],
    },
    backgroundColor: colorVars['--color-background-surface'],
    color: colorVars['--color-text-accent'],
    zIndex: 9999,
    textDecoration: 'none',
    fontWeight: fontWeightVars['--font-weight-semibold'],
    fontSize: typeScaleVars['--text-body-size'],
  },
  // Programmatic focus target for the skip link. While main fits, it is only
  // focusable via tabIndex={-1} (never tabbable), so a focus ring around the
  // entire content area would be noise rather than guidance — suppress it.
  mainFocusTarget: {
    outline: {
      default: null,
      ':focus': 'none',
    },
  },
  // While main's focus ring shows, main follows the elevated surface's
  // rounded top-start corner, so the ring keeps the surface's shape instead of
  // drawing a square corner. Otherwise main keeps its corner and clips nothing.
  mainElevatedCorner: {
    borderStartStartRadius: {
      default: null,
      ':focus-visible': radiusVars['--radius-page'],
    },
  },
  // While main scrolls its overflowing content it is a keyboard stop, and
  // keyboard focus on it draws the standard ring, inset so the shell's own
  // clipping cannot hide it.
  mainScrollRegionInset: {
    outlineOffset: {
      default: '0',
      ':focus-visible': `calc(-1 * ${focusVars['--focus-outline-width']})`,
    },
  },

  elevatedBackdrop: {
    position: 'absolute',
    inset: 0,
    backgroundColor: colorVars['--color-background-surface'],
    borderStartStartRadius: radiusVars['--radius-page'],
    pointerEvents: 'none',
  },
  contentWrapper: {
    display: 'contents',
  },
  elevatedContentWrapper: {
    position: 'relative',
    display: 'flex',
    flex: 1,
    minHeight: 0,
    height: '100%',
  },
  contentBgSurface: {
    backgroundColor: colorVars['--color-background-surface'],
  },
  contentBgWash: {
    backgroundColor: colorVars['--color-background-body'],
  },
  contentBgTransparent: {
    backgroundColor: 'transparent',
    isolation: 'isolate',
  },
  navAreaWash: {
    backgroundColor: colorVars['--color-background-body'],
  },
  navAreaSurface: {
    backgroundColor: colorVars['--color-background-surface'],
  },
  banner: {
    flexShrink: 0,
  },
  hidden: {
    display: 'none',
  },
  autoMobileTopBar: {
    display: 'flex',
    alignItems: 'center',
    height: spacingVars['--spacing-12'],
    paddingInline: spacingVars['--spacing-2'],
  },
  // Sticky header for auto height mode. The header stays at its local
  // stacking level — Field-owned input surfaces contain their own local
  // z-index layers (AST-027), so no escalated page-level value is needed
  // for the header to paint above scrolled content.
  headerSticky: {
    position: 'sticky',
    top: 0,
    zIndex: 1,
  },
  // The insets are zero unless the page sets `viewport-fit=cover`. The header
  // background goes under the status bar and to the screen sides, as a UIKit
  // bar does.
  headerSafeAreaTop: {
    paddingBlockStart: 'env(safe-area-inset-top, 0px)',
  },
  // The insets are physical sides, so a right-to-left context swaps them on
  // the inline sides.
  headerSafeAreaSides: {
    paddingInlineStart: {
      default: 'env(safe-area-inset-left, 0px)',
      ':is([dir="rtl"] *)': 'env(safe-area-inset-right, 0px)',
    },
    paddingInlineEnd: {
      default: 'env(safe-area-inset-right, 0px)',
      ':is([dir="rtl"] *)': 'env(safe-area-inset-left, 0px)',
    },
  },
  // In `auto`, the banner's wrapper and the phone top bar both stick. Below a
  // banner, the bar sticks under the top inset, so its items stay clear of the
  // status bar.
  headerStickyBelowTopInset: {
    top: 'env(safe-area-inset-top, 0px)',
  },
  // Main adds the bottom inset to the padding that LayoutContent publishes for
  // `contentPadding`. The published value excludes the inset, so a bleed child
  // subtracts only `contentPadding`. Main is border-box, so a child that fills
  // it ends above the inset.
  mainSafeAreaEnd: {
    paddingBlockEnd:
      'calc(var(--container-padding-block-end, 0px) + env(safe-area-inset-bottom, 0px))',
  },
  // Sticky sideNav for auto height mode — sticks within the wrapper.
  // This div replaces the panel as the direct flex child of the middle
  // (horizontal) container, so it needs the same flex properties that
  // LayoutPanel applies: flexShrink: 0 prevents the flex container
  // from collapsing the sidenav, and overflow: clip matches the panel's
  // default so content doesn't bleed horizontally.
  sideNavSticky: {
    flexShrink: 0,
    overflow: 'clip',
    position: 'sticky',
    top: 'var(--_app-shell-header-height, 0px)',
    height: 'calc(100dvh - var(--_app-shell-header-height, 0px))',
    // Ensure children (LayoutPanel → SideNav) fill the sticky container
    display: 'flex',
    flexDirection: 'column',
  },
  // Panel fill for auto mode — panel fills the sticky container vertically
  // and scrolls independently since the page (not the panel) owns the scroll
  panelAutoFill: {
    flex: 1,
    overflow: 'auto',
  },
});

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

/**
 * Page shell for an application. Provides the structural frame for an app:
 * top navigation, side navigation, and main content area.
 *
 * Slot-based API with `topNav`, `sideNav`, `banner`, and `children`.
 * Supports two height modes (`fill` and `auto`), responsive side nav
 * collapse, and mobile overlay with backdrop.
 *
 * @example
 * ```
 * <AppShell
 *   topNav={<TopNav label="Navigation" heading={<TopNavHeading heading="My App" />} />}
 *   sideNav={<SideNav>{navSections}</SideNav>}
 *   mobileNav={
 *     <MobileNav isOpen={mobileOpen} onOpenChange={(open) => setMobileOpen(open)} header="My App">
 *       {navSections}
 *     </MobileNav>
 *   }>
 *   <Content />
 * </AppShell>
 * ```
 */

/**
 * The column beside the rail that holds `main`: its ancestor whose parent
 * also holds the rail. The glide moves it; the rail's edge rides it.
 */
function columnOf(main: HTMLElement, rail: HTMLElement | null): HTMLElement {
  let column = main;
  while (column.parentElement != null && !column.parentElement.contains(rail)) {
    column = column.parentElement;
  }
  return column;
}

export function AppShell({
  variant = 'elevated',
  banner,
  children,
  contentPadding,
  'data-testid': dataTestId,
  height = 'fill',
  mobileNav,
  sideNav,
  topNav,
  xstyle,
  className,
  style,
  ref,
  ...rest
}: AppShellProps) {
  const t = useComponentTranslator();
  const activeTheme = useThemeDefinition();
  // =========================================================================
  // Parse mobileNav prop — normalize to config, custom element, or disabled
  // =========================================================================
  const mobileNavDisabled = mobileNav === false;
  const mobileNavConfig: MobileNavConfig | null =
    mobileNav != null &&
    mobileNav !== false &&
    typeof mobileNav === 'object' &&
    !isValidElement(mobileNav)
      ? (mobileNav as MobileNavConfig)
      : null;
  const sideNavBreakpoint: AppShellBreakpoint =
    mobileNavConfig?.breakpoint ?? 'md';
  // ReactNode shorthand — user provides <MobileNav> directly as the prop
  const mobileNavReactNode: ReactNode | null =
    mobileNav != null &&
    mobileNav !== false &&
    (isValidElement(mobileNav) || typeof mobileNav === 'string')
      ? mobileNav
      : null;
  // Custom content from config object
  const mobileNavConfigContent: ReactNode | null =
    mobileNavConfig?.content ?? null;
  const mobileNavHasToggle = mobileNavConfig?.hasToggle !== false;
  const mobileNavIsControlled = mobileNavConfig?.isOpen !== undefined;

  // =========================================================================
  // Slot presence — checks whether slot containers have rendered DOM content.
  // Refs are attached to wrapper divs around each slot; a MutationObserver
  // checks childNodes to track whether each slot has rendered content.
  // =========================================================================

  // =========================================================================
  // Mobile nav open state (controlled + uncontrolled)
  // =========================================================================
  const activeWidthBreakpoints = activeTheme?.__adaptations?.widthBreakpoints;
  const breakpointQuery =
    sideNavBreakpoint === 'none'
      ? '(width < 0px)'
      : `(width < ${
          activeWidthBreakpoints?.[sideNavBreakpoint] ??
          DEFAULT_WIDTH_BREAKPOINTS[sideNavBreakpoint]
        }px)`;
  const isBelowBreakpoint = useMediaQuery(
    breakpointQuery,
    sideNavBreakpoint === 'none' ? false : mobileNavConfig?.defaultIsMobile,
  );
  const [uncontrolledMobileOpen, setUncontrolledMobileOpen] = useState(false);
  const isMobileNavOpen = mobileNavConfig?.isOpen ?? uncontrolledMobileOpen;

  // Holds the mobile nav's `Activity` boundary visible for a beat after a
  // close, so MobileNav's own close effect gets a real chance to run its
  // slide-out transition and schedule its delayed `dialog.close()` before
  // Activity hides the subtree (#5701). Only the CLOSE is deferred: opening
  // reads `isMobileNavOpen` directly below, so a controlled open is visible in
  // the commit that carries it instead of one effect later.
  const [isMobileNavCloseHeld, setIsMobileNavCloseHeld] =
    useState(isMobileNavOpen);
  // Arm the hold during render, from the open state itself, so no Effect has
  // to copy props into state; the Effect below only owns the release timer.
  if (isMobileNavOpen && !isMobileNavCloseHeld) {
    setIsMobileNavCloseHeld(true);
  }
  // Syncs the mobile-nav close hold with a timer. The hold ends after the
  // slide-out delay.
  useEffect(() => {
    if (!HasActivity || isMobileNavOpen) {
      return;
    }
    const delayMs = matchesMediaQuery(
      window,
      '(prefers-reduced-motion: reduce)',
    )
      ? 0
      : MOBILE_NAV_MAX_CLOSE_DELAY_MS + ACTIVITY_HIDE_BUFFER_MS;
    const timeout = setTimeout(() => {
      setIsMobileNavCloseHeld(false);
    }, delayMs);
    return () => clearTimeout(timeout);
  }, [isMobileNavOpen]);
  const isMobileNavActivityVisible = isMobileNavOpen || isMobileNavCloseHeld;

  const mobileNavOnOpenChange = mobileNavConfig?.onOpenChange;
  const setMobileNavOpen = useCallback(
    (open: boolean) => {
      if (!mobileNavIsControlled) {
        setUncontrolledMobileOpen(open);
      }
      mobileNavOnOpenChange?.(open);
    },
    // Depend on the callback itself, not on the config object: the documented
    // usage is an inline `mobileNav={{isOpen, onOpenChange}}` literal, which is
    // a new object every render and would otherwise churn this callback and the
    // context value memo built from it on every render of the shell.
    [mobileNavIsControlled, mobileNavOnOpenChange],
  );

  const mainContentId = useAppShellMainId();
  // Move focus to the main content container when the skip link is activated.
  // Hash navigation alone doesn't reliably move focus in every browser, so
  // focus the target explicitly (it's focusable via tabIndex={-1}).
  const handleSkipLinkClick = useCallback(() => {
    document.getElementById(mainContentId)?.focus();
  }, [mainContentId]);

  // Main draws its focus ring only for focus a Tab press moved onto it, and
  // keeps it for as long as that focus stays, even once the content fits.
  // Programmatic focus (the skip link, a script's focus() on a route change)
  // draws none (FR4), even after keyboard input, where :focus-visible alone
  // would match. See the effect below for how a Tab move is told apart.
  const [isTabFocus, setIsTabFocus] = useState(false);
  // A window or tab switch blurs main without moving focus off it: main stays
  // the document's active element, and focus comes back to it with no Tab
  // press. The ring holds across that round trip; any real focus move ends it.
  const isMainAwayRef = useRef(false);
  const handleMainBlur = useCallback(
    (event: React.FocusEvent<HTMLDivElement>) => {
      if (event.target !== event.currentTarget) {
        return;
      }
      if (document.activeElement === event.currentTarget) {
        isMainAwayRef.current = true;
        return;
      }
      isMainAwayRef.current = false;
      setIsTabFocus(false);
    },
    [],
  );

  const isFill = height === 'fill';
  const isAuto = height === 'auto';

  // With `fill`, main is the page's scroller. While its content overflows it
  // must be reachable from the keyboard even when nothing inside it is
  // focusable (AST-025 FR12): it joins the tab order, and Tab entry moves on
  // to its first link or button when it has one. Only `fill` observes main
  // (PR1); LayoutContent keeps owning main's overflow and styles.
  const [isMainOverflowing, setIsMainOverflowing] = useState(false);
  const isMainScrollRegion = isFill && isMainOverflowing;
  // Main's node is owned through a ref, never React state. Under `fill` its
  // overflow is observed while the node is attached, and while main is a
  // scroll region the keyboard delegation is attached to it. The ref callback
  // changes with `fill`, so switching modes detaches and re-attaches main in
  // the same commit; a detached or replaced node releases both before the new
  // node takes over.
  const mainNodeRef = useRef<HTMLDivElement | null>(null);
  const mainOverflowRef = useRef<{
    node: HTMLDivElement;
    stop: () => void;
  } | null>(null);
  const mainDelegationRef = useRef<{
    node: HTMLDivElement;
    release: () => void;
  } | null>(null);
  const isMainScrollRegionRef = useRef(isMainScrollRegion);
  const syncMainDelegation = useCallback(() => {
    const node = isMainScrollRegionRef.current ? mainNodeRef.current : null;
    const current = mainDelegationRef.current;
    if (current?.node === node) {
      return;
    }
    current?.release();
    mainDelegationRef.current =
      node == null
        ? null
        : {node, release: attachScrollKeyboardDelegation(node, node)};
  }, []);
  const setMainNode = useCallback(
    (node: HTMLDivElement | null) => {
      mainNodeRef.current = node;
      const observed = isFill ? node : null;
      const current = mainOverflowRef.current;
      if (current?.node !== observed) {
        current?.stop();
        mainOverflowRef.current =
          observed == null
            ? null
            : {
                node: observed,
                stop: observeMainOverflow(observed, setIsMainOverflowing),
              };
        if (observed == null) {
          setIsMainOverflowing(false);
        }
      }
      syncMainDelegation();
    },
    [isFill, syncMainDelegation],
  );
  useEffect(() => {
    isMainScrollRegionRef.current = isMainScrollRegion;
    syncMainDelegation();
  }, [isMainScrollRegion, syncMainDelegation]);

  // Nav style derived values
  const hasBanner = isRenderable(banner);
  const hasTopNav = isRenderable(topNav);
  const hasSideNav = isRenderable(sideNav);
  const hasNavContent = hasTopNav || hasSideNav;
  const mobileNavEnabled =
    !mobileNavDisabled && hasNavContent && mobileNavReactNode == null;
  const navHasDividers = variant === 'section';
  const isElevated = variant === 'elevated';
  const navAreaStyle =
    variant === 'wash' || variant === 'elevated'
      ? styles.navAreaWash
      : variant === 'surface'
        ? styles.navAreaSurface
        : undefined;
  // Section normally inherits the shell's surface background. Its auto-height
  // header needs to paint that surface itself while content scrolls beneath it.
  const headerAreaStyle =
    navAreaStyle ??
    (isAuto && variant === 'section' ? styles.navAreaSurface : undefined);
  const contentAreaStyle =
    variant === 'wash'
      ? styles.contentBgWash
      : variant === 'elevated' && hasTopNav && hasSideNav && !isBelowBreakpoint
        ? styles.contentBgTransparent
        : variant === 'surface' || variant === 'elevated'
          ? styles.contentBgSurface
          : undefined;

  // Background for sticky elements in auto mode — must be opaque so content
  // doesn't show through when scrolling underneath. Uses the nav area bg if
  // set, otherwise falls back to the shell variant bg (always surface for section).
  const stickyBgStyle = navAreaStyle ?? styles.navAreaSurface;

  // =========================================================================
  // Header height measurement for sticky sideNav offset (auto mode)
  // =========================================================================
  const headerRef = useRef<HTMLDivElement>(null);
  const shellRef = useRef<HTMLDivElement>(null);

  // Syncs the header-height CSS variable with a ResizeObserver while the height
  // is automatic.
  useEffect(() => {
    if (!isAuto || !headerRef.current || !shellRef.current) {
      return;
    }

    const headerEl = headerRef.current;
    const shellEl = shellRef.current;

    const updateHeight = () => {
      const height = headerEl.getBoundingClientRect().height;
      shellEl.style.setProperty('--_app-shell-header-height', `${height}px`);
    };

    return observeResize(headerEl, () => updateHeight());
  }, [isAuto]);

  // =========================================================================
  // Determine if sideNav should show as overlay (mobile) or inline
  // =========================================================================
  const showSideNavInline = hasSideNav && !isBelowBreakpoint;

  // Mobile nav rendering modes:
  // 1. ReactNode shorthand — user provided <MobileNav> directly
  const shouldRenderMobileNavReactNode = mobileNavReactNode != null;
  // 2. Config with custom content
  const shouldRenderConfigContent =
    mobileNavEnabled && mobileNavConfigContent != null && isBelowBreakpoint;

  // =========================================================================
  // Mobile context — shared with MobileNavToggle and future TopNav mobile
  // =========================================================================
  // Stable id shared by the drawer (applied as its `id`) and the toggle
  // (referenced via `aria-controls`) so screen readers know what it controls.
  const mobileNavId = useId();
  const mobileContextValue = useMemo<AppShellMobileContextValue>(
    () => ({
      isMobile: isBelowBreakpoint,
      isMobileNavOpen,
      mobileNavId,
      toggleMobileNav: () =>
        mobileNavEnabled && setMobileNavOpen(!isMobileNavOpen),
      openMobileNav: () => mobileNavEnabled && setMobileNavOpen(true),
      closeMobileNav: () => setMobileNavOpen(false),
      isMobileNavEnabled: mobileNavEnabled,
      hasAutoToggle: mobileNavHasToggle,
    }),
    [
      isBelowBreakpoint,
      isMobileNavOpen,
      mobileNavId,
      setMobileNavOpen,
      mobileNavEnabled,
      mobileNavHasToggle,
    ],
  );

  // =========================================================================
  // Build header content (topNav + banner)
  //
  // In auto mode, the header wrapper gets sticky positioning so the topNav
  // stays pinned while the page scrolls. The ref is used to measure header
  // height for the sideNav's sticky offset.
  // =========================================================================
  // When below breakpoint, TopNav renders in mobile-bar mode (heading + endContent + toggle).
  // Wrap with mobile content context so TopNav knows there's SideNav content
  // in the drawer and shows the toggle even without its own collapsible items.
  const mobileContentValue =
    hasSideNav && mobileNavHasToggle ? (
      // eslint-disable-next-line @eslint-react/no-unstable-context-value -- context transports ReactNode; instability is inherent
      <SideNavRenderContext value="drawer-content">
        {sideNav}
      </SideNavRenderContext>
    ) : null;

  const drawerMobileContentValue = hasSideNav ? (
    // eslint-disable-next-line @eslint-react/no-unstable-context-value -- context transports ReactNode; instability is inherent
    <SideNavRenderContext value="drawer-content">
      {sideNav}
    </SideNavRenderContext>
  ) : null;

  const topNavContent = hasTopNav ? (
    isBelowBreakpoint && !mobileNavDisabled && mobileNavReactNode == null ? (
      <TopNavMobileContentContext value={mobileContentValue}>
        <TopNavRenderContext value="mobile-bar">{topNav}</TopNavRenderContext>
      </TopNavMobileContentContext>
    ) : (
      topNav
    )
  ) : null;

  const headerInner =
    hasTopNav || hasBanner ? (
      <LayoutHeader padding={0} hasDivider={navHasDividers && hasTopNav}>
        {hasBanner && (
          <div {...stylex.props(styles.banner, navAreaStyle)}>{banner}</div>
        )}
        {hasTopNav && topNavContent}
      </LayoutHeader>
    ) : undefined;

  const headerContent = isRenderable(headerInner) ? (
    <div
      ref={headerRef}
      // Top-level banner landmark for the header region (topNav + banner).
      // Safe here: the wrapper is never nested inside main/nav/other landmarks.
      role="banner"
      {...mergeProps(
        themeProps('app-shell-header', {variant}),
        stylex.props(
          headerAreaStyle,
          isAuto && styles.headerSticky,
          styles.headerSafeAreaTop,
          styles.headerSafeAreaSides,
        ),
      )}>
      {headerInner}
    </div>
  ) : undefined;

  // =========================================================================
  // While the inline side nav collapses or expands, the content area holds
  // its own animated layout handle (`component:AppShell` FR17): the column
  // beside the rail glides from its old place, and the content swaps its old
  // wrap for its new one in place (`spec:AST-105` FR8), on the rail's clock
  // (`component:SideNav` FR6).
  const railRef = useRef<HTMLDivElement>(null);
  const mainRef = useRef<HTMLDivElement>(null);
  // Main's node goes to the glide above and to the overflow observation
  // that, under `fill`, makes main a keyboard stop.
  const mainRefs = useMergedRefs(mainRef, setMainNode);
  const backdropRef = useRef<HTMLDivElement>(null);
  const contentLayout = useAnimatedLayout({containerRef: shellRef});
  const pendingContentRef = useRef<{
    /** The column's glide, reported only for a spring motion. */
    change: LayoutChange | null;
    swap: LayoutSwap | null;
    before: DOMRect;
    /** The opacities the held and the entering wrap start from. */
    held: number;
    entering: number;
  } | null>(null);
  // The running swap: when it started and its wraps' starting opacities, so a
  // change made during it starts its cross-fade from what the content shows.
  const lastSwapRef = useRef<{
    startedAt: number;
    held: number;
    entering: number;
  } | null>(null);
  const sideNavShell = useMemo<SideNavShell>(
    () => ({
      animatedLayout: contentLayout,
      rail: () => railRef.current,
      column: () =>
        mainRef.current == null
          ? null
          : columnOf(mainRef.current, railRef.current),
      landContent() {
        if (mainRef.current != null) {
          landLayoutGlide(columnOf(mainRef.current, railRef.current));
        }
      },
      beforeRailChange() {
        const main = mainRef.current;
        if (main == null) {
          return;
        }
        const motion = layoutMotionFor(main);
        // Only a glide moves the column; under Reduce Motion the two wraps
        // cross-fade over a steady surface (`design:reduced-motion` DR2).
        let change: LayoutChange | null = null;
        if (motion.kind === 'glide') {
          change = reportLayoutChange(contentLayout, railRef);
          change.measureBefore();
        }
        // At rest the copy (the wrap shown now) starts opaque and the entering
        // wrap unseen; mid-swap the wrap in the DOM is the entering one and
        // the copy's wrap is the one entering next, each at what it shows.
        let held = 1;
        let entering = 0;
        const last = lastSwapRef.current;
        if (last != null && motion.kind === 'glide') {
          // Read at the change's own start, where the glide it retargets
          // carries on. After a block, that is later than the frame the
          // timeline still reads.
          const elapsed = Math.max(
            0,
            layoutStartFor(main.ownerDocument) - last.startedAt,
          );
          if (elapsed < motion.progress.durationMs) {
            const p = 1 - motion.progress.remaining(elapsed);
            held = last.entering + (1 - last.entering) * p;
            entering = last.held * (1 - p);
          }
        }
        lastSwapRef.current = null;
        pendingContentRef.current = {
          change,
          swap: holdLayoutSwap(contentLayout, main, {isVisiblePart: true}),
          before: main.getBoundingClientRect(),
          held,
          entering,
        };
      },
      afterRailChange() {
        const pending = pendingContentRef.current;
        pendingContentRef.current = null;
        const main = mainRef.current;
        if (pending == null || main == null) {
          return () => {};
        }
        pending.change?.animate();
        // The column beside the rail, which the glide moves: the copy sits
        // beside it, in its parent, and rides its glide.
        const column = columnOf(main, railRef.current);
        const after = main.getBoundingClientRect();
        const isRtl = getComputedStyle(main).direction === 'rtl';
        const travel = isRtl
          ? pending.before.right - after.right
          : pending.before.left - after.left;
        // An expand slides the narrower column in from its old start, which
        // opens a gap at its trailing edge: the content surface (the elevated
        // backdrop, or the main element) reaches over it as it closes,
        // whether or not the old wrap is held.
        const cover: {element: Element; frames: (p: number) => Keyframe}[] = [];
        const surface = backdropRef.current ?? main;
        const color = getComputedStyle(surface).backgroundColor;
        const isPainted = !/^rgba\(.*,\s*0\)$|^transparent$/.test(color);
        const glides = layoutMotionFor(main).kind === 'glide';
        if ((isRtl ? travel > 0 : travel < 0) && glides && isPainted) {
          cover.push({
            element: surface,
            frames: p => ({
              boxShadow: `${-travel * (1 - p)}px 0px 0px 0px ${color}`,
            }),
          });
        }
        if (pending.swap == null || column.parentElement == null) {
          return playLayoutFrames(contentLayout, cover);
        }
        // Under Reduce Motion nothing glides: the old wrap's copy paints the
        // surface it sat on, so that surface fades out with it where it was
        // (`design:reduced-motion` DR2) instead of leaving a bare strip.
        if (!glides && isPainted) {
          pending.swap.copy.style.backgroundColor = color;
        }
        const {held, entering} = pending;
        lastSwapRef.current = {
          startedAt: layoutStartFor(main.ownerDocument),
          held,
          entering,
        };
        return playLayoutSwap(pending.swap, {
          host: column.parentElement,
          copy: p => ({opacity: held * (1 - p)}),
          rideWith: {element: column, travel: {x: travel, y: 0}},
          incoming: [
            ...Array.from(main.children, element => ({
              element,
              frames: (p: number) => ({opacity: entering + (1 - entering) * p}),
            })),
            ...cover,
          ],
        });
      },
    }),
    [contentLayout],
  );

  // Build sideNav content
  //
  // In auto mode, the sideNav panel is not internally scrollable (the page
  // scrolls as a whole), but it gets sticky positioning so it stays pinned
  // below the header while the main content scrolls. A wrapper div applies
  // the sticky behavior since LayoutPanel doesn't accept style/className.
  // =========================================================================
  const sideNavPanel = showSideNavInline ? (
    <LayoutPanel
      ref={railRef}
      padding={0}
      hasDivider={navHasDividers}
      isScrollable={isFill}
      {...themeProps('app-shell-sidenav', {variant})}
      xstyle={[
        navAreaStyle,
        isAuto && stickyBgStyle,
        isAuto && styles.panelAutoFill,
      ]}>
      <SideNavShellContext value={sideNavShell}>{sideNav}</SideNavShellContext>
    </LayoutPanel>
  ) : undefined;

  const sideNavContent =
    sideNavPanel != null && isAuto ? (
      <div {...stylex.props(styles.sideNavSticky)}>{sideNavPanel}</div>
    ) : (
      sideNavPanel
    );

  // =========================================================================
  // Build main content
  // =========================================================================
  const shouldElevateWithCorner = isElevated && hasTopNav && showSideNavInline;
  // While main is a keyboard stop, a Tab keydown anywhere in the document
  // (capture, so Shift+Tab from the page start counts too) marks the next
  // focus move, and so does the window's focus event for keyboard focus that
  // enters the document from outside (Tab or Shift+Tab from the page
  // embedding this one), where the browser's own `:focus-visible` then tells
  // a key from a pointer. A mark counts only once its event's dispatch has
  // finished uncancelled (`eventPhase === 0`): the browser's own focus move
  // follows that dispatch in the same task, while a focus() a page's handler
  // calls during it is programmatic and draws no ring (FR4). The marks expire
  // on a zero-delay timer, so a cancelled Tab, a Tab out of the document or a
  // window focus with nothing focused leaves nothing for a later focus().
  useEffect(() => {
    if (!isMainScrollRegion) {
      return;
    }
    let tabKeydown: KeyboardEvent | null = null;
    let windowFocus: FocusEvent | null = null;
    let expiry: ReturnType<typeof setTimeout> | undefined;
    const expireMarks = () => {
      clearTimeout(expiry);
      expiry = setTimeout(() => {
        tabKeydown = null;
        windowFocus = null;
      }, 0);
    };
    const onKeyDown = (event: KeyboardEvent) => {
      tabKeydown = event.key === 'Tab' ? event : null;
      windowFocus = null;
      expireMarks();
    };
    const onPointerDown = () => {
      tabKeydown = null;
      windowFocus = null;
    };
    const onWindowFocus = (event: FocusEvent) => {
      windowFocus = event;
      expireMarks();
    };
    const onFocusIn = (event: FocusEvent) => {
      // Still dispatching: this focus move is a handler's focus(), so it
      // reads no mark and leaves the mark for the browser's own move.
      const tabDone = tabKeydown != null && tabKeydown.eventPhase === 0;
      const focusDone = windowFocus != null && windowFocus.eventPhase === 0;
      const arrivedByTab = tabDone && tabKeydown?.defaultPrevented === false;
      const enteredDocument = focusDone;
      if (tabDone) {
        tabKeydown = null;
      }
      if (focusDone) {
        windowFocus = null;
      }
      const main = mainNodeRef.current;
      const isMain = event.target != null && event.target === main;
      if (isMainAwayRef.current) {
        // Focus comes back after a window or tab switch (main keeps the ring
        // it had), or lands elsewhere (main's ring is over).
        isMainAwayRef.current = false;
        if (isMain && !arrivedByTab) {
          return;
        }
        if (!isMain) {
          setIsTabFocus(false);
          return;
        }
      }
      if (isMain) {
        setIsTabFocus(
          arrivedByTab || (enteredDocument && main.matches(':focus-visible')),
        );
      }
    };
    document.addEventListener('keydown', onKeyDown, true);
    document.addEventListener('pointerdown', onPointerDown, true);
    document.addEventListener('focusin', onFocusIn, true);
    window.addEventListener('focus', onWindowFocus);
    return () => {
      document.removeEventListener('keydown', onKeyDown, true);
      document.removeEventListener('pointerdown', onPointerDown, true);
      document.removeEventListener('focusin', onFocusIn, true);
      window.removeEventListener('focus', onWindowFocus);
      clearTimeout(expiry);
    };
  }, [isMainScrollRegion]);

  // Tab focus on main draws the ring until main loses focus; programmatic
  // focus never does (FR4).
  const drawsMainFocusRing = isTabFocus;

  const mainInner = (
    <LayoutContent
      ref={mainRefs}
      padding={contentPadding ?? 0}
      role="main"
      id={mainContentId}
      // Focusable skip-link target (WCAG 2.4.1) — without tabIndex, several
      // browsers won't move focus to the div when the skip link is activated.
      // A keyboard stop only while it scrolls overflowing content.
      tabIndex={isMainScrollRegion ? 0 : -1}
      isScrollable={isFill}
      onBlur={handleMainBlur}
      xstyle={[
        contentAreaStyle,
        drawsMainFocusRing &&
          shouldElevateWithCorner &&
          styles.mainElevatedCorner,
        drawsMainFocusRing
          ? [focusOutlineStyles.focusVisible, styles.mainScrollRegionInset]
          : styles.mainFocusTarget,
        styles.mainSafeAreaEnd,
      ]}>
      <AppShellNestingContext value={true}>{children}</AppShellNestingContext>
    </LayoutContent>
  );

  // Keep the parent and mainInner's position stable across breakpoints. Outside
  // the elevated desktop layout, the wrapper generates no layout box.
  const mainContent = (
    <div
      {...stylex.props(
        shouldElevateWithCorner
          ? styles.elevatedContentWrapper
          : styles.contentWrapper,
      )}>
      {shouldElevateWithCorner && (
        <div ref={backdropRef} {...stylex.props(styles.elevatedBackdrop)} />
      )}
      {mainInner}
    </div>
  );

  // =========================================================================
  // Render
  //
  // TODO: Include root providers (ThemeProvider, ProseProvider, LayerProvider)
  // at the app level once they're available for wrapping.
  // =========================================================================
  // =========================================================================
  // Build auto mobile nav hamburger for TopNav
  // Injected into the headerContent when mobileNav is enabled and hasToggle
  // =========================================================================
  const shouldShowAutoToggle =
    !mobileNavDisabled && mobileNavHasToggle && isBelowBreakpoint;

  // For sidenav-only layouts with no TopNav, render the sideNav in topbar
  // mode — it shows heading + footer icons horizontally, with the hamburger
  const autoMobileTopBar =
    shouldShowAutoToggle && !hasTopNav && hasSideNav ? (
      <div
        // Banner landmark for the mobile top bar, so the sidenav-only layout
        // exposes the same landmark structure as the topNav one. Only when
        // there is no headerContent: a banner slot with no topNav renders both,
        // and two sibling banner regions is worse than the one this restores.
        role={headerContent == null ? 'banner' : undefined}
        {...mergeProps(
          themeProps('app-shell-header', {variant}),
          stylex.props(
            headerAreaStyle,
            isAuto && styles.headerSticky,
            styles.headerSafeAreaSides,
            // Under a banner, the banner's wrapper pads the top inset. This top
            // bar takes only the side insets.
            headerContent == null && styles.headerSafeAreaTop,
            isAuto && headerContent != null && styles.headerStickyBelowTopInset,
          ),
        )}>
        <LayoutHeader padding={0} hasDivider={navHasDividers}>
          <div
            {...stylex.props(styles.autoMobileTopBar)}
            role="navigation"
            aria-label={t('@astryx.appShell.mobileNavigation')}>
            <SideNavRenderContext value="topbar">
              {sideNav}
            </SideNavRenderContext>
            <MobileNavToggle />
          </div>
        </LayoutHeader>
      </div>
    ) : undefined;

  return (
    <AppShellMobileContext value={mobileContextValue}>
      <div
        {...rest}
        ref={useMergedRefs(ref, shellRef)}
        data-testid={dataTestId}
        {...mergeProps(
          themeProps('app-shell', {variant}),
          stylex.props(
            styles.root,
            // A layout root (FR18): nothing an ancestor Layout, Card or
            // Section publishes reaches the shell (component:Layout FR8).
            layoutReset,
            variant === 'wash'
              ? styles.variantWash
              : variant === 'surface'
                ? styles.variantSurface
                : variant === 'section'
                  ? styles.variantSection
                  : styles.variantElevated,
            isFill ? styles.rootFill : styles.rootAuto,
            xstyle,
          ),
          className,
          style,
        )}>
        {/* The Layout area, slot and divider defaults an ancestor Layout
            provides stop at the root too, for every child (FR18). */}
        <LayoutAreaContext value={null}>
          <LayoutSlotsContext value={DEFAULT_LAYOUT_SLOTS}>
            <LayoutDividerContext value={null}>
              {/* Skip-to-content link */}
              <a
                href={`#${mainContentId}`}
                onClick={handleSkipLinkClick}
                {...focusOutlineProps.focusVisible(styles.skipLink)}
                data-testid="skip-to-content">
                {t('@astryx.appShell.skipToContent')}
              </a>

              <Layout
                height={height}
                padding={0}
                header={
                  <>
                    {headerContent}
                    {autoMobileTopBar}
                  </>
                }
                start={sideNavContent}
                content={mainContent}
              />

              {/* Mobile nav — always mounted below breakpoint via Activity so DOM
            presence detection works. Hidden until the drawer opens. */}
              {shouldRenderMobileNavReactNode && mobileNavReactNode}
              {shouldRenderConfigContent && mobileNavConfigContent}
              {isBelowBreakpoint &&
                !mobileNavDisabled &&
                mobileNavReactNode == null &&
                !mobileNavConfigContent && (
                  <ActivityWrapper
                    mode={isMobileNavActivityVisible ? 'visible' : 'hidden'}>
                    {/* SideNav drawer — always mounted so presence detection works.
                Hidden when TopNav owns the drawer (combined mode passes
                sideNav via TopNav's mobile content context instead). */}
                    {hasSideNav && !hasTopNav && (
                      <SideNavRenderContext value="drawer">
                        {sideNav}
                      </SideNavRenderContext>
                    )}
                    {hasTopNav && (
                      <TopNavMobileContentContext
                        value={drawerMobileContentValue}>
                        <TopNavRenderContext value="drawer">
                          {topNav}
                        </TopNavRenderContext>
                      </TopNavMobileContentContext>
                    )}
                  </ActivityWrapper>
                )}
            </LayoutDividerContext>
          </LayoutSlotsContext>
        </LayoutAreaContext>
      </div>
    </AppShellMobileContext>
  );
}

AppShell.displayName = 'AppShell';