pixelize-native-library 1.2.0 → 1.3.0

package/lib/module/modules/modal/MODULE.md

@@ -10,17 +10,14 @@ VoiceOver's escape gesture via `onAccessibilityEscape`).
 
 | File | Role |
 |------|------|
-| `Modal.tsx` | The component. RN `<Modal>` composition, backdrop, overlay, panel, title. Falls back to the web portal mechanism below when opted in. |
+| `Modal.tsx` | The component. RN `<Modal>` composition, backdrop, overlay, panel, title. Panel lift/scrim opacity use `useMotion` + `useAnimatedValue` (Reanimated). Falls back to the web portal mechanism below when opted in. |
 | `Modal.variants.ts` | Pure resolvers (`MODAL_SIZES`, `resolveModalPanelColors`, `resolveModalAnimationType`) + the themed structural resolvers (`modalOverlayStructure`, `modalPanelStructure`). No React, no lucide. Untouched by the web portal mechanism — see below. |
 | `ModalPortalContext.ts` | The web-only portal-container `React.Context<unknown>`, default `null`. Read by `Modal`, `Select`, `MultiSelect`, and `Menu`. |
 | `ModalPortalProvider.tsx` | Public provider wrapping `ModalPortalContext.Provider`. A consumer's opt-in API. |
 | `renderWebPortal.ts` / `renderWebPortal.web.ts` | The platform-split portal renderer — see "Web portal mechanism" below. |
 | `index.ts` | Public surface: `Modal`, `ModalProps`, `ModalSize`, `ModalPortalProvider`, `ModalPortalProviderProps`. |
-| `__tests__/Modal.test.ts` | Pure: WCAG contrast (all brands × modes), size-cap sanity, reduced-motion contract. |
-| `__tests__/Modal.render.test.tsx` | Render: visibility, title semantics, backdrop dismissal, and the web-portal opt-in branch (mocking `renderWebPortal`). |
-| `__tests__/ModalPortalProvider.test.tsx` | The provider forwards `container` onto `ModalPortalContext`; an unwrapped tree reads the `null` default. |
-| `__tests__/renderWebPortal.test.ts` / `renderWebPortal.web.test.ts` | Each platform file in isolation — the native file is always a no-op; the web file calls `ReactDOM.createPortal` with the exact children/container (mocked — no real DOM under Jest). |
-| `__tests__/Modal.keyboard.web.test.tsx` | Escape / Tab trap / focus restore on the portal branch, and their deliberate ABSENCE on the RNModal branch. |
+| `__tests__/Modal.test.ts` / `Modal.render.test.tsx` | Pure (WCAG contrast, size caps, reduced motion) + render (visibility, title semantics, backdrop dismissal, portal branch). |
+| `__tests__/ModalPortalProvider.test.tsx`, `renderWebPortal*.test.ts`, `Modal.keyboard.web.test.tsx` | Provider context default; each platform portal file in isolation; Escape/Tab-trap/focus-restore on the portal branch and their deliberate absence on the RNModal branch. |
 
 ## Props
 
@@ -29,7 +26,11 @@ VoiceOver's escape gesture via `onAccessibilityEscape`).
 | `visible` | `boolean` | — | Required. Fully controlled — no internal open state. |
 | `onRequestClose` | `() => void` | — | Required. Fired by the backdrop press, Android hardware back, and iOS VoiceOver's escape gesture (`onAccessibilityEscape` on the panel). |
 | `title` | `string` | — | Optional heading, rendered `accessibilityRole="header"`. |
+| `subtitle` | `string` | — | Optional muted line under the title (`fg.muted`). |
 | `children` | `ReactNode` | — | Required. Panel content. |
+| `footer` | `ReactNode` | — | Actions row below body (e.g. Cancel / Save). |
+| `isLoading` | `boolean` | `false` | Scrim + centered `Spinner` over the panel; swallows taps, so footer and body cannot be activated while it is up. |
+| `hideCloseButton` | `boolean` | `true` | When `false`, renders an explicit header close control wired to `onRequestClose`. |
 | `size` | `sm \| md \| lg` | `md` | Closed union — panel max width, reusing the shared `sizes` primitive (384/448/512dp). |
 | `testID` | `string` | — | Also seeds `${testID}-backdrop` and `${testID}-panel`. |
 
@@ -44,16 +45,12 @@ No `style`/`containerStyle` — see "Why no `style`" below.
 - **2.3.3** — `resolveModalAnimationType(reducedMotion)` returns `"none"` instead of `"fade"` when
   the OS reduce-motion setting is on.
 - The title is `accessibilityRole="header"`, giving it heading semantics for screen readers.
-- The backdrop is `accessible={false}` — a decorative dismiss target, not a focusable element (same
-  treatment as `Select`'s backdrop). It is never the *only* way to close: Android hardware back also
-  fires `onRequestClose`, and the panel's `onAccessibilityEscape={onRequestClose}` gives iOS
-  VoiceOver users a real two-finger-Z "escape" gesture to dismiss without hunting for the invisible
-  backdrop. (RN's `<Modal>` only treats a swipe as a dismiss when `allowSwipeDismissal` is passed —
-  this component doesn't set it — and `transparent` with no `presentationStyle` forces
-  `overFullScreen`, which has no native iOS swipe-to-dismiss gesture at all; `onAccessibilityEscape`
-  is the real, working native hook here, not a swipe.)
-- No touch-target sizing needed: the only interactive surface is the full-screen backdrop, already
-  far larger than the 44dp floor.
+- The backdrop is `accessible={false}` — a decorative dismiss target, never the *only* way to
+  close: Android hardware back fires `onRequestClose`, and `onAccessibilityEscape` on the panel
+  gives VoiceOver a real two-finger-Z dismiss. There is no iOS swipe-to-dismiss here —
+  `transparent` with no `presentationStyle` forces `overFullScreen`, which has no such gesture.
+- Touch targets need no local sizing: the backdrop is full-screen, and the optional header close
+  control is a library `Button`, which already enforces the 44dp floor.
 
 ## Why no `style`
 
@@ -64,101 +61,78 @@ component spec omits `style` rather than including it as an unused escape hatch.
 
 ## Web portal mechanism (opt-in)
 
-`react-native-web`'s own `<Modal>` unconditionally portals to `document.body`
-(`ModalPortal.js` in the installed 0.21.2 does `document.body.appendChild(...)` then
-`createPortal(children, elementRef.current)` — no `container`/`portalHost` prop exists to
-override it, confirmed by reading the source). That's correct for a full app, but breaks visual
-containment inside a fixed-size preview frame (`example/DeviceFrame.tsx`'s 390px phone card): the
-overlay renders full-browser-viewport instead of clipped to the frame. Same problem, same fix, for
-`Select`'s option sheet, `MultiSelect`'s option sheet, and `Menu`'s action sheet — all three render
-their own RN `<Modal>` directly (never this module's `Modal` component) and read the identical
-mechanism below.
-
-- **`ModalPortalContext`** — a `React.Context<unknown>`, default `null`. `unknown` because this
-  package has no `"dom"` lib entry (native has no DOM) — a `HTMLElement` type here wouldn't
-  compile. Internal; a consumer never reads it directly.
+`react-native-web`'s `<Modal>` portals to `document.body` unconditionally with no `container` prop
+to override it, which breaks containment inside a fixed-size preview frame
+(`example/DeviceFrame.tsx`). `Select`, `MultiSelect` and `Menu` render their own RN `<Modal>`
+directly (never this component) and read the identical mechanism.
+
+- **`ModalPortalContext`** — `React.Context<unknown>`, default `null`. `unknown` because the
+  package has no `"dom"` lib entry, so `HTMLElement` would not compile. Internal.
 - **`ModalPortalProvider`** — the public opt-in. `<ModalPortalProvider container={node}>` makes
-  every `Modal` / `AlertDialog` / `Select` / `MultiSelect` / `Menu` underneath portal into `node`
-  instead of `document.body`. Safe to mount unconditionally on every platform — there's no DOM to
-  portal into outside web, so `container` is simply never read off the context there.
-- **`renderWebPortal.ts` (base) / `renderWebPortal.web.ts` (web)** — a Metro platform-extension
-  pair, same idea as `theme/platform/*.native.ts` but the other direction: the BASE file (no
-  suffix) is the safe default every platform except an actual web bundle resolves to (a pure
-  no-op — always returns `null`), and `renderWebPortal.web.ts` (the only file that imports
-  `react-dom`) is what an actual web bundle resolves to instead. Metro never resolves
-  `react-dom` for a native bundle, so it's never part of that dependency graph — verified via
-  `expo export --platform ios` vs `--platform web`, grepping each bundle for a marker string
-  unique to each file. Jest's `react-native` preset has no `web` haste platform either, so every
-  test also resolves the base file by default — this is why `Modal.render.test.tsx` /
-  `Select.render.test.tsx` / `MultiSelect.render.test.tsx` / `Menu.render.test.tsx` mock
-  `renderWebPortal` directly to exercise the opt-in branch, and `renderWebPortal.web.test.ts` is the
-  one place the real `ReactDOM.createPortal` call is verified (mocking `react-dom` itself — no real
-  DOM under Jest).
+  every `Modal` / `AlertDialog` / `Select` / `MultiSelect` / `Menu` underneath portal into `node`.
+  Safe to mount on every platform; off web, `container` is never read.
+- **`renderWebPortal.ts` / `.web.ts`** — a Metro platform-extension pair where the BASE file is the
+  no-op default and only the `.web` file imports `react-dom`, so `react-dom` never enters a native
+  bundle. Jest has no `web` haste platform either, so render tests mock `renderWebPortal` to reach
+  the opt-in branch; `renderWebPortal.web.test.ts` is the only place the real `createPortal` is
+  verified.
 - **Backward compatibility (the hard bar):** `Platform.OS === "web" && portalContainer != null`
-  gates the whole mechanism — every existing consumer (native, or web with no provider) takes the
-  exact same code path as before this mechanism existed: RN's own `<Modal>`, untouched. Neither
-  `Modal.variants.ts` nor `Select.variants.ts`/`MultiSelect.variants.ts`/`Menu.variants.ts`'s
-  structural resolvers were touched — the portal path reproduces just the sizing RN's `<Modal>`
-  otherwise supplies (a `StyleSheet.absoluteFill` wrapper around the SAME backdrop+panel tree)
-  rather than changing the shared resolvers, so the default path's styles are provably unaffected.
-- **Known simplification:** the portal path skips RN `<Modal>`'s open/close animation entirely
-  (mounts/unmounts on `visible`/`open` directly) — `resolveModalAnimationType`/reduced-motion only
-  apply to the RNModal path. Acceptable: the goal is containment, not animation fidelity, and this
-  only affects a consumer that has opted in.
+  gates the whole mechanism, so native and provider-less web take the untouched RN `<Modal>` path.
+  No shared structural resolver was changed — the portal path only reproduces the sizing RN's
+  `<Modal>` otherwise supplies around the same backdrop+panel tree.
+- **The portal path runs its own motion**, not RN `<Modal>`'s: the shared `enter` value drives the
+  panel and scrim, and `mounted` holds the tree through a timed exit rather than unmounting on
+  `visible`. `resolveModalAnimationType` applies only to the RNModal branch.
 - `react-dom` is an **optional peer dependency** (`peerDependenciesMeta.react-dom.optional`) —
   only needed by an app that actually renders for web; native-only consumers never install it.
 
 ### Keyboard — the portal branch has to supply its own
 
-Every keyboard behaviour a web `<Modal>` has comes from `react-native-web`'s own `ModalContent`
-(Escape) and `ModalFocusTrap` (Tab cycling + focus restore). The portal branch renders no
-`<RNModal>`, so mounting a `ModalPortalProvider` silently lost all three at once: Escape did
-nothing, Tab walked into the page behind the scrim, and closing dropped focus on `<body>`.
+Escape, Tab cycling and focus restore all come from `react-native-web`'s own `ModalContent` /
+`ModalFocusTrap`, which the portal branch never renders. `Modal.tsx` therefore calls
+`useDismissOnEscape` + `useFocusTrap` (`core/a11y/keyboard`, imported directly) gated on
+`portalled && visible`. **The RNModal path must stay unwired** — two Escape listeners and two
+competing traps is a worse bug than the one being fixed. Both hooks are native no-ops by file
+resolution. `AlertDialog`, `LimitReachedModal` and `ImageViewer` compose this and inherit all of
+it, each with a test asserting the inheritance.
 
-`Modal.tsx` therefore calls `useDismissOnEscape` + `useFocusTrap` (`core/a11y/keyboard`, imported
-directly — not through the `core/a11y` barrel) gated on `portalled && visible`. **The RNModal path
-must stay unwired**: two Escape listeners and two competing traps on one dialog is a worse bug than
-the one being fixed. Both hooks are no-ops on native by file resolution, so nothing changes there.
+## Patterns copied from Button / Select (the reference modules)
 
-`AlertDialog`, `LimitReachedModal` and `ImageViewer` compose this component and inherit all of it —
-none of them contains keyboard code, and each has a test asserting the inheritance.
+Structure vs colour split (`createThemedVariants` for sizing, `RoleColors` inline); pure resolvers
+in `Modal.variants.ts` unit-tested against real palettes; RN's own `<Modal>` rather than a
+hand-rolled portal; a closed `size` union reusing the shared `sizes` primitive.
 
-## Patterns copied from Button / Select (the reference modules)
+## Android edge-to-edge
 
-1. **Structure vs colour split** — sizing/spacing/radius via `createThemedVariants`; colour
-   resolved from `RoleColors`, applied inline.
-2. **Pure, testable resolvers** in `Modal.variants.ts` — WCAG contrast and the reduced-motion
-   contract are unit-tested against real palettes, never eyeballed.
-3. **RN's own `<Modal>`, not a hand-rolled portal** — `transparent` + backdrop `Pressable` +
-   `pointerEvents="box-none"` overlay, the same shape `Select`'s option list uses (converged on
-   independently — this module owns none of that code, built in parallel).
-4. **Closed `size` union** reusing the shared `sizes` primitive (384/448/512dp) instead of
-   Modal-local numbers — `theme/tokens/primitives/sizes.ts` is documented for exactly this case.
+Every RN `<Modal transparent>` in this library (`Modal`, `Select`, `MultiSelect`, `Combobox`,
+`Menu`, `OrgSwitcher`, `PickerShell`, `Drawer`) also sets `statusBarTranslucent` and
+`navigationBarTranslucent`, both `true`. Without them, Android edge-to-edge (Expo default since
+SDK 53) paints the modal's backing window opaque instead of transparent — the whole screen goes
+solid white on open. Add both any time a new module renders its own RN `<Modal transparent>`.
 
 ## Known gaps
 
-- **No full SCREEN-READER trap.** iOS gets `accessibilityViewIsModal` (constrains VoiceOver to the
-  panel). Android has no JS-level equivalent for marking background siblings
-  `importantForAccessibility="no-hide-descendants"` from inside this component (that prop applies
-  to the element it's set on, not to arbitrary siblings elsewhere in the tree) — a full Android
-  reader trap needs the app root to cooperate. Out of scope for v1. (The web *keyboard* trap above
-  is a separate mechanism and is wired.)
+- **No full SCREEN-READER trap on Android.** iOS gets `accessibilityViewIsModal`; Android has no
+  JS-level way to mark background siblings hidden from inside this component, so a reader trap
+  there needs the app root to cooperate. The web *keyboard* trap above is separate, and is wired.
 - **The web keyboard trap only cycles Tab.** It does not pull focus back if focus leaves the panel
   by a click outside or a programmatic `focus()` — that needs sentinel nodes at the panel's edges,
   a component-level change nobody has needed yet. Inherited from `core/a11y/keyboard`.
 - **No built-in scrolling.** The panel caps at `maxHeight: "92%"` but does not wrap `children` in a
   `ScrollView` — forcing one risks nested-`VirtualizedList` warnings if a consumer's content is
   already scrollable. Tall content is the consumer's own `ScrollView`/`FlatList` to add.
-- No close ("×") button — not in this module's prop contract; dismissal is backdrop press, Android
-  back, or iOS VoiceOver's escape gesture. A consumer wanting an explicit close control renders its
-  own `Button` (`icon="x"`) inside `children`.
+- **`isLoading` was visual-only before this release** — the spinner scrim rendered with
+  `pointerEvents: "none"`, so taps reached the footer underneath and a consumer could fire a submit
+  twice. A consumer pinned to an older version must still disable its own footer buttons.
 
 ## Performance
 
-Both `Modal` and `ModalPortalProvider` are wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). `Modal.tsx` has no `.map()` lists and no library child components (only RN host elements); `ModalPortalProvider` just passes `container`/`children` into a `Context.Provider` — nothing to memoize in either.
+Both `Modal` and `ModalPortalProvider` are wrapped in `React.memo`. Neither has a `.map()` list or
+a memoizable child — `ModalPortalProvider` only passes `container`/`children` into a provider.
 
-## Modernization (v1.0.7)
+## Motion
 
-- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
-- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
-- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.
+One `enter` shared value drives panel slide+fade and scrim opacity together on both branches, so
+they are a single gesture; `MODAL_BACKDROP` takes its alpha from `MOTION_TRANSFORM.scrimOpacity`.
+The inner content layer additionally carries `FadeInDown`/`FadeOut`/`LinearTransition`, each with
+`ReduceMotion.System`.

package/lib/module/modules/modal/Modal.js

@@ -33,110 +33,231 @@
  * which is where all three silently went missing.
  */
 
-import { memo, useContext, useEffect, useMemo, useRef } from "react";
-import { Animated, Modal as RNModal, Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import { memo, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { Modal as RNModal, Platform, Pressable, StyleSheet, View } from "react-native";
+import Reanimated, { FadeInDown, FadeOut, interpolate, LinearTransition, ReduceMotion, useAnimatedStyle } from "react-native-reanimated";
 import { useDismissOnEscape, useFocusTrap } from "../../core/a11y/keyboard";
-import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { renderNodeSlot } from "../../core/slot/index.js";
+import { MOTION_TRANSFORM, useMotion, useAnimatedValue } from "../../core/motion/index.js";
+import { withAlpha } from "../../core/gradient/index.js";
+import { elevation, floatingBackground, floatingSurfaceStyle, highlight } from "../../theme/platform/index.js";
+import { elevation as elevationTokens } from "../../theme/tokens/primitives/index.js";
 import { useTheme } from "../../theme/hooks.js";
+import { Button } from "../button/index.js";
+import { Spinner } from "../spinner/index.js";
+import { Heading, Text } from "../text/index.js";
 import { ModalPortalContext } from "./ModalPortalContext.js";
 import { renderWebPortal } from "./renderWebPortal";
-import { modalOverlayStructure, modalPanelStructure, resolveModalAnimationType, resolveModalPanelColors } from "./Modal.variants.js";
+import { modalOverlayStructure, modalPanelStructure, resolveModalAnimationType } from "./Modal.variants.js";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-// Decorative dismiss scrim behind the panel — a design constant, not a role token: it is neither
-// text nor an interactive boundary, so WCAG's contrast minimums don't apply to it. Same
-// justification as Button's PRESS_SCRIM_DARK/LIGHT and Select's BACKDROP_SCRIM.
-const MODAL_BACKDROP = "#00000080";
+// Decorative dismiss scrim, not a role token — same reasoning Button's PRESS_SCRIM and Select's
+// BACKDROP_SCRIM record. Opacity is the shared `scrimOpacity` knob, not a locally-guessed hex.
+const MODAL_BACKDROP = withAlpha("#000000", MOTION_TRANSFORM.scrimOpacity);
 export const Modal = /*#__PURE__*/memo(function Modal({
   visible,
   onRequestClose,
   title,
+  subtitle,
   children,
+  footer,
+  isLoading = false,
+  hideCloseButton = true,
   size = "md",
   testID
 }) {
   const theme = useTheme();
   const motion = useMotion();
-  const panelColors = useMemo(() => resolveModalPanelColors(theme.colors), [theme.colors]);
   const portalContainer = useContext(ModalPortalContext);
   const panelRef = useRef(null);
   const portalled = Platform.OS === "web" && portalContainer != null;
   useDismissOnEscape(portalled && visible, onRequestClose);
   useFocusTrap(panelRef, portalled && visible);
+
+  // `mounted` only gates the web-portal render below — the RNModal branch keeps handing `visible`
+  // straight to RN's own <Modal>, which still owns that surface's native fade in and out.
+  const [mounted, setMounted] = useState(visible);
+  const mountedRef = useRef(mounted);
+  mountedRef.current = mounted;
   const enter = useAnimatedValue(visible ? 1 : 0);
-  const entering = useRef(null);
+  const running = useRef(null);
+  const offsetY = motion.transform.offsetY;
+  const unmountTimer = useRef(null);
   useEffect(() => {
-    entering.current?.stop();
-    if (!visible) {
-      enter.setValue(0);
+    const clearUnmount = () => {
+      if (unmountTimer.current !== null) {
+        clearTimeout(unmountTimer.current);
+        unmountTimer.current = null;
+      }
+    };
+    running.current?.stop();
+    clearUnmount();
+    if (visible) {
+      setMounted(true);
+      if (!motion.enabled) {
+        enter.value = 1;
+        return;
+      }
+      enter.value = 0;
+      running.current = motion.timing(enter, 1, {
+        easing: "decelerate"
+      });
+      running.current.start();
       return;
     }
-    if (!motion.enabled) {
-      enter.setValue(1);
+    if (!mountedRef.current) return;
+    const exitMs = motion.duration("fast");
+    if (!motion.enabled || exitMs === 0) {
+      enter.value = 0;
+      setMounted(false);
       return;
     }
-    enter.setValue(0);
-    entering.current = motion.timing(enter, 1, {
-      easing: "decelerate"
+    running.current = motion.timing(enter, 0, {
+      duration: "fast",
+      easing: "accelerate"
     });
-    entering.current.start();
+    running.current.start();
+    unmountTimer.current = setTimeout(() => {
+      unmountTimer.current = null;
+      setMounted(false);
+    }, exitMs);
+    return clearUnmount;
   }, [visible, motion, enter]);
-  useEffect(() => () => entering.current?.stop(), []);
-  const panelStyle = useMemo(() => [modalPanelStructure(theme, {
+  useEffect(() => () => {
+    running.current?.stop();
+    if (unmountTimer.current !== null) clearTimeout(unmountTimer.current);
+  }, []);
+  const floatingStyle = useMemo(() => {
+    highlight("subtle", theme.mode);
+    elevation(elevationTokens.lg);
+    void theme.elevatedSurfaces;
+    return {
+      backgroundColor: floatingBackground(theme, "lg"),
+      ...floatingSurfaceStyle(theme, "lg")
+    };
+  }, [theme]);
+  const panelStaticStyle = useMemo(() => [modalPanelStructure(theme, {
     size
-  }), {
-    backgroundColor: panelColors.background,
+  }), floatingStyle], [theme, size, floatingStyle]);
+  const panelAnimatedStyle = useAnimatedStyle(() => ({
+    opacity: enter.value,
     transform: [{
-      translateY: enter.interpolate({
-        inputRange: [0, 1],
-        outputRange: [motion.transform.offsetY, 0]
-      })
+      translateY: interpolate(enter.value, [0, 1], [offsetY, 0])
     }]
-  }], [theme, size, panelColors.background, enter, motion.transform.offsetY]);
-  const titleStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.semibold), {
-    fontSize: theme.fontSizes.lg,
-    color: panelColors.title,
-    marginBottom: theme.space[3]
-  }], [theme, panelColors.title]);
+  }));
+  const backdropAnimatedStyle = useAnimatedStyle(() => ({
+    opacity: enter.value
+  }));
+  const panelSlotTextStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    color: theme.colors.fg.default,
+    fontSize: theme.fontSizes.md
+  }], [theme]);
+  const titleBlock = title !== undefined || !hideCloseButton ? /*#__PURE__*/_jsxs(View, {
+    style: {
+      flexDirection: "row",
+      alignItems: "flex-start",
+      justifyContent: "space-between",
+      gap: theme.space[2],
+      marginBottom: theme.space[3]
+    },
+    children: [/*#__PURE__*/_jsxs(View, {
+      style: {
+        flex: 1,
+        gap: theme.space[1]
+      },
+      children: [title !== undefined ? /*#__PURE__*/_jsx(Heading, {
+        variant: "h3",
+        children: title
+      }) : null, subtitle !== undefined ? /*#__PURE__*/_jsx(Text, {
+        variant: "body-sm",
+        color: "muted",
+        children: subtitle
+      }) : null]
+    }), !hideCloseButton ? /*#__PURE__*/_jsx(Button, {
+      variant: "ghost",
+      icon: "x",
+      accessibilityLabel: "Close",
+      onPress: onRequestClose,
+      testID: testID ? `${testID}-close` : undefined
+    }) : null]
+  }) : subtitle !== undefined ? /*#__PURE__*/_jsx(Text, {
+    variant: "body-sm",
+    color: "muted",
+    style: {
+      marginBottom: theme.space[3]
+    },
+    children: subtitle
+  }) : null;
   const overlay = /*#__PURE__*/_jsxs(_Fragment, {
     children: [/*#__PURE__*/_jsx(Pressable, {
       testID: testID ? `${testID}-backdrop` : undefined,
       accessible: false,
       tabIndex: -1,
-      style: styles.backdrop,
-      onPress: onRequestClose
+      style: StyleSheet.absoluteFill,
+      onPress: onRequestClose,
+      children: /*#__PURE__*/_jsx(Reanimated.View, {
+        style: [styles.backdrop, backdropAnimatedStyle, {
+          pointerEvents: 'none'
+        }]
+      })
     }), /*#__PURE__*/_jsx(View, {
-      style: modalOverlayStructure(theme),
-      pointerEvents: "box-none",
-      children: /*#__PURE__*/_jsxs(Animated.View, {
+      style: [modalOverlayStructure(theme), {
+        pointerEvents: 'box-none'
+      }],
+      children: /*#__PURE__*/_jsx(Reanimated.View, {
         ref: panelRef,
         testID: testID ? `${testID}-panel` : undefined,
         accessibilityViewIsModal: true,
         onAccessibilityEscape: onRequestClose,
-        style: panelStyle,
-        children: [title !== undefined && /*#__PURE__*/_jsx(Text, {
-          accessibilityRole: "header",
-          style: titleStyle,
-          children: title
-        }), children]
+        style: [panelStaticStyle, panelAnimatedStyle],
+        children: /*#__PURE__*/_jsxs(Reanimated.View, {
+          entering: FadeInDown.springify().reduceMotion(ReduceMotion.System),
+          exiting: FadeOut.reduceMotion(ReduceMotion.System),
+          layout: LinearTransition.reduceMotion(ReduceMotion.System),
+          style: {
+            position: "relative"
+          },
+          children: [titleBlock, renderNodeSlot(children, panelSlotTextStyle), footer !== undefined ? /*#__PURE__*/_jsx(View, {
+            style: {
+              marginTop: theme.space[4],
+              gap: theme.space[2]
+            },
+            children: renderNodeSlot(footer, panelSlotTextStyle)
+          }) : null, isLoading ? /*#__PURE__*/_jsx(View, {
+            testID: testID ? `${testID}-loading-overlay` : undefined,
+            style: {
+              ...StyleSheet.absoluteFill,
+              alignItems: "center",
+              justifyContent: "center",
+              backgroundColor: withAlpha(theme.colors.bg.surface, 0.72),
+              pointerEvents: 'auto'
+            },
+            children: /*#__PURE__*/_jsx(Spinner, {
+              testID: testID ? `${testID}-loading` : undefined
+            })
+          }) : null]
+        })
       })
     })]
   });
   if (portalled) {
-    if (!visible) return null;
+    if (!mounted) return null;
     // RN's own <Modal> supplies a `position: fixed`/full-screen ancestor for `overlay`'s children
     // to size against (see ModalPortalContext.ts) — reproduce just that sizing here (never touching
     // the shared `modalOverlayStructure`/`modalPanelStructure` resolvers the RNModal path below
     // still uses untouched) so the same tree fills `portalContainer`'s bounds instead of the
     // viewport.
     return renderWebPortal(/*#__PURE__*/_jsx(View, {
-      style: StyleSheet.absoluteFill,
-      pointerEvents: "box-none",
+      style: [StyleSheet.absoluteFill, {
+        pointerEvents: 'box-none'
+      }],
       children: overlay
     }), portalContainer);
   }
   return /*#__PURE__*/_jsx(RNModal, {
     visible: visible,
     transparent: true,
+    statusBarTranslucent: true,
+    navigationBarTranslucent: true,
     animationType: resolveModalAnimationType(!motion.enabled),
     onRequestClose: onRequestClose,
     children: overlay

package/lib/module/modules/modal/Modal.variants.js

@@ -69,8 +69,8 @@ export const modalPanelStructure = createThemedVariants(theme => ({
     width: "100%",
     maxHeight: "92%",
     borderRadius: theme.radii.lg,
-    padding: theme.space[5],
-    ...theme.elevation.lg
+    borderCurve: "continuous",
+    padding: theme.space[5]
   },
   variants: {
     size: {

package/lib/module/modules/modal/ModalPortalContext.js

@@ -1,25 +1,4 @@
 "use strict";
 
-/**
- * Web-only escape hatch for where Modal (and, via this same context, Select/Menu's option/action
- * sheets) portal their overlay content on `react-native-web`.
- *
- * `react-native-web`'s own `<Modal>` unconditionally portals to `document.body`
- * (`react-native-web/src/exports/Modal/ModalPortal.js` — `document.body.appendChild(...)`, then
- * `createPortal(children, elementRef.current)`; no `container`/`portalHost` prop exists to
- * override it, verified against the installed 0.21.2 source). That is correct for a full app, but
- * breaks visual containment inside a fixed-size preview frame (see `example/DeviceFrame.tsx`): the
- * overlay renders full-browser-viewport instead of clipped to the frame.
- *
- * Defaults to `null` — every existing consumer, native or web, reads `null` here and keeps
- * rendering through RN's own `<Modal>` exactly as before this context existed. A consumer opts in
- * via `ModalPortalProvider` (`./ModalPortalProvider`).
- *
- * Typed `unknown`, not a DOM type: this package has no `"dom"` lib entry (native has no DOM), so a
- * `HTMLElement`/`Element` annotation here would fail to compile. On web the value must be a real
- * DOM node capable of receiving `ReactDOM.createPortal` — `renderWebPortal.web.ts` is the one place
- * that actually dereferences it, and does the environment-appropriate cast there.
- */
-import { createContext } from "react";
-export const ModalPortalContext = /*#__PURE__*/createContext(null);
+export { ModalPortalContext } from "../../core/overlay/ModalPortalContext.js";
 //# sourceMappingURL=ModalPortalContext.js.map

package/lib/module/modules/modal/ModalPortalProvider.js

@@ -1,7 +1,7 @@
 "use strict";
 
 import { memo } from "react";
-import { ModalPortalContext } from "./ModalPortalContext.js";
+import { ModalPortalContext } from "../../core/overlay/ModalPortalContext.js";
 import { jsx as _jsx } from "react/jsx-runtime";
 /**
  * Opts a subtree into containing its Modal / AlertDialog / Select / Menu overlays inside

package/lib/module/modules/modal/ModalPortalProviderProps.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=ModalPortalProviderProps.js.map

package/lib/module/modules/modal/ModalProps.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=ModalProps.js.map

package/lib/module/modules/modal/renderWebPortal.js

@@ -1,18 +1,4 @@
 "use strict";
 
-/**
- * Native/default counterpart of `renderWebPortal.web.ts`. There is no DOM to portal into outside a
- * web environment, so this always returns `null` — the caller (Modal/Select/Menu) then falls back
- * to rendering through RN's own `<Modal>`, exactly as it did before this mechanism existed.
- *
- * Exists so the bare specifier `import { renderWebPortal } from "./renderWebPortal"` has a
- * same-shaped default to resolve to on every platform except an actual web bundle: Metro's
- * platform-extension resolution picks `renderWebPortal.web.ts` only when bundling for web, and
- * falls back to THIS file everywhere else (iOS, Android, and Jest — Jest's `react-native` preset
- * haste config has no `web` platform, so it also always resolves here). `react-dom` therefore never
- * enters a native dependency graph.
- */
-export function renderWebPortal(_children, _container) {
-  return null;
-}
+export { renderWebPortal } from "../../core/overlay/renderWebPortal";
 //# sourceMappingURL=renderWebPortal.js.map

package/lib/module/modules/modal/renderWebPortal.web.js

@@ -1,24 +1,4 @@
 "use strict";
 
-import { createPortal } from "react-dom";
-/**
- * Web implementation: portals `children` into `container` via `ReactDOM.createPortal`, bypassing
- * `react-native-web`'s own `<Modal>` (which always portals to `document.body` — see
- * `ModalPortalContext.ts`). Returns `null` when `container` is nullish so the caller falls back to
- * the default `<Modal>` path.
- *
- * `container` is cast from `unknown` to `Element` here — the one place this mechanism's `unknown`
- * portal-container contract gets a concrete DOM type, since only this file (Metro only ever
- * resolves it for an actual web bundle — see `renderWebPortal.ts`) has a real DOM environment to
- * assume. A caller that passes something that isn't really a DOM node fails at `createPortal`'s own
- * runtime, same as any other incorrect `ReactDOM.createPortal` call would.
- *
- * This module's exported signature stays identical to `renderWebPortal.ts`'s (`ReactNode`,
- * `unknown` — never a `react-dom` type), so a consumer never needs `@types/react-dom` just because
- * they import `pixelize-native-library/modal`; that type dependency stays internal to this one file.
- */
-export function renderWebPortal(children, container) {
-  if (container == null) return null;
-  return /*#__PURE__*/createPortal(children, container);
-}
+export { renderWebPortal } from "../../core/overlay/renderWebPortal.web.js";
 //# sourceMappingURL=renderWebPortal.web.js.map

package/lib/module/modules/more-items/MODULE.md

@@ -34,6 +34,9 @@ Renders `null` when the count is ≤0 and there is no `triggerText` — nothing
 - **Touch target (WCAG 2.5.5 / 2.5.8)** — the trigger carries `minHeight: 44` (this library's
   floor). It is a standalone node with no neighbouring target to overlap, so the floor is real
   height via `minHeight`, not `hitSlop` expansion the way `Button`'s shorter sizes reach it.
+- **Android touch feedback** — the trigger carries `android_ripple` (`rippleColor(theme.mode)`,
+  `borderless: false`), gated on `Platform.OS === "android"`. The scrim `Pressable` gets none — it is
+  the same `accessible={false}` decoy described under Modal semantics below, not a real press target.
 - **Label in Name (WCAG 2.5.3)** — the accessible name is built to CONTAIN the visible text
   (`"${triggerText} +${count} more"`, or just `"+${count} more"` with no leading text), not a
   separately-worded `"${count} more items"`. Voice control says what it reads; the old name shared no