@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/src/theme/tokens.ts

@@ -10,6 +10,11 @@
  * build-time theme adapters, chart configuration, canvas/SVG rendering, tests,
  * or plain JS theme objects for other styling libraries.
  *
+ * Derived tokens can reference other tokens (`var(--color-accent)`) and use CSS
+ * color functions (`color-mix`). The resolver follows those references through
+ * the theme iteratively and evaluates the supported color functions so callers
+ * receive concrete raw values, not CSS expressions.
+ *
  * SYNC: When modified, update:
  * - /packages/core/src/theme/useTheme.ts
  * - /packages/core/src/theme/index.ts
@@ -21,6 +26,7 @@ import {
   type TokenName,
   type TokenValue,
 } from './defineTheme';
+import {parseColor, formatColor} from '../utils/color';
 
 /** Resolved color mode used when choosing the side of light/dark token values. */
 export type ResolvedThemeMode = 'light' | 'dark';
@@ -144,14 +150,243 @@ function resolveXDSTokenValue(
   return value;
 }
 
+// =============================================================================
+// Reference resolution — turn token expressions into concrete raw values
+// =============================================================================
+//
+// Generated themes emit derived tokens as references to other tokens rather
+// than baked-in values, so a scoped CSS override of a base token re-themes the
+// subtree that references it. The CSS cascade resolves those references, but
+// non-CSS consumers (canvas, SVG, data-viz) need the concrete value. These
+// helpers replay the same resolution in JS: follow `var()` references through
+// the resolved token map (iteratively, guarding against cycles) and evaluate
+// the CSS color functions used by the theme generator against those values.
+
+/** Index of the `)` matching the `(` at `openIndex`, or -1 when unbalanced. */
+function findMatchingParen(input: string, openIndex: number): number {
+  let depth = 0;
+  for (let i = openIndex; i < input.length; i++) {
+    const char = input[i];
+    if (char === '(') {
+      depth++;
+    } else if (char === ')') {
+      depth--;
+      if (depth === 0) {
+        return i;
+      }
+    }
+  }
+  return -1;
+}
+
+/** Split a color-mix component into its color and optional percentage. */
+function parseMixComponent(
+  part: string,
+): {color: string; percentage: number | null} | null {
+  const trimmed = part.trim();
+  const match = trimmed.match(/\s+([\d.]+)%$/);
+  if (match) {
+    return {
+      color: trimmed.slice(0, match.index).trim(),
+      percentage: parseFloat(match[1]),
+    };
+  }
+  return {color: trimmed, percentage: null};
+}
+
+/**
+ * Evaluate `color-mix(in <space>, c1 [p1], c2 [p2])` to a concrete color.
+ *
+ * Supports the `srgb` color space (the one the theme generator emits) using
+ * the CSS Color 5 algorithm: normalize the percentages, interpolate the
+ * premultiplied channels, then apply the alpha multiplier when the mix weights
+ * sum to less than 100%. Returns null for anything it can't evaluate so the
+ * original expression is preserved rather than guessed.
+ */
+function evaluateColorMix(body: string): string | null {
+  const spaceMatch = body.match(/^in\s+([\w-]+)\s*,\s*(.+)$/s);
+  if (!spaceMatch) {
+    return null;
+  }
+  const [, colorSpace, rest] = spaceMatch;
+  if (colorSpace.toLowerCase() !== 'srgb') {
+    return null;
+  }
+
+  const split = splitTopLevelComma(rest);
+  if (split === null) {
+    return null;
+  }
+  const first = parseMixComponent(split[0]);
+  const second = parseMixComponent(split[1]);
+  if (first === null || second === null) {
+    return null;
+  }
+
+  const c1 = parseColor(first.color);
+  const c2 = parseColor(second.color);
+  if (c1 === null || c2 === null) {
+    return null;
+  }
+
+  // Fill in omitted percentages, then normalize so they sum to 100%.
+  let p1: number;
+  let p2: number;
+  if (first.percentage !== null && second.percentage !== null) {
+    p1 = first.percentage;
+    p2 = second.percentage;
+  } else if (first.percentage !== null) {
+    p1 = first.percentage;
+    p2 = 100 - p1;
+  } else if (second.percentage !== null) {
+    p2 = second.percentage;
+    p1 = 100 - p2;
+  } else {
+    p1 = 50;
+    p2 = 50;
+  }
+  const sum = p1 + p2;
+  if (sum <= 0) {
+    return null;
+  }
+  const w1 = p1 / sum;
+  const w2 = p2 / sum;
+  const alphaMultiplier = sum < 100 ? sum / 100 : 1;
+
+  // Interpolate in premultiplied sRGB, then un-premultiply.
+  const mixedA = w1 * c1.a + w2 * c2.a;
+  const premix = (k1: number, k2: number): number =>
+    w1 * k1 * c1.a + w2 * k2 * c2.a;
+  const rp = premix(c1.r, c2.r);
+  const gp = premix(c1.g, c2.g);
+  const bp = premix(c1.b, c2.b);
+  const rgb =
+    mixedA === 0
+      ? {r: 0, g: 0, b: 0}
+      : {r: rp / mixedA, g: gp / mixedA, b: bp / mixedA};
+
+  return formatColor({...rgb, a: mixedA * alphaMultiplier});
+}
+
+/** Evaluate every supported color function in an expression, innermost first. */
+function evaluateColorFunctions(expr: string): string {
+  const idx = expr.indexOf('color-mix(');
+  if (idx === -1) {
+    return expr;
+  }
+  const openIndex = idx + 'color-mix'.length;
+  const closeIndex = findMatchingParen(expr, openIndex);
+  if (closeIndex === -1) {
+    return expr;
+  }
+  const body = evaluateColorFunctions(expr.slice(openIndex + 1, closeIndex));
+  const evaluated = evaluateColorMix(body);
+  const replacement = evaluated ?? `color-mix(${body})`;
+  return (
+    expr.slice(0, idx) +
+    replacement +
+    evaluateColorFunctions(expr.slice(closeIndex + 1))
+  );
+}
+
+/**
+ * Substitute `var(--name[, fallback])` references with their resolved values.
+ * `seen` tracks the reference chain so cycles resolve to the literal reference
+ * instead of recursing forever.
+ */
+function substituteVars(
+  expr: string,
+  raw: Record<string, string>,
+  cache: Record<string, string>,
+  seen: Set<string>,
+): string {
+  const start = expr.indexOf('var(');
+  if (start === -1) {
+    return expr;
+  }
+  const openIndex = start + 'var'.length;
+  const closeIndex = findMatchingParen(expr, openIndex);
+  if (closeIndex === -1) {
+    return expr;
+  }
+
+  const inner = expr.slice(openIndex + 1, closeIndex);
+  const commaSplit = splitTopLevelComma(inner);
+  const name = (commaSplit ? commaSplit[0] : inner).trim();
+  const fallback = commaSplit ? commaSplit[1] : null;
+
+  let replacement: string;
+  if (seen.has(name)) {
+    replacement = expr.slice(start, closeIndex + 1);
+  } else if (name in raw) {
+    seen.add(name);
+    replacement = resolveReference(name, raw, cache, seen);
+    seen.delete(name);
+  } else if (fallback !== null) {
+    replacement = substituteVars(fallback.trim(), raw, cache, seen);
+  } else {
+    replacement = expr.slice(start, closeIndex + 1);
+  }
+
+  const rest = substituteVars(expr.slice(closeIndex + 1), raw, cache, seen);
+  return expr.slice(0, start) + replacement + rest;
+}
+
+/** Fully resolve a single expression: substitute references, then evaluate colors. */
+function resolveExpression(
+  expr: string,
+  raw: Record<string, string>,
+  cache: Record<string, string>,
+  seen: Set<string>,
+): string {
+  if (!expr.includes('var(') && !expr.includes('color-mix(')) {
+    return expr;
+  }
+  const substituted = substituteVars(expr, raw, cache, seen);
+  return evaluateColorFunctions(substituted);
+}
+
+/** Resolve one token by name, memoizing the result in `cache`. */
+function resolveReference(
+  name: string,
+  raw: Record<string, string>,
+  cache: Record<string, string>,
+  seen: Set<string>,
+): string {
+  if (name in cache) {
+    return cache[name];
+  }
+  const value = raw[name];
+  if (value === undefined) {
+    return '';
+  }
+  const resolved = resolveExpression(value, raw, cache, seen);
+  cache[name] = resolved;
+  return resolved;
+}
+
+/** Resolve every reference/color function in a raw token map to concrete values. */
+function resolveReferences(
+  raw: Record<string, string>,
+): Record<string, string> {
+  const cache: Record<string, string> = {};
+  for (const name of Object.keys(raw)) {
+    resolveReference(name, raw, cache, new Set<string>());
+  }
+  return cache;
+}
+
 /**
  * Resolve all Astryx token values for a theme and effective color mode.
  *
  * The result starts with `tokenDefaults`, applies `theme.tokens`, then
  * reapplies `theme.__inputTokens` when available so explicit tuple overrides
  * retain their original light/dark sides instead of relying on CSS parsing.
- * This mirrors the token resolution used by `useTheme()` but does not need
- * React context or media queries.
+ * A final pass resolves any `var()` references between tokens and evaluates
+ * the CSS color functions the theme generator emits (e.g. `color-mix`), so
+ * derived tokens like `--color-text-accent` return concrete values rather than
+ * `var(--color-accent)`. This mirrors the token resolution used by
+ * `useTheme()` but does not need React context or media queries.
  *
  * Pass `theme` as null/undefined to resolve defaults only.
  */
@@ -167,7 +402,7 @@ export function resolveThemeTokens(
   }
 
   if (theme == null) {
-    return resolved;
+    return resolveReferences(resolved);
   }
 
   for (const [key, value] of Object.entries(theme.tokens)) {
@@ -182,7 +417,7 @@ export function resolveThemeTokens(
     }
   }
 
-  return resolved;
+  return resolveReferences(resolved);
 }
 
 /** Resolve one Astryx token value for a theme and effective color mode. */

package/src/theme/useTheme.test.tsx

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect, vi} from 'vitest';
-import {renderHook} from '@testing-library/react';
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {render, renderHook, act, waitFor} from '@testing-library/react';
 import React from 'react';
 import {Theme} from './Theme';
 import {defineTheme} from './defineTheme';
@@ -122,4 +122,128 @@ describe('useTheme', () => {
       resolveThemeTokens(testTheme, {mode: 'dark'}),
     );
   });
+
+  it('resolves derived accent tokens to raw values, not var()/color-mix', () => {
+    const brandTheme = defineTheme({name: 'brand', color: {accent: '#0064E0'}});
+    const {result} = renderHook(() => useTheme(), {
+      wrapper: ({children}) => (
+        <Theme theme={brandTheme} mode="light">
+          {children}
+        </Theme>
+      ),
+    });
+
+    const accent = result.current.token('--color-accent');
+    expect(result.current.token('--color-text-accent')).toBe(accent);
+    expect(result.current.token('--color-icon-accent')).toBe(accent);
+    expect(result.current.token('--color-accent-muted')).toMatch(/^(#|rgb)/);
+    expect(result.current.token('--color-accent-muted')).not.toContain('var(');
+    expect(result.current.token('--color-accent-muted')).not.toContain(
+      'color-mix',
+    );
+  });
+});
+
+// Covers the fallback used when a component calls useTheme() with no
+// ThemeContext ancestor reachable — e.g. a detached tree (useToast's
+// fallback viewport, other portals appended straight to document.body).
+// Root Theme instances sync their mode to <html data-theme> specifically so
+// this fallback can resolve the app's actual mode instead of jumping
+// straight to OS preference (see Theme.tsx's useRootThemeSync).
+describe('useTheme mode resolution without a ThemeContext ancestor', () => {
+  afterEach(async () => {
+    // The hook from each `it` below is still mounted and subscribed to the
+    // shared MutationObserver when this runs (RTL's own cleanup — which
+    // unmounts it — is registered after this file's afterEach), so removing
+    // the attribute here triggers a live state update; flush it inside act
+    // so React doesn't warn about an update outside one.
+    await act(async () => {
+      document.documentElement.removeAttribute('data-theme');
+    });
+  });
+
+  it('resolves mode from <html data-theme> when set', () => {
+    document.documentElement.setAttribute('data-theme', 'dark');
+    const {result} = renderHook(() => useTheme());
+    expect(result.current.mode).toBe('dark');
+  });
+
+  it('falls back to OS preference when <html data-theme> is absent', () => {
+    // useMediaQuery is mocked to false (light) at the top of this file.
+    const {result} = renderHook(() => useTheme());
+    expect(result.current.mode).toBe('light');
+  });
+
+  it('stays live when <html data-theme> changes after mount', async () => {
+    const {result} = renderHook(() => useTheme());
+    expect(result.current.mode).toBe('light');
+
+    act(() => {
+      document.documentElement.setAttribute('data-theme', 'dark');
+    });
+
+    await waitFor(() => expect(result.current.mode).toBe('dark'));
+  });
+});
+
+// Covers the singleton MutationObserver + no-op gating in useRootThemeModeAttr:
+// provider-path consumers (a ThemeContext ancestor is reachable) must not
+// create an observer or react to <html data-theme> at all, and every
+// no-context consumer must share exactly one observer, refcounted down to
+// zero as they unmount.
+describe('useTheme root-attribute observer lifecycle', () => {
+  afterEach(() => {
+    document.documentElement.removeAttribute('data-theme');
+    // vi.stubGlobal'd MutationObserver stubs below are torn down here even if
+    // a test fails partway through, instead of relying on a manual restore
+    // line at the end of each test that a mid-test throw would skip.
+    vi.unstubAllGlobals();
+  });
+
+  it('creates no observer and does not re-render provider-path consumers when <html data-theme> changes', () => {
+    const ObserverSpy = vi.fn();
+    vi.stubGlobal('MutationObserver', ObserverSpy);
+
+    const renders = {count: 0};
+    function Consumer() {
+      useTheme();
+      renders.count++;
+      return null;
+    }
+
+    render(
+      <Theme theme={testTheme} mode="light">
+        <Consumer />
+      </Theme>,
+    );
+
+    expect(ObserverSpy).not.toHaveBeenCalled();
+
+    const before = renders.count;
+    act(() => {
+      document.documentElement.setAttribute('data-theme', 'dark');
+    });
+    expect(renders.count).toBe(before);
+  });
+
+  it('shares one observer across multiple no-context consumers and disconnects once all unmount', () => {
+    const observe = vi.fn();
+    const disconnect = vi.fn();
+    const ObserverSpy = vi.fn().mockImplementation(function () {
+      return {observe, disconnect};
+    });
+    vi.stubGlobal('MutationObserver', ObserverSpy);
+
+    const first = renderHook(() => useTheme());
+    const second = renderHook(() => useTheme());
+
+    expect(ObserverSpy).toHaveBeenCalledTimes(1);
+    expect(observe).toHaveBeenCalledTimes(1);
+
+    first.unmount();
+    expect(disconnect).not.toHaveBeenCalled();
+
+    second.unmount();
+    expect(disconnect).toHaveBeenCalledTimes(1);
+  });
 });

package/src/theme/useTheme.ts

@@ -9,14 +9,19 @@
  * @position Theme hook; used by data viz, canvas, and non-CSS consumers
  *
  * Provides synchronous access to theme token values resolved for the
- * current color mode — no DOM reads, no double render. Token resolution
- * is shared with the server-safe helpers in ./tokens.ts.
+ * current color mode — no DOM reads on the provider path, no double render.
+ * Without a reachable ThemeContext it consults `<html data-theme>` (kept in
+ * sync by Theme) via a single shared, refcounted MutationObserver before
+ * assuming OS preference; provider-path consumers subscribe to a no-op
+ * store instead (the same args-switch technique useMediaQuery uses), so
+ * mounting under a Theme never creates an observer. Token resolution is
+ * shared with the server-safe helpers in ./tokens.ts.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/theme/index.ts
  */
 
-import {createContext, use, useMemo} from 'react';
+import {createContext, use, useMemo, useSyncExternalStore} from 'react';
 import type {ThemeMode} from './types';
 import type {DefinedTheme} from './defineTheme';
 import {resolveThemeTokens} from './tokens';
@@ -87,6 +92,76 @@ export interface UseThemeReturn {
 // Hook
 // =============================================================================
 
+function getRootThemeAttrSnapshot(): 'light' | 'dark' | null {
+  if (typeof document === 'undefined') {
+    return null;
+  }
+  const attr = document.documentElement.getAttribute('data-theme');
+  return attr === 'light' || attr === 'dark' ? attr : null;
+}
+
+function getRootThemeAttrServerSnapshot(): 'light' | 'dark' | null {
+  return null;
+}
+
+function getNullThemeMode(): null {
+  return null;
+}
+
+// Every no-context consumer wants the same <html data-theme> attribute, so
+// one MutationObserver — refcounted via this listener set — serves all of
+// them instead of one per consumer.
+const rootThemeAttrListeners = new Set<() => void>();
+let rootThemeAttrObserver: MutationObserver | null = null;
+
+function notifyRootThemeAttrListeners(): void {
+  for (const listener of rootThemeAttrListeners) {
+    listener();
+  }
+}
+
+function subscribeRootThemeAttr(onStoreChange: () => void): () => void {
+  rootThemeAttrListeners.add(onStoreChange);
+
+  if (
+    rootThemeAttrListeners.size === 1 &&
+    typeof MutationObserver !== 'undefined'
+  ) {
+    rootThemeAttrObserver = new MutationObserver(notifyRootThemeAttrListeners);
+    rootThemeAttrObserver.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['data-theme'],
+    });
+  }
+
+  return () => {
+    rootThemeAttrListeners.delete(onStoreChange);
+    if (rootThemeAttrListeners.size === 0 && rootThemeAttrObserver) {
+      rootThemeAttrObserver.disconnect();
+      rootThemeAttrObserver = null;
+    }
+  };
+}
+
+function subscribeNoop(): () => void {
+  return () => {};
+}
+
+/**
+ * Reads the root Theme's mode off `<html data-theme>`, live via the shared
+ * MutationObserver. Null means no root Theme has synced it (none present,
+ * or mode is 'system'). `hasCtx` switches which store this subscribes to —
+ * a no-op store when a ThemeContext exists — instead of skipping the hook
+ * call, so provider-path consumers never touch the DOM or the observer.
+ */
+function useRootThemeModeAttr(hasCtx: boolean): 'light' | 'dark' | null {
+  return useSyncExternalStore(
+    hasCtx ? subscribeNoop : subscribeRootThemeAttr,
+    hasCtx ? getNullThemeMode : getRootThemeAttrSnapshot,
+    getRootThemeAttrServerSnapshot,
+  );
+}
+
 /**
  * Access the current Astryx theme's token values, resolved for the active color mode.
  *
@@ -95,8 +170,9 @@ export interface UseThemeReturn {
  * (e.g. Vega, D3, Chart.js) that need concrete values rather than
  * CSS custom property references.
  *
- * When called outside an <Theme> provider, returns the default theme
- * tokens resolved against the current system color mode.
+ * When called outside a <Theme> provider, resolves mode from the root
+ * Theme's `<html data-theme>` when one is present, falling back to the
+ * current system color mode otherwise.
  *
  * @example
  * ```
@@ -114,10 +190,15 @@ export interface UseThemeReturn {
 export function useTheme(): UseThemeReturn {
   const ctx = use(ThemeContext);
 
+  // Falls back to the root Theme's mode via <html data-theme> when there's
+  // no ThemeContext ancestor (e.g. useToast's detached fallback viewport).
+  // Resolves to null when `ctx` is present, so it has no effect there.
+  const rootAttrMode = useRootThemeModeAttr(ctx != null);
+
   // Resolve 'system' to 'light' | 'dark' using the OS preference
   const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');
 
-  const mode = ctx?.mode ?? 'system';
+  const mode = ctx?.mode ?? rootAttrMode ?? 'system';
   const theme = ctx?.theme ?? null;
 
   const effectiveMode: 'light' | 'dark' =

package/src/utils/color.test.ts

@@ -0,0 +1,133 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {parseHex, parseRgb, parseColor, formatHex, formatColor} from './color';
+
+describe('parseHex', () => {
+  it('parses #rrggbb', () => {
+    expect(parseHex('#0064E0')).toEqual({r: 0, g: 100, b: 224, a: 1});
+  });
+
+  it('parses without a leading #', () => {
+    expect(parseHex('0064E0')).toEqual({r: 0, g: 100, b: 224, a: 1});
+  });
+
+  it('expands #rgb shorthand', () => {
+    expect(parseHex('#abc')).toEqual({r: 0xaa, g: 0xbb, b: 0xcc, a: 1});
+  });
+
+  it('parses #rrggbbaa alpha', () => {
+    expect(parseHex('#00000080')).toEqual({r: 0, g: 0, b: 0, a: 128 / 255});
+  });
+
+  it('expands #rgba shorthand alpha', () => {
+    expect(parseHex('#f008')).toEqual({
+      r: 0xff,
+      g: 0,
+      b: 0,
+      a: 0x88 / 255,
+    });
+  });
+
+  it('returns null for non-hex input', () => {
+    expect(parseHex('rgb(0,0,0)')).toBeNull();
+    expect(parseHex('#12')).toBeNull();
+    expect(parseHex('#zzzzzz')).toBeNull();
+    // @ts-expect-error runtime guard for non-string input
+    expect(parseHex(null)).toBeNull();
+  });
+});
+
+describe('parseRgb', () => {
+  it('parses comma-separated rgb()', () => {
+    expect(parseRgb('rgb(0, 100, 224)')).toEqual({
+      r: 0,
+      g: 100,
+      b: 224,
+      a: 1,
+    });
+  });
+
+  it('parses rgba() with alpha', () => {
+    expect(parseRgb('rgba(0, 0, 0, 0.5)')).toEqual({r: 0, g: 0, b: 0, a: 0.5});
+  });
+
+  it('parses space-separated with slash alpha', () => {
+    expect(parseRgb('rgb(0 100 224 / 0.25)')).toEqual({
+      r: 0,
+      g: 100,
+      b: 224,
+      a: 0.25,
+    });
+  });
+
+  it('parses percentage channels', () => {
+    expect(parseRgb('rgb(100%, 0%, 0%)')).toEqual({
+      r: 255,
+      g: 0,
+      b: 0,
+      a: 1,
+    });
+  });
+
+  it('clamps alpha and channels into range', () => {
+    expect(parseRgb('rgba(300, -20, 10, 2)')).toEqual({
+      r: 255,
+      g: 0,
+      b: 10,
+      a: 1,
+    });
+  });
+
+  it('returns null when it cannot parse', () => {
+    expect(parseRgb('rgb(0, 0)')).toBeNull();
+    expect(parseRgb('#000000')).toBeNull();
+  });
+});
+
+describe('parseColor', () => {
+  it('routes hex and rgb strings to the right parser', () => {
+    expect(parseColor('#FFFFFF')).toEqual({r: 255, g: 255, b: 255, a: 1});
+    expect(parseColor('rgb(1, 2, 3)')).toEqual({r: 1, g: 2, b: 3, a: 1});
+  });
+
+  it('resolves the named colors used in token expressions', () => {
+    expect(parseColor('transparent')).toEqual({r: 0, g: 0, b: 0, a: 0});
+    expect(parseColor('BLACK')).toEqual({r: 0, g: 0, b: 0, a: 1});
+    expect(parseColor('white')).toEqual({r: 255, g: 255, b: 255, a: 1});
+  });
+
+  it('returns null for unsupported colors so callers can preserve them', () => {
+    expect(parseColor('var(--color-accent)')).toBeNull();
+    expect(parseColor('oklch(0.5 0.1 200)')).toBeNull();
+    expect(parseColor('rebeccapurple')).toBeNull();
+  });
+});
+
+describe('formatHex', () => {
+  it('formats channels as uppercase #RRGGBB', () => {
+    expect(formatHex(0, 100, 224)).toBe('#0064E0');
+  });
+
+  it('rounds and clamps out-of-range channels', () => {
+    expect(formatHex(-5, 300, 127.6)).toBe('#00FF80');
+  });
+});
+
+describe('formatColor', () => {
+  it('formats opaque colors as hex', () => {
+    expect(formatColor({r: 0, g: 100, b: 224, a: 1})).toBe('#0064E0');
+  });
+
+  it('formats translucent colors as rgba()', () => {
+    expect(formatColor({r: 0, g: 100, b: 224, a: 0.2})).toBe(
+      'rgba(0, 100, 224, 0.2)',
+    );
+  });
+
+  it('round-trips through parseColor', () => {
+    const parsed = parseColor('rgba(10, 20, 30, 0.5)');
+    expect(parsed).not.toBeNull();
+    expect(formatColor(parsed!)).toBe('rgba(10, 20, 30, 0.5)');
+  });
+});