@astryxdesign/core 0.2.0 → 0.3.0-canary.041a0ef

package/src/hooks/useTypeahead.test.tsx

@@ -106,4 +106,154 @@ describe('useTypeahead', () => {
     expect(api.onKeyDown(key(' '))).toBe(false);
     expect(onMatch).not.toHaveBeenCalled();
   });
+
+  it('extends a live buffer with a space', () => {
+    const onMatch = vi.fn();
+    const {result} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => ['Newark', 'New York'],
+        onMatch,
+      }),
+    );
+    for (const k of 'new ') {
+      result.current.onKeyDown(key(k));
+    }
+    result.current.onKeyDown(key('y'));
+    // "new y" reaches New York; a space that ended the buffer instead would
+    // leave "newy", which matches nothing.
+    expect(onMatch).toHaveBeenLastCalledWith(1);
+  });
+
+  it('ignores a Space chorded with ctrl or meta even mid-buffer', () => {
+    const onMatch = vi.fn();
+    const {result} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => ['Melon', 'New York'],
+        onMatch,
+      }),
+    );
+    expect(result.current.onKeyDown(key('n'))).toBe(true);
+    expect(onMatch).toHaveBeenLastCalledWith(1);
+
+    // A chord is not typing. Consuming it would append a raw space and leave
+    // the buffer as "n ", poisoning every keystroke until the reset window.
+    expect(
+      result.current.onKeyDown(
+        new KeyboardEvent('keydown', {key: ' ', ctrlKey: true}),
+      ),
+    ).toBe(false);
+    expect(
+      result.current.onKeyDown(
+        new KeyboardEvent('keydown', {key: ' ', metaKey: true}),
+      ),
+    ).toBe(false);
+
+    result.current.onKeyDown(key('e'));
+    expect(onMatch).toHaveBeenCalledTimes(2);
+    expect(onMatch).toHaveBeenLastCalledWith(1);
+  });
+
+  it('starts a fresh single-character search after the current item', () => {
+    const {onMatch, api} = setup({current: 0}); // Apple is current
+    api.onKeyDown(key('a'));
+    // A single-character search begins at current + 1, so pressing the current
+    // item's own initial advances instead of re-matching it into a dead key.
+    expect(onMatch).toHaveBeenCalledWith(1); // Apricot
+  });
+
+  it('searches from the top when there is no current item', () => {
+    // The last item also matches, so this distinguishes "from the top" from
+    // wrapping backwards off -1 and hitting the bottom of the list first.
+    const onMatch = vi.fn();
+    const {result} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => ['Apple', 'Berry', 'Avocado'],
+        onMatch,
+        getCurrentIndex: () => -1,
+      }),
+    );
+    result.current.onKeyDown(key('a'));
+    expect(onMatch).toHaveBeenCalledWith(0); // Apple, not Avocado
+  });
+
+  it('keeps the current item in range once the buffer is multi-character', () => {
+    const {onMatch, api} = setup({current: 0});
+    api.onKeyDown(key('a')); // single char: advances to Apricot
+    expect(onMatch).toHaveBeenLastCalledWith(1);
+    api.onKeyDown(key('p')); // "ap" refines, so Apple is a candidate again
+    expect(onMatch).toHaveBeenLastCalledWith(0);
+  });
+
+  it('skips unmatchable label slots without shifting the reported index', () => {
+    // Callers may pass null/empty entries to keep the index mapping 1:1 with
+    // their own items — menus pass el.textContent, which can be null.
+    const onMatch = vi.fn();
+    const {result} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => [null, '', '   ', undefined, 'Apple'],
+        onMatch,
+      }),
+    );
+    result.current.onKeyDown(key('a'));
+    expect(onMatch).toHaveBeenCalledWith(4);
+  });
+
+  it('treats any negative or stale current index safely', () => {
+    // A sentinel other than -1, and an index left over from a longer list:
+    // neither may search backwards or report an index outside the list.
+    const fromBelowZero = vi.fn();
+    const {result: below} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => LABELS,
+        onMatch: fromBelowZero,
+        getCurrentIndex: () => -5,
+      }),
+    );
+    below.current.onKeyDown(key('a'));
+    expect(fromBelowZero).toHaveBeenCalledWith(0); // Apple, from the top
+
+    const fromStale = vi.fn();
+    const {result: stale} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => LABELS,
+        onMatch: fromStale,
+        getCurrentIndex: () => 7,
+      }),
+    );
+    stale.current.onKeyDown(key('b'));
+    expect(fromStale).toHaveBeenCalledWith(2); // Banana, in range
+  });
+
+  it('wraps onto the only item when the list has one entry', () => {
+    // "Advance past the current item" is about cycling; with one item the
+    // cycle is itself. The caller decides whether that is a no-op.
+    const onMatch = vi.fn();
+    const {result} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => ['Apple'],
+        onMatch,
+        getCurrentIndex: () => 0,
+      }),
+    );
+    expect(result.current.onKeyDown(key('a'))).toBe(true);
+    expect(onMatch).toHaveBeenCalledWith(0);
+  });
+
+  it('matches characters composed with Option/Alt', () => {
+    const onMatch = vi.fn();
+    const {result} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => ['Ångström', 'Berlin'],
+        onMatch,
+        getCurrentIndex: () => -1,
+      }),
+    );
+    // Option+a on macOS emits a printable 'å' with altKey set. Excluding it
+    // makes accented labels untypeable; real chords still carry ctrl/meta.
+    const handled = result.current.onKeyDown(
+      new KeyboardEvent('keydown', {key: 'å', altKey: true}),
+    );
+    expect(handled).toBe(true);
+    expect(onMatch).toHaveBeenCalledWith(0);
+  });
 });

package/src/hooks/useTypeahead.ts

@@ -32,8 +32,9 @@ export interface UseTypeaheadOptions {
 
   /**
    * The index to start searching from — typically the currently focused item,
-   * so repeated presses of the same letter cycle through matches. Defaults to
-   * -1 (search from the top).
+   * so repeated presses of the same letter cycle through matches. Any negative
+   * value (the default) means nothing is current: the search runs from the top
+   * and never skips the first item.
    */
   getCurrentIndex?: () => number;
 
@@ -67,9 +68,12 @@ export interface UseTypeaheadReturn {
 function isPrintableCharacter(e: React.KeyboardEvent | KeyboardEvent): boolean {
   return (
     e.key.length === 1 &&
+    // Alt alone is not excluded: Option+letter on macOS composes a printable
+    // character (Option+a → "å"), and dropping those makes accented labels
+    // untypeable. Real chords still carry ctrl or meta — including AltGr,
+    // which sets ctrlKey on Windows and Linux.
     !e.ctrlKey &&
     !e.metaKey &&
-    !e.altKey &&
     // A lone space is used for activation in menus, not typeahead-from-empty.
     e.key !== ' '
   );
@@ -133,8 +137,14 @@ export function useTypeahead(options: UseTypeaheadOptions): UseTypeaheadReturn {
   const onKeyDown = useCallback(
     (e: React.KeyboardEvent | KeyboardEvent): boolean => {
       // A bare Space with no active buffer is not typeahead (menus activate on
-      // Space); once the user is mid-typing, Space extends the query.
-      const isSpaceMidType = e.key === ' ' && bufferRef.current.length > 0;
+      // Space); once the user is mid-typing, Space extends the query. Chorded
+      // with ctrl or meta it is neither — that is an OS or IME shortcut, and
+      // consuming it would append a raw space that poisons the whole buffer.
+      const isSpaceMidType =
+        e.key === ' ' &&
+        !e.ctrlKey &&
+        !e.metaKey &&
+        bufferRef.current.length > 0;
       if (!isPrintableCharacter(e) && !isSpaceMidType) {
         return false;
       }
@@ -154,11 +164,16 @@ export function useTypeahead(options: UseTypeaheadOptions): UseTypeaheadReturn {
       bufferRef.current = nextBuffer;
       scheduleReset();
 
-      const start = getCurrentIndex?.() ?? -1;
+      const current = getCurrentIndex?.() ?? -1;
       const count = labels.length;
-      // When repeating a single char, start the search AFTER the current item
-      // so we advance; otherwise include the current item.
-      const offset = isRepeatSameChar ? 1 : 0;
+      const hasCurrent = current >= 0;
+      const start = hasCurrent ? current : 0;
+      // A single-character search starts AFTER the current item, so pressing a
+      // letter walks to the next item beginning with it instead of re-matching
+      // the one already selected (native <select> and APG getIndexByLetter).
+      // Once the buffer is longer it is refining a match, so the current item
+      // stays in range. With nothing current there is nothing to advance past.
+      const offset = hasCurrent && nextBuffer.length === 1 ? 1 : 0;
 
       for (let i = 0; i < count; i++) {
         const index = (start + offset + i + count) % count;

package/src/i18n/InternationalizationProvider.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'InternationalizationProvider',
@@ -37,6 +37,11 @@ export const docs = {
         description:
           'Use real BCP 47 tags such as `fr`, `pt-BR`, or `ar`; regional locales fall back to their base language before English.',
       },
+      {
+        guidance: true,
+        description:
+          'Set the `dir` attribute on `<html>` (or a wrapping element) yourself — the provider does not set it. Astryx components mirror layout and directional icons from the DOM `dir`, so an RTL locale won\'t visually mirror without it. Use `getLocaleDirection(locale)` to derive the value for both the provider and the DOM.',
+      },
       {
         guidance: false,
         description:
@@ -66,6 +71,13 @@ export const docs = {
       description:
         'Sparse per-locale key overrides applied on top of shipped defaults. Overrides are locale-keyed so a runtime locale swap picks up the correct set.',
     },
+    {
+      name: 'dir',
+      type: "'ltr' | 'rtl'",
+      required: false,
+      description:
+        'Explicit text-direction override for the context. When omitted, direction is derived from `locale` via `Intl.Locale.getTextInfo()`. This sets the direction Astryx reads, but it does NOT set the DOM `dir` attribute — you must set `dir` on `<html>` (or a wrapping element) yourself, since Astryx components mirror layout and directional icons from the DOM `dir`, not from this prop. Set both to the same value and keep them in sync.',
+    },
     {
       name: 'children',
       type: 'ReactNode',
@@ -128,7 +140,7 @@ export function AppI18n({children}: {children: ReactNode}) {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Wraps app to set active locale and (optionally) merge translation catalogs + per-locale overrides. Astryx components resolve strings against this context; missing keys fall back to shipped English.',

package/src/i18n/InternationalizationProvider.tsx

@@ -61,6 +61,12 @@ export interface InternationalizationProviderProps {
    * from `locale` via `Intl.Locale.getTextInfo()`. Provide this to force a
    * direction (e.g. RTL layout testing under an English catalog) or to skip the
    * derivation when you already know the direction.
+   *
+   * This sets the direction astryx reads via context; it does NOT set the DOM
+   * `dir` attribute. You must set `dir` on `<html>` (or a wrapping element)
+   * yourself — astryx components mirror layout and directional icons from the
+   * DOM `dir`, so an RTL locale won't visually mirror without it. Keep the two
+   * in sync (e.g. `dir={getLocaleDirection(locale)}` on both).
    */
   dir?: 'ltr' | 'rtl';
   children: ReactNode;

package/src/i18n/useDirection.ts

@@ -10,9 +10,12 @@
  *   when called outside a provider (matches the silent-en-fallback pattern of
  *   useTranslator).
  *
- * Use this in components that need to swap directional icons, mirror
- * behavioral logic (slider math, keyboard nav), or apply direction-specific
- * styling that CSS logical properties can't express.
+ * Render-time last resort. Prefer, in order: CSS logical properties; the shared
+ * `rtlStyles.mirror` for directional icons (CSS scaleX, not a JS icon-name
+ * swap); and lazy DOM reads (`isRtlElement`) for behavioral logic like keyboard
+ * nav or drag math. Reach for this hook only when you need the direction value
+ * during render and none of those fit — note it can mismatch on hydration if
+ * the provider's direction disagrees with the actual `<html dir>`.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/i18n/InternationalizationContext.ts

package/src/i18n/useTranslator.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useTranslator',
   displayName: 'useTranslator',
@@ -31,7 +31,7 @@ export const docs = {
   importPath: '@astryxdesign/core',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Hook returning a translator function bound to the current InternationalizationProvider context. Call with an ICU MessageFormat key and values to get the formatted string for the active locale.',

package/src/index.ts

@@ -33,6 +33,7 @@ export * from './Calendar';
 export * from './Center';
 export * from './CodeBlock';
 export * from './CommandPalette';
+export * from './ComplexSelector';
 export * from './Chat';
 export * from './Markdown';
 export * from './Citation';
@@ -168,25 +169,8 @@ export * from './hooks';
 export * from './utils';
 
 // Theme
+export type {TextColorMap} from './Text';
 export * from './theme';
 
 // Internationalization
 export * from './i18n';
-
-// Doc types — for external library authors writing .doc.mjs files
-export type {
-  ComponentDoc,
-  SingleComponentDoc,
-  MultiComponentDoc,
-  PropDoc,
-  ComponentEntry,
-  ThemingTarget,
-  ComponentVar,
-  DerivedVar,
-  TranslationDoc,
-  GroupDoc,
-  ReferenceDoc,
-  ReferenceSection,
-  ContentBlock,
-  TokenPreviewType,
-} from './docs-types';

package/src/theme/MediaTheme.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'MediaTheme',
@@ -100,7 +100,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
     description:

package/src/theme/SyntaxTheme.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'SyntaxTheme',
@@ -74,7 +74,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
     description:

package/src/theme/Theme.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Theme',
@@ -86,7 +86,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
     description:

package/src/theme/Theme.tsx

@@ -41,8 +41,8 @@ import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
 import type {ThemeMode} from './types';
 import {colorVars, typographyVars} from './tokens.stylex';
-import {registerIcons} from '../Icon/globalIconRegistry';
 import {generateThemeCSS, type DefinedTheme} from './defineTheme';
+import {registerTheme} from './themeRegistry';
 import {dataAttr} from '../naming';
 import {ThemeContext} from './useTheme';
 import {warnOnce} from '../utils/devWarning';
@@ -243,6 +243,8 @@ export function Theme({
 }: ThemeProps): React.ReactElement {
   const isNested = use(ThemeNestingContext);
 
+  registerTheme(theme);
+
   useThemeStyleInjection(theme);
   useRootThemeSync(isNested, mode, theme.name);
 
@@ -254,12 +256,6 @@ export function Theme({
         ? wrapperStyles.light
         : wrapperStyles.system;
 
-  // Icons — register globally (works in both server and client environments)
-  const icons = theme.icons;
-  if (icons != null) {
-    registerIcons(icons);
-  }
-
   // Memoize the context value to prevent unnecessary re-renders
   const ctxValue = useMemo(() => ({theme, mode}), [theme, mode]);
 

package/src/theme/contrast.test.ts

@@ -0,0 +1,94 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {relativeLuminance, compositeOver, contrastRatio} from './contrast';
+import {parseColor} from '../utils/color';
+
+describe('relativeLuminance', () => {
+  it('is 0 for black and 1 for white', () => {
+    expect(relativeLuminance({r: 0, g: 0, b: 0, a: 1})).toBe(0);
+    expect(relativeLuminance({r: 255, g: 255, b: 255, a: 1})).toBeCloseTo(
+      1,
+      10,
+    );
+  });
+
+  it('weights channels per WCAG (green brightest, blue darkest)', () => {
+    const red = relativeLuminance({r: 255, g: 0, b: 0, a: 1});
+    const green = relativeLuminance({r: 0, g: 255, b: 0, a: 1});
+    const blue = relativeLuminance({r: 0, g: 0, b: 255, a: 1});
+    expect(red).toBeCloseTo(0.2126, 4);
+    expect(green).toBeCloseTo(0.7152, 4);
+    expect(blue).toBeCloseTo(0.0722, 4);
+  });
+});
+
+describe('contrastRatio', () => {
+  it('is 21 for black on white and 1 for identical colors', () => {
+    expect(contrastRatio('#000000', '#FFFFFF')).toBeCloseTo(21, 5);
+    expect(contrastRatio('#3B82F6', '#3B82F6')).toBe(1);
+  });
+
+  it('is symmetric in fg/bg for opaque colors', () => {
+    expect(contrastRatio('#0064E0', '#FCFDFE')).toBeCloseTo(
+      contrastRatio('#FCFDFE', '#0064E0'),
+      10,
+    );
+  });
+
+  it('matches the canonical 4.5:1 boundary gray (#767676 on white)', () => {
+    const ratio = contrastRatio('#767676', '#FFFFFF');
+    expect(ratio).toBeGreaterThanOrEqual(4.5);
+    expect(ratio).toBeLessThan(4.6);
+  });
+
+  it('composites a translucent foreground over the background', () => {
+    // 50% black over white paints as mid-gray, not black.
+    const composited = contrastRatio('rgba(0, 0, 0, 0.5)', '#FFFFFF');
+    expect(composited).toBeLessThan(contrastRatio('#000000', '#FFFFFF'));
+    expect(composited).toBeCloseTo(
+      contrastRatio('rgb(127.5, 127.5, 127.5)', '#FFFFFF'),
+      10,
+    );
+  });
+
+  it('rejects a translucent background', () => {
+    expect(() => contrastRatio('#000000', '#FFFFFF80')).toThrow(
+      /background must be opaque/,
+    );
+  });
+
+  it('rejects unparseable colors', () => {
+    expect(() => contrastRatio('var(--color-accent)', '#FFFFFF')).toThrow(
+      /could not parse foreground/,
+    );
+    expect(() => contrastRatio('#000000', 'oklch(0.5 0.1 200)')).toThrow(
+      /could not parse background/,
+    );
+  });
+});
+
+describe('compositeOver', () => {
+  it('returns the foreground when opaque and the backdrop at alpha 0', () => {
+    const fg = parseColor('#123456');
+    const bg = parseColor('#FFFFFF');
+    if (fg === null || bg === null) {
+      throw new Error('fixture colors must parse');
+    }
+    expect(compositeOver(fg, bg)).toEqual({...fg, a: 1});
+    expect(compositeOver({...fg, a: 0}, bg)).toEqual({...bg, a: 1});
+  });
+
+  it('blends in gamma-encoded sRGB space like CSS', () => {
+    const fg = parseColor('rgba(0, 0, 0, 0.5)');
+    const bg = parseColor('#FFFFFF');
+    if (fg === null || bg === null) {
+      throw new Error('fixture colors must parse');
+    }
+    const out = compositeOver(fg, bg);
+    expect(out.r).toBeCloseTo(127.5, 5);
+    expect(out.g).toBeCloseTo(127.5, 5);
+    expect(out.b).toBeCloseTo(127.5, 5);
+    expect(out.a).toBe(1);
+  });
+});

package/src/theme/contrast.ts

@@ -0,0 +1,99 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file contrast.ts
+ * @input CSS color strings (hex, rgb()/rgba()) or parsed RGBA values
+ * @output WCAG 2.x relative luminance and contrast ratios
+ * @position Theme utility; consumed by expandColorScale.ts and theme tests
+ *
+ * Dependency-free WCAG 2.x contrast math. Backs the contrast guarantees
+ * for generated color tokens (WCAG 1.4.3 text contrast >= 4.5:1,
+ * WCAG 1.4.11 non-text contrast >= 3:1).
+ *
+ * Semi-transparent foregrounds are composited over their backdrop in
+ * gamma-encoded sRGB space (matching CSS alpha compositing) before the
+ * ratio is measured — a translucent token has no contrast of its own,
+ * only against what it renders on.
+ */
+
+import type {RGBA} from '../utils/color';
+import {parseColor} from '../utils/color';
+
+/**
+ * WCAG 2.x relative luminance of an sRGB color (alpha ignored).
+ * 0 = black, 1 = white.
+ *
+ * https://www.w3.org/WAI/WCAG22/Techniques/general/G18
+ */
+export function relativeLuminance(color: RGBA): number {
+  const channel = (c: number): number => {
+    const s = c / 255;
+    return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  };
+  return (
+    0.2126 * channel(color.r) +
+    0.7152 * channel(color.g) +
+    0.0722 * channel(color.b)
+  );
+}
+
+/**
+ * Composite a (possibly translucent) foreground over an opaque backdrop
+ * using standard source-over alpha blending in gamma-encoded sRGB space,
+ * matching how CSS paints translucent tokens. Returns an opaque color.
+ */
+export function compositeOver(foreground: RGBA, backdrop: RGBA): RGBA {
+  const a = foreground.a;
+  return {
+    r: foreground.r * a + backdrop.r * (1 - a),
+    g: foreground.g * a + backdrop.g * (1 - a),
+    b: foreground.b * a + backdrop.b * (1 - a),
+    a: 1,
+  };
+}
+
+function resolve(value: string | RGBA, label: string): RGBA {
+  if (typeof value !== 'string') {
+    return value;
+  }
+  const parsed = parseColor(value);
+  if (parsed === null) {
+    throw new TypeError(`contrastRatio: could not parse ${label} "${value}"`);
+  }
+  return parsed;
+}
+
+/**
+ * WCAG 2.x contrast ratio between a foreground and an opaque background.
+ * Returns a value in [1, 21].
+ *
+ * A translucent foreground is composited over the background first.
+ * A translucent background is rejected — composite it over its own
+ * backdrop before calling, since its rendered color is unknowable here.
+ *
+ * @example
+ * ```
+ * contrastRatio('#000000', '#FFFFFF'); // 21
+ * contrastRatio('#0D131A', '#FCFDFE') >= 4.5; // text-on-surface check
+ * ```
+ */
+export function contrastRatio(
+  foreground: string | RGBA,
+  background: string | RGBA,
+): number {
+  const bg = resolve(background, 'background');
+  if (bg.a < 1) {
+    throw new TypeError(
+      'contrastRatio: background must be opaque — composite it over its backdrop first',
+    );
+  }
+  let fg = resolve(foreground, 'foreground');
+  if (fg.a < 1) {
+    fg = compositeOver(fg, bg);
+  }
+  const lumA = relativeLuminance(fg);
+  const lumB = relativeLuminance(bg);
+  const lighter = Math.max(lumA, lumB);
+  const darker = Math.min(lumA, lumB);
+  return (lighter + 0.05) / (darker + 0.05);
+}