@mrmeg/expo-ui 0.27.0 → 0.28.0

package/dist/hooks/useTheme.js

@@ -1,8 +1,10 @@
 import { useCallback, useEffect, useMemo } from "react";
-import { colors, resolveRawColor } from "../constants/colors.js";
+import { useShallow } from "zustand/react/shallow";
+import { colors, palette, resolveRawColor } from "../constants/colors.js";
 import { Platform, StyleSheet } from "react-native";
 import { resolveThemePreference, useThemeStore } from "../state/themeStore.js";
 import { useThemeColorScope } from "../state/themeColorScope.js";
+import { useInitialScheme } from "../state/initialScheme.js";
 import { spacing as spacingConstants } from "../constants/spacing.js";
 // Module-level cache for contrast calculations to avoid memory leak
 // and share across components
@@ -22,6 +24,144 @@ function getCachedOrCompute(key, compute) {
     contrastCache.set(key, result);
     return result;
 }
+/**
+ * Web: keeps `<html data-theme>` and `color-scheme` — what the CSS variables
+ * from `getThemeCssVariables()` key on — on the store's resolved scheme.
+ *
+ * One store subscription for the whole app, started by the first `useTheme`
+ * consumer to mount (the same moment the old per-consumer effect first
+ * wrote), writing only when the resolved scheme changes. It used to be an
+ * effect in every consumer, which re-ran in each of them on every scheme
+ * switch.
+ */
+let documentThemeSyncStarted = false;
+let documentScheme = null;
+function writeDocumentScheme(state) {
+    const scheme = resolveThemePreference(state.userTheme, state.systemTheme);
+    if (scheme === documentScheme)
+        return;
+    documentScheme = scheme;
+    document.documentElement.dataset.theme = scheme;
+    document.documentElement.style.colorScheme = scheme;
+}
+function startDocumentThemeSync() {
+    if (documentThemeSyncStarted || Platform.OS !== "web" || typeof document === "undefined") {
+        return;
+    }
+    documentThemeSyncStarted = true;
+    writeDocumentScheme(useThemeStore.getState());
+    useThemeStore.subscribe(writeDocumentScheme);
+}
+/**
+ * Shadow presets, per scheme.
+ *
+ * Light: the shadow does the work, at about twice the alpha the original
+ * presets used (0.04 became 0.08). Dark: the original presets tripled a 0.04
+ * alpha, which is invisible on the near-black base; these are black at real
+ * alpha, with the edge highlight in front. `subtle`, `soft` and `elevated`
+ * were tuned in the Surface Lab (`client/showcase/SurfaceLabScreen.tsx`); the
+ * other raised presets sit between them. `sharp` keeps its original light
+ * alpha and its original tripled dark alpha; `glow` is one vivid layer in both.
+ */
+const SHADOW_CONFIGS = {
+    subtle: {
+        light: [
+            { x: 0, y: 1, blur: 3, opacity: 0.08 },
+            { x: 0, y: 2, blur: 8, opacity: 0.06 },
+        ],
+        dark: [
+            { x: 0, y: 1, blur: 2, opacity: 0.4 },
+            { x: 0, y: 8, blur: 24, opacity: 0.35 },
+        ],
+        highlight: 0.05,
+    },
+    base: {
+        light: [
+            { x: 0, y: 2, blur: 6, opacity: 0.1 },
+            { x: 0, y: 4, blur: 12, opacity: 0.06 },
+        ],
+        dark: [
+            { x: 0, y: 2, blur: 3, opacity: 0.4 },
+            { x: 0, y: 10, blur: 28, opacity: 0.38 },
+        ],
+    },
+    soft: {
+        light: [
+            { x: 0, y: 4, blur: 10, opacity: 0.1 },
+            { x: 0, y: 8, blur: 20, opacity: 0.06 },
+        ],
+        dark: [
+            { x: 0, y: 2, blur: 4, opacity: 0.45 },
+            { x: 0, y: 14, blur: 36, opacity: 0.45 },
+        ],
+        highlight: 0.06,
+    },
+    card: {
+        light: [
+            { x: 0, y: 4, blur: 12, opacity: 0.1 },
+            { x: 0, y: 8, blur: 24, opacity: 0.06 },
+        ],
+        dark: [
+            { x: 0, y: 2, blur: 4, opacity: 0.42 },
+            { x: 0, y: 10, blur: 30, opacity: 0.4 },
+        ],
+        highlight: 0.05,
+    },
+    cardSubtle: {
+        light: [
+            { x: 0, y: 1, blur: 3, opacity: 0.1 },
+            { x: 0, y: 3, blur: 9, opacity: 0.06 },
+        ],
+        dark: [
+            { x: 0, y: 1, blur: 2, opacity: 0.4 },
+            { x: 0, y: 4, blur: 12, opacity: 0.3 },
+        ],
+        highlight: 0.05,
+    },
+    cardHover: {
+        light: [
+            { x: 0, y: 8, blur: 24, opacity: 0.12 },
+            { x: 0, y: 16, blur: 48, opacity: 0.08 },
+        ],
+        dark: [
+            { x: 0, y: 3, blur: 6, opacity: 0.48 },
+            { x: 0, y: 18, blur: 48, opacity: 0.5 },
+        ],
+        highlight: 0.06,
+    },
+    elevated: {
+        light: [
+            { x: 0, y: 16, blur: 48, opacity: 0.16 },
+            { x: 0, y: 32, blur: 96, opacity: 0.1 },
+        ],
+        dark: [
+            { x: 0, y: 4, blur: 8, opacity: 0.5 },
+            { x: 0, y: 24, blur: 56, opacity: 0.55 },
+        ],
+        highlight: 0.06,
+    },
+    glass: {
+        light: [
+            { x: 0, y: 4, blur: 30, opacity: 0.1 },
+            { x: 0, y: 8, blur: 60, opacity: 0.06 },
+        ],
+        dark: [
+            { x: 0, y: 4, blur: 30, opacity: 0.4 },
+            { x: 0, y: 8, blur: 60, opacity: 0.3 },
+        ],
+        highlight: 0.05,
+    },
+    // Single layer — intentional crispness, not a soft dual-layer shadow.
+    sharp: {
+        light: [{ x: 0, y: 1, blur: 1, opacity: 0.15 }],
+        dark: [{ x: 0, y: 1, blur: 1, opacity: 0.45 }],
+    },
+    // Single layer — already a deliberate, vivid accent glow.
+    glow: {
+        light: [{ x: 0, y: 4, blur: 20, opacity: 0.4 }],
+        dark: [{ x: 0, y: 4, blur: 20, opacity: 0.4 }],
+    },
+};
 /**
  * useTheme
  *
@@ -42,16 +182,26 @@ function getCachedOrCompute(key, compute) {
  * - getTextColorForBackground("#000") → "light"
  * - getContrastingColor("#f4f4f4", "#222", "#fff") → "#222"
  * - withAlpha("#336699", 0.6) → "rgba(51,102,153,0.6)"
- * - getShadowStyle('base') → { boxShadow: "0px 2px 6px rgba(0, 0, 0, 0.05), 0px 4px 12px rgba(0, 0, 0, 0.03)" }
+ * - getShadowStyle('base') → { boxShadow: "0px 2px 6px rgba(0, 0, 0, 0.1), 0px 4px 12px rgba(0, 0, 0, 0.06)" } (light)
  */
 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);
+    // One store subscription per consumer, re-rendering only when one of these
+    // four fields changes (shallow compare), instead of four subscriptions.
+    const { userTheme, systemTheme, hasLoadedTheme, setTheme, colorOverrides } = useThemeStore(useShallow((s) => ({
+        userTheme: s.userTheme,
+        systemTheme: s.systemTheme,
+        hasLoadedTheme: s.hasLoadedTheme,
+        setTheme: s.setTheme,
+        colorOverrides: s.colorOverrides,
+    })));
     const scoped = useThemeColorScope();
-    // Determine which theme to use (user preference or system)
-    const effectiveScheme = resolveThemePreference(userTheme, systemTheme);
+    const initialScheme = useInitialScheme();
+    // Determine which theme to use: the app's first-render hint until the
+    // persisted preference has been read (server render, hydration), then the
+    // user preference or system scheme. See state/initialScheme.tsx.
+    const effectiveScheme = initialScheme !== undefined && !hasLoadedTheme
+        ? initialScheme
+        : resolveThemePreference(userTheme, systemTheme);
     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
@@ -72,13 +222,9 @@ export function useTheme() {
             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") {
-            document.documentElement.dataset.theme = effectiveScheme;
-            document.documentElement.style.colorScheme = effectiveScheme;
-        }
-    }, [effectiveScheme]);
+    // Sync theme to DOM so CSS in +html.tsx follows the app's runtime theme.
+    // Starts the app-wide sync on the first mount; a no-op in every later one.
+    useEffect(startDocumentThemeSync, []);
     // Toggle between light, dark, and system themes
     const toggleTheme = useCallback(() => {
         if (userTheme === "light") {
@@ -105,61 +251,26 @@ export function useTheme() {
      * single-layer) is a dual-layer shadow: a tight "contact" layer plus a
      * wider, softer "ambient" layer, pitsi-ui-style. Layers are comma-joined
      * into one `boxShadow` value.
+     *
+     * Light and dark have their own layers. Light is the shadow alone. Dark is
+     * edge-lit: a 1px inset white highlight along the top edge, plus black
+     * layers at real alpha, deeper and larger than light's. On the near-black
+     * dark base a faint drop shadow is invisible, so the highlight carries the
+     * "lit from above" cue and the shadow only grounds the surface. The
+     * highlight is on the raised presets; `sharp` and `glow` have none.
      */
     const getShadowStyle = useCallback((type) => {
-        // Each preset is one or more layers of [offsetX, offsetY, blurRadius, color, opacity].
-        // Darker themes get a stronger alpha so shadows stay visible.
-        const boost = theme.dark ? 3 : 1;
         const overlay = theme.colors.overlay;
-        const shadowConfigs = {
-            subtle: [
-                { x: 0, y: 1, blur: 3, color: overlay, opacity: 0.04 },
-                { x: 0, y: 2, blur: 8, color: overlay, opacity: 0.03 },
-            ],
-            base: [
-                { x: 0, y: 2, blur: 6, color: overlay, opacity: 0.05 },
-                { x: 0, y: 4, blur: 12, color: overlay, opacity: 0.03 },
-            ],
-            soft: [
-                { x: 0, y: 4, blur: 10, color: overlay, opacity: 0.05 },
-                { x: 0, y: 8, blur: 20, color: overlay, opacity: 0.03 },
-            ],
-            card: [
-                { x: 0, y: 4, blur: 12, color: overlay, opacity: 0.05 },
-                { x: 0, y: 8, blur: 24, color: overlay, opacity: 0.03 },
-            ],
-            cardSubtle: [
-                { x: 0, y: 1, blur: 3, color: overlay, opacity: 0.05 },
-                { x: 0, y: 3, blur: 9, color: overlay, opacity: 0.03 },
-            ],
-            cardHover: [
-                { x: 0, y: 8, blur: 24, color: overlay, opacity: 0.06 },
-                { x: 0, y: 16, blur: 48, color: overlay, opacity: 0.04 },
-            ],
-            elevated: [
-                { x: 0, y: 16, blur: 48, color: overlay, opacity: 0.08 },
-                { x: 0, y: 32, blur: 96, color: overlay, opacity: 0.05 },
-            ],
-            glass: [
-                { x: 0, y: 4, blur: 30, color: overlay, opacity: 0.05 },
-                { x: 0, y: 8, blur: 60, color: overlay, opacity: 0.03 },
-            ],
-            // Single layer — intentional crispness, not a soft dual-layer shadow.
-            sharp: [
-                { x: 0, y: 1, blur: 1, color: overlay, opacity: 0.15 },
-            ],
-            // Single layer — already a deliberate, vivid accent glow.
-            glow: [
-                { x: 0, y: 4, blur: 20, color: theme.colors.primary, opacity: 0.4 },
-            ],
-        };
-        const layers = shadowConfigs[type].map(({ x, y, blur, color, opacity }) => {
-            // Don't boost the glow accent — it's already a deliberate, vivid alpha.
-            const alpha = color === theme.colors.primary ? opacity : Math.min(opacity * boost, 1);
-            return `${x}px ${y}px ${blur}px ${withAlpha(color, alpha)}`;
-        });
+        const config = SHADOW_CONFIGS[type];
+        const layers = theme.dark ? config.dark : config.light;
+        // Don't tint `glow` with the overlay: it is a deliberate, vivid accent glow.
+        const color = type === "glow" ? theme.colors.primary : overlay;
+        const parts = layers.map(({ x, y, blur, opacity }) => `${x}px ${y}px ${blur}px ${withAlpha(color, opacity)}`);
+        if (theme.dark && config.highlight !== undefined) {
+            parts.unshift(`inset 0px 1px 0px ${withAlpha(palette.white, config.highlight)}`);
+        }
         return {
-            boxShadow: layers.join(", "),
+            boxShadow: parts.join(", "),
         };
     }, [theme]);
     const getFocusRingStyle = useCallback((offset = 2) => {

package/dist/hooks/useWindowInsets.d.ts

@@ -0,0 +1,13 @@
+import { type EdgeInsets } from "react-native-safe-area-context";
+/**
+ * The window's safe-area insets, wherever the component renders.
+ *
+ * `useSafeAreaInsets()` throws outside a `SafeAreaProvider` and reads zeros
+ * inside content the system presents outside the provider's view — an iOS
+ * `Modal`, a native bottom sheet, a `UIProvider` mounted above the app's
+ * provider. This reads the provider's context when it is there and falls back
+ * to `initialWindowMetrics` (the window the app launched in), edge by edge, so
+ * overlays, toasts and `Screen` clear the Dynamic Island and home indicator in
+ * every one of those cases. Zeros on web and in tests without a provider.
+ */
+export declare function useWindowInsets(): EdgeInsets;

package/dist/hooks/useWindowInsets.js

@@ -0,0 +1,23 @@
+import { use } from "react";
+import { SafeAreaInsetsContext, initialWindowMetrics, } from "react-native-safe-area-context";
+/**
+ * The window's safe-area insets, wherever the component renders.
+ *
+ * `useSafeAreaInsets()` throws outside a `SafeAreaProvider` and reads zeros
+ * inside content the system presents outside the provider's view — an iOS
+ * `Modal`, a native bottom sheet, a `UIProvider` mounted above the app's
+ * provider. This reads the provider's context when it is there and falls back
+ * to `initialWindowMetrics` (the window the app launched in), edge by edge, so
+ * overlays, toasts and `Screen` clear the Dynamic Island and home indicator in
+ * every one of those cases. Zeros on web and in tests without a provider.
+ */
+export function useWindowInsets() {
+    const context = use(SafeAreaInsetsContext);
+    const fallback = initialWindowMetrics?.insets;
+    return {
+        top: context?.top || fallback?.top || 0,
+        bottom: context?.bottom || fallback?.bottom || 0,
+        left: context?.left || fallback?.left || 0,
+        right: context?.right || fallback?.right || 0,
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export * from "./components";
-export * from "./constants";
-export * from "./hooks";
-export * from "./state";
-export * from "./lib";
+export * from "./components/index.js";
+export * from "./constants/index.js";
+export * from "./hooks/index.js";
+export * from "./state/index.js";
+export * from "./lib/index.js";

package/dist/lib/composeRefs.d.ts

@@ -0,0 +1,8 @@
+import type { Ref, RefCallback } from "react";
+/**
+ * One ref callback that feeds every ref given — object refs (`.current`) and
+ * callback refs alike, `null`/`undefined` skipped. For a component that needs
+ * the host node itself (e.g. to set a DOM attribute) while its consumer, or an
+ * `asChild` slot, also passes a `ref`.
+ */
+export declare function composeRefs<T>(...refs: Array<Ref<T> | undefined>): RefCallback<T>;

package/dist/lib/composeRefs.js

@@ -0,0 +1,20 @@
+/**
+ * One ref callback that feeds every ref given — object refs (`.current`) and
+ * callback refs alike, `null`/`undefined` skipped. For a component that needs
+ * the host node itself (e.g. to set a DOM attribute) while its consumer, or an
+ * `asChild` slot, also passes a `ref`.
+ */
+export function composeRefs(...refs) {
+    return (node) => {
+        for (const ref of refs) {
+            if (!ref)
+                continue;
+            if (typeof ref === "function") {
+                ref(node);
+            }
+            else {
+                ref.current = node;
+            }
+        }
+    };
+}

package/dist/lib/haptics.d.ts

@@ -1,3 +1,15 @@
+/** A light tap, unconditionally. Prefer `hapticPress` / `hapticSelection`. */
 export declare function hapticLight(): void;
 export declare function hapticMedium(): void;
 export declare function hapticSuccess(): void;
+/**
+ * The tap a control fires when its state changes (Switch, Checkbox, Toggle,
+ * ToggleGroup, SegmentedControl). Fires under the `"selection"` (default) and
+ * `"all"` settings; silent under `"off"`.
+ */
+export declare function hapticSelection(): void;
+/**
+ * The tap a pressable fires on press-in (Button, pressable Card and Item,
+ * `useScalePress` consumers). Fires only under the `"all"` setting.
+ */
+export declare function hapticPress(): void;

package/dist/lib/haptics.js

@@ -1,4 +1,5 @@
 import { Platform } from "react-native";
+import { useFeedbackStore } from "../state/feedbackStore.js";
 function runHaptic(fn) {
     if (Platform.OS === "web")
         return;
@@ -9,6 +10,7 @@ function runHaptic(fn) {
         // Haptics not available
     }
 }
+/** A light tap, unconditionally. Prefer `hapticPress` / `hapticSelection`. */
 export function hapticLight() {
     runHaptic(() => {
         const H = require("expo-haptics");
@@ -27,3 +29,22 @@ export function hapticSuccess() {
         H.notificationAsync(H.NotificationFeedbackType.Success);
     });
 }
+/**
+ * The tap a control fires when its state changes (Switch, Checkbox, Toggle,
+ * ToggleGroup, SegmentedControl). Fires under the `"selection"` (default) and
+ * `"all"` settings; silent under `"off"`.
+ */
+export function hapticSelection() {
+    if (useFeedbackStore.getState().haptics === "off")
+        return;
+    hapticLight();
+}
+/**
+ * The tap a pressable fires on press-in (Button, pressable Card and Item,
+ * `useScalePress` consumers). Fires only under the `"all"` setting.
+ */
+export function hapticPress() {
+    if (useFeedbackStore.getState().haptics !== "all")
+        return;
+    hapticLight();
+}

package/dist/lib/index.d.ts

@@ -1,4 +1,6 @@
-export * from "./animations";
-export * from "./haptics";
-export * from "./i18n";
-export * from "./themedStyles";
+export * from "./animations.js";
+export * from "./composeRefs.js";
+export * from "./haptics.js";
+export * from "./i18n.js";
+export * from "./stateSurface.js";
+export * from "./themedStyles.js";

package/dist/lib/index.js

@@ -1,4 +1,6 @@
 export * from "./animations.js";
+export * from "./composeRefs.js";
 export * from "./haptics.js";
 export * from "./i18n.js";
+export * from "./stateSurface.js";
 export * from "./themedStyles.js";

package/dist/lib/interFonts.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The packaged Inter faces `useResources` registers through `expo-font` —
+ * web variant: none.
+ *
+ * Web loads Inter as one multi-weight CSS family from Google Fonts (see
+ * `useResources`), and `constants/fonts.ts` points every web weight at that
+ * family, so no static `.ttf` would ever be referenced. Importing one here
+ * would still make the bundler emit it as a web asset, so this variant imports
+ * nothing. Metro resolves `interFonts.native.ts` on iOS and Android instead.
+ *
+ * Private module: not re-exported from `lib/index.ts`, and `lib/*` is not an
+ * exported subpath, so consumers can't reach it.
+ */
+export type InterFontMap = Readonly<Record<string, number>>;
+export declare const interFontMap: InterFontMap | null;

package/dist/lib/interFonts.js

@@ -0,0 +1 @@
+export const interFontMap = null;

package/dist/lib/interFonts.native.d.ts

@@ -0,0 +1,3 @@
+import type { InterFontMap } from "./interFonts.js";
+export type { InterFontMap };
+export declare const interFontMap: InterFontMap | null;

package/dist/lib/interFonts.native.js

@@ -0,0 +1,20 @@
+/**
+ * The packaged Inter faces `useResources` registers through `expo-font` —
+ * native variant.
+ *
+ * Exactly the four static weights the native `sansSerif` family keys point at
+ * (see `constants/fonts.ts`), each imported from its own per-weight subpath.
+ * The `@expo-google-fonts/inter` root entry `require`s all 18 files (every
+ * weight, plus italics), and Metro ships every file a bundle requires, so
+ * importing it added 14 unused faces (~4.8 MB) to every native app.
+ */
+import { Inter_400Regular } from "@expo-google-fonts/inter/400Regular";
+import { Inter_500Medium } from "@expo-google-fonts/inter/500Medium";
+import { Inter_600SemiBold } from "@expo-google-fonts/inter/600SemiBold";
+import { Inter_700Bold } from "@expo-google-fonts/inter/700Bold";
+export const interFontMap = {
+    Inter_400Regular,
+    Inter_500Medium,
+    Inter_600SemiBold,
+    Inter_700Bold,
+};

package/dist/lib/popoverPlacement.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Side and height cap for a native popover.
+ *
+ * `@rn-primitives/popover` places native content on the requested side and,
+ * when it does not fit, clamps it to the screen edge instead of flipping, so an
+ * oversized popover covers its own trigger or sits under the system bars.
+ * `PopoverContent` resolves the side and a height cap here first; the content
+ * then scrolls inside the cap. Web never calls this: Radix flips on its own.
+ */
+export type PopoverSide = "top" | "bottom";
+export interface PopoverPlacementInput {
+    /** Requested side; undefined means the primitive's default, `"bottom"`. */
+    side: PopoverSide | undefined;
+    sideOffset: number;
+    /** The trigger's measured screen frame, or null until the primitive measures it. */
+    trigger: {
+        pageY: number;
+        height: number;
+    } | null;
+    screenHeight: number;
+    insets: {
+        top?: number;
+        bottom?: number;
+    };
+    /** The content's uncapped height, card chrome included; undefined while unknown. */
+    naturalHeight: number | undefined;
+    avoidCollisions: boolean;
+}
+export interface PopoverPlacement {
+    side: PopoverSide;
+    /** Undefined when the popover is not capped. */
+    maxHeight: number | undefined;
+}
+/** Smallest cap; with less room than this the primitive's inset clamp places the card. */
+export declare const POPOVER_MIN_CAP = 120;
+export declare function resolvePopoverPlacement({ side, sideOffset, trigger, screenHeight, insets, naturalHeight, avoidCollisions, }: PopoverPlacementInput): PopoverPlacement;

package/dist/lib/popoverPlacement.js

@@ -0,0 +1,29 @@
+/**
+ * Side and height cap for a native popover.
+ *
+ * `@rn-primitives/popover` places native content on the requested side and,
+ * when it does not fit, clamps it to the screen edge instead of flipping, so an
+ * oversized popover covers its own trigger or sits under the system bars.
+ * `PopoverContent` resolves the side and a height cap here first; the content
+ * then scrolls inside the cap. Web never calls this: Radix flips on its own.
+ */
+/** Smallest cap; with less room than this the primitive's inset clamp places the card. */
+export const POPOVER_MIN_CAP = 120;
+export function resolvePopoverPlacement({ side, sideOffset, trigger, screenHeight, insets, naturalHeight, avoidCollisions, }) {
+    const requested = side ?? "bottom";
+    if (!avoidCollisions || !trigger) {
+        return { side: requested, maxHeight: undefined };
+    }
+    const room = {
+        top: trigger.pageY - sideOffset - (insets.top ?? 0),
+        bottom: screenHeight - (insets.bottom ?? 0) - (trigger.pageY + trigger.height + sideOffset),
+    };
+    const opposite = requested === "top" ? "bottom" : "top";
+    // Without the natural height (not measured yet, or content that scrolls
+    // itself) there is nothing to compare, so only cap the requested side.
+    const flips = naturalHeight !== undefined &&
+        naturalHeight > room[requested] &&
+        room[opposite] > room[requested];
+    const chosen = flips ? opposite : requested;
+    return { side: chosen, maxHeight: Math.max(room[chosen], POPOVER_MIN_CAP) };
+}

package/dist/lib/stateSurface.d.ts

@@ -0,0 +1,28 @@
+import { type ViewProps } from "react-native";
+/**
+ * Props for a "state surface": a plain `View` whose `opacity`, `pointerEvents`
+ * or `display` is computed from component state (`disabled`, `loading`,
+ * `checked`, `editable`, …).
+ *
+ * On Android (Fabric) a View forms a stacking context only while one of those
+ * props says so. A filled or bordered View at opacity 1 still gets a native
+ * view, but its children are hoisted into the nearest stacking-context
+ * ancestor; the moment its opacity drops below 1 the children are pulled back
+ * under it. A state flip that races a navigation pop therefore re-parents
+ * views mid-mutation and crashed with `addViewAt: cannot insert view … View
+ * already has a parent` (doglog #57, Pixel 6a). `collapsable={false}` makes
+ * the View a permanent stacking context, so the native tree shape never
+ * changes with state. iOS and web return nothing: their mounting layers
+ * re-parent safely and the extra native view would only cost.
+ *
+ * RN's `Pressable` already sets `collapsable={false}` on its own View, so only
+ * plain `View` surfaces need this. Spread it before any consumer prop spread so
+ * a caller can still override it.
+ *
+ * ```tsx
+ * <View {...stateSurfaceProps()} style={{ opacity: disabled ? 0.5 : 1 }} />
+ * ```
+ *
+ * Reads `Platform.OS` at call time so per-test platform flips apply.
+ */
+export declare function stateSurfaceProps(): Pick<ViewProps, "collapsable">;

package/dist/lib/stateSurface.js

@@ -0,0 +1,30 @@
+import { Platform } from "react-native";
+/**
+ * Props for a "state surface": a plain `View` whose `opacity`, `pointerEvents`
+ * or `display` is computed from component state (`disabled`, `loading`,
+ * `checked`, `editable`, …).
+ *
+ * On Android (Fabric) a View forms a stacking context only while one of those
+ * props says so. A filled or bordered View at opacity 1 still gets a native
+ * view, but its children are hoisted into the nearest stacking-context
+ * ancestor; the moment its opacity drops below 1 the children are pulled back
+ * under it. A state flip that races a navigation pop therefore re-parents
+ * views mid-mutation and crashed with `addViewAt: cannot insert view … View
+ * already has a parent` (doglog #57, Pixel 6a). `collapsable={false}` makes
+ * the View a permanent stacking context, so the native tree shape never
+ * changes with state. iOS and web return nothing: their mounting layers
+ * re-parent safely and the extra native view would only cost.
+ *
+ * RN's `Pressable` already sets `collapsable={false}` on its own View, so only
+ * plain `View` surfaces need this. Spread it before any consumer prop spread so
+ * a caller can still override it.
+ *
+ * ```tsx
+ * <View {...stateSurfaceProps()} style={{ opacity: disabled ? 0.5 : 1 }} />
+ * ```
+ *
+ * Reads `Platform.OS` at call time so per-test platform flips apply.
+ */
+export function stateSurfaceProps() {
+    return Platform.OS === "android" ? { collapsable: false } : {};
+}

package/dist/lib/themedStyles.d.ts

@@ -1,4 +1,4 @@
-import { type Theme } from "../constants/colors";
+import { type Theme } from "../constants/colors.js";
 /**
  * Registers theme-dependent styles at module scope so react-native-web
  * inserts their CSS rules into the sheet before the prerendered document

package/dist/lib/useAnimatedValue.d.ts

@@ -0,0 +1,15 @@
+import { Animated } from "react-native";
+/**
+ * An `Animated.Value` created once, on the first render, and stable for the
+ * component's lifetime — React Native's `useAnimatedValue`, which
+ * react-native-web 0.21 does not export.
+ *
+ * Replaces `useRef(new Animated.Value(x)).current`, which built and discarded
+ * a value on every render and read a ref during render, so the React Compiler
+ * skipped the whole component. A lazy state initializer is allocated once and
+ * returns a plain value the compiler can reason about. Like the ref version,
+ * only the first render's `initialValue` is used.
+ *
+ * Private to the package: not re-exported from `lib/index.ts`.
+ */
+export declare function useAnimatedValue(initialValue: number): Animated.Value;

package/dist/lib/useAnimatedValue.js

@@ -0,0 +1,19 @@
+import { useState } from "react";
+import { Animated } from "react-native";
+/**
+ * An `Animated.Value` created once, on the first render, and stable for the
+ * component's lifetime — React Native's `useAnimatedValue`, which
+ * react-native-web 0.21 does not export.
+ *
+ * Replaces `useRef(new Animated.Value(x)).current`, which built and discarded
+ * a value on every render and read a ref during render, so the React Compiler
+ * skipped the whole component. A lazy state initializer is allocated once and
+ * returns a plain value the compiler can reason about. Like the ref version,
+ * only the first render's `initialValue` is used.
+ *
+ * Private to the package: not re-exported from `lib/index.ts`.
+ */
+export function useAnimatedValue(initialValue) {
+    const [value] = useState(() => new Animated.Value(initialValue));
+    return value;
+}