@mrmeg/expo-ui 0.27.1 → 0.29.0

package/dist/components/Item.d.ts

@@ -1,14 +1,56 @@
 import React from "react";
 import { StyleProp, ViewStyle } from "react-native";
-import { type TextProps } from "./StyledText";
-import { type IconName, type ThemeColorName } from "./Icon";
+import { type TextProps } from "./StyledText.js";
+import { type IconName, type ThemeColorName } from "./Icon.js";
+/**
+ * What a row tells the controls inside it: the title's text when it is a plain
+ * string (the accessible name on every platform), and — once ids can be
+ * trusted — the id its `ItemTitle` renders under (`nativeID`), so a composed
+ * title can still be linked with `aria-labelledby`.
+ *
+ * `titleId` is `undefined` during SSR and the hydration pass on web: `useId()`
+ * values do not survive Expo Router's streamed hydration (see `useHydrated`),
+ * so ids only appear in the first client render after it.
+ */
+export interface ItemLabel {
+    titleId: string | undefined;
+    title: string | undefined;
+}
+/**
+ * The row label a control inside an `Item` can borrow, or `null` outside a
+ * row. `Switch`, `Checkbox` and `Toggle` use it when they have no label of
+ * their own: `aria-labelledby={titleId}` on web, `accessibilityLabel={title}`
+ * on native. Apps composing their own controls can do the same.
+ */
+export declare function useItemLabel(): ItemLabel | null;
+type OwnLabelProps = {
+    accessibilityLabel?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    accessibilityLabelledBy?: string | string[];
+};
+/**
+ * Accessibility props a control inside an `Item` should spread when it has no
+ * label of its own — its own props always win, so this returns `{}` whenever
+ * any label prop is set, or outside a row. A plain-text title becomes the
+ * control's `accessibilityLabel` (`aria-label` on web) on every platform, in
+ * the server HTML too. A composed title has no text to copy, so the control
+ * points at the title's id instead — `aria-labelledby` on web,
+ * `accessibilityLabelledBy` on Android — once that id exists (after hydration
+ * on web; see `ItemLabel`).
+ */
+export declare function useItemControlLabel(own: OwnLabelProps): OwnLabelProps;
 export interface ItemProps {
     children?: React.ReactNode;
     /** Makes the row pressable with scale feedback (mirrors Card's pattern). */
     onPress?: () => void;
     /** Disables press handling when `onPress` is set. */
     disabled?: boolean;
-    /** Renders a hairline divider below the row, inset past the media slot. */
+    /**
+     * Renders a hairline divider below the row, starting under the title (past
+     * the `ItemMedia` slot when there is one). Inside an `ItemGroup` the group
+     * sets this for every row but the last; pass `false` to drop one row's line.
+     */
     separator?: boolean;
     /** Custom style override for the row. */
     style?: StyleProp<ViewStyle>;
@@ -20,7 +62,9 @@ export interface ItemProps {
  * `spacing.rowPaddingX`) and gap, a 44pt min height on native (40 on web),
  * and an optional pressable scale interaction. Compose
  * with `ItemMedia`, `ItemContent` (+ `ItemTitle`/`ItemDescription`), and
- * `ItemActions`.
+ * `ItemActions`. Stack rows in an `ItemGroup`, which draws the separators;
+ * the row's own padding is the screen's only horizontal inset, so don't wrap
+ * rows in a padded or bordered container.
  *
  * @example
  * ```tsx
@@ -37,6 +81,60 @@ export interface ItemProps {
  * ```
  */
 export declare function Item({ children, onPress, disabled, separator, style }: ItemProps): React.JSX.Element;
+export interface ItemGroupProps {
+    /**
+     * Section label above the rows: an uppercase eyebrow in the muted color,
+     * announced as a header.
+     */
+    title?: string;
+    /** Supporting copy under the title. */
+    description?: string;
+    /** Helper text under the rows, e.g. what the settings above it do. */
+    footer?: string;
+    /**
+     * The rows: `Item`s, or components that render one. Each direct child is
+     * one row; the group draws the hairline under every row but the last.
+     */
+    children?: React.ReactNode;
+    /** Style override for the group container (outer margins, width). */
+    style?: StyleProp<ViewStyle>;
+    /** Test id for the group container. */
+    testID?: string;
+}
+/**
+ * ItemGroup
+ *
+ * A flat grouped list: an optional eyebrow title and description, full-width
+ * `Item` rows separated by inset hairlines, and optional footer text. No
+ * border, radius, shadow, or fill: the header and footer sit on the row
+ * padding (`spacing.rowPaddingX`), so the group needs no horizontal padding
+ * from its parent. Space groups apart with `spacing.sectionSpacing`.
+ *
+ * @example
+ * ```tsx
+ * <ItemGroup title="Account" footer="Signed in as jane@example.com">
+ *   <Item onPress={openProfile}>
+ *     <ItemMedia icon="user" />
+ *     <ItemContent>
+ *       <ItemTitle>Edit profile</ItemTitle>
+ *     </ItemContent>
+ *     <ItemActions>
+ *       <Icon name="chevron-right" size={18} color="mutedForeground" />
+ *     </ItemActions>
+ *   </Item>
+ *   <Item>
+ *     <ItemMedia icon="bell" />
+ *     <ItemContent>
+ *       <ItemTitle>Notifications</ItemTitle>
+ *     </ItemContent>
+ *     <ItemActions>
+ *       <Switch checked={enabled} onCheckedChange={setEnabled} />
+ *     </ItemActions>
+ *   </Item>
+ * </ItemGroup>
+ * ```
+ */
+export declare function ItemGroup({ title, description, footer, children, style, testID }: ItemGroupProps): React.JSX.Element;
 export interface ItemMediaProps {
     /** Square size of the media slot in pixels. @default 40 */
     size?: number;
@@ -92,3 +190,4 @@ export interface ItemActionsProps {
  * icon, a `Switch`, value text, etc.).
  */
 export declare function ItemActions({ children, style }: ItemActionsProps): React.JSX.Element;
+export {};

package/dist/components/Item.js

@@ -1,14 +1,93 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { Children, createContext, isValidElement, use, useId } from "react";
 import { View, Pressable, StyleSheet, Platform, Animated, } from "react-native";
-import { StyledText, CaptionText } from "./StyledText.js";
+import { StyledText, CaptionText, EyebrowText } from "./StyledText.js";
+import { useHydrated } from "../hooks/useHydrated.js";
 import { Icon } from "./Icon.js";
 import { useTheme } from "../hooks/useTheme.js";
 import { useScalePress } from "../hooks/useScalePress.js";
+import { useFocusVisible } from "../hooks/useFocusVisible.js";
 import { spacing } from "../constants/spacing.js";
-// Default ItemMedia footprint (see ItemMedia's `size` prop) — used to inset
-// the optional separator past the media slot without needing a context.
+import { interaction } from "../constants/interaction.js";
+// Default ItemMedia footprint (see ItemMedia's `size` prop).
 const DEFAULT_MEDIA_SIZE = 40;
-const SEPARATOR_INSET = spacing.rowPaddingX + DEFAULT_MEDIA_SIZE + spacing.rowGap;
+const ItemGroupRowContext = createContext(null);
+const SEPARATED_ROW = { separator: true };
+const LAST_ROW = { separator: false };
+const ItemLabelContext = createContext(null);
+/** True inside `ItemContent`, where the row's title lives. */
+const ItemContentContext = createContext(false);
+/**
+ * The row's title, read synchronously from its element tree: the first
+ * `ItemTitle` directly inside a direct `ItemContent`. `found` is false when
+ * the row has no such title (a media-only or custom row), so controls in it
+ * borrow nothing. `text` is the title when its children are strings (or
+ * numbers); a composed title (`<ItemTitle>{name} <Badge/></ItemTitle>`) gives
+ * `undefined` — web still links by id, native then needs an explicit label.
+ */
+function scanTitle(children) {
+    for (const child of Children.toArray(children)) {
+        if (!isValidElement(child))
+            continue;
+        if (child.type === ItemContent) {
+            for (const inner of Children.toArray(child.props.children)) {
+                if (isValidElement(inner) && inner.type === ItemTitle) {
+                    const parts = Children.toArray(inner.props.children);
+                    const plain = parts.length > 0 && parts.every((part) => typeof part === "string" || typeof part === "number");
+                    return { found: true, text: plain ? parts.join("") : undefined };
+                }
+            }
+        }
+    }
+    return { found: false, text: undefined };
+}
+/**
+ * The row label a control inside an `Item` can borrow, or `null` outside a
+ * row. `Switch`, `Checkbox` and `Toggle` use it when they have no label of
+ * their own: `aria-labelledby={titleId}` on web, `accessibilityLabel={title}`
+ * on native. Apps composing their own controls can do the same.
+ */
+export function useItemLabel() {
+    return use(ItemLabelContext);
+}
+/**
+ * Accessibility props a control inside an `Item` should spread when it has no
+ * label of its own — its own props always win, so this returns `{}` whenever
+ * any label prop is set, or outside a row. A plain-text title becomes the
+ * control's `accessibilityLabel` (`aria-label` on web) on every platform, in
+ * the server HTML too. A composed title has no text to copy, so the control
+ * points at the title's id instead — `aria-labelledby` on web,
+ * `accessibilityLabelledBy` on Android — once that id exists (after hydration
+ * on web; see `ItemLabel`).
+ */
+export function useItemControlLabel(own) {
+    const label = use(ItemLabelContext);
+    if (!label ||
+        own.accessibilityLabel !== undefined ||
+        own["aria-label"] !== undefined ||
+        own["aria-labelledby"] !== undefined ||
+        own.accessibilityLabelledBy !== undefined) {
+        return {};
+    }
+    if (label.title !== undefined)
+        return { accessibilityLabel: label.title };
+    if (label.titleId === undefined)
+        return {};
+    return Platform.OS === "web" ? { "aria-labelledby": label.titleId } : { accessibilityLabelledBy: label.titleId };
+}
+/**
+ * Where a row's hairline starts: under the title when the row leads with an
+ * `ItemMedia` (row padding + media + gap, so a custom `size` lines up too),
+ * otherwise at the row padding.
+ */
+function separatorInset(children) {
+    for (const child of Children.toArray(children)) {
+        if (isValidElement(child) && child.type === ItemMedia) {
+            return spacing.rowPaddingX + (child.props.size ?? DEFAULT_MEDIA_SIZE) + spacing.rowGap;
+        }
+    }
+    return spacing.rowPaddingX;
+}
 /**
  * Item
  *
@@ -16,7 +95,9 @@ const SEPARATOR_INSET = spacing.rowPaddingX + DEFAULT_MEDIA_SIZE + spacing.rowGa
  * `spacing.rowPaddingX`) and gap, a 44pt min height on native (40 on web),
  * and an optional pressable scale interaction. Compose
  * with `ItemMedia`, `ItemContent` (+ `ItemTitle`/`ItemDescription`), and
- * `ItemActions`.
+ * `ItemActions`. Stack rows in an `ItemGroup`, which draws the separators;
+ * the row's own padding is the screen's only horizontal inset, so don't wrap
+ * rows in a padded or bordered container.
  *
  * @example
  * ```tsx
@@ -32,20 +113,78 @@ const SEPARATOR_INSET = spacing.rowPaddingX + DEFAULT_MEDIA_SIZE + spacing.rowGa
  * </Item>
  * ```
  */
-export function Item({ children, onPress, disabled, separator = false, style }) {
-    const { theme } = useTheme();
+export function Item({ children, onPress, disabled, separator, style }) {
+    const { theme, getFocusRingStyle } = useTheme();
+    const groupRow = use(ItemGroupRowContext);
+    const showSeparator = separator ?? groupRow?.separator ?? false;
+    const reactId = useId();
+    const hydrated = useHydrated();
+    const { found: hasTitle, text: title } = scanTitle(children);
+    // Ids only after hydration on web (see ItemLabel); native has no hydration.
+    const titleId = Platform.OS !== "web" || hydrated ? reactId : undefined;
+    const label = React.useMemo(() => (hasTitle ? { titleId, title } : null), [hasTitle, titleId, title]);
     const { animatedStyle, pressHandlers } = useScalePress({
         disabled: !onPress || !!disabled,
         scaleTo: 0.98,
-        haptic: false,
     });
-    const row = (_jsx(View, { style: [styles.row, style], children: children }));
-    const content = separator ? (_jsxs(View, { children: [row, _jsx(View, { style: [styles.separator, { backgroundColor: theme.colors.border }] })] })) : (row);
+    const focus = useFocusVisible();
+    const row = (_jsx(View, { style: [styles.row, style], children: _jsx(ItemLabelContext.Provider, { value: label, children: children }) }));
+    const content = showSeparator ? (_jsxs(View, { children: [row, _jsx(View, { style: [
+                    styles.separator,
+                    { marginLeft: separatorInset(children), backgroundColor: theme.colors.border },
+                ] })] })) : (row);
     if (onPress) {
-        return (_jsx(Pressable, { onPress: onPress, disabled: disabled, accessibilityRole: "button", accessibilityState: { disabled: !!disabled }, ...pressHandlers, style: Platform.OS === "web" ? { cursor: "pointer" } : undefined, children: _jsx(Animated.View, { style: animatedStyle, children: content }) }));
+        return (_jsx(Pressable, { onPress: onPress, disabled: disabled, accessibilityRole: "button", accessibilityState: { disabled: !!disabled }, ...pressHandlers, onFocus: focus.onFocus, onBlur: focus.onBlur, style: ({ pressed }) => [
+                { borderRadius: spacing.radiusSm },
+                Platform.OS === "web" && { cursor: "pointer", outlineStyle: "none" },
+                pressed && { opacity: interaction.pressedOpacity },
+                focus.focused && !disabled && getFocusRingStyle(),
+            ], children: _jsx(Animated.View, { style: animatedStyle, children: content }) }));
     }
     return content;
 }
+/**
+ * ItemGroup
+ *
+ * A flat grouped list: an optional eyebrow title and description, full-width
+ * `Item` rows separated by inset hairlines, and optional footer text. No
+ * border, radius, shadow, or fill: the header and footer sit on the row
+ * padding (`spacing.rowPaddingX`), so the group needs no horizontal padding
+ * from its parent. Space groups apart with `spacing.sectionSpacing`.
+ *
+ * @example
+ * ```tsx
+ * <ItemGroup title="Account" footer="Signed in as jane@example.com">
+ *   <Item onPress={openProfile}>
+ *     <ItemMedia icon="user" />
+ *     <ItemContent>
+ *       <ItemTitle>Edit profile</ItemTitle>
+ *     </ItemContent>
+ *     <ItemActions>
+ *       <Icon name="chevron-right" size={18} color="mutedForeground" />
+ *     </ItemActions>
+ *   </Item>
+ *   <Item>
+ *     <ItemMedia icon="bell" />
+ *     <ItemContent>
+ *       <ItemTitle>Notifications</ItemTitle>
+ *     </ItemContent>
+ *     <ItemActions>
+ *       <Switch checked={enabled} onCheckedChange={setEnabled} />
+ *     </ItemActions>
+ *   </Item>
+ * </ItemGroup>
+ * ```
+ */
+export function ItemGroup({ title, description, footer, children, style, testID }) {
+    const { theme } = useTheme();
+    const rows = Children.toArray(children);
+    // react-native-web renders an unlevelled header as h1; level the title as h2
+    // there. Native has no heading levels and takes the role alone. Read at render
+    // time (not module load) so tests can flip `Platform.OS`.
+    const headingLevel = Platform.OS === "web" ? { "aria-level": 2 } : undefined;
+    return (_jsxs(View, { style: style, testID: testID, children: [(!!title || !!description) && (_jsxs(View, { style: styles.groupHeader, children: [!!title && (_jsx(EyebrowText, { accessibilityRole: "header", ...headingLevel, style: { color: theme.colors.mutedForeground }, children: title })), !!description && (_jsx(CaptionText, { style: { color: theme.colors.textDim }, children: description }))] })), rows.map((row, index) => (_jsx(ItemGroupRowContext.Provider, { value: index < rows.length - 1 ? SEPARATED_ROW : LAST_ROW, children: row }, isValidElement(row) && row.key != null ? row.key : index))), !!footer && (_jsx(View, { style: styles.groupFooter, children: _jsx(CaptionText, { style: { color: theme.colors.mutedForeground }, children: footer }) }))] }));
+}
 /**
  * ItemMedia
  *
@@ -73,7 +212,7 @@ export function ItemMedia({ size = DEFAULT_MEDIA_SIZE, icon, iconColor = "mutedF
  * content). Sits between `ItemMedia` and `ItemActions`.
  */
 export function ItemContent({ children, style }) {
-    return _jsx(View, { style: [styles.content, style], children: children });
+    return (_jsx(View, { style: [styles.content, style], children: _jsx(ItemContentContext.Provider, { value: true, children: children }) }));
 }
 /**
  * ItemTitle
@@ -81,7 +220,13 @@ export function ItemContent({ children, style }) {
  * `Item` row title — label weight (medium) at body size.
  */
 export function ItemTitle({ children, style, ...props }) {
-    return (_jsx(StyledText, { size: "body", fontWeight: "medium", ...props, style: style, children: children }));
+    // The row's title (the one inside ItemContent) carries the id the row hands
+    // to its controls; titles used elsewhere (ItemMedia initials, a value in
+    // ItemActions) render without it.
+    const label = use(ItemLabelContext);
+    const inContent = use(ItemContentContext);
+    const nativeID = inContent ? label?.titleId : undefined;
+    return (_jsx(StyledText, { size: "body", fontWeight: "medium", nativeID: nativeID, ...props, style: style, children: children }));
 }
 /**
  * ItemDescription
@@ -101,7 +246,7 @@ export function ItemDescription({ children, style, ...props }) {
 export function ItemActions({ children, style }) {
     return _jsx(View, { style: [styles.actions, style], children: children });
 }
-const styles = StyleSheet.create({
+const styles = /*#__PURE__*/ StyleSheet.create({
     row: {
         flexDirection: "row",
         alignItems: "center",
@@ -122,6 +267,14 @@ const styles = StyleSheet.create({
     },
     separator: {
         height: StyleSheet.hairlineWidth,
-        marginLeft: SEPARATOR_INSET,
+    },
+    groupHeader: {
+        paddingHorizontal: spacing.rowPaddingX,
+        paddingBottom: spacing.xs,
+        gap: spacing.xxs,
+    },
+    groupFooter: {
+        paddingHorizontal: spacing.rowPaddingX,
+        paddingTop: spacing.xs,
     },
 });

package/dist/components/KeyboardAvoidingView.d.ts

@@ -18,5 +18,5 @@ export declare function useKeyboardAvoidance(): boolean;
  * so screens can avoid the soft keyboard with `automaticOffset`; web renders a
  * plain `View`.
  */
-export declare function KeyboardAvoidingView({ children, style, behavior, automaticOffset, contentContainerStyle, keyboardVerticalOffset, ...props }: KeyboardAvoidingViewProps): React.JSX.Element;
+export declare function KeyboardAvoidingView({ children, style, behavior: behaviorProp, automaticOffset, contentContainerStyle, keyboardVerticalOffset, ...props }: KeyboardAvoidingViewProps): React.JSX.Element;
 export {};

package/dist/components/KeyboardAvoidingView.js

@@ -14,7 +14,10 @@ export function useKeyboardAvoidance() {
  * so screens can avoid the soft keyboard with `automaticOffset`; web renders a
  * plain `View`.
  */
-export function KeyboardAvoidingView({ children, style, behavior = Platform.OS === "ios" ? "padding" : "height", automaticOffset = true, contentContainerStyle, keyboardVerticalOffset, ...props }) {
+export function KeyboardAvoidingView({ children, style, behavior: behaviorProp, automaticOffset = true, contentContainerStyle, keyboardVerticalOffset, ...props }) {
+    // Resolved in the body rather than as a default parameter: the React
+    // Compiler can't reorder a computed default, and skipped the component.
+    const behavior = behaviorProp === undefined ? (Platform.OS === "ios" ? "padding" : "height") : behaviorProp;
     if (Platform.OS === "web") {
         return (_jsx(KeyboardAvoidanceContext.Provider, { value: true, children: _jsx(View, { style: style, ...props, children: children }) }));
     }

package/dist/components/Label.js

@@ -4,6 +4,7 @@ import * as LabelPrimitive from "@rn-primitives/label";
 import { useTheme } from "../hooks/useTheme.js";
 import { useFontStyle } from "../hooks/useFontStyle.js";
 import { spacing } from "../constants/spacing.js";
+import { interaction } from "../constants/interaction.js";
 import { StyledText } from "./StyledText.js";
 import { createThemedStyles } from "../lib/themedStyles.js";
 const SIZE_CONFIGS = {
@@ -85,7 +86,7 @@ const createStyles = (theme) => StyleSheet.create({
         color: theme.colors.destructive,
     },
     disabledLabel: {
-        opacity: 0.6,
+        opacity: interaction.disabledOpacity,
     },
 });
-const themedStyles = createThemedStyles(createStyles);
+const themedStyles = /*#__PURE__*/ createThemedStyles(createStyles);

package/dist/components/MaxWidthContainer.js

@@ -57,7 +57,7 @@ export function MaxWidthContainer({ children, maxWidth, preset = "2xl", style, c
             style,
         ], children: children }));
 }
-const styles = StyleSheet.create({
+const styles = /*#__PURE__*/ StyleSheet.create({
     container: {
         flex: 1,
     },

package/dist/components/Notification.js

@@ -1,19 +1,35 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, use, useEffect, useEffectEvent, useRef } from "react";
+import { useCallback, useEffect, useEffectEvent, useMemo, useRef } from "react";
 import { Animated, Easing, StyleSheet, View, ActivityIndicator, Pressable, Platform } from "react-native";
-import { SafeAreaInsetsContext } from "react-native-safe-area-context";
+import { useStore } from "zustand";
 import { Icon } from "./Icon.js";
 import { useTheme, withAlpha } from "../hooks/useTheme.js";
 import { useReducedMotion } from "../hooks/useReduceMotion.js";
+import { useWindowInsets } from "../hooks/useWindowInsets.js";
 import { spacing } from "../constants/spacing.js";
 import { durations } from "../constants/motion.js";
 import { StyledText } from "./StyledText.js";
 import { palette } from "../constants/colors.js";
 import { translateText } from "../lib/i18n.js";
 import { createThemedStyles } from "../lib/themedStyles.js";
-import { globalUIStore } from "../state/globalUIStore.js";
-const timingIn = { duration: durations.fast, easing: Easing.out(Easing.quad), useNativeDriver: true };
-const timingOut = { duration: durations.instant, easing: Easing.in(Easing.quad), useNativeDriver: true };
+import { useAnimatedValue } from "../lib/useAnimatedValue.js";
+import { shouldUseNativeDriver } from "../lib/animations.js";
+import { globalUIStore, selectNotificationOffset } from "../state/globalUIStore.js";
+const timingIn = { duration: durations.fast, easing: Easing.out(Easing.quad), useNativeDriver: shouldUseNativeDriver };
+const timingOut = { duration: durations.instant, easing: Easing.in(Easing.quad), useNativeDriver: shouldUseNativeDriver };
+/**
+ * Run an action's handler, then dismiss, even when the handler throws. A
+ * module-level function because the React Compiler can't compile a
+ * `try`/`finally` and would otherwise skip the whole component.
+ */
+function runThenDismiss(run, dismiss) {
+    try {
+        run();
+    }
+    finally {
+        dismiss();
+    }
+}
 /**
  * Notification
  *
@@ -35,22 +51,27 @@ const timingOut = { duration: durations.instant, easing: Easing.in(Easing.quad),
 export const Notification = () => {
     const { theme, getShadowStyle } = useTheme();
     const reduceMotion = useReducedMotion();
-    const insets = use(SafeAreaInsetsContext);
-    const { alert, hide } = globalUIStore();
+    // Window insets, not the provider context alone: a toast host above the
+    // app's SafeAreaProvider (or inside a Modal) used to fall back to 20 pt and
+    // sit under the Dynamic Island.
+    const insets = useWindowInsets();
+    // Read the store through zustand's `useStore`, not by calling
+    // `globalUIStore()` directly: the React Compiler recognizes hooks by their
+    // `use` prefix, so it treated that call as a plain function, cached its
+    // result, and skipped the hook on the next render (React error #311).
+    const { alert, hide } = useStore(globalUIStore);
+    // Bars a layout registered with `useNotificationOffset` (a tab bar, a
+    // floating header), measured from the window edge like the insets. Select
+    // the stable record and derive the maxima here: a selector that built a new
+    // object per call would never satisfy `useSyncExternalStore`'s snapshot check.
+    const notificationOffsets = useStore(globalUIStore, (state) => state.notificationOffsets);
+    const offset = useMemo(() => selectNotificationOffset({ notificationOffsets }), [notificationOffsets]);
     const styles = themedStyles(theme);
     const position = alert?.position ?? "top";
     const isBottom = position === "bottom";
     // Just opacity + translateY — no scale (scale = bouncy feel)
-    const opacityRef = useRef(null);
-    if (opacityRef.current === null) {
-        opacityRef.current = new Animated.Value(0);
-    }
-    const opacity = opacityRef.current;
-    const translateYRef = useRef(null);
-    if (translateYRef.current === null) {
-        translateYRef.current = new Animated.Value(0);
-    }
-    const translateY = translateYRef.current;
+    const opacity = useAnimatedValue(0);
+    const translateY = useAnimatedValue(0);
     const wasVisibleRef = useRef(false);
     const timerRef = useRef(null);
     const hideNotification = useCallback(() => {
@@ -88,12 +109,7 @@ export const Notification = () => {
         const action = alert?.action;
         if (!action)
             return;
-        try {
-            action.onPress();
-        }
-        finally {
-            animateOut();
-        }
+        runThenDismiss(() => action.onPress(), animateOut);
     }, [alert?.action, animateOut]);
     // The auto-dismiss timer only needs the latest animateOut; wrapping it in an
     // Effect Event keeps it out of the deps so the effect doesn't re-run (and
@@ -150,8 +166,10 @@ export const Notification = () => {
         opacity,
         transform: [{ translateY }],
     };
-    const topPosition = insets?.top ? insets.top : 20;
-    const bottomPosition = insets?.bottom ? insets.bottom : 20;
+    // 8 pt of air past the inset or a registered bar, whichever reaches further;
+    // without either, 20 pt from the edge (as before).
+    const topPosition = Math.max(insets.top, spacing.smd, offset.top) + spacing.sm;
+    const bottomPosition = Math.max(insets.bottom, spacing.smd, offset.bottom) + spacing.sm;
     const getIconProps = () => {
         switch (alert?.type) {
             case "error":
@@ -208,7 +226,7 @@ export const Notification = () => {
     if (!alert?.show) {
         return null;
     }
-    return (_jsx(Animated.View, { accessibilityLiveRegion: "polite", accessibilityRole: "alert", style: [
+    return (_jsx(Animated.View, { testID: "ui-notification", accessibilityLiveRegion: "polite", accessibilityRole: "alert", style: [
             styles.container,
             isBottom
                 ? { bottom: bottomPosition }
@@ -302,4 +320,4 @@ const createStyles = (theme) => StyleSheet.create({
         ...(Platform.OS === "web" && { cursor: "pointer" }),
     },
 });
-const themedStyles = createThemedStyles(createStyles);
+const themedStyles = /*#__PURE__*/ createThemedStyles(createStyles);

package/dist/components/Popover.d.ts

@@ -3,22 +3,34 @@ import * as React from "react";
 import { ViewProps } from "react-native";
 /**
  * Popover Trigger Component
- * The element that triggers the popover to open/close
+ * The element that triggers the popover to open/close. Its ref exposes
+ * `open()` / `close()` for driving the popover from outside.
  */
-type PopoverTriggerProps = PopoverPrimitive.TriggerProps;
+type PopoverTriggerProps = PopoverPrimitive.TriggerProps & React.RefAttributes<PopoverPrimitive.TriggerRef>;
+/** What a `PopoverTrigger` ref holds: the pressable plus `open()` / `close()`. */
+type PopoverTriggerRef = PopoverPrimitive.TriggerRef;
 declare function PopoverTrigger({ disabled, ...props }: PopoverTriggerProps): React.JSX.Element;
 interface PopoverContentProps extends PopoverPrimitive.ContentProps {
     /**
      * Optional portal host name for custom portal mounting
      */
     portalHost?: string;
+    /**
+     * Scroll the children once they outgrow the room on the popover's side
+     * (default). Pass `false` for content that brings its own list: a `FlatList`
+     * inside a vertical ScrollView warns. The height cap still applies, but the
+     * popover can no longer measure its full height, so it stays on `side`.
+     */
+    scrollable?: boolean;
 }
 /**
  * Popover Content Component
- * The content that appears in the popover overlay
- * Supports smart positioning, animations, and theme integration
+ * The content that appears in the popover overlay. `side` is a preference: on
+ * native the popover opens on the other side when the content does not fit
+ * and there is more room there, caps its height to the room, and scrolls.
+ * A `style` merges over the themed surface; `insets` default to the safe area.
  */
-declare function PopoverContent({ side, align, sideOffset, portalHost, ...props }: PopoverContentProps): React.JSX.Element;
+declare function PopoverContent({ portalHost, insets, ...props }: PopoverContentProps): React.JSX.Element;
 /**
  * Popover Header Component
  * Optional header section for the popover content
@@ -62,3 +74,4 @@ type PopoverComponent = typeof PopoverRoot & {
  */
 declare const Popover: PopoverComponent;
 export { Popover, PopoverTrigger, PopoverContent, PopoverHeader, PopoverBody, PopoverFooter, };
+export type { PopoverTriggerRef };