Skip to content

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

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

'use client';

/**
 * Theme Provider Component
 *
 * Applies theme tokens and sets color-scheme for light-dark() to work.
 * Themes are created with `defineTheme()` and applied via CSS:
 * - Token overrides set as CSS custom properties on [data-astryx-theme]
 * - Component overrides scoped via @scope'd CSS selectors on stable Astryx
 *   target classes combined with reflected `data-*` prop/state attributes
 *
 * Root detection: The first Theme in the tree (no parent Theme)
 * automatically syncs attributes to `document.documentElement`:
 * - `data-theme` — drives `color-scheme` via reset.css rules, ensuring browser
 *   chrome (scrollbars, native form controls, date pickers) reflects the mode.
 * - `data-astryx-theme` — enables @scope'd theme CSS to reach elements rendered
 *   outside the Theme wrapper (portals, toast fallback viewports).
 *
 * The root Theme also reads the reader's text size (iOS Dynamic Type) from a
 * hidden, empty `font: -apple-system-body` probe and keeps the page's scales
 * in an adopted stylesheet; every theme's font sizes follow them, and no
 * attribute is written (see dynamicType.ts).
 *
 * For RSC / SSR, set `data-theme` on `<html>` in your root server layout
 * to avoid a flash of wrong theme before hydration:
 *
 *   <html lang="en" data-theme="dark">
 *
 * @example
 * ```
 * const ocean = defineTheme({
 *   name: 'ocean',
 *   tokens: { '--color-accent': ['#0077B6', '#48CAE4'] },
 *   components: { card: { base: { borderWidth: '2px' } } },
 *   icons: oceanIcons,
 * });
 * <Theme theme={ocean}><App /></Theme>
 * ```
 */

import React, {use, useId, useInsertionEffect, useMemo, useState} from 'react';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import * as stylex from '@stylexjs/stylex';
import type {ThemeMode} from './types';
import {colorVars, typographyVars} from './tokens.stylex';
import {generateThemeCSS, type DefinedTheme} from './defineTheme';
import {registerTheme} from './themeRegistry';
import {dataAttr} from '../naming';
import {syncReaderTextSize} from './dynamicType';
import {ThemeContext} from './useTheme';
import {warnOnce} from '../utils/devWarning';
import {REDUCED_MOTION_PROPERTY, resolveMotionKnobs} from './themeMotion';
import {
  reducedMotionMarkProps,
  setRootReducedMotionMark,
} from '../privateAttributes/reducedMotion.stylex';
import {createSharedContext} from '../utils/sharedContext';

/**
 * Theme provider props
 */
interface ThemeProps {
  /** Theme from defineTheme() */
  theme: DefinedTheme;
  /** Color mode - 'system' follows OS preference */
  mode?: ThemeMode;
  /** Children to render */
  children: React.ReactNode;
}

/**
 * Styles for the theme wrapper
 */
const wrapperStyles = stylex.create({
  base: {
    display: 'contents',
    color: colorVars['--color-text-primary'],
    fontFamily: typographyVars['--font-family-body'],
  },
  light: {
    colorScheme: 'light',
  },
  dark: {
    colorScheme: 'dark',
  },
  system: {
    colorScheme: 'light dark',
  },
  // The mark's custom property (REDUCED_MOTION_PROPERTY), which every element
  // under the mark inherits.
  reducedMotion: {
    '--_astryx-reduced-motion': '1',
  },
});

// =============================================================================
// Nesting context — detect root vs nested Theme
// =============================================================================

/**
 * True below a Theme; the root Theme (no parent context) syncs data-theme
 * to <html>. A detached React root that conceptually sits inside the app
 * (useToast's fallback viewport) provides it as `true` itself, so a Theme
 * rendered in toast content themes its subtree without claiming <html> as
 * if it were the app's root Theme.
 * @internal Not exported from the theme barrel; useToast imports it from
 * './theme/Theme' directly.
 */
export const ThemeNestingContext = createSharedContext(
  'ThemeNestingContext',
  1,
  false,
);
ThemeNestingContext.displayName = 'ThemeNestingContext';

// =============================================================================
// Style injection for unbuilt themes
// =============================================================================

/**
 * The CSS is shared by the whole document. Remove it only when the last
 * `Theme` that uses it unmounts.
 */
interface InjectedTheme {
  /**
   * Each mounted `Theme` that uses this name, with its theme and id. The key
   * is one object per `Theme` instance: `useId` values can repeat across
   * separate React roots.
   */
  users: Map<object, {theme: DefinedTheme; id: string}>;
  /** The `Theme` whose theme is in the document. */
  owner: object;
  /**
   * The owner that last handed the CSS over. When the same `Theme` sets up
   * again in the same commit (its own theme changed), it takes the CSS back.
   */
  formerOwner: object | null;
  /** The theme whose CSS is in the document. */
  theme: DefinedTheme;
  styles: HTMLStyleElement[];
}
const injectedThemes = new Map<string, InjectedTheme>();
const THEME_LAYER_ORDER = '@layer reset, astryx-base, astryx-theme;';

function writeThemeStyles(theme: DefinedTheme, id: string): HTMLStyleElement[] {
  const {prose, component} = generateThemeCSS(theme);
  const styles: HTMLStyleElement[] = [];

  // Prose defaults go into @layer reset — lowest priority, scoped to
  // the theme region. Any class-based style (StyleX, .xds-*) wins.
  if (prose) {
    const proseStyle = document.createElement('style');
    proseStyle.setAttribute(dataAttr('theme-prose'), theme.name);
    proseStyle.setAttribute(dataAttr('id'), id);
    proseStyle.textContent = `${THEME_LAYER_ORDER}\n@layer reset {\n${prose}\n}`;
    document.head.appendChild(proseStyle);
    styles.push(proseStyle);
  }

  // Component overrides go into @layer astryx-theme — above StyleX layers
  // so themes can intentionally restyle components.
  if (component) {
    const compStyle = document.createElement('style');
    compStyle.setAttribute(dataAttr('theme'), theme.name);
    compStyle.setAttribute(dataAttr('id'), id);
    compStyle.textContent = `${THEME_LAYER_ORDER}\n@layer astryx-theme {\n${component}\n}`;
    document.head.appendChild(compStyle);
    styles.push(compStyle);
  }
  return styles;
}

/** Replace an entry's CSS with `theme`'s. */
function rewriteThemeStyles(
  entry: InjectedTheme,
  theme: DefinedTheme,
  id: string,
): void {
  for (const style of entry.styles) {
    style.remove();
  }
  entry.theme = theme;
  entry.styles = writeThemeStyles(theme, id);
}

/**
 * Hook to inject theme CSS into the document.
 * Built themes (from `astryx theme build`) skip injection — their CSS
 * is in a separate file imported by the consumer.
 */
function useThemeStyleInjection(theme: DefinedTheme): void {
  const id = useId();
  const [instance] = useState(() => ({}));

  // Syncs the document's stylesheets with the runtime theme CSS.
  useInsertionEffect(() => {
    // Built themes have their CSS in a separate file — skip injection
    if (theme.__built) {
      return;
    }

    const themeKey = `astryx-theme-${theme.name}`;
    let entry = injectedThemes.get(themeKey);
    if (entry == null) {
      // One-time perf hint per theme
      warnOnce(
        `theme-injection:${theme.name}`,
        'Theme',
        `"${theme.name}" is using runtime style injection. ` +
          `For better performance, use the pre-built theme:\n\n` +
          `  import {${theme.name}Theme} from '@astryxdesign/theme-${theme.name}/built';\n` +
          `  import '@astryxdesign/theme-${theme.name}/theme.css';\n\n` +
          `For custom themes, run \`npx @astryxdesign/cli theme build <file>\` to generate ` +
          `the built artifacts.`,
      );
      entry = {
        users: new Map(),
        owner: instance,
        formerOwner: null,
        theme,
        styles: writeThemeStyles(theme, id),
      };
      injectedThemes.set(themeKey, entry);
    }
    // A later `Theme` does no generation. The CSS of the first `Theme` that
    // injected the name stays in the document.
    entry.users.set(instance, {theme, id});
    if (entry.formerOwner === instance) {
      // The owner's own theme changed: its new definition paints, as on main.
      entry.owner = instance;
      entry.formerOwner = null;
      if (entry.theme !== theme) {
        rewriteThemeStyles(entry, theme, id);
      }
    }
    const current = entry;

    return () => {
      current.users.delete(instance);
      if (current.users.size === 0) {
        for (const style of current.styles) {
          style.remove();
        }
        injectedThemes.delete(themeKey);
        return;
      }
      if (current.owner !== instance) {
        return;
      }
      // The earliest-mounted `Theme` that remains takes over the CSS. If its
      // theme differs, as after a redefinition under the same name, its CSS
      // replaces the old one.
      const [nextOwner, next] = [...current.users][0];
      current.owner = nextOwner;
      current.formerOwner = instance;
      if (next.theme !== current.theme) {
        rewriteThemeStyles(current, next.theme, next.id);
      }
    };
  }, [theme, id, instance]);
}

// =============================================================================
// Root color-scheme sync
// =============================================================================

/**
 * Hook to sync theme attributes to document.documentElement for the root provider.
 * Skipped for nested Theme instances.
 *
 * Syncs two attributes:
 * - `data-theme` (light/dark) — reset.css maps this to color-scheme, controlling
 *   browser chrome (scrollbars, native form controls, date pickers).
 * - `data-astryx-theme` (theme name) — enables @scope'd theme CSS to reach elements
 *   outside the Theme wrapper (e.g. toast fallback viewports, portals).
 *
 * - 'light' | 'dark' → sets data-theme="light" | "dark"
 * - 'system' → removes data-theme (reset.css defaults to color-scheme: light dark)
 *
 * A theme that reduces motion for everyone also marks `<html>` with
 * `data-astryx-reduced-motion` and its custom property, so layers portaled
 * outside the wrapper reduce their motion too.
 */
function useRootThemeSync(
  isNested: boolean,
  mode: ThemeMode,
  themeName: string,
  reducesMotion: boolean,
): void {
  // Syncs the theme attributes on the root `<html>` element.
  useIsomorphicLayoutEffect(() => {
    if (isNested) {
      return;
    }
    if (typeof document === 'undefined') {
      return;
    }

    if (mode === 'light' || mode === 'dark') {
      document.documentElement.setAttribute('data-theme', mode);
    } else {
      // system — remove attribute, let reset.css default apply
      document.documentElement.removeAttribute('data-theme');
    }

    // Sync theme name so @scope rules reach portals/fallback viewports.
    document.documentElement.setAttribute(dataAttr('theme'), themeName);
    setRootReducedMotionMark(document.documentElement, reducesMotion);
    if (reducesMotion) {
      document.documentElement.style.setProperty(REDUCED_MOTION_PROPERTY, '1');
    } else {
      document.documentElement.style.removeProperty(REDUCED_MOTION_PROPERTY);
    }

    return () => {
      document.documentElement.removeAttribute('data-theme');
      document.documentElement.removeAttribute(dataAttr('theme'));
      setRootReducedMotionMark(document.documentElement, false);
      document.documentElement.style.removeProperty(REDUCED_MOTION_PROPERTY);
    };
  }, [isNested, mode, themeName, reducesMotion]);
}

/**
 * Hook to keep the page's text size scales on the reader's text size (iOS
 * Dynamic Type, or `env(preferred-text-scale)` elsewhere) for the root
 * provider; see dynamicType.ts. Skipped for nested Theme instances.
 */
function useRootTextSizeSync(isNested: boolean): void {
  useIsomorphicLayoutEffect(() => {
    if (isNested || typeof document === 'undefined') {
      return;
    }
    return syncReaderTextSize(document);
  }, [isNested]);
}

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

/**
 * Theme provider component
 *
 * Sets data-astryx-theme attribute so @scope'd CSS takes effect.
 * Component overrides are pure CSS scoped under the theme attribute —
 * components render with stable `.xds-*` classes plus `data-*` prop
 * reflections and don't need context.
 *
 * When this is the root Theme (no parent Theme in the tree),
 * it syncs `data-theme` and `data-astryx-theme` to `<html>` so browser
 * chrome reflects the active mode and @scope'd CSS reaches portals.
 * Nested Theme instances skip the sync.
 */
export function Theme({
  theme,
  mode = 'system',
  children,
}: ThemeProps): React.ReactElement {
  const isNested = use(ThemeNestingContext);

  registerTheme(theme);

  useThemeStyleInjection(theme);
  // resolveMotionKnobs resolves no public theme to 'always', so no theme
  // marks its root.
  const reducesMotion =
    resolveMotionKnobs(theme.__axes?.motion).reducedMotion === 'always';
  useRootThemeSync(isNested, mode, theme.name, reducesMotion);
  useRootTextSizeSync(isNested);

  // Get color-scheme style
  const colorSchemeStyle =
    mode === 'dark'
      ? wrapperStyles.dark
      : mode === 'light'
        ? wrapperStyles.light
        : wrapperStyles.system;

  // Memoize the context value to prevent unnecessary re-renders
  const ctxValue = useMemo(() => ({theme, mode}), [theme, mode]);

  return (
    <ThemeContext value={ctxValue}>
      <ThemeNestingContext value={true}>
        <div
          {...stylex.props(
            wrapperStyles.base,
            colorSchemeStyle,
            reducesMotion && wrapperStyles.reducedMotion,
          )}
          data-astryx-theme={theme.name}
          {...reducedMotionMarkProps(reducesMotion)}
          data-theme={mode === 'system' ? undefined : mode}>
          {children}
        </div>
      </ThemeNestingContext>
    </ThemeContext>
  );
}

Theme.displayName = 'Theme';