Skip to content

The Open Standard for Generative UI

9.1 KB
Raw Blame
import React, { createContext, useContext, useId, useInsertionEffect, useMemo } from "react";
import { defaultDarkTheme, defaultLightTheme } from "./defaultTheme";
import { Theme, ThemeMode } from "./types";
import { KNOWN_THEME_KEYS, themeToCssVars } from "./utils";

/**
 * Props for the {@link ThemeProvider} component.
 */
export type ThemeProps = {
  /** Active color scheme. Defaults to the parent ThemeProvider mode when nested, otherwise `"light"`. */
  mode?: ThemeMode;
  /** Application content rendered inside the theme context. */
  children?: React.ReactNode;
  /**
   * Partial overrides for **light** mode, merged onto the built-in light
   * defaults.  Omitted keys fall back to the built-in defaults.
   * Preferred over the deprecated `theme` prop.
   */
  lightTheme?: Theme;
  /**
   * Partial overrides for **dark** mode, merged onto the built-in dark
   * defaults.  When omitted, `lightTheme` overrides are applied to both modes
   * so a single set of brand customizations "just works".
   */
  darkTheme?: Theme;
  /**
   * @deprecated Use `lightTheme` instead. Kept for backward compatibility;
   * mapped to `lightTheme` internally. If both `theme` and `lightTheme` are
   * provided, `lightTheme` wins.
   */
  theme?: Theme;
  /**
   * CSS selector where `--openui-*` custom properties are injected.
   * Change this when mounting multiple independent theme scopes.
   * @default "body"
   */
  cssSelector?: string;
};

type ThemeContextType = {
  theme: Theme;
  mode: ThemeMode;
  portalThemeClassName: string;
};

/**
 * React context that carries the resolved theme, active mode, and a CSS class
 * name for portals. Consumed via {@link useTheme}.
 */
export const ThemeContext = createContext<ThemeContextType>({
  theme: defaultLightTheme,
  mode: "light",
  portalThemeClassName: "",
});

/**
 * Access the current theme, mode, and portal class name from the nearest
 * {@link ThemeProvider}.
 *
 * @returns An object with:
 *  - `theme` – the fully resolved {@link Theme} object
 *  - `mode` – `"light"` or `"dark"`
 *  - `portalThemeClassName` – a unique CSS class name to apply on portal
 *     containers so they inherit the same `--openui-*` custom properties
 *
 * Falls back to the default light theme when no provider is present.
 *
 * @example
 * ```tsx
 * const { theme, mode, portalThemeClassName } = useTheme();
 * ```
 */
export const useTheme = () => useContext(ThemeContext);

const themes = {
  light: defaultLightTheme,
  dark: defaultDarkTheme,
} as const;

// ---------------------------------------------------------------------------
// Internal context for nesting detection
// ---------------------------------------------------------------------------
const OPENUI_THEME_SENTINEL = Symbol("openui-theme-provider");

type InternalContextType = {
  [OPENUI_THEME_SENTINEL]: true;
  theme: Theme;
  mode: ThemeMode;
  portalThemeClassName: string;
};

const InternalContext = createContext<InternalContextType | null>(null);

// ---------------------------------------------------------------------------
// Dev-mode warning deduplication
// ---------------------------------------------------------------------------
const _devWarned = new Set<string>();

function warnOnce(key: string, message: string) {
  if (_devWarned.has(key)) return;
  _devWarned.add(key);
  console.warn(message);
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
function cssSafeId(id: string): string {
  return id.replace(/[^a-zA-Z0-9-_]/g, "");
}

function validateThemeObject(themeObj: Theme, propName: string) {
  for (const [key, value] of Object.entries(themeObj)) {
    if (value !== undefined && typeof value !== "string" && !Array.isArray(value)) {
      warnOnce(
        `non-string:${propName}:${key}`,
        `[OpenUI] ${propName} key "${key}" has a non-string value (${typeof value}). All theme values should be strings.`,
      );
    }
    if (!KNOWN_THEME_KEYS.has(key)) {
      warnOnce(
        `unknown-key:${propName}:${key}`,
        `[OpenUI] ${propName} contains unknown key "${key}". It will be ignored. Use createTheme() for typo detection with suggestions.`,
      );
    }
  }
}

/**
 * Injects the OpenUI design-token CSS custom properties (`--openui-*`) into the
 * DOM and provides theme context to all descendant components.
 *
 * Supports automatic scoping when nested inside another ThemeProvider: the inner
 * provider wraps its children in a `<div>` with `display: contents` and injects
 * a scoped style rule instead of targeting `body`.
 *
 * @example
 * ```tsx
 * <ThemeProvider
 *   mode="dark"
 *   lightTheme={createTheme({ interactiveAccentDefault: "oklch(0.6 0.2 260)" })}
 * >
 *   <App />
 * </ThemeProvider>
 * ```
 */

export const ThemeProvider = ({
  mode: modeProp,
  children,
  lightTheme,
  darkTheme,
  theme: deprecatedTheme,
  cssSelector = "body",
}: ThemeProps) => {
  const id = cssSafeId(useId());
  const parent = useContext(InternalContext);
  const isNested = parent != null;
  const mode = modeProp ?? parent?.mode ?? "light";
  const effectiveCssSelector = cssSelector || "body";
  const hasExplicitSelector = effectiveCssSelector !== "body";

  // Resolve the deprecated `theme` prop → `lightTheme` takes precedence
  const userLightTheme = lightTheme ?? deprecatedTheme ?? {};
  const userDarkTheme = darkTheme;

  // ---------------------------------------------------------------------------
  // Dev-mode warnings
  // ---------------------------------------------------------------------------
  if (typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
    if (deprecatedTheme !== undefined && lightTheme !== undefined) {
      warnOnce(
        "theme+lightTheme",
        '[OpenUI] Both "theme" and "lightTheme" were passed to ThemeProvider. "lightTheme" takes precedence. Remove the deprecated "theme" prop.',
      );
    }

    if (deprecatedTheme !== undefined && lightTheme === undefined) {
      warnOnce(
        "deprecated-theme",
        '[OpenUI] The "theme" prop on ThemeProvider is deprecated. Use "lightTheme" instead.',
      );
    }

    validateThemeObject(userLightTheme, "lightTheme");
    if (userDarkTheme) {
      validateThemeObject(userDarkTheme, "darkTheme");
    }

    // if (isNested && !hasExplicitSelector) {
    //   warnOnce(
    //     "nested-global",
    //     '[OpenUI] A nested ThemeProvider is targeting "body". The inner provider will auto-scope to avoid overwriting the parent. Pass an explicit cssSelector to opt out.',
    //   );
    // }
  }

  // ---------------------------------------------------------------------------
  // Theme resolution
  // ---------------------------------------------------------------------------
  const resolvedLightTheme = useMemo(
    () => ({ ...themes.light, ...userLightTheme }),
    [userLightTheme],
  );

  const resolvedDarkTheme = useMemo(() => {
    const overrides = userDarkTheme ?? userLightTheme;
    return { ...themes.dark, ...overrides };
  }, [userDarkTheme, userLightTheme]);

  const activeTheme = mode === "light" ? resolvedLightTheme : resolvedDarkTheme;
  const cssVarsString = useMemo(() => themeToCssVars(activeTheme), [activeTheme]);

  const portalClassName = `openui-theme-portal-${id}`;
  const scopedClassName = `openui-theme-${id}`;

  const contextValue = useMemo<ThemeContextType>(
    () => ({ theme: activeTheme, mode, portalThemeClassName: portalClassName }),
    [activeTheme, mode, portalClassName],
  );

  const internalValue = useMemo<InternalContextType>(
    () => ({
      [OPENUI_THEME_SENTINEL]: true as const,
      theme: activeTheme,
      mode,
      portalThemeClassName: portalClassName,
    }),
    [activeTheme, mode, portalClassName],
  );

  // ---------------------------------------------------------------------------
  // Style injection via useInsertionEffect (Step 4)
  // ---------------------------------------------------------------------------
  const useAutoScope = isNested && !hasExplicitSelector;
  const styleSelector = useAutoScope ? `.${scopedClassName}` : effectiveCssSelector;

  // Intentionally unlayered — must override component styles in both modes,
  // including when consumers opt into layered-components.css (@layer openui),
  // so runtime theming always wins. See README "Styling integration" before changing.
  useInsertionEffect(() => {
    const style = document.createElement("style");
    style.setAttribute("data-openui-theme", id);
    style.textContent = `${styleSelector}, .${portalClassName} { ${cssVarsString} }`;
    document.head.appendChild(style);
    return () => style.remove();
  }, [cssVarsString, styleSelector, portalClassName, id]);

  // ---------------------------------------------------------------------------
  // Render
  // ---------------------------------------------------------------------------
  return (
    <InternalContext.Provider value={internalValue}>
      <ThemeContext.Provider value={contextValue}>
        {useAutoScope ? (
          <div className={scopedClassName} style={{ display: "contents" }}>
            {children}
          </div>
        ) : (
          children
        )}
      </ThemeContext.Provider>
    </InternalContext.Provider>
  );
};