@oxyhq/bloom 0.38.0 → 0.40.0

package/src/theme/adaptive-colors.ts

@@ -23,6 +23,9 @@ function getAndroidColors(): ThemeColors | null {
       primaryLight: c(d.primaryContainer),
       primaryDark: c(d.onPrimaryContainer),
       secondary: c(d.secondary),
+      secondaryForeground: c(d.onSecondary),
+      tertiary: c(d.tertiary),
+      tertiaryForeground: c(d.onTertiary),
       tint: c(d.primary),
       icon: c(d.onSurfaceVariant),
       iconActive: c(d.primary),
@@ -66,6 +69,9 @@ function getIOSColors(): ThemeColors | null {
       primaryLight: c(i.systemGray6),
       primaryDark: c(i.systemBlue),
       secondary: c(i.systemPurple),
+      secondaryForeground: '#FFFFFF',
+      tertiary: c(i.systemTeal),
+      tertiaryForeground: '#FFFFFF',
       tint: c(i.systemBlue),
       icon: c(i.secondaryLabel),
       iconActive: c(i.systemBlue),

package/src/theme/build-theme-from-seed.ts

@@ -0,0 +1,99 @@
+import { generateRoleColors, type RoleColors, type SchemeVariant } from './color-engine';
+import { buildSeedScopeVars } from './color-scope/seed-scope';
+import { STATUS_COLORS } from './build-theme';
+import { THEME_GRADIENTS } from './gradients';
+import type { Theme, ThemeColors } from './types';
+
+/**
+ * Build the JS `theme.colors` object from an ARBITRARY seed colour — the dynamic
+ * counterpart of `buildTheme(preset, …)`.
+ *
+ * This mirrors `buildColorsFromPreset` (`build-theme.ts`) field-for-field, but
+ * sources its tokens from `buildSeedScopeVars({ seed })` instead of a named
+ * preset, so a preset's seed reproduces that preset's JS theme exactly. Keeping
+ * the two in lockstep is enforced by `__tests__/build-theme-from-seed-parity.test.ts`.
+ *
+ * Token-backed fields read the resolved `rgb(...)` token map; the brand-tint
+ * family (primarySubtle / negative / …) reads the engine's container/error roles
+ * directly — identical to the preset path.
+ */
+export function buildColorsFromSeed(
+  seed: string,
+  resolved: 'light' | 'dark',
+  variant?: SchemeVariant,
+  contrastLevel?: number,
+): ThemeColors {
+  const t = buildSeedScopeVars({ seed, mode: resolved, variant, contrastLevel });
+  const isDark = resolved === 'dark';
+
+  // Read a resolved `rgb(...)` token by its bare name (no leading `--`).
+  const g = (k: string): string => t[`--${k}`] ?? 'rgb(0 0 0)';
+
+  const r: RoleColors = generateRoleColors({
+    seed,
+    variant,
+    isDark,
+    contrastLevel,
+  });
+
+  return {
+    background: g('background'),
+    backgroundSecondary: g('surface'),
+    backgroundTertiary: g('popover'),
+
+    text: g('foreground'),
+    textSecondary: g('muted-foreground'),
+    textTertiary: r.outline,
+
+    border: g('border'),
+    borderLight: g('input'),
+
+    primary: g('primary'),
+    primaryForeground: g('primary-foreground'),
+    primaryLight: g('surface'),
+    primaryDark: g('background'),
+
+    secondary: g('secondary'),
+    secondaryForeground: g('secondary-foreground'),
+    tertiary: g('tertiary'),
+    tertiaryForeground: g('tertiary-foreground'),
+
+    tint: g('primary'),
+    icon: g('muted-foreground'),
+    iconActive: g('primary'),
+
+    ...STATUS_COLORS,
+
+    primarySubtle: r.primaryContainer,
+    primarySubtleForeground: r.onPrimaryContainer,
+    negative: r.error,
+    negativeForeground: r.onError,
+    negativeSubtle: r.errorContainer,
+    negativeSubtleForeground: r.onErrorContainer,
+    contrast50: g('muted'),
+
+    card: g('card'),
+    shadow: isDark ? 'rgba(0, 0, 0, 0.3)' : 'rgba(0, 0, 0, 0.1)',
+    overlay: 'rgba(0, 0, 0, 0.5)',
+  };
+}
+
+/**
+ * Build a full `Theme` from a seed colour and a resolved light/dark mode. Unlike
+ * `buildTheme`, there is no adaptive (Material You / iOS dynamic) override — a
+ * seed IS the dynamic source here.
+ */
+export function buildThemeFromSeed(
+  seed: string,
+  resolved: 'light' | 'dark',
+  variant?: SchemeVariant,
+  contrastLevel?: number,
+): Theme {
+  return {
+    mode: resolved,
+    colors: buildColorsFromSeed(seed, resolved, variant, contrastLevel),
+    gradients: THEME_GRADIENTS,
+    isDark: resolved === 'dark',
+    isLight: resolved === 'light',
+  };
+}

package/src/theme/build-theme.ts

@@ -67,8 +67,12 @@ function buildColorsFromPreset(
     primaryLight: g('surface'),
     primaryDark: g('background'),
 
-    // The FIX: `secondary` is now a real contrast colour (engine `secondary`).
+    // The M3 accent trio: secondary is a real contrast colour (engine `secondary`),
+    // and tertiary completes primary/secondary/tertiary.
     secondary: g('secondary'),
+    secondaryForeground: g('secondary-foreground'),
+    tertiary: g('tertiary'),
+    tertiaryForeground: g('tertiary-foreground'),
 
     tint: g('primary'),
     icon: g('muted-foreground'),

package/src/theme/color-scope/seed-scope.ts

@@ -0,0 +1,105 @@
+import { generateRoleColors, type RoleColors, type SchemeVariant } from '../color-engine';
+import { CANONICAL_TOKENS } from '../token-registry';
+
+/**
+ * The canonical role → token assignment, sourced from an arbitrary seed's role
+ * set instead of a named preset.
+ *
+ * This MUST stay byte-for-byte identical to the mapping in `getPresetVars`
+ * (`preset-vars.ts`): a named preset is just a fixed seed, so scoping a subtree
+ * to a preset via `buildScopeVars` and scoping it to that preset's seed hex via
+ * `buildSeedScopeVars` are required to produce the same tokens. The parity test
+ * (`__tests__/seed-scope-parity.test.ts`) fails CI if the two ever drift.
+ *
+ * Values are full `rgb(r g b)` strings straight from the engine — no HSL-triple
+ * intermediate, so they flow through the scope pipeline unchanged (same as the
+ * preset path after `getResolvedTokens`).
+ */
+export function roleColorsToPresetTokens(r: RoleColors): Record<string, string> {
+  return {
+    // --- base shadcn palette ---
+    '--background': r.background,
+    '--foreground': r.onBackground,
+    '--surface': r.surfaceContainerLow,
+    '--surface-foreground': r.onSurface,
+    '--popover': r.surfaceContainer,
+    '--popover-foreground': r.onSurface,
+    '--primary': r.primary,
+    '--primary-foreground': r.onPrimary,
+    '--secondary': r.secondary,
+    '--secondary-foreground': r.onSecondary,
+    '--tertiary': r.tertiary,
+    '--tertiary-foreground': r.onTertiary,
+    '--muted': r.surfaceContainerHigh,
+    '--muted-foreground': r.onSurfaceVariant,
+    '--accent': r.secondaryContainer,
+    '--accent-foreground': r.onSecondaryContainer,
+    '--destructive': r.error,
+    '--border': r.outlineVariant,
+    '--input': r.outlineVariant,
+    '--ring': r.primary,
+    '--sidebar': r.surfaceContainerLow,
+
+    // --- extended tokens ---
+    '--card': r.surfaceContainerLowest,
+    '--card-foreground': r.onSurface,
+    '--chart-1': r.primary,
+    '--chart-2': r.secondary,
+    '--chart-3': r.tertiary,
+    '--chart-4': r.primaryContainer,
+    '--chart-5': r.tertiaryContainer,
+    '--content-area': r.background,
+    '--sidebar-foreground': r.onSurface,
+    '--sidebar-primary': r.primary,
+    '--sidebar-primary-foreground': r.onPrimary,
+    '--sidebar-accent': r.secondaryContainer,
+    '--sidebar-accent-foreground': r.onSecondaryContainer,
+    '--sidebar-border': r.outlineVariant,
+    '--sidebar-ring': r.primary,
+  };
+}
+
+/** Options for deriving scope vars directly from a seed colour. */
+export interface SeedScopeOptions {
+  /** The seed colour, `#rrggbb`. */
+  seed: string;
+  mode: 'light' | 'dark';
+  /**
+   * The tonal scheme variant. Defaults to `'vibrant'` — the same variant every
+   * named Bloom preset uses, so a preset's seed reproduces that preset exactly.
+   */
+  variant?: SchemeVariant;
+  /** −1 (low) … 0 (normal) … 1 (high). Defaults to 0. */
+  contrastLevel?: number;
+}
+
+/**
+ * Build the CSS custom-property map for an ARBITRARY seed colour — the dynamic
+ * (non-preset) counterpart of `buildScopeVars`. Feeds the seed through the
+ * colour engine's `generateRoleColors` and assigns the roles to Bloom's
+ * canonical token names, then adds the Tailwind v4 `--color-x` aliases (required
+ * on web so scoped utilities resolve against the subtree instead of the document
+ * root).
+ *
+ * Scope the returned record onto an element (web: inline `style`; native:
+ * NativeWind `VariableContextProvider`) to tint just that subtree — e.g. the
+ * ambient region behind album/artist artwork — without re-theming the whole app.
+ */
+export function buildSeedScopeVars(options: SeedScopeOptions): Record<string, string> {
+  const roles = generateRoleColors({
+    seed: options.seed,
+    isDark: options.mode === 'dark',
+    contrastLevel: options.contrastLevel ?? 0,
+  });
+  const tokens = roleColorsToPresetTokens(roles);
+  const vars: Record<string, string> = { ...tokens };
+
+  for (const token of CANONICAL_TOKENS) {
+    const value = tokens[`--${token}`];
+    if (value !== undefined) {
+      vars[`--color-${token}`] = value;
+    }
+  }
+
+  return vars;
+}

package/src/theme/index.ts

@@ -5,7 +5,28 @@ export type {
 } from './BloomThemeProvider';
 export { BloomColorScope, useColorScopeStyle } from './color-scope';
 export type { BloomColorScopeProps } from './color-scope';
+export { BloomSeedScope } from './seed-scope';
+export type { BloomSeedScopeProps } from './seed-scope';
+export { buildSeedScopeVars, roleColorsToPresetTokens } from './color-scope/seed-scope';
+export type { SeedScopeOptions } from './color-scope/seed-scope';
+// Colour engine — the dependency-free tonal system that turns ANY seed colour
+// into a full role set. Surfaced here so consumers can derive dynamic themes
+// (e.g. from artwork) without reaching into the internal color-engine path.
+export {
+  generateRoleColors,
+  seedHexFromImagePixels,
+  seedsFromImagePixels,
+  quantizeImage,
+  argbFromHex,
+  hexFromArgb,
+  argbFromRgb,
+  redFromArgb,
+  greenFromArgb,
+  blueFromArgb,
+} from './color-engine';
+export type { RoleColors, GenerateOptions, RoleName, SchemeVariant } from './color-engine';
 export { buildTheme, STATUS_COLORS } from './build-theme';
+export { buildThemeFromSeed, buildColorsFromSeed } from './build-theme-from-seed';
 export { THEME_GRADIENTS } from './gradients';
 export { useTheme, useThemeColor, useBloomTheme } from './use-theme';
 export { useNavigationTheme } from './use-navigation-theme';

package/src/theme/preset-vars.ts

@@ -48,6 +48,10 @@ export function getPresetVars(
     // role), not a mirror of `primary`.
     '--secondary': r.secondary,
     '--secondary-foreground': r.onSecondary,
+    // The third accent of the M3 trio, exposed so `bg-tertiary` / `colors.tertiary`
+    // work alongside primary + secondary.
+    '--tertiary': r.tertiary,
+    '--tertiary-foreground': r.onTertiary,
     '--muted': r.surfaceContainerHigh,
     '--muted-foreground': r.onSurfaceVariant,
     '--accent': r.secondaryContainer,

package/src/theme/seed-scope/index.tsx

@@ -0,0 +1,100 @@
+import React, { Children, cloneElement, isValidElement, useContext, useMemo } from 'react';
+import { View, type StyleProp, type ViewStyle } from 'react-native';
+
+import { BloomThemeContext, type BloomThemeContextValue } from '../BloomThemeProvider';
+import { buildSeedScopeVars } from '../color-scope/seed-scope';
+import { getVariableContextProvider } from '../color-scope/style-builder';
+import { buildThemeFromSeed } from '../build-theme-from-seed';
+import type { SchemeVariant } from '../color-engine';
+
+export interface BloomSeedScopeProps {
+  /**
+   * The seed colour (`#rrggbb`) to derive this subtree's palette from. When
+   * `undefined`, the scope is a no-op and children inherit the parent scope
+   * unchanged — pass `undefined` to fall back to the app preset (e.g. on
+   * mouse-leave/blur when restoring the default theme).
+   */
+  seed: string | undefined;
+  /** Tonal scheme variant. Defaults to `'vibrant'` (matches Bloom presets). */
+  variant?: SchemeVariant;
+  /** −1 (low) … 0 (normal) … 1 (high). Defaults to 0. */
+  contrastLevel?: number;
+  /**
+   * When `true`, do not render a wrapping `<View>`. The single child is cloned
+   * with the caller's `style` merged into its `style` prop (Radix-style).
+   */
+  asChild?: boolean;
+  /** Additional style applied to the wrapping `<View>` (or merged into the cloned child with `asChild`). */
+  style?: StyleProp<ViewStyle>;
+  children: React.ReactNode;
+}
+
+interface StyleableProps {
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Native `<BloomSeedScope>`: scopes a subtree to an ARBITRARY seed colour's
+ * palette (the dynamic counterpart of `<BloomColorScope>`, which takes a named
+ * preset). Feeds the seed through the colour engine and (1) provides the
+ * resulting canonical CSS vars to descendants via react-native-css's
+ * `VariableContext` — so `bg-background` / `bg-card` / `var(--primary)` resolve
+ * against the seed inside this subtree — and (2) publishes a matching JS `theme`
+ * on `BloomThemeContext`, so `useTheme()`/`useBloomTheme()` consumers inside the
+ * subtree also re-theme. The `colorPreset` field is left as the parent's (a seed
+ * is not a named preset).
+ */
+export function BloomSeedScope({
+  seed,
+  variant,
+  contrastLevel,
+  asChild = false,
+  style,
+  children,
+}: BloomSeedScopeProps) {
+  // Hooks run unconditionally; conditional no-op/throw is applied afterwards.
+  const parent = useContext(BloomThemeContext);
+  const resolvedMode = parent?.theme.mode ?? 'light';
+
+  const nativeVars = useMemo<Record<string, string> | null>(
+    () => (seed ? buildSeedScopeVars({ seed, mode: resolvedMode, variant, contrastLevel }) : null),
+    [seed, resolvedMode, variant, contrastLevel],
+  );
+
+  const contextValue = useMemo<BloomThemeContextValue | null>(() => {
+    if (!parent || !seed) return null;
+    const theme = buildThemeFromSeed(seed, resolvedMode, variant, contrastLevel);
+    return { ...parent, theme };
+  }, [parent, seed, resolvedMode, variant, contrastLevel]);
+
+  if (!parent) {
+    throw new Error('BloomSeedScope must be used within a <BloomThemeProvider>');
+  }
+  // `seed` undefined => no-op; children inherit the parent scope.
+  if (!nativeVars || !contextValue) return <>{children}</>;
+
+  const VariableProvider = getVariableContextProvider();
+
+  let content: React.ReactNode;
+  if (asChild) {
+    const child = Children.only(children);
+    if (!isValidElement<StyleableProps>(child)) {
+      throw new Error(
+        'BloomSeedScope with `asChild` requires a single React element child that accepts a `style` prop.',
+      );
+    }
+    const childStyle = child.props.style;
+    const mergedStyle: StyleProp<ViewStyle> = [style, childStyle];
+    content = cloneElement(child, { style: mergedStyle });
+  } else {
+    content = <View style={[{ flex: 1 }, style]}>{children}</View>;
+  }
+
+  const scoped = VariableProvider ? (
+    <VariableProvider value={nativeVars}>{content}</VariableProvider>
+  ) : (
+    content
+  );
+
+  return <BloomThemeContext.Provider value={contextValue}>{scoped}</BloomThemeContext.Provider>;
+}

package/src/theme/seed-scope/index.web.tsx

@@ -0,0 +1,110 @@
+import React, { Children, cloneElement, isValidElement, useContext, useMemo } from 'react';
+
+import { BloomThemeContext, type BloomThemeContextValue } from '../BloomThemeProvider';
+import { buildSeedScopeVars } from '../color-scope/seed-scope';
+import { buildThemeFromSeed } from '../build-theme-from-seed';
+import type { SchemeVariant } from '../color-engine';
+
+export interface BloomSeedScopeProps {
+  /**
+   * The seed colour (`#rrggbb`) to derive this subtree's palette from. When
+   * `undefined`, the scope is a no-op and children inherit the parent scope
+   * unchanged — pass `undefined` to fall back to the app preset (e.g. on
+   * mouse-leave/blur when restoring the default theme).
+   */
+  seed: string | undefined;
+  /** Tonal scheme variant. Defaults to `'vibrant'` (matches Bloom presets). */
+  variant?: SchemeVariant;
+  /** −1 (low) … 0 (normal) … 1 (high). Defaults to 0. */
+  contrastLevel?: number;
+  /**
+   * When `true`, do not render a wrapping `<div>`. The single child is cloned
+   * with the scope's CSS vars merged into its `style` prop (Radix-style).
+   */
+  asChild?: boolean;
+  /** Additional style applied to the wrapping `<div>` (or merged into the cloned child with `asChild`). */
+  style?: React.CSSProperties;
+  children: React.ReactNode;
+}
+
+/**
+ * On web the single `asChild` child is frequently a react-native-web component
+ * whose `style` prop is a style ARRAY (or a numeric registered-style id), not a
+ * plain object. Spreading such an array into an object literal would copy its
+ * numeric indices as keys and crash RNW; merge as an array instead.
+ */
+type WebStyle =
+  | React.CSSProperties
+  | number
+  | null
+  | undefined
+  | false
+  | ReadonlyArray<WebStyle>;
+
+interface StyleableProps {
+  style?: WebStyle;
+}
+
+/**
+ * Web `<BloomSeedScope>`: scopes a subtree to an ARBITRARY seed colour's palette
+ * (the dynamic counterpart of `<BloomColorScope>`). It (1) writes every canonical
+ * `--x` token plus the Tailwind v4 `--color-x` aliases (already resolved to
+ * `rgb(...)`) onto the wrapping element's inline `style`, so NativeWind classes
+ * inside resolve against the seed palette instead of the document root, and
+ * (2) publishes a matching JS `theme` on `BloomThemeContext` so
+ * `useTheme()`/`useBloomTheme()` consumers inside the subtree re-theme too. The
+ * `colorPreset` field is left as the parent's (a seed is not a named preset).
+ */
+export function BloomSeedScope({
+  seed,
+  variant,
+  contrastLevel,
+  asChild = false,
+  style,
+  children,
+}: BloomSeedScopeProps) {
+  const parent = useContext(BloomThemeContext);
+  const resolvedMode = parent?.theme.mode ?? 'light';
+
+  const varsStyle = useMemo<React.CSSProperties | null>(
+    () =>
+      seed
+        ? (buildSeedScopeVars({
+            seed,
+            mode: resolvedMode,
+            variant,
+            contrastLevel,
+          }) as React.CSSProperties)
+        : null,
+    [seed, resolvedMode, variant, contrastLevel],
+  );
+
+  const contextValue = useMemo<BloomThemeContextValue | null>(() => {
+    if (!parent || !seed) return null;
+    const theme = buildThemeFromSeed(seed, resolvedMode, variant, contrastLevel);
+    return { ...parent, theme };
+  }, [parent, seed, resolvedMode, variant, contrastLevel]);
+
+  if (!parent) {
+    throw new Error('BloomSeedScope must be used within a <BloomThemeProvider>');
+  }
+  if (!varsStyle || !contextValue) return <>{children}</>;
+
+  let content: React.ReactNode;
+  if (asChild) {
+    const child = Children.only(children);
+    if (!isValidElement<StyleableProps>(child)) {
+      throw new Error(
+        'BloomSeedScope with `asChild` requires a single React element child that accepts a `style` prop.',
+      );
+    }
+    const childStyle = child.props.style;
+    const mergedStyle: WebStyle = [varsStyle, style, childStyle];
+    content = cloneElement(child, { style: mergedStyle });
+  } else {
+    const mergedStyle: React.CSSProperties = { ...varsStyle, ...style };
+    content = <div style={mergedStyle}>{children}</div>;
+  }
+
+  return <BloomThemeContext.Provider value={contextValue}>{content}</BloomThemeContext.Provider>;
+}

package/src/theme/token-registry.ts

@@ -25,6 +25,8 @@ export const CANONICAL_TOKENS = [
   'primary-foreground',
   'secondary',
   'secondary-foreground',
+  'tertiary',
+  'tertiary-foreground',
   'muted',
   'muted-foreground',
   'accent',

package/src/theme/types.ts

@@ -19,8 +19,12 @@ export interface ThemeColors {
   /** Legacy alias: the page background (`--background`), NOT the focus ring. */
   primaryDark: string;
 
-  /** Legacy alias: mirrors `primary` (`--primary`) for backwards compatibility. */
+  /** The M3 secondary accent — a real contrast colour (no longer a mirror of primary). */
   secondary: string;
+  secondaryForeground: string;
+  /** The M3 tertiary accent, completing the primary/secondary/tertiary trio. */
+  tertiary: string;
+  tertiaryForeground: string;
 
   tint: string;
   icon: string;