@astryxdesign/core 0.1.3 → 0.1.4-canary.01e5b29

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

@@ -122,4 +122,24 @@ 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',
+    );
+  });
 });

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)');
+  });
+});

package/src/utils/color.ts

@@ -0,0 +1,148 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file color.ts
+ * @input CSS color strings (hex, rgb()/rgba(), a small set of named colors)
+ * @output Shared color parsing/formatting primitives used across the design system
+ * @position Package utility; backs theme token resolution, HCT color math, and chart rendering
+ *
+ * A single home for the color parsers that were previously duplicated across
+ * the theme layer, charts, and lab. Consumers get one well-tested definition of
+ * "parse this color" rather than several subtly different regexes.
+ */
+
+/** A color decomposed into 0-255 RGB channels and a 0-1 alpha. */
+export interface RGBA {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+/** The named colors the design system relies on in token expressions. */
+const NAMED_COLORS: Record<string, RGBA> = {
+  transparent: {r: 0, g: 0, b: 0, a: 0},
+  black: {r: 0, g: 0, b: 0, a: 1},
+  white: {r: 255, g: 255, b: 255, a: 1},
+};
+
+const clamp = (value: number, min: number, max: number): number =>
+  Math.max(min, Math.min(max, value));
+
+/** Expand a shorthand hex body (`rgb`/`rgba`) to its full form (`rrggbb`/`rrggbbaa`). */
+function expandShorthand(body: string): string {
+  return body
+    .split('')
+    .map(c => c + c)
+    .join('');
+}
+
+/**
+ * Parse a hex color into {@link RGBA}. Accepts `#rgb`, `#rgba`, `#rrggbb`, and
+ * `#rrggbbaa`, with or without the leading `#`. Returns null for anything else.
+ */
+export function parseHex(hex: string): RGBA | null {
+  if (typeof hex !== 'string') {
+    return null;
+  }
+  const body = hex.trim().replace(/^#/, '');
+  const normalized =
+    body.length === 3 || body.length === 4 ? expandShorthand(body) : body;
+
+  if (
+    (normalized.length !== 6 && normalized.length !== 8) ||
+    !/^[0-9a-fA-F]+$/.test(normalized)
+  ) {
+    return null;
+  }
+
+  return {
+    r: parseInt(normalized.slice(0, 2), 16),
+    g: parseInt(normalized.slice(2, 4), 16),
+    b: parseInt(normalized.slice(4, 6), 16),
+    a: normalized.length === 8 ? parseInt(normalized.slice(6, 8), 16) / 255 : 1,
+  };
+}
+
+/**
+ * Parse an `rgb()`/`rgba()` color into {@link RGBA}. Accepts comma- or
+ * space-separated channels, an optional `/ alpha`, and percentage channels.
+ */
+export function parseRgb(value: string): RGBA | null {
+  const open = value.indexOf('(');
+  if (open === -1 || !value.trim().endsWith(')')) {
+    return null;
+  }
+  const body = value
+    .slice(open + 1, value.lastIndexOf(')'))
+    .replace(/\//g, ' ');
+  const parts = body
+    .split(/[\s,]+/)
+    .map(p => p.trim())
+    .filter(Boolean);
+  if (parts.length < 3) {
+    return null;
+  }
+
+  const channel = (p: string): number => {
+    const n = p.endsWith('%') ? (parseFloat(p) / 100) * 255 : parseFloat(p);
+    return clamp(n, 0, 255);
+  };
+  const r = channel(parts[0]);
+  const g = channel(parts[1]);
+  const b = channel(parts[2]);
+  if ([r, g, b].some(Number.isNaN)) {
+    return null;
+  }
+
+  let a = 1;
+  if (parts.length >= 4) {
+    const raw = parts[3];
+    a = raw.endsWith('%') ? parseFloat(raw) / 100 : parseFloat(raw);
+    if (Number.isNaN(a)) {
+      return null;
+    }
+    a = clamp(a, 0, 1);
+  }
+  return {r, g, b, a};
+}
+
+/**
+ * Parse a concrete CSS color string into {@link RGBA}. Supports hex,
+ * `rgb()`/`rgba()`, and the named colors used in token expressions. Returns
+ * null for anything it can't evaluate (e.g. `var()`, `oklch()`, unknown names)
+ * so callers can preserve the original expression rather than guessing.
+ */
+export function parseColor(value: string): RGBA | null {
+  const trimmed = value.trim();
+  const named = NAMED_COLORS[trimmed.toLowerCase()];
+  if (named) {
+    return {...named};
+  }
+  if (trimmed.startsWith('#')) {
+    return parseHex(trimmed);
+  }
+  if (/^rgba?\(/i.test(trimmed)) {
+    return parseRgb(trimmed);
+  }
+  return null;
+}
+
+/** Format RGB channels (0-255) as an uppercase `#RRGGBB` string. */
+export function formatHex(r: number, g: number, b: number): string {
+  const channel = (c: number): string =>
+    clamp(Math.round(c), 0, 255).toString(16).padStart(2, '0').toUpperCase();
+  return `#${channel(r)}${channel(g)}${channel(b)}`;
+}
+
+/**
+ * Serialize {@link RGBA} to a compact, JS-usable CSS color: `#RRGGBB` when
+ * fully opaque, otherwise `rgba(r, g, b, a)`.
+ */
+export function formatColor({r, g, b, a}: RGBA): string {
+  if (a >= 1) {
+    return formatHex(r, g, b);
+  }
+  const round = (n: number): number => clamp(Math.round(n), 0, 255);
+  return `rgba(${round(r)}, ${round(g)}, ${round(b)}, ${parseFloat(a.toFixed(4))})`;
+}

package/src/utils/composeEventHandlers.test.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it, vi} from 'vitest';
+import type {SyntheticEvent} from 'react';
+import {composeEventHandlers} from './composeEventHandlers';
+
+function fakeEvent(): SyntheticEvent {
+  const event = {
+    defaultPrevented: false,
+    preventDefault() {
+      event.defaultPrevented = true;
+    },
+  };
+  return event as unknown as SyntheticEvent;
+}
+
+describe('composeEventHandlers', () => {
+  it('calls every handler in argument order', () => {
+    const calls: string[] = [];
+    const composed = composeEventHandlers(
+      () => calls.push('first'),
+      () => calls.push('second'),
+    );
+    composed(fakeEvent());
+    expect(calls).toEqual(['first', 'second']);
+  });
+
+  it('skips undefined handlers', () => {
+    const handler = vi.fn();
+    const composed = composeEventHandlers(undefined, handler, undefined);
+    composed(fakeEvent());
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('passes the same event to each handler', () => {
+    const event = fakeEvent();
+    const a = vi.fn();
+    const b = vi.fn();
+    composeEventHandlers(a, b)(event);
+    expect(a).toHaveBeenCalledWith(event);
+    expect(b).toHaveBeenCalledWith(event);
+  });
+
+  it('stops after a handler prevents default', () => {
+    const first = vi.fn((e: SyntheticEvent) => e.preventDefault());
+    const second = vi.fn();
+    composeEventHandlers(first, second)(fakeEvent());
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).not.toHaveBeenCalled();
+  });
+
+  it('lets a consumer handler opt out of later behavior (consumer-first order)', () => {
+    const consumer = vi.fn((e: SyntheticEvent) => e.preventDefault());
+    const ownBehavior = vi.fn();
+    composeEventHandlers(consumer, ownBehavior)(fakeEvent());
+    expect(ownBehavior).not.toHaveBeenCalled();
+  });
+
+  it('runs later handlers when default is not prevented', () => {
+    const consumer = vi.fn();
+    const ownBehavior = vi.fn();
+    composeEventHandlers(consumer, ownBehavior)(fakeEvent());
+    expect(ownBehavior).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns a no-op-safe function when all handlers are undefined', () => {
+    expect(() =>
+      composeEventHandlers(undefined, undefined)(fakeEvent()),
+    ).not.toThrow();
+  });
+});

package/src/utils/composeEventHandlers.ts

@@ -0,0 +1,44 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file composeEventHandlers.ts
+ * @input Multiple React event handlers (or undefined)
+ * @output A single handler that calls each in order, stopping if one prevents default
+ * @position Utility; used by components that own an interaction (a click that
+ *   selects, a keydown that drives arrow navigation) but also accept a consumer
+ *   handler for the same event through {...rest}. Composes them instead of
+ *   letting one clobber the other.
+ *
+ * Order is call order: the first argument runs first. Put the consumer handler
+ * first so it can opt out of the component's built-in behavior via
+ * `event.preventDefault()`; put the component's handler first when its behavior
+ * must always run regardless of the consumer.
+ */
+
+import type {SyntheticEvent} from 'react';
+
+/**
+ * Compose event handlers into one. Each handler runs in argument order; if any
+ * calls `event.preventDefault()`, the remaining handlers are skipped.
+ *
+ * @example
+ * ```tsx
+ * // Consumer first: a consumer onClick can preventDefault to block selection.
+ * <button onClick={composeEventHandlers(onClickProp, handleSelect)} />
+ *
+ * // Component first: built-in keyboard nav always runs.
+ * <div onKeyDown={composeEventHandlers(handleArrowKeys, onKeyDownProp)} />
+ * ```
+ */
+export function composeEventHandlers<E extends SyntheticEvent>(
+  ...handlers: (((event: E) => void) | undefined)[]
+): (event: E) => void {
+  return (event: E) => {
+    for (const handler of handlers) {
+      handler?.(event);
+      if (event.defaultPrevented) {
+        return;
+      }
+    }
+  };
+}