@mrmeg/expo-ui 0.5.0 → 0.6.1

package/LLM_USAGE.md

@@ -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

package/dist/components/DropdownMenu.d.ts

@@ -9,15 +9,6 @@ declare const DropdownMenu: {
     } & React.RefAttributes<View>): React.JSX.Element;
     displayName: string;
 };
-declare const DropdownMenuTrigger: {
-    ({ asChild, onPress: onPressProp, disabled, ref, ...props }: Omit<import("react-native").PressableProps & React.RefAttributes<View>, "ref"> & {
-        asChild?: boolean;
-    } & {
-        onKeyDown?: (ev: React.KeyboardEvent) => void;
-        onKeyUp?: (ev: React.KeyboardEvent) => void;
-    } & React.RefAttributes<import("@rn-primitives/dropdown-menu").TriggerRef>): React.JSX.Element;
-    displayName: string;
-};
 declare const DropdownMenuGroup: {
     ({ asChild, ref, ...props }: import("react-native").ViewProps & {
         asChild?: boolean;
@@ -44,6 +35,18 @@ declare const DropdownMenuRadioGroup: {
     } & React.RefAttributes<View>): React.JSX.Element;
     displayName: string;
 };
+/**
+ * DropdownMenuTrigger Component
+ * Wraps the primitive Trigger to default `accessibilityRole="button"`.
+ *
+ * The underlying @rn-primitives Trigger renders a RN-Web Pressable (or a Slot
+ * when `asChild`) without a role, so on web it becomes `role="generic"` —
+ * breaking screen-reader semantics and `getByRole("button")` queries. When
+ * `asChild` is used, the child's own role still wins (the Slot merges child
+ * props over slot props), so this only fills the gap when none is set.
+ */
+type DropdownMenuTriggerProps = DropdownMenuPrimitive.TriggerProps;
+declare function DropdownMenuTrigger({ ...props }: DropdownMenuTriggerProps): import("react/jsx-runtime").JSX.Element;
 /**
  * DropdownMenuSubTrigger Component
  * Trigger for sub-menus with automatic chevron icon
@@ -117,4 +120,4 @@ interface DropdownMenuShortcutProps {
 }
 declare function DropdownMenuShortcut({ style: styleOverride, ...props }: DropdownMenuShortcutProps): import("react/jsx-runtime").JSX.Element;
 export { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, };
-export type { DropdownMenuSubTriggerProps, DropdownMenuSubContentProps, DropdownMenuContentProps, DropdownMenuItemProps, DropdownMenuCheckboxItemProps, DropdownMenuRadioItemProps, DropdownMenuLabelProps, DropdownMenuSeparatorProps, DropdownMenuShortcutProps, };
+export type { DropdownMenuTriggerProps, DropdownMenuSubTriggerProps, DropdownMenuSubContentProps, DropdownMenuContentProps, DropdownMenuItemProps, DropdownMenuCheckboxItemProps, DropdownMenuRadioItemProps, DropdownMenuLabelProps, DropdownMenuSeparatorProps, DropdownMenuShortcutProps, };

package/dist/components/DropdownMenu.js

@@ -11,13 +11,15 @@ import { FullWindowOverlay as RNFullWindowOverlay } from "react-native-screens";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 // Re-export primitives that don't need styling
 const DropdownMenu = DropdownMenuPrimitive.Root;
-const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger;
 const DropdownMenuGroup = DropdownMenuPrimitive.Group;
 const DropdownMenuPortal = DropdownMenuPrimitive.Portal;
 const DropdownMenuSub = DropdownMenuPrimitive.Sub;
 const DropdownMenuRadioGroup = DropdownMenuPrimitive.RadioGroup;
 // Platform-specific overlay
 const FullWindowOverlay = Platform.OS === "ios" ? RNFullWindowOverlay : React.Fragment;
+function DropdownMenuTrigger({ ...props }) {
+    return _jsx(DropdownMenuPrimitive.Trigger, { accessibilityRole: "button", ...props });
+}
 function DropdownMenuSubTrigger({ inset = false, children, style: styleOverride, ...props }) {
     const { theme } = useTheme();
     const { open } = DropdownMenuPrimitive.useSubContext();

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
@@ -48,23 +49,29 @@ export function useTheme() {
     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 base = colors[effectiveScheme];
-    // Layer any app-injected palette over the package defaults for the active
-    // scheme. When no 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 override = colorOverrides[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(() => {
-        if (!override || Object.keys(override).length === 0) {
-            return base;
+        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, ...override },
+            colors: { ...base.colors, ...storeOverride, ...scopedOverride },
         };
-    }, [base, override]);
+    }, [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/package.json

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