@mrmeg/expo-ui 0.4.3 → 0.6.0

package/LLM_USAGE.md

@@ -37,7 +37,7 @@ near the root when the app uses package feedback or overlay components.
 `@rn-primitives` portal host.
 
 ```tsx
-import { ThemeProvider } from "@react-navigation/native";
+import { ThemeProvider } from "expo-router";
 import { UIProvider } from "@mrmeg/expo-ui/components";
 import { colors } from "@mrmeg/expo-ui/constants";
 import { useResources, useTheme } from "@mrmeg/expo-ui/hooks";
@@ -149,6 +149,17 @@ OS color-scheme subscription, including web `prefers-color-scheme`. Do not add
 app-local Appearance or `matchMedia` listeners for package components; import
 `useTheme()`, `useStyles()`, and `useThemeStore` from `@mrmeg/expo-ui`.
 
+`useTheme()` resolves colors in three layers, last wins: package defaults →
+global brand (`useThemeStore.getState().setColors(overrides)`) → scoped
+override (`ThemeColorScope`). Each override is `{ light?, dark? }` of
+`Partial<ThemeColors>`; only the keys you pass are replaced. Call `setColors`
+once to forward the app's brand palette globally. Wrap a subtree in
+`<ThemeColorScope colors={{ light, dark }}>` for transient per-subtree theming
+(user-created palettes, previews, embeds) that must not leak globally — it is
+React context, scoped keys win over the global brand inside it, and nested
+scopes merge (inner wins, outer fills in). With no override at either layer,
+`useTheme()` returns the base theme by reference.
+
 ## Component Use-Case Index
 
 Use this table before creating a new app-local primitive.

package/README.md

@@ -122,6 +122,47 @@ const { styles } = useStyles(({ theme, spacing, withAlpha }) => ({
 }));
 ```
 
+### Color overrides
+
+The package ships a neutral default palette. `useTheme()` resolves colors in
+three layers, last wins:
+
+1. **Package defaults** — the built-in zinc/teal palette.
+2. **Global brand** (`setColors`) — your app's one palette, applied everywhere.
+3. **Scoped override** (`ThemeColorScope`) — a per-subtree palette layered on
+   top of the brand, for transient theming that should not leak globally.
+
+With no override at either layer, `useTheme()` returns the base theme by
+reference — identical to pre-override behavior, with no extra allocation.
+
+Forward your app's brand palette once (e.g. from a top-level effect). Each
+scheme is a `Partial<ThemeColors>`, so you only specify the keys you want to
+re-skin:
+
+```tsx
+import { useThemeStore } from "@mrmeg/expo-ui/state";
+
+useThemeStore.getState().setColors({
+  light: { primary: "#7c3aed", accent: "#14b8a6" },
+  dark: { primary: "#a78bfa", accent: "#2dd4bf" },
+});
+```
+
+Use `ThemeColorScope` to override colors for one subtree without touching the
+global theme — a survey with a user-created palette, a preview pane, an embed.
+It is React context, so it applies only inside the provider and unwinds when
+that subtree unmounts. Nested scopes compose (inner keys win, outer fill in),
+and a scoped key wins over the global brand for components inside it:
+
+```tsx
+import { ThemeColorScope } from "@mrmeg/expo-ui/state";
+
+<ThemeColorScope colors={{ light: surveyColors, dark: surveyColors }}>
+  {/* every package component in here renders with the survey palette */}
+  <SurveyScreen />
+</ThemeColorScope>
+```
+
 Use `StyledText` for theme-aware text:
 
 ```tsx
@@ -307,7 +348,7 @@ LLM rules:
 Call `useResources()` once near the Expo app root before hiding the splash screen:
 
 ```tsx
-import { ThemeProvider } from "@react-navigation/native";
+import { ThemeProvider } from "expo-router";
 import { colors } from "@mrmeg/expo-ui/constants";
 import { useResources, useTheme } from "@mrmeg/expo-ui/hooks";
 import { UIProvider } from "@mrmeg/expo-ui/components";

package/dist/hooks/useTheme.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useMemo } from "react";
 import { colors } from "../constants/colors.js";
 import { Platform, StyleSheet } from "react-native";
 import { resolveThemePreference, useThemeStore } from "../state/themeStore.js";
+import { useThemeColorScope } from "../state/themeColorScope.js";
 import { spacing as spacingConstants } from "../constants/spacing.js";
 // Module-level cache for contrast calculations to avoid memory leak
 // and share across components
@@ -47,9 +48,30 @@ export function useTheme() {
     const userTheme = useThemeStore((s) => s.userTheme);
     const systemTheme = useThemeStore((s) => s.systemTheme);
     const setTheme = useThemeStore((s) => s.setTheme);
+    const colorOverrides = useThemeStore((s) => s.colorOverrides);
+    const scoped = useThemeColorScope();
     // Determine which theme to use (user preference or system)
     const effectiveScheme = resolveThemePreference(userTheme, systemTheme);
-    const theme = colors[effectiveScheme];
+    const base = colors[effectiveScheme];
+    // Layer overrides on top of the package defaults for the active scheme, in
+    // precedence order: package default → global store (app brand) → scoped
+    // context (per-subtree, e.g. a survey theme). When neither override is
+    // present we return the base theme *by reference* so memoization and identity
+    // checks downstream stay stable (and the package behaves exactly as it did
+    // before overrides existed).
+    const storeOverride = colorOverrides[effectiveScheme]; // global app brand
+    const scopedOverride = scoped?.[effectiveScheme]; // subtree override
+    const theme = useMemo(() => {
+        const hasStore = storeOverride && Object.keys(storeOverride).length > 0;
+        const hasScoped = scopedOverride && Object.keys(scopedOverride).length > 0;
+        if (!hasStore && !hasScoped) {
+            return base; // identity preserved — no allocation, stable references
+        }
+        return {
+            ...base,
+            colors: { ...base.colors, ...storeOverride, ...scopedOverride },
+        };
+    }, [base, storeOverride, scopedOverride]);
     // Sync theme to DOM so CSS in +html.tsx follows the app's runtime theme
     useEffect(() => {
         if (Platform.OS === "web" && typeof document !== "undefined") {

package/dist/state/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./globalUIStore";
 export * from "./themeStore";
+export * from "./themeColorScope";
 export * from "./SsrViewportContext";

package/dist/state/index.js

@@ -1,3 +1,4 @@
 export * from "./globalUIStore.js";
 export * from "./themeStore.js";
+export * from "./themeColorScope.js";
 export * from "./SsrViewportContext.js";

package/dist/state/themeColorScope.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from "react";
+import type { ColorOverrides } from "./themeStore";
+/** Read the active scoped override (null when not inside a scope). */
+export declare function useThemeColorScope(): ColorOverrides | null;
+export declare function ThemeColorScope({ colors, children, }: {
+    /** Per-scheme partial overrides — same shape as `setColors`. */
+    colors: ColorOverrides;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/state/themeColorScope.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+/**
+ * Per-subtree color overrides, layered on top of the global theme by `useTheme`.
+ *
+ * Unlike `setColors` (a global singleton on the theme store, meant for the app's
+ * one brand palette), this is React context: it applies only to components
+ * rendered inside the provider, and unwinds automatically when that subtree
+ * unmounts. Use it for transient, scoped theming — a survey with custom brand
+ * colors, a preview pane, an embed — where a global swap would bleed into the
+ * rest of the app.
+ */
+const ThemeColorScopeContext = createContext(null);
+/** Read the active scoped override (null when not inside a scope). */
+export function useThemeColorScope() {
+    return useContext(ThemeColorScopeContext);
+}
+// Nested scopes layer: the inner scope's keys win, the outer scope's fill in.
+function mergeScopes(parent, next) {
+    if (!parent)
+        return next;
+    return {
+        light: { ...parent.light, ...next.light },
+        dark: { ...parent.dark, ...next.dark },
+    };
+}
+export function ThemeColorScope({ colors, children, }) {
+    const parent = useContext(ThemeColorScopeContext);
+    const value = useMemo(() => mergeScopes(parent, colors), [parent, colors]);
+    return (_jsx(ThemeColorScopeContext.Provider, { value: value, children: children }));
+}

package/dist/state/themeStore.d.ts

@@ -1,10 +1,40 @@
+import type { ThemeColors } from "../constants/colors";
 export type ThemePreference = "system" | "light" | "dark";
 export type ResolvedTheme = "light" | "dark";
+/**
+ * Per-scheme color overrides a host app can inject to brand the package.
+ *
+ * The package ships a neutral default palette (see `constants/colors.ts`).
+ * A consuming app almost always has its own brand palette; without a way to
+ * push it in, package components (Badge, Button, inputs, …) render with the
+ * package's colors while app-authored siblings render with the app's — the
+ * two disagree on what e.g. `primary` means, producing collisions such as
+ * white text on a white badge. `setColors` lets the app forward its palette
+ * once so every package component resolves against the same source of truth.
+ *
+ * Each scheme is `Partial<ThemeColors>`: only the keys provided are overridden,
+ * so an app can re-skin `primary`/`accent` while inheriting neutral defaults.
+ */
+export type ColorOverrides = {
+    light?: Partial<ThemeColors>;
+    dark?: Partial<ThemeColors>;
+};
 export type ThemeStore = {
     userTheme: ThemePreference;
     systemTheme: ResolvedTheme;
+    /**
+     * App-injected palette overrides, applied by `useTheme` on top of the
+     * package defaults. Empty by default — zero override means the package
+     * behaves exactly as before this field existed (fully backward compatible).
+     */
+    colorOverrides: ColorOverrides;
     setTheme: (theme: ThemePreference) => void;
     setSystemTheme: (theme: ResolvedTheme) => void;
+    /**
+     * Replace the active color overrides. Pass `{}` (or omit both schemes) to
+     * clear overrides and fall back to the package defaults.
+     */
+    setColors: (overrides: ColorOverrides) => void;
     loadTheme: () => void;
 };
 export declare function resolveThemePreference(userTheme: ThemePreference, systemTheme: ResolvedTheme): ResolvedTheme;

package/dist/state/themeStore.js

@@ -16,6 +16,12 @@ export const useThemeStore = create((set) => ({
     // Always start with "light" so SSR and the first client render agree.
     // Real values are populated by `syncThemeFromEnvironment()` after mount.
     systemTheme: "light",
+    // No overrides by default: the package renders with its built-in palette
+    // until a host app calls `setColors`.
+    colorOverrides: {},
+    setColors: (overrides) => {
+        set({ colorOverrides: overrides ?? {} });
+    },
     setTheme: (theme) => {
         set({
             userTheme: theme,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrmeg/expo-ui",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [