@mrmeg/expo-ui 0.27.0 → 0.28.0

package/dist/design-system.json

@@ -1,7 +1,7 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "package": "@mrmeg/expo-ui",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "tokens": {
     "spacing": {
       "entries": [
@@ -97,6 +97,10 @@
           "name": "touchTarget",
           "value": 44
         },
+        {
+          "name": "minTarget",
+          "value": 24
+        },
         {
           "name": "buttonPadding",
           "value": 10
@@ -170,6 +174,50 @@
           "value": 48
         }
       ]
+    },
+    "typography": {
+      "entries": [
+        {
+          "name": "xs",
+          "value": 11,
+          "lineHeight": 16.5
+        },
+        {
+          "name": "sm",
+          "value": 12,
+          "lineHeight": 18
+        },
+        {
+          "name": "base",
+          "value": 14,
+          "lineHeight": 21
+        },
+        {
+          "name": "body",
+          "value": 15,
+          "lineHeight": 24.75
+        },
+        {
+          "name": "lg",
+          "value": 18,
+          "lineHeight": 27
+        },
+        {
+          "name": "xl",
+          "value": 22,
+          "lineHeight": 26.4
+        },
+        {
+          "name": "xxl",
+          "value": 28,
+          "lineHeight": 33.6
+        },
+        {
+          "name": "display",
+          "value": 34,
+          "lineHeight": 40.8
+        }
+      ]
     }
   },
   "palette": {
@@ -450,6 +498,86 @@
     "serif",
     "mono"
   ],
+  "fonts": {
+    "families": {
+      "serif": {
+        "light": [
+          "Georgia, 'Times New Roman', serif",
+          "Georgia"
+        ],
+        "regular": [
+          "Georgia, 'Times New Roman', serif",
+          "Georgia"
+        ],
+        "medium": [
+          "Georgia, 'Times New Roman', serif",
+          "Georgia"
+        ],
+        "semibold": [
+          "Georgia, 'Times New Roman', serif",
+          "Georgia"
+        ],
+        "bold": [
+          "Georgia, 'Times New Roman', serif",
+          "Georgia"
+        ]
+      },
+      "sansSerif": {
+        "light": [
+          "\"Inter\", system-ui, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif, \"Apple Color Emoji\", \"Segoe UI Emoji\", \"Segoe UI Symbol\"",
+          "Inter_400Regular",
+          "sans-serif"
+        ],
+        "regular": [
+          "\"Inter\", system-ui, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif, \"Apple Color Emoji\", \"Segoe UI Emoji\", \"Segoe UI Symbol\"",
+          "Inter_400Regular",
+          "sans-serif"
+        ],
+        "medium": [
+          "\"Inter\", system-ui, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif, \"Apple Color Emoji\", \"Segoe UI Emoji\", \"Segoe UI Symbol\"",
+          "Inter_500Medium",
+          "sans-serif"
+        ],
+        "semibold": [
+          "\"Inter\", system-ui, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif, \"Apple Color Emoji\", \"Segoe UI Emoji\", \"Segoe UI Symbol\"",
+          "Inter_600SemiBold",
+          "sans-serif"
+        ],
+        "bold": [
+          "\"Inter\", system-ui, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif, \"Apple Color Emoji\", \"Segoe UI Emoji\", \"Segoe UI Symbol\"",
+          "Inter_700Bold",
+          "sans-serif"
+        ]
+      },
+      "mono": {
+        "light": [
+          "ui-monospace, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace",
+          "Menlo",
+          "monospace"
+        ],
+        "regular": [
+          "ui-monospace, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace",
+          "Menlo",
+          "monospace"
+        ],
+        "medium": [
+          "ui-monospace, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace",
+          "Menlo",
+          "monospace"
+        ],
+        "semibold": [
+          "ui-monospace, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace",
+          "Menlo",
+          "monospace"
+        ],
+        "bold": [
+          "ui-monospace, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace",
+          "Menlo",
+          "monospace"
+        ]
+      }
+    }
+  },
   "components": [
     {
       "name": "Accordion",
@@ -1297,6 +1425,14 @@
       "variantValues": null,
       "sizeValues": null
     },
+    {
+      "name": "Hydrated",
+      "file": "Hydrated.tsx",
+      "hasSize": false,
+      "variantProp": null,
+      "variantValues": null,
+      "sizeValues": null
+    },
     {
       "name": "Icon",
       "file": "Icon.tsx",
@@ -1321,6 +1457,14 @@
       "variantValues": null,
       "sizeValues": null
     },
+    {
+      "name": "ItemGroup",
+      "file": "Item.tsx",
+      "hasSize": false,
+      "variantProp": null,
+      "variantValues": null,
+      "sizeValues": null
+    },
     {
       "name": "ItemMedia",
       "file": "Item.tsx",
@@ -1404,6 +1548,14 @@
       "variantValues": null,
       "sizeValues": null
     },
+    {
+      "name": "Screen",
+      "file": "Screen.tsx",
+      "hasSize": false,
+      "variantProp": null,
+      "variantValues": null,
+      "sizeValues": null
+    },
     {
       "name": "Popover",
       "file": "Popover.tsx",

package/dist/hooks/index.d.ts

@@ -1,7 +1,12 @@
-export * from "./useDimensions";
-export * from "./useFontStyle";
-export * from "./useReduceMotion";
-export * from "./useResources";
-export * from "./useScalePress";
-export * from "./useStaggeredEntrance";
-export * from "./useTheme";
+export * from "./useDimensions.js";
+export * from "./useFocusVisible.js";
+export * from "./useFontStyle.js";
+export * from "./useReduceMotion.js";
+export * from "./useResources.js";
+export * from "./useScalePress.js";
+export * from "./useShape.js";
+export * from "./useStaggeredEntrance.js";
+export * from "./useTheme.js";
+export { useHydrated } from "./useHydrated.js";
+export { useNotificationOffset } from "./useNotificationOffset.js";
+export { useWindowInsets } from "./useWindowInsets.js";

package/dist/hooks/index.js

@@ -1,7 +1,12 @@
 export * from "./useDimensions.js";
+export * from "./useFocusVisible.js";
 export * from "./useFontStyle.js";
 export * from "./useReduceMotion.js";
 export * from "./useResources.js";
 export * from "./useScalePress.js";
+export * from "./useShape.js";
 export * from "./useStaggeredEntrance.js";
 export * from "./useTheme.js";
+export { useHydrated } from "./useHydrated.js";
+export { useNotificationOffset } from "./useNotificationOffset.js";
+export { useWindowInsets } from "./useWindowInsets.js";

package/dist/hooks/useDimensions.d.ts

@@ -4,7 +4,7 @@
  *   1. A desktop visitor sees no reflow — their real viewport lands in the
  *      same breakpoint.
  *   2. A mobile visitor gets one frame of desktop-styled content before the
- *      post-mount effect snaps to real dimensions — better than the inverse
+ *      post-hydration update snaps to real dimensions — better than the inverse
  *      (every desktop visitor seeing mobile-tiny, then snapping).
  *   3. It matches the frame the app hands `SafeAreaProvider`, and it is the
  *      value the HTML shell `expo export` renders in Node is built from, so
@@ -29,13 +29,18 @@ type WindowDimensions = {
 * Provides a consistent way to access window dimensions and screen size
 * information across mobile and web.
 *
-* On web the first render can't read the window: server-side there is no DOM,
-* and reading it during the browser's first render would disagree with the
-* markup it hydrates. The width comes from `SsrViewportContext` when the host
-* provides a per-request value (server render + first client render must
-* provide the same one), falling back to `DEFAULT_VIEWPORT_WIDTH` / `_HEIGHT`.
-* A post-mount effect swaps in the real viewport and follows resize from
-* there.
+* On web the server render and the browser's hydration pass can't read the
+* window: server-side there is no DOM, and reading it while hydrating would
+* disagree with the markup. Both use the width from `SsrViewportContext` when
+* the host provides a per-request value (server render + first client render
+* must provide the same one), falling back to `DEFAULT_VIEWPORT_WIDTH` /
+* `_HEIGHT`. Right after hydration the real viewport takes over, and resize
+* is followed from there. Every consumer shares one window listener and one
+* snapshot, re-renders only when the width or height changes, and a component
+* that mounts after hydration reads the current viewport straight away.
+*
+* The platform branch is chosen once, at module load (`Platform.OS` never
+* changes at runtime), so each platform calls exactly one set of hooks.
 */
 export declare const useDimensions: () => WindowDimensions;
 export {};

package/dist/hooks/useDimensions.js

@@ -1,4 +1,4 @@
-import { use, useEffect, useState } from "react";
+import { use, useMemo, useSyncExternalStore } from "react";
 import { Platform, useWindowDimensions } from "react-native";
 import { SsrViewportContext } from "../state/SsrViewportContext.js";
 /**
@@ -7,7 +7,7 @@ import { SsrViewportContext } from "../state/SsrViewportContext.js";
  *   1. A desktop visitor sees no reflow — their real viewport lands in the
  *      same breakpoint.
  *   2. A mobile visitor gets one frame of desktop-styled content before the
- *      post-mount effect snaps to real dimensions — better than the inverse
+ *      post-hydration update snaps to real dimensions — better than the inverse
  *      (every desktop visitor seeing mobile-tiny, then snapping).
  *   3. It matches the frame the app hands `SafeAreaProvider`, and it is the
  *      value the HTML shell `expo export` renders in Node is built from, so
@@ -34,61 +34,136 @@ const calculateDimensionFlags = (width, height) => {
         isLargeScreen: width > SCREEN_SIZES.MEDIUM,
     };
 };
-// Persist the real viewport width as a cookie on first mount so subsequent
-// SSR requests can render at the user's actual layout (no reflow on repeat
-// visits). The server reads this cookie via resolveSsrViewportWidth in
-// server/lib/ssrViewport.ts.
+// Persist the real viewport width as a cookie so subsequent SSR requests can
+// render at the user's actual layout (no reflow on repeat visits). The server
+// reads this cookie via resolveSsrViewportWidth in server/lib/ssrViewport.ts.
 const SSR_VIEWPORT_COOKIE = "mrmeg-vw";
 const SSR_VIEWPORT_COOKIE_MAX_AGE = 60 * 60 * 24 * 365; // 1 year
+// Resize fires continuously while a window is dragged; the cookie only has to
+// hold the width the drag settled on.
+const SSR_VIEWPORT_COOKIE_DEBOUNCE_MS = 250;
+// Round to nearest 10 so resize-driven writes don't bust HTTP caching on
+// every pixel of horizontal movement.
+const roundViewportWidth = (width) => Math.round(width / 10) * 10;
+// ---------------------------------------------------------------------------
+// Web: one window store shared by every useDimensions() consumer (same shape
+// as useReduceMotion's). A single `resize` listener, attached while at least
+// one consumer is mounted, updates one snapshot and notifies consumers only
+// when the width or height actually changed.
+// ---------------------------------------------------------------------------
+let windowSnapshot = null;
+const windowListeners = new Set();
+let writtenCookieWidth = null;
+let pendingCookieWidth = null;
+let cookieTimer = null;
 function writeViewportCookie(width) {
     if (typeof document === "undefined")
         return;
-    // Round to nearest 10 so resize-driven writes don't bust HTTP caching on
-    // every pixel of horizontal movement.
-    const rounded = Math.round(width / 10) * 10;
+    const rounded = roundViewportWidth(width);
+    writtenCookieWidth = rounded;
     document.cookie = `${SSR_VIEWPORT_COOKIE}=${rounded}; path=/; max-age=${SSR_VIEWPORT_COOKIE_MAX_AGE}; SameSite=Lax`;
 }
+/** Reads the window, reusing the current snapshot when nothing changed. */
+function readWindow() {
+    const width = typeof window === "undefined" ? DEFAULT_VIEWPORT_WIDTH : window.innerWidth;
+    const height = typeof window === "undefined" ? DEFAULT_VIEWPORT_HEIGHT : window.innerHeight;
+    if (!windowSnapshot || windowSnapshot.width !== width || windowSnapshot.height !== height) {
+        windowSnapshot = calculateDimensionFlags(width, height);
+    }
+    return windowSnapshot;
+}
+function flushViewportCookie() {
+    if (cookieTimer !== null) {
+        clearTimeout(cookieTimer);
+        cookieTimer = null;
+    }
+    if (pendingCookieWidth !== null) {
+        const width = pendingCookieWidth;
+        pendingCookieWidth = null;
+        writeViewportCookie(width);
+    }
+}
+function scheduleViewportCookie(width) {
+    if (roundViewportWidth(width) === writtenCookieWidth) {
+        pendingCookieWidth = null;
+        if (cookieTimer !== null) {
+            clearTimeout(cookieTimer);
+            cookieTimer = null;
+        }
+        return;
+    }
+    pendingCookieWidth = width;
+    if (cookieTimer !== null)
+        clearTimeout(cookieTimer);
+    cookieTimer = setTimeout(flushViewportCookie, SSR_VIEWPORT_COOKIE_DEBOUNCE_MS);
+}
+function handleWindowResize() {
+    const previous = windowSnapshot;
+    const next = readWindow();
+    if (next !== previous) {
+        for (const listener of windowListeners)
+            listener();
+    }
+    scheduleViewportCookie(next.width);
+}
+// useSyncExternalStore contract: the first consumer attaches the one window
+// listener (and records the real width in the cookie, once per page view
+// rather than once per consumer); the last one to unmount detaches it.
+function subscribeToWindow(listener) {
+    windowListeners.add(listener);
+    if (windowListeners.size === 1 && canListenToWindow()) {
+        window.addEventListener("resize", handleWindowResize);
+        writeViewportCookie(readWindow().width);
+    }
+    return () => {
+        windowListeners.delete(listener);
+        if (windowListeners.size === 0 && canListenToWindow()) {
+            window.removeEventListener("resize", handleWindowResize);
+            flushViewportCookie();
+        }
+    };
+}
+function canListenToWindow() {
+    return typeof window !== "undefined" && typeof window.addEventListener === "function";
+}
+function getWindowSnapshot() {
+    // While subscribed, the resize listener keeps the snapshot current, so a
+    // render never reads (and forces layout on) the window.
+    return windowListeners.size > 0 && windowSnapshot ? windowSnapshot : readWindow();
+}
+// The server has no window, and the browser's hydration pass must render what
+// the server did: `null` selects the seeded frame below for both.
+function getServerWindowSnapshot() {
+    return null;
+}
+function useWebDimensions() {
+    const ssrWidth = use(SsrViewportContext);
+    const live = useSyncExternalStore(subscribeToWindow, getWindowSnapshot, getServerWindowSnapshot);
+    const seeded = useMemo(() => calculateDimensionFlags(ssrWidth ?? DEFAULT_VIEWPORT_WIDTH, DEFAULT_VIEWPORT_HEIGHT), [ssrWidth]);
+    return live ?? seeded;
+}
+// Native reads come from useWindowDimensions, which subscribes to rotation /
+// split-screen / resize and tears the listener down for us — no manual
+// Dimensions.addEventListener to leak.
+function useNativeDimensions() {
+    const { width, height } = useWindowDimensions();
+    return useMemo(() => calculateDimensionFlags(width, height), [width, height]);
+}
 /**
 * Provides a consistent way to access window dimensions and screen size
 * information across mobile and web.
 *
-* On web the first render can't read the window: server-side there is no DOM,
-* and reading it during the browser's first render would disagree with the
-* markup it hydrates. The width comes from `SsrViewportContext` when the host
-* provides a per-request value (server render + first client render must
-* provide the same one), falling back to `DEFAULT_VIEWPORT_WIDTH` / `_HEIGHT`.
-* A post-mount effect swaps in the real viewport and follows resize from
-* there.
+* On web the server render and the browser's hydration pass can't read the
+* window: server-side there is no DOM, and reading it while hydrating would
+* disagree with the markup. Both use the width from `SsrViewportContext` when
+* the host provides a per-request value (server render + first client render
+* must provide the same one), falling back to `DEFAULT_VIEWPORT_WIDTH` /
+* `_HEIGHT`. Right after hydration the real viewport takes over, and resize
+* is followed from there. Every consumer shares one window listener and one
+* snapshot, re-renders only when the width or height changes, and a component
+* that mounts after hydration reads the current viewport straight away.
+*
+* The platform branch is chosen once, at module load (`Platform.OS` never
+* changes at runtime), so each platform calls exactly one set of hooks.
 */
-export const useDimensions = () => {
-    const isWeb = Platform.OS === "web";
-    const ssrWidth = use(SsrViewportContext);
-    // Native reads come from useWindowDimensions, which subscribes to rotation /
-    // split-screen / resize and tears the listener down for us — no manual
-    // Dimensions.addEventListener to leak. On web we ignore it and drive layout
-    // from the seeded frame + the resize listener below.
-    const native = useWindowDimensions();
-    const [dimensions, setDimensions] = useState(() => calculateDimensionFlags(ssrWidth ?? DEFAULT_VIEWPORT_WIDTH, DEFAULT_VIEWPORT_HEIGHT));
-    // Web: read the real viewport after mount and follow resize events. Keeping
-    // this in an effect (not render) keeps the first render identical to the
-    // exported markup it hydrates.
-    useEffect(() => {
-        if (!isWeb)
-            return;
-        const syncFromWindow = () => {
-            setDimensions(calculateDimensionFlags(window.innerWidth, window.innerHeight));
-            writeViewportCookie(window.innerWidth);
-        };
-        syncFromWindow();
-        window.addEventListener("resize", syncFromWindow);
-        return () => {
-            window.removeEventListener("resize", syncFromWindow);
-        };
-    }, [isWeb]);
-    // Native: useWindowDimensions already reacts to changes; mirror it into our
-    // enriched flags. (On web `native` is unused — the effect above wins.)
-    if (!isWeb) {
-        return calculateDimensionFlags(native.width, native.height);
-    }
-    return dimensions;
-};
+export const useDimensions = Platform.OS === "web" ? useWebDimensions : useNativeDimensions;

package/dist/hooks/useFocusVisible.d.ts

@@ -0,0 +1,30 @@
+import { type NativeSyntheticEvent, type TargetedEvent } from "react-native";
+export type FocusVisibleEvent = NativeSyntheticEvent<TargetedEvent>;
+export interface UseFocusVisibleOptions<E = FocusVisibleEvent> {
+    /** Caller's focus handler, invoked after the ring state updates. */
+    onFocus?: ((event: E) => void) | null;
+    /** Caller's blur handler, invoked after the ring state updates. */
+    onBlur?: ((event: E) => void) | null;
+}
+/**
+ * Focus-ring state gated on `:focus-visible`.
+ *
+ * On web a pointer tap focuses the element too, which left the ring visible
+ * after every click; `:focus-visible` is only true for keyboard-driven focus,
+ * so the ring follows it and falls back to showing when the target can't be
+ * queried (non-DOM targets, older engines). Off web every focus shows the
+ * ring. Spread `onFocus`/`onBlur` onto the Pressable and layer
+ * `getFocusRingStyle()` while `focused` is true and the control is enabled.
+ *
+ * @example
+ * ```tsx
+ * const focus = useFocusVisible({ onFocus, onBlur });
+ * <Pressable onFocus={focus.onFocus} onBlur={focus.onBlur}
+ *   style={[styles.base, focus.focused && !disabled && getFocusRingStyle()]} />
+ * ```
+ */
+export declare function useFocusVisible<E = FocusVisibleEvent>(options?: UseFocusVisibleOptions<E>): {
+    focused: boolean;
+    onFocus: (event: E) => void;
+    onBlur: (event: E) => void;
+};

package/dist/hooks/useFocusVisible.js

@@ -0,0 +1,45 @@
+import { useCallback, useState } from "react";
+import { Platform } from "react-native";
+/**
+ * Focus-ring state gated on `:focus-visible`.
+ *
+ * On web a pointer tap focuses the element too, which left the ring visible
+ * after every click; `:focus-visible` is only true for keyboard-driven focus,
+ * so the ring follows it and falls back to showing when the target can't be
+ * queried (non-DOM targets, older engines). Off web every focus shows the
+ * ring. Spread `onFocus`/`onBlur` onto the Pressable and layer
+ * `getFocusRingStyle()` while `focused` is true and the control is enabled.
+ *
+ * @example
+ * ```tsx
+ * const focus = useFocusVisible({ onFocus, onBlur });
+ * <Pressable onFocus={focus.onFocus} onBlur={focus.onBlur}
+ *   style={[styles.base, focus.focused && !disabled && getFocusRingStyle()]} />
+ * ```
+ */
+export function useFocusVisible(options = {}) {
+    const { onFocus: onFocusProp, onBlur: onBlurProp } = options;
+    const [focused, setFocused] = useState(false);
+    const onFocus = useCallback((event) => {
+        setFocused(isKeyboardFocus(event));
+        onFocusProp?.(event);
+    }, [onFocusProp]);
+    const onBlur = useCallback((event) => {
+        setFocused(false);
+        onBlurProp?.(event);
+    }, [onBlurProp]);
+    return { focused, onFocus, onBlur };
+}
+function isKeyboardFocus(event) {
+    if (Platform.OS !== "web")
+        return true;
+    const target = event?.nativeEvent?.target;
+    if (!target || typeof target.matches !== "function")
+        return true;
+    try {
+        return target.matches(":focus-visible");
+    }
+    catch {
+        return true;
+    }
+}

package/dist/hooks/useFontStyle.d.ts

@@ -1,4 +1,4 @@
-import { type FontFamilyWeight, type FontVariant, type ResolvedFontStyle } from "../constants/fonts";
+import { type FontFamilyWeight, type FontStyleOptions, type FontVariant, type ResolvedFontStyle } from "../constants/fonts.js";
 /**
  * Resolve a `{ fontFamily, fontWeight? }` style through the theme store's
  * font overrides, re-rendering when a host app calls `setFonts`.
@@ -8,4 +8,4 @@ import { type FontFamilyWeight, type FontVariant, type ResolvedFontStyle } from
  * is identical to the package's hardcoded families, so layering it after a
  * static themed style changes nothing by default.
  */
-export declare function useFontStyle(weight?: FontFamilyWeight, variant?: FontVariant): ResolvedFontStyle;
+export declare function useFontStyle(weight?: FontFamilyWeight, variant?: FontVariant, options?: Pick<FontStyleOptions, "italic">): ResolvedFontStyle;

package/dist/hooks/useFontStyle.js

@@ -9,9 +9,10 @@ import { useThemeStore } from "../state/themeStore.js";
  * is identical to the package's hardcoded families, so layering it after a
  * static themed style changes nothing by default.
  */
-export function useFontStyle(weight = "regular", variant = "sansSerif") {
+export function useFontStyle(weight = "regular", variant = "sansSerif", options = {}) {
     // Subscribed, not read via getState(), so a `setFonts` call after mount
     // re-renders instead of leaving stale families on screen.
     const fontOverrides = useThemeStore((s) => s.fontOverrides);
-    return resolveFontStyle(fontOverrides, variant, weight);
+    const serifPreset = useThemeStore((s) => s.serifPreset);
+    return resolveFontStyle(fontOverrides, variant, weight, { italic: options.italic, serifPreset });
 }

package/dist/hooks/useHydrated.d.ts

@@ -0,0 +1,13 @@
+/**
+ * False during server rendering and the hydration pass, true once the tree
+ * is live on the client (and always true on native, which never hydrates).
+ *
+ * Use it to defer DOM output that cannot be reproduced on the server. The one
+ * case in the kit: `useId()`-based `id` / `aria-labelledby` pairs. Under Expo
+ * Router's streamed SSR the client's hydration pass computes different tree
+ * ids than the server did, so an id emitted on both sides logs "A tree hydrated
+ * but some attributes … didn't match" and the link points at a stale id.
+ * Adding the attributes in the first client render after hydration is an
+ * ordinary update instead.
+ */
+export declare function useHydrated(): boolean;

package/dist/hooks/useHydrated.js

@@ -0,0 +1,19 @@
+import { useSyncExternalStore } from "react";
+const subscribe = () => () => { };
+const clientSnapshot = () => true;
+const serverSnapshot = () => false;
+/**
+ * False during server rendering and the hydration pass, true once the tree
+ * is live on the client (and always true on native, which never hydrates).
+ *
+ * Use it to defer DOM output that cannot be reproduced on the server. The one
+ * case in the kit: `useId()`-based `id` / `aria-labelledby` pairs. Under Expo
+ * Router's streamed SSR the client's hydration pass computes different tree
+ * ids than the server did, so an id emitted on both sides logs "A tree hydrated
+ * but some attributes … didn't match" and the link points at a stale id.
+ * Adding the attributes in the first client render after hydration is an
+ * ordinary update instead.
+ */
+export function useHydrated() {
+    return useSyncExternalStore(subscribe, clientSnapshot, serverSnapshot);
+}

package/dist/hooks/useNotificationOffset.d.ts

@@ -0,0 +1,20 @@
+import { type NotificationOffset } from "../state/globalUIStore.js";
+/**
+ * Keep global toasts clear of a bar this layout owns, for as long as it is
+ * mounted. The offset is measured from the window edge and includes the
+ * safe-area inset there, so a JS tab layout passes `useBottomTabBarHeight()`
+ * as-is and a native tab layout passes the bar height plus the bottom inset;
+ * `Notification` then sits 8 pt past the larger of the inset and the offset.
+ * Pass `null` (or `undefined`) to register nothing — for instance while the
+ * tab bar is hidden behind the keyboard. Several layouts may register at once;
+ * the largest value per edge wins. A no-op during server rendering.
+ *
+ * ```tsx
+ * // app/(tabs)/_layout.tsx with Expo Router's JS <Tabs>
+ * function TabBarOffset() {
+ *   useNotificationOffset({ bottom: useBottomTabBarHeight() });
+ *   return null;
+ * }
+ * ```
+ */
+export declare function useNotificationOffset(offset: NotificationOffset | null | undefined): void;

package/dist/hooks/useNotificationOffset.js

@@ -0,0 +1,34 @@
+import { useEffect, useId } from "react";
+import { globalUIStore } from "../state/globalUIStore.js";
+/**
+ * Keep global toasts clear of a bar this layout owns, for as long as it is
+ * mounted. The offset is measured from the window edge and includes the
+ * safe-area inset there, so a JS tab layout passes `useBottomTabBarHeight()`
+ * as-is and a native tab layout passes the bar height plus the bottom inset;
+ * `Notification` then sits 8 pt past the larger of the inset and the offset.
+ * Pass `null` (or `undefined`) to register nothing — for instance while the
+ * tab bar is hidden behind the keyboard. Several layouts may register at once;
+ * the largest value per edge wins. A no-op during server rendering.
+ *
+ * ```tsx
+ * // app/(tabs)/_layout.tsx with Expo Router's JS <Tabs>
+ * function TabBarOffset() {
+ *   useNotificationOffset({ bottom: useBottomTabBarHeight() });
+ *   return null;
+ * }
+ * ```
+ */
+export function useNotificationOffset(offset) {
+    const key = useId();
+    const top = offset?.top;
+    const bottom = offset?.bottom;
+    const active = offset != null && (top !== undefined || bottom !== undefined);
+    useEffect(() => {
+        if (!active)
+            return;
+        globalUIStore.getState().setNotificationOffset(key, { top, bottom });
+        return () => {
+            globalUIStore.getState().clearNotificationOffset(key);
+        };
+    }, [active, key, top, bottom]);
+}