pixelize-native-library 1.2.1 → 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,76 +61,46 @@ 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>`.
-
-`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.
-
-`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.
+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.
 
 ## Patterns copied from Button / Select (the reference modules)
 
-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.
+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.
 
 ## Android edge-to-edge
 
@@ -145,31 +112,27 @@ solid white on open. Add both any time a new module renders its own RN `<Modal t
 
 ## 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.
-
-## Modernization (v1.0.7)
+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.
 
-- 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.
+## Motion
 
-- **Round 2 visual** — radii retarget (`radii.md`/`lg`/`xl`/`full`), `borderCurve: continuous` on md+ corners; floating surfaces wire platform elevation/highlight where applicable.
-- **Round 5 motion** — dropped the ad hoc reanimated `FadeInDown`/`FadeOut` layer; the panel's own `enter` value now drives backdrop opacity too, so scrim fade and panel slide+fade are one gesture on both the RNModal and web-portal paths. The portal branch now tracks `mounted` through a real timed exit instead of unmounting instantly. `MODAL_BACKDROP`'s opacity comes from `MOTION_TRANSFORM.scrimOpacity`.
+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

@@ -34,14 +34,18 @@
  */
 
 import { memo, useContext, useEffect, useMemo, useRef, useState } from "react";
-import { Animated, Modal as RNModal, Platform, Pressable, StyleSheet, View } from "react-native";
+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 { MOTION_TRANSFORM, 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 { Heading } from "../text/index.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 } from "./Modal.variants.js";
@@ -53,7 +57,11 @@ export const Modal = /*#__PURE__*/memo(function Modal({
   visible,
   onRequestClose,
   title,
+  subtitle,
   children,
+  footer,
+  isLoading = false,
+  hideCloseButton = true,
   size = "md",
   testID
 }) {
@@ -72,6 +80,7 @@ export const Modal = /*#__PURE__*/memo(function Modal({
   mountedRef.current = mounted;
   const enter = useAnimatedValue(visible ? 1 : 0);
   const running = useRef(null);
+  const offsetY = motion.transform.offsetY;
   const unmountTimer = useRef(null);
   useEffect(() => {
     const clearUnmount = () => {
@@ -85,10 +94,10 @@ export const Modal = /*#__PURE__*/memo(function Modal({
     if (visible) {
       setMounted(true);
       if (!motion.enabled) {
-        enter.setValue(1);
+        enter.value = 1;
         return;
       }
-      enter.setValue(0);
+      enter.value = 0;
       running.current = motion.timing(enter, 1, {
         easing: "decelerate"
       });
@@ -98,7 +107,7 @@ export const Modal = /*#__PURE__*/memo(function Modal({
     if (!mountedRef.current) return;
     const exitMs = motion.duration("fast");
     if (!motion.enabled || exitMs === 0) {
-      enter.setValue(0);
+      enter.value = 0;
       setMounted(false);
       return;
     }
@@ -126,26 +135,57 @@ export const Modal = /*#__PURE__*/memo(function Modal({
       ...floatingSurfaceStyle(theme, "lg")
     };
   }, [theme]);
-  const panelStyle = useMemo(() => [modalPanelStructure(theme, {
+  const panelStaticStyle = useMemo(() => [modalPanelStructure(theme, {
     size
-  }), floatingStyle, {
-    opacity: enter,
+  }), 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, floatingStyle, enter, motion.transform.offsetY]);
-  const backdropStyle = useMemo(() => [styles.backdrop, {
-    opacity: enter
-  }], [enter]);
-  const titleBlock = title !== undefined ? /*#__PURE__*/_jsx(Heading, {
-    variant: "h3",
+  }));
+  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: title
+    children: subtitle
   }) : null;
   const overlay = /*#__PURE__*/_jsxs(_Fragment, {
     children: [/*#__PURE__*/_jsx(Pressable, {
@@ -154,20 +194,48 @@ export const Modal = /*#__PURE__*/memo(function Modal({
       tabIndex: -1,
       style: StyleSheet.absoluteFill,
       onPress: onRequestClose,
-      children: /*#__PURE__*/_jsx(Animated.View, {
-        pointerEvents: "none",
-        style: backdropStyle
+      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: [titleBlock, 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]
+        })
       })
     })]
   });
@@ -179,8 +247,9 @@ export const Modal = /*#__PURE__*/memo(function Modal({
     // 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);
   }

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

@@ -73,5 +73,3 @@ Renders `null` when the count is ≤0 and there is no `triggerText` — nothing
 
 - Rows are display-only — no press/selection. A selectable overflow list would be a different
   component (`Select`/`Menu`), not a prop added here.
-
-- **Round 2 visual** — radii retarget (`radii.md`/`lg`/`xl`/`full`), `borderCurve: continuous` on md+ corners; floating surfaces wire platform elevation/highlight where applicable.

package/lib/module/modules/more-items/MoreItems.js

@@ -5,14 +5,16 @@
  */
 
 import { memo, useCallback, useMemo, useState } from "react";
-import { Animated, Modal, Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import { Modal, Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import Reanimated from "react-native-reanimated";
 import { VirtualList } from "../../core/list/index.js";
-import { useEnterExit, usePressMotion } from "../../core/motion/index.js";
+import { withAlpha } from "../../core/gradient/index.js";
+import { MOTION_TRANSFORM, useEnterExit, usePressMotion } from "../../core/motion/index.js";
 import { useTheme } from "../../theme/hooks.js";
 import { rippleColor } from "../../theme/platform/stateLayer.native.js";
 import { moreItemsBadgeStructure, moreItemsDotStructure, moreItemsOverlayStructure, moreItemsRowStructure, moreItemsSheetStructure, moreItemsTriggerContentStructure, moreItemsTriggerStructure, resolveMoreItemsCount, resolveMoreItemsDotColor } from "./MoreItems.variants.js";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-const BACKDROP = "#00000080";
+const BACKDROP = withAlpha("#000000", MOTION_TRANSFORM.scrimOpacity);
 const MoreItemsRow = /*#__PURE__*/memo(function MoreItemsRow({
   item,
   theme,
@@ -109,7 +111,7 @@ export const MoreItems = /*#__PURE__*/memo(function MoreItems({
       onPressOut: press.onPressOut,
       android_ripple: androidRipple,
       style: triggerStyle,
-      children: /*#__PURE__*/_jsxs(Animated.View, {
+      children: /*#__PURE__*/_jsxs(Reanimated.View, {
         style: [triggerContentStructure, press.style],
         children: [triggerText !== undefined && /*#__PURE__*/_jsx(Text, {
           numberOfLines: 1,
@@ -137,9 +139,10 @@ export const MoreItems = /*#__PURE__*/memo(function MoreItems({
           style: styles.backdrop
         })
       }), /*#__PURE__*/_jsx(View, {
-        style: overlayStructure,
-        pointerEvents: "box-none",
-        children: /*#__PURE__*/_jsx(Animated.View, {
+        style: [overlayStructure, {
+          pointerEvents: 'box-none'
+        }],
+        children: /*#__PURE__*/_jsx(Reanimated.View, {
           testID: testID ? `${testID}-sheet` : undefined
           // The modal-semantics pair every other overlay in this library gives its panel, plus a
           // name: the sheet had neither, so VoiceOver could wander into the row behind it.

package/lib/module/modules/more-items/MoreItems.variants.js

@@ -1,7 +1,9 @@
 "use strict";
 
+import { MIN_TOUCH_TARGET } from "../../core/a11y/touchTarget.js";
 import { createThemedVariants } from "../../core/style/index.js";
 import { resolveBadgeTone } from "../badge/Badge.variants.js";
+export { MIN_TOUCH_TARGET };
 export function resolveMoreItemsCount(moreCount, itemsLength) {
   return moreCount ?? itemsLength;
 }
@@ -18,7 +20,6 @@ export const MORE_ITEMS_SHEET_MAX_HEIGHT = 280;
  * neighbouring target to overlap, and a slop-expanded rectangle would still leave a ~22dp visual
  * control that misses under an unsteady finger.
  */
-export const MIN_TOUCH_TARGET = 44;
 export const moreItemsTriggerStructure = createThemedVariants(_theme => ({
   base: {
     maxWidth: 250,

package/lib/module/modules/more-items/MoreItemsProps.js

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