Skip to content

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

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

'use client';

/**
 * @file useAutoMediaMode.ts
 * @input Ref to the element whose backdrop should be measured
 * @output 'dark' | 'light' | null (not yet measurable)
 * @position Internal; powers `MediaTheme mode="auto"`. Not exported from the
 *   package. Sibling to useImageMode, which does the same for images.
 */

// The hook measures what the browser painted and does not trust a token's
// name. `--color-background-inverted` need not be inverted: a theme can make
// it pale grey, and a fixed `mode="dark"` then paints white text on it at
// 1.25:1. The surface color is a runtime value, so only a measurement can
// catch this.
//
// The answer can be `'off'` when the surface's own text already reads on it.
// A dark page already resolves those tokens to the media context's values,
// so a chromatic but legible surface loses nothing.

import {useRef, useState} from 'react';
import type {RefObject} from 'react';
import type {RGBA} from '../utils/color';
import {parseColor, formatColor} from '../utils/color';
import {contrastRatio, compositeOver} from '../theme/contrast';
import {useTheme} from '../theme/useTheme';
import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';

/** A surface luminance context, or `"off"` when no media context is wanted. */
export type DetectedMediaMode = 'dark' | 'light' | 'off';

/**
 * Resolve token references to the colors they paint, through a hidden probe.
 * `getPropertyValue` returns a token's specified text, and Astryx tokens are
 * `light-dark(a, b)` pairs that resolve only in a real property. The probe
 * sets each token as `color` and reads the computed value. `display: none`
 * keeps the probe out of layout, so this costs a style recalc and no reflow.
 */
function resolvePaintedColors(
  host: HTMLElement,
  tokens: ReadonlyArray<string>,
): (RGBA | null)[] {
  const probe = document.createElement('span');
  probe.style.display = 'none';
  host.appendChild(probe);
  try {
    return tokens.map(token => {
      probe.style.color = `var(${token})`;
      return parseColor(getComputedStyle(probe).color);
    });
  } finally {
    probe.remove();
  }
}

/**
 * The color actually behind an element: its own background if opaque,
 * otherwise its translucent layers composited down onto the first opaque
 * ancestor.
 *
 * Returns null when the paint is not knowable from CSS:
 * - a `background-image` (gradient, photo, video poster) anywhere in the
 *   chain — its pixels need sampling, which is `useImageMode`'s job and
 *   needs CORS access the stylesheet cannot give us;
 * - no opaque layer at all, where the paint is the browser canvas.
 */
function resolveBackdrop(element: HTMLElement): RGBA | null {
  const layers: RGBA[] = [];
  let node: HTMLElement | null = element;

  while (node !== null) {
    const style = getComputedStyle(node);
    if (style.backgroundImage !== 'none') {
      return null;
    }
    const color = parseColor(style.backgroundColor);
    if (color !== null && color.a > 0) {
      layers.push(color);
      if (color.a >= 1) {
        break;
      }
    }
    node = node.parentElement;
  }

  const base = layers.pop();
  if (base === undefined || base.a < 1) {
    return null;
  }
  // layers is now top-first; composite downward so the topmost lands last.
  return layers.reduceRight(
    (backdrop, layer) => compositeOver(layer, backdrop),
    base,
  );
}

/**
 * Contrast at which a surface's own text reads well enough that no media
 * context is wanted. This is WCAG's large-text line. It is low on purpose: it
 * decides if a surface is effectively inverted, not if its text meets a
 * standard. A media context on a 3:1 pairing changes accent, overlays and
 * borders with no legibility gain.
 */
const AMBIENT_READS_AT = 3;

/**
 * Which media context a surface wants: `'off'` when its ambient text already
 * reads on the surface, otherwise whichever on-color reads better. Pure — the
 * DOM read is the caller's. Ties between the two sides go to dark, matching
 * the convention that an inverted surface is usually the dark one.
 *
 * The `'off'` answer is the point of measuring at all. A surface that a theme
 * calls inverted but paints pale does not want an inverted context; its own
 * text is already correct for it, and forcing one is how white-on-pale-grey
 * happens.
 */
export function pickMediaMode(
  background: RGBA,
  ambient: RGBA | null,
  onDark: RGBA | null,
  onLight: RGBA | null,
): DetectedMediaMode | null {
  if (onDark === null || onLight === null) {
    return null;
  }

  if (
    ambient !== null &&
    contrastRatio(ambient, background) >= AMBIENT_READS_AT
  ) {
    return 'off';
  }

  return contrastRatio(onDark, background) >= contrastRatio(onLight, background)
    ? 'dark'
    : 'light';
}

/**
 * Detect the media context for the element's surroundings.
 *
 * Measures `ref`'s PARENT, never `ref` itself: MediaTheme sets its media
 * attribute on its own element, so measuring that would feed the decision
 * back into its own input and let it oscillate. The parent owns the
 * background and sits outside the media context, so both inputs stay
 * independent of the result.
 *
 * Returns null until a measurement succeeds — on the server, before the
 * layout effect runs, and whenever the backdrop is not knowable from CSS.
 * The caller renders its fallback for those.
 */
export function useAutoMediaMode(
  ref: RefObject<HTMLElement | null>,
  isEnabled: boolean,
): DetectedMediaMode | null {
  const [detected, setDetected] = useState<DetectedMediaMode | null>(null);
  // `tokens` is a stable reference unless the theme or color mode changes.
  const {tokens} = useTheme();
  const lastRef = useRef<{background: string; tokens: unknown} | null>(null);

  // Syncs the media mode with the painted color behind the element.
  // No dependency array. A surface color is a painted value, and it changes
  // when a prop on some ancestor changes. No dependency that this hook can
  // name catches that. So the measurement runs on each render, and it skips
  // its expensive half when nothing moved (see the early return below).
  useIsomorphicLayoutEffect(() => {
    const surface = ref.current?.parentElement ?? null;
    if (!isEnabled || surface === null) {
      return;
    }

    const background = resolveBackdrop(surface);
    if (background === null) {
      return;
    }

    // The probe adds a node and forces another style resolution. Skip it when
    // neither the painted backdrop nor the theme moved, which is the usual
    // case.
    const backgroundKey = formatColor(background);
    const last = lastRef.current;
    if (
      last !== null &&
      last.background === backgroundKey &&
      last.tokens === tokens
    ) {
      return;
    }
    lastRef.current = {background: backgroundKey, tokens};

    const [ambient, onDark, onLight] = resolvePaintedColors(surface, [
      '--color-text-primary',
      '--color-on-dark',
      '--color-on-light',
    ]);
    const next = pickMediaMode(background, ambient, onDark, onLight);
    if (next === null) {
      return;
    }

    // eslint-disable-next-line @eslint-react/set-state-in-effect -- the mode is derived from painted DOM colors
    setDetected(current => (current === next ? current : next));
  });

  // A disabled hook must not answer with a value measured while it was on.
  return isEnabled ? detected : null;
}