@oxyhq/bloom 0.6.13 → 0.6.14

package/src/theme/build-theme.ts

@@ -0,0 +1,128 @@
+import { Platform } from 'react-native';
+import { APP_COLOR_PRESETS, type AppColorName, type PresetTokens } from './color-presets';
+import { getAdaptiveColors } from './adaptive-colors';
+import type { Theme, ThemeColors } from './types';
+
+/**
+ * Status colors used across the design system. Independent of the accent
+ * preset so semantic intent stays stable across themes.
+ */
+export const STATUS_COLORS = {
+  success: '#10B981',
+  error: '#EF4444',
+  warning: '#F59E0B',
+  info: '#3B82F6',
+} as const;
+
+/**
+ * Convert a shadcn-style HSL CSS variable (`'H S% L%'` or `'H S% L% / A'`)
+ * into a fully-resolved `hsl()` / `hsla()` color string consumable by both
+ * web `style` and React Native.
+ */
+function hslVarToColor(hslVar: string): string {
+  const parts = hslVar.split('/').map((p) => p.trim());
+  const triple = parts[0] ?? '0 0% 0%';
+  const components = triple.replace(/\s+/g, ', ');
+
+  if (parts.length === 2) {
+    const alpha = parseFloat(parts[1] ?? '100') / 100;
+    return `hsla(${components}, ${alpha})`;
+  }
+  return `hsl(${components})`;
+}
+
+function extractHue(hslVar: string): number {
+  const first = hslVar.split(/\s+/)[0] ?? '0';
+  const hue = parseInt(first, 10);
+  return Number.isFinite(hue) ? hue : 0;
+}
+
+function hsl(h: number, s: number, l: number): string {
+  return `hsl(${h}, ${s}%, ${l}%)`;
+}
+
+function readToken(tokens: PresetTokens, key: string, fallback = '0 0% 0%'): string {
+  return hslVarToColor(tokens[key] ?? fallback);
+}
+
+function buildColorsFromPreset(
+  preset: AppColorName,
+  resolved: 'light' | 'dark',
+): ThemeColors {
+  const config = APP_COLOR_PRESETS[preset];
+  const tokens = resolved === 'dark' ? config.dark : config.light;
+  const isDark = resolved === 'dark';
+
+  const primaryHue = extractHue(tokens['--primary'] ?? '0 0% 50%');
+  const destructiveHue = extractHue(tokens['--destructive'] ?? '0 0% 0%');
+
+  const background = readToken(tokens, '--background');
+  const surface = readToken(tokens, '--surface');
+  const mutedForeground = readToken(tokens, '--muted-foreground', '0 0% 50%');
+  const primaryColor = readToken(tokens, '--primary', '0 0% 50%');
+  const primaryForeground = readToken(tokens, '--primary-foreground', '0 0% 100%');
+
+  return {
+    background,
+    backgroundSecondary: surface,
+    backgroundTertiary: readToken(tokens, '--muted'),
+
+    text: readToken(tokens, '--foreground', '0 0% 100%'),
+    textSecondary: mutedForeground,
+    textTertiary: mutedForeground,
+
+    border: readToken(tokens, '--border', '0 0% 20%'),
+    borderLight: readToken(tokens, '--input', '0 0% 20%'),
+
+    primary: primaryColor,
+    primaryForeground,
+    // Legacy aliases retained for backwards compatibility with downstream
+    // consumers. `primaryLight` should be a brand tint, not the surface, but
+    // changing this is a breaking change handled in a separate major.
+    primaryLight: surface,
+    primaryDark: background,
+
+    // `secondary` historically mirrored `primary`. Retained for compatibility.
+    secondary: primaryColor,
+
+    tint: primaryColor,
+    icon: mutedForeground,
+    iconActive: primaryColor,
+
+    ...STATUS_COLORS,
+
+    primarySubtle: isDark ? hsl(primaryHue, 50, 10) : hsl(primaryHue, 70, 93),
+    primarySubtleForeground: isDark ? hsl(primaryHue, 70, 65) : hsl(primaryHue, 90, 25),
+    negative: hsl(destructiveHue, 84, 45),
+    negativeForeground: '#FFFFFF',
+    negativeSubtle: isDark ? hsl(destructiveHue, 50, 10) : hsl(destructiveHue, 90, 95),
+    negativeSubtleForeground: isDark ? hsl(destructiveHue, 70, 65) : hsl(destructiveHue, 80, 40),
+    contrast50: isDark ? hsl(primaryHue, 15, 12) : hsl(primaryHue, 10, 93),
+
+    card: surface,
+    shadow: isDark ? 'rgba(0, 0, 0, 0.3)' : 'rgba(0, 0, 0, 0.1)',
+    overlay: 'rgba(0, 0, 0, 0.5)',
+  };
+}
+
+/**
+ * Build a `Theme` from a color preset and a resolved light/dark mode.
+ *
+ * When `isAdaptive` is true and the platform exposes adaptive (Material You /
+ * iOS dynamic) colors, those override the preset-derived palette.
+ */
+export function buildTheme(
+  preset: AppColorName,
+  resolved: 'light' | 'dark',
+  isAdaptive: boolean = false,
+): Theme {
+  const adaptive = isAdaptive && Platform.OS !== 'web' ? getAdaptiveColors() : undefined;
+  const colors = adaptive ?? buildColorsFromPreset(preset, resolved);
+
+  return {
+    mode: resolved,
+    colors,
+    isDark: resolved === 'dark',
+    isLight: resolved === 'light',
+  };
+}

package/src/theme/color-presets.ts

@@ -1,13 +1,29 @@
 export type AppColorName = 'teal' | 'blue' | 'green' | 'amber' | 'yellow' | 'red' | 'purple' | 'pink' | 'sky' | 'orange' | 'mint' | 'oxy' | 'faircoin';
 
+/**
+ * Palette tokens for a single mode (light or dark) of a color preset.
+ *
+ * Keys carry a leading `--` for historical reasons (shadcn-style CSS variable
+ * names) — keep in mind the values are platform-agnostic **raw HSL triples**
+ * (e.g. `'185 100% 20%'` or `'185 100% 20% / 0.5'`), not CSS-resolved colors.
+ * The same map drives both:
+ *   - the web layer (written verbatim into `document.documentElement.style`
+ *     so Tailwind's `hsl(var(--primary))` plumbing picks them up), and
+ *   - the native layer (`buildTheme` resolves them into `hsl(...)` strings
+ *     consumable by React Native styles).
+ *
+ * The `--` prefix is an implementation detail we will drop in a future major.
+ */
+export type PresetTokens = Record<string, string>;
+
 export interface AppColorPreset {
   name: AppColorName;
   hex: string;
-  light: Record<string, string>;
-  dark: Record<string, string>;
+  light: PresetTokens;
+  dark: PresetTokens;
 }
 
-export const APP_COLOR_NAMES: AppColorName[] = ['teal', 'blue', 'green', 'amber', 'yellow', 'red', 'purple', 'pink', 'sky', 'orange', 'mint', 'oxy', 'faircoin'];
+export const APP_COLOR_NAMES: readonly AppColorName[] = ['teal', 'blue', 'green', 'amber', 'yellow', 'red', 'purple', 'pink', 'sky', 'orange', 'mint', 'oxy', 'faircoin'];
 
 export const HEX_TO_APP_COLOR: Record<string, AppColorName> = {
   '#005c67': 'teal',

package/src/theme/index.ts

@@ -1,9 +1,21 @@
-export { BloomThemeProvider, BloomColorScope, buildTheme } from './BloomThemeProvider';
-export type { BloomThemeProviderProps, BloomThemeContextValue, BloomColorScopeProps } from './BloomThemeProvider';
+export { BloomThemeProvider, BloomColorScope } from './BloomThemeProvider';
+export type {
+  BloomThemeProviderProps,
+  BloomThemeContextValue,
+  BloomColorScopeProps,
+} from './BloomThemeProvider';
+export { buildTheme, STATUS_COLORS } from './build-theme';
 export { useTheme, useThemeColor, useBloomTheme } from './use-theme';
 export type { Theme, ThemeColors, ThemeMode } from './types';
-export type { AppColorName, AppColorPreset } from './color-presets';
-export { APP_COLOR_NAMES, APP_COLOR_PRESETS, HEX_TO_APP_COLOR, hexToAppColorName } from './color-presets';
+export type { AppColorName, AppColorPreset, PresetTokens } from './color-presets';
+export {
+  APP_COLOR_NAMES,
+  APP_COLOR_PRESETS,
+  HEX_TO_APP_COLOR,
+  hexToAppColorName,
+} from './color-presets';
 export { applyDarkClass } from './apply-dark-class';
 export { setColorSchemeSafe } from './set-color-scheme-safe';
 export { initCssInteropDarkMode } from './init-css-interop';
+export type { BloomThemeStorage, PersistedThemeState } from './persistence';
+export { webLocalStorage } from './persistence';

package/src/theme/persistence.ts

@@ -0,0 +1,149 @@
+import { Platform } from 'react-native';
+import { APP_COLOR_NAMES, type AppColorName } from './color-presets';
+import type { ThemeMode } from './types';
+
+const VALID_PRESETS = new Set<string>(APP_COLOR_NAMES);
+const VALID_MODES = new Set<string>(['light', 'dark', 'system', 'adaptive']);
+
+/**
+ * Storage adapter for persisting Bloom theme state.
+ *
+ * Methods may be synchronous or asynchronous. The provider awaits both, so
+ * `AsyncStorage`-compatible adapters on native and `localStorage`-backed
+ * adapters on web both work without consumer-side branching.
+ *
+ * On web, a synchronous adapter lets Bloom hydrate before the first paint —
+ * preventing a flash of the default palette. On native, the provider can
+ * gate `children` rendering until hydration completes (see
+ * `awaitHydration` on `BloomThemeProvider`).
+ */
+export interface BloomThemeStorage {
+  getItem(key: string): string | null | Promise<string | null>;
+  setItem(key: string, value: string): void | Promise<void>;
+}
+
+export interface PersistedThemeState {
+  mode?: ThemeMode;
+  colorPreset?: AppColorName;
+}
+
+const isValidMode = (value: unknown): value is ThemeMode =>
+  typeof value === 'string' && VALID_MODES.has(value);
+
+const isValidPreset = (value: unknown): value is AppColorName =>
+  typeof value === 'string' && VALID_PRESETS.has(value);
+
+function parsePersistedTheme(raw: unknown): PersistedThemeState | null {
+  if (typeof raw !== 'string') return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== 'object') return null;
+  const obj = parsed as { mode?: unknown; colorPreset?: unknown };
+
+  const mode = isValidMode(obj.mode) ? obj.mode : undefined;
+  const colorPreset = isValidPreset(obj.colorPreset) ? obj.colorPreset : undefined;
+
+  if (!mode && !colorPreset) return null;
+  return { mode, colorPreset };
+}
+
+export type SyncReadResult =
+  | { kind: 'sync'; state: PersistedThemeState | null }
+  | { kind: 'async' }
+  | { kind: 'none' };
+
+const isThenable = (value: unknown): value is Promise<unknown> =>
+  !!value && typeof (value as { then?: unknown }).then === 'function';
+
+/**
+ * Read persisted state during the first render. Returns a discriminated union
+ * so the provider can tell apart:
+ *   - `none`: persistence not configured.
+ *   - `sync`: adapter returned a value synchronously (web `localStorage`).
+ *     Provider can render immediately with the resolved state.
+ *   - `async`: adapter returned a Promise (native `AsyncStorage`). Provider
+ *     must await `readPersistedTheme` before painting if gating is enabled.
+ */
+export function readPersistedThemeSync(
+  persistKey: string | undefined,
+  storage: BloomThemeStorage | undefined,
+): SyncReadResult {
+  if (!persistKey || !storage) return { kind: 'none' };
+
+  let raw: string | null | Promise<string | null>;
+  try {
+    raw = storage.getItem(persistKey);
+  } catch {
+    return { kind: 'sync', state: null };
+  }
+
+  if (isThenable(raw)) return { kind: 'async' };
+  return { kind: 'sync', state: parsePersistedTheme(raw) };
+}
+
+export async function readPersistedTheme(
+  persistKey: string | undefined,
+  storage: BloomThemeStorage | undefined,
+): Promise<PersistedThemeState | null> {
+  if (!persistKey || !storage) return null;
+
+  try {
+    const raw = await storage.getItem(persistKey);
+    return parsePersistedTheme(raw);
+  } catch {
+    return null;
+  }
+}
+
+export async function writePersistedTheme(
+  persistKey: string | undefined,
+  storage: BloomThemeStorage | undefined,
+  state: PersistedThemeState,
+): Promise<void> {
+  if (!persistKey || !storage) return;
+
+  const payload: PersistedThemeState = {};
+  if (state.mode !== undefined) payload.mode = state.mode;
+  if (state.colorPreset !== undefined) payload.colorPreset = state.colorPreset;
+
+  try {
+    await storage.setItem(persistKey, JSON.stringify(payload));
+  } catch {
+    // Persistence is best-effort: ignore quota and privacy-mode errors.
+  }
+}
+
+/**
+ * `localStorage`-backed storage adapter. Only defined on web; on native the
+ * export is `undefined` so consumers pass an `AsyncStorage` adapter explicitly.
+ */
+export const webLocalStorage: BloomThemeStorage | undefined = (() => {
+  if (Platform.OS !== 'web') return undefined;
+  if (typeof globalThis === 'undefined') return undefined;
+  if (!('localStorage' in globalThis)) return undefined;
+
+  const ls = (globalThis as { localStorage: Storage }).localStorage;
+
+  return {
+    getItem: (key) => {
+      try {
+        return ls.getItem(key);
+      } catch {
+        return null;
+      }
+    },
+    setItem: (key, value) => {
+      try {
+        ls.setItem(key, value);
+      } catch {
+        // Swallow quota / privacy-mode errors.
+      }
+    },
+  };
+})();

package/src/theme/use-isomorphic-layout-effect.ts

@@ -0,0 +1,10 @@
+import { useEffect, useLayoutEffect } from 'react';
+import { Platform } from 'react-native';
+
+/**
+ * `useLayoutEffect` on web (and native — react-native polyfills it) but falls
+ * back to `useEffect` during SSR to avoid the React warning. Bloom apps are
+ * primarily Expo (no SSR), but Next.js consumers of the web bundle need this.
+ */
+export const useIsomorphicLayoutEffect =
+  Platform.OS === 'web' && typeof document === 'undefined' ? useEffect : useLayoutEffect;