pixelize-native-library 1.0.7 → 1.2.0

package/lib/module/modules/menu/Menu.js

@@ -1,39 +1,84 @@
 "use strict";
 
 /**
- * Menu — a small anchored action list opened from a caller-supplied trigger. Unlike Select (whose
- * open/closed state is a `value`/`onValueChange` pair the caller owns), Menu is self-contained: a
- * transient action list manages its own visibility, closing itself after every dismissal path.
+ * Menu — a small anchored action list opened from a caller-supplied trigger.
  *
- * The trigger is composed via `React.cloneElement` — never `{...rest}` — injecting only `onPress`,
- * chained after any handler the trigger already defined (the same "merge, never clobber" technique
- * Tooltip uses for its child). The dropdown itself is React Native's OWN `Modal`, imported directly
- * from `"react-native"` on purpose: this module must never depend on the library's own `Modal`
- * COMPONENT — this library's own `Modal` (built in parallel elsewhere) is for persistent app
- * dialogs with a title/children contract, not a quick transient overlay — the same distinction
- * Select already draws for its own option list.
+ * The sheet is the menu itself: it carries `accessibilityRole="menu"` over the `menuitem` rows, and
+ * the `accessibilityViewIsModal` / `onAccessibilityEscape` pair `Modal.tsx` establishes — set on the
+ * sheet node itself so the web-portal path (which has no RN `<Modal>`) is modal to assistive tech too.
  *
- * The one deliberate exception is the web portal mechanism: `ModalPortalContext`/`renderWebPortal`
- * are a plain context + a stateless helper with no React-tree footprint of their own (not the
- * `Modal` component), so Menu reads the same ones `Modal.tsx` and `Select.tsx` read to stay
- * consistent once a consumer opts in via `ModalPortalProvider` — see `../modal/ModalPortalContext.ts`.
+ * Motion split, same as this library's own `Modal`: RN `<Modal>`'s native `animationType` owns the
+ * scrim fade (in AND out, with no JS timer, so a selection closes the menu on the same tick it
+ * always did), and the global motion system (`core/motion`) owns the sheet's own scale + lift on
+ * enter. The sheet is centered rather than anchored (see MODULE.md), so it scales from its centre.
  */
 
-import { cloneElement, memo, useCallback, useContext, useState } from "react";
-import { Modal, Platform, Pressable, ScrollView, StyleSheet, Text, View } from "react-native";
-import { useReducedMotion } from "../../core/a11y/index.js";
+import { cloneElement, memo, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { Animated, Modal, Platform, Pressable, ScrollView, StyleSheet, Text, View } from "react-native";
+import { focusItemProps, useDismissOnEscape, useFocusTrap, useRovingKeys, useSpaceActivation } from "../../core/a11y/keyboard";
+import { useMotion } from "../../core/motion/index.js";
 import { Icon } from "../../core/icon/index.js";
-import { useTheme } from "../../theme/index.js";
+import { VirtualList } from "../../core/list/index.js";
+import { useTheme } from "../../theme/hooks.js";
 import { ModalPortalContext } from "../modal/ModalPortalContext.js";
 import { renderWebPortal } from "../modal/renderWebPortal";
-import { MENU_ROW_ICON_SIZE, menuOverlayStructure, menuRowStructure, menuSheetStructure, resolveMenuItemColor } from "./Menu.variants.js";
-
-/** The subset of props Menu reads from / injects into its trigger child. */
+import { MENU_ROW_ICON_SIZE, MENU_ROW_MIN_HEIGHT, menuOverlayStructure, menuRowStructure, menuSheetStructure, resolveMenuItemColor, resolveMenuRowPressedBackground } from "./Menu.variants.js";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const VIRTUALIZE_THRESHOLD = 15;
 const ICON_STROKE = 2;
-// Decorative dismiss scrim behind the sheet — 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.
 const BACKDROP_SCRIM = "#00000099";
+const MenuRow = /*#__PURE__*/memo(function MenuRow({
+  item,
+  index,
+  tabIndex,
+  theme,
+  pressedRowBg,
+  onSelect,
+  testID
+}) {
+  const color = resolveMenuItemColor(theme.colors, item.tone ?? "default");
+  const handlePress = useCallback(() => onSelect(item), [onSelect, item]);
+  const rowRef = useRef(null);
+  const active = tabIndex === 0;
+
+  // The tabindex alone only names the tab stop — focus has to follow the arrows too, or the focus
+  // trap's Tab handler sees a focused row that is no longer tabbable and lets Tab leave the menu.
+  useEffect(() => {
+    if (!active || Platform.OS !== "web") return;
+    rowRef.current?.focus();
+  }, [active]);
+
+  // `menuitem` is not `button`, so RNW never presses on Space — see `core/a11y/keyboard.web.ts`.
+  useSpaceActivation(rowRef, handlePress);
+  const rowStyle = useCallback(({
+    pressed
+  }) => [menuRowStructure(theme), pressed && {
+    backgroundColor: pressedRowBg
+  }], [theme, pressedRowBg]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    flex: 1,
+    fontSize: theme.fontSizes.md,
+    color
+  }], [theme, color]);
+  return /*#__PURE__*/_jsxs(Pressable, {
+    ref: rowRef,
+    testID: testID ? `${testID}-item-${index}` : undefined,
+    accessibilityRole: "menuitem",
+    tabIndex: tabIndex,
+    onPress: handlePress,
+    style: rowStyle,
+    children: [item.icon !== undefined && /*#__PURE__*/_jsx(Icon, {
+      name: item.icon,
+      size: MENU_ROW_ICON_SIZE,
+      color: color,
+      strokeWidth: ICON_STROKE
+    }), /*#__PURE__*/_jsx(Text, {
+      numberOfLines: 1,
+      style: labelStyle,
+      children: item.label
+    })]
+  });
+});
 export const Menu = /*#__PURE__*/memo(function Menu({
   trigger,
   items,
@@ -41,21 +86,54 @@ export const Menu = /*#__PURE__*/memo(function Menu({
   testID
 }) {
   const theme = useTheme();
-  const reducedMotion = useReducedMotion();
+  const motion = useMotion();
   const portalContainer = useContext(ModalPortalContext);
   const [open, setOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const sheetRef = useRef(null);
+  const enter = useRef(new Animated.Value(0)).current;
+  const entering = useRef(null);
+  useEffect(() => {
+    entering.current?.stop();
+    if (!open) {
+      enter.setValue(0);
+      return;
+    }
+    if (!motion.enabled) {
+      enter.setValue(1);
+      return;
+    }
+    enter.setValue(0);
+    entering.current = motion.timing(enter, 1, {
+      duration: "fast",
+      easing: "decelerate"
+    });
+    entering.current.start();
+  }, [open, motion, enter]);
+  useEffect(() => () => entering.current?.stop(), []);
   const openMenu = useCallback(() => {
     if (disabled) return;
+    setActiveIndex(0);
     setOpen(true);
   }, [disabled]);
   const closeMenu = useCallback(() => setOpen(false), []);
-  const selectItem = item => {
+  const selectItem = useCallback(item => {
     closeMenu();
     item.onPress();
-  };
+  }, [closeMenu]);
+  const typeaheadLabels = useMemo(() => items.map(item => item.label), [items]);
 
-  // Passed to `trigger` — a consumer-supplied CHILD component (typically this library's own
-  // Button) — via cloneElement, so it is memoized like any other child-bound callback.
+  // Keyboard (web only — every hook below is a no-op on native, see `core/a11y/keyboard.ts`).
+  // No `onActivate`: RNW already presses a `menuitem` on Enter, and each row's own
+  // `useSpaceActivation` owns Space — passing it here would activate the item twice.
+  useDismissOnEscape(open, closeMenu);
+  useFocusTrap(sheetRef, open);
+  useRovingKeys(sheetRef, open, {
+    count: items.length,
+    activeIndex,
+    onActiveIndexChange: setActiveIndex,
+    typeaheadLabels
+  });
   const handleTriggerPress = useCallback(event => {
     trigger.props.onPress?.(event);
     openMenu();
@@ -63,53 +141,78 @@ export const Menu = /*#__PURE__*/memo(function Menu({
   const clonedTrigger = /*#__PURE__*/cloneElement(trigger, {
     onPress: handleTriggerPress
   });
-  const sheet = /*#__PURE__*/_jsxs(_Fragment, {
+  const pressedRowBg = useMemo(() => resolveMenuRowPressedBackground(theme.colors), [theme.colors]);
+  const keyExtractor = useCallback((item, index) => `${item.label}-${index}`, []);
+  const renderItem = useCallback(({
+    item,
+    index
+  }) => /*#__PURE__*/_jsx(MenuRow, {
+    item: item,
+    index: index,
+    tabIndex: focusItemProps(index, activeIndex).tabIndex,
+    theme: theme,
+    pressedRowBg: pressedRowBg,
+    onSelect: selectItem,
+    testID: testID
+  }), [activeIndex, theme, pressedRowBg, selectItem, testID]);
+  const sheetStyle = useMemo(() => [menuSheetStructure(theme), {
+    backgroundColor: theme.colors.bg.surface,
+    transform: [{
+      scale: enter.interpolate({
+        inputRange: [0, 1],
+        outputRange: [motion.transform.pressScale, 1]
+      })
+    }, {
+      translateY: enter.interpolate({
+        inputRange: [0, 1],
+        outputRange: [motion.transform.offsetY, 0]
+      })
+    }]
+  }], [theme, enter, motion.transform.pressScale, motion.transform.offsetY]);
+
+  // Built only while open: a closed Menu must not materialize one element per item on every render
+  // of the screen that hosts it.
+  const sheet = open ? /*#__PURE__*/_jsxs(_Fragment, {
     children: [/*#__PURE__*/_jsx(Pressable, {
       testID: testID ? `${testID}-backdrop` : undefined,
       accessible: false,
-      style: [StyleSheet.absoluteFill, {
-        backgroundColor: BACKDROP_SCRIM
-      }],
+      tabIndex: -1,
+      style: styles.backdrop,
       onPress: closeMenu
     }), /*#__PURE__*/_jsx(View, {
       style: menuOverlayStructure(theme),
       pointerEvents: "box-none",
-      children: /*#__PURE__*/_jsx(View, {
-        style: [menuSheetStructure(theme), {
-          backgroundColor: theme.colors.bg.surface
-        }],
-        children: /*#__PURE__*/_jsx(ScrollView, {
+      children: /*#__PURE__*/_jsx(Animated.View, {
+        ref: sheetRef,
+        testID: testID ? `${testID}-sheet` : undefined
+        // The container role the `menuitem` rows below need, plus the modal semantics every other
+        // overlay in this library gives its panel. Declared HERE, before the portal branch, so the
+        // web-portal path — which renders no RN `<Modal>` at all — inherits them too.
+        ,
+        accessibilityRole: "menu",
+        accessibilityViewIsModal: true,
+        onAccessibilityEscape: closeMenu,
+        style: sheetStyle,
+        children: items.length >= VIRTUALIZE_THRESHOLD ? /*#__PURE__*/_jsx(VirtualList, {
+          data: items,
+          keyExtractor: keyExtractor,
+          renderItem: renderItem,
+          itemHeight: MENU_ROW_MIN_HEIGHT
+        }) : /*#__PURE__*/_jsx(ScrollView, {
           bounces: false,
-          children: items.map((item, index) => {
-            const color = resolveMenuItemColor(theme.colors, item.tone ?? "default");
-            return /*#__PURE__*/_jsxs(Pressable, {
-              testID: testID ? `${testID}-item-${index}` : undefined,
-              accessibilityRole: "menuitem",
-              onPress: () => selectItem(item),
-              style: menuRowStructure(theme),
-              children: [item.icon !== undefined && /*#__PURE__*/_jsx(Icon, {
-                name: item.icon,
-                size: MENU_ROW_ICON_SIZE,
-                color: color,
-                strokeWidth: ICON_STROKE
-              }), /*#__PURE__*/_jsx(Text, {
-                numberOfLines: 1,
-                style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-                  flex: 1,
-                  fontSize: theme.fontSizes.md,
-                  color
-                }],
-                children: item.label
-              })]
-            }, `${item.label}-${index}`);
-          })
+          children: items.map((item, index) => /*#__PURE__*/_jsx(MenuRow, {
+            item: item,
+            index: index,
+            tabIndex: focusItemProps(index, activeIndex).tabIndex,
+            theme: theme,
+            pressedRowBg: pressedRowBg,
+            onSelect: selectItem,
+            testID: testID
+          }, `${item.label}-${index}`))
         })
       })
     })]
-  });
-
-  // Web portal opt-in — see Modal.tsx's identical branch + ModalPortalContext.ts. Every other case
-  // (native, or web with no ModalPortalProvider) renders through RN's own <Modal> below, unchanged.
+  }) : null;
   const menu = Platform.OS === "web" && portalContainer != null ? open ? renderWebPortal(/*#__PURE__*/_jsx(View, {
     style: StyleSheet.absoluteFill,
     pointerEvents: "box-none",
@@ -117,7 +220,7 @@ export const Menu = /*#__PURE__*/memo(function Menu({
   }), portalContainer) : null : /*#__PURE__*/_jsx(Modal, {
     visible: open,
     transparent: true,
-    animationType: reducedMotion ? "none" : "fade",
+    animationType: motion.enabled ? "fade" : "none",
     onRequestClose: closeMenu,
     children: sheet
   });
@@ -125,4 +228,10 @@ export const Menu = /*#__PURE__*/memo(function Menu({
     children: [clonedTrigger, menu]
   });
 });
+const styles = StyleSheet.create({
+  backdrop: {
+    ...StyleSheet.absoluteFill,
+    backgroundColor: BACKDROP_SCRIM
+  }
+});
 //# sourceMappingURL=Menu.js.map

package/lib/module/modules/menu/Menu.variants.js

@@ -39,6 +39,16 @@ export function resolveMenuItemColor(colors, tone) {
   }
 }
 
+/**
+ * A row's background while pressed — `bg.sunken`, not `bg.hover`: same class of fix `Button`'s
+ * "neutral" tone and `RadioGroup`/`Accordion` document (the saturated `hover` mid-tone risks
+ * dropping a tinted label below 4.5:1; the pale `sunken` tint doesn't). One background for every
+ * tone: `default` and `danger` labels are both measured against it in `Menu.test.ts`.
+ */
+export function resolveMenuRowPressedBackground(colors) {
+  return colors.bg.sunken;
+}
+
 /**
  * Structural styles only — layout, padding, radius, border WIDTH. No colours (those are resolved
  * from `RoleColors` and applied inline), so this compiles once per theme identity via the themed

package/lib/module/modules/message-bubble/MODULE.md

@@ -0,0 +1,38 @@
+# message-bubble/
+
+Single chat bubble — `user` (accent) or `assistant` (surface + border). Plain `content` string.
+
+## Motion contract
+
+**No motion at all — this component animates nothing, on any tier.** It is a list cell (`core/motion/
+MODULE.md` rule 5: no per-row motion that runs during scroll), so it renders its final state on its
+first frame, exactly like `ListItem`.
+
+It used to play a decorative-gated `opacity` + `translateY` enter, guarded by an `entered` ref so it
+ran "at most once per mount". That property was true and beside the point: `FlatList` unmounts and
+remounts cells as they leave and re-enter its window, so the ref reset and **every bubble scrolled
+back into view faded in again** — per-row motion, mid-scroll, on the thread a chat screen can least
+afford it. `__tests__/MessageBubble.motion.test.tsx` now pins the absence of that animation.
+
+## Known gap
+
+There is no longer a "new message arrived" reveal. Mounting cannot express it (see above); scoping
+it to genuinely new messages needs an id or timestamp high-water mark the consumer owns, which would
+mean a new prop — not added speculatively.
+
+## Accessibility contract (WCAG)
+
+- **1.3.1** — who sent a turn is otherwise carried only by `alignSelf` and the fill colour
+  (`MessageBubble.variants.ts` `variant` styles), neither of which reaches assistive tech. The
+  accessible label is `"<sender>: <content>"` ("You" / "Assistant"), resolved by
+  `resolveMessageBubbleAccessibility` from the existing `variant` prop — no new prop needed. The
+  visible bubble still renders `content` alone; only the announced name carries the sender.
+
+## Props
+
+| Prop | Type | Default |
+|------|------|---------|
+| `variant` | `user \| assistant` | `assistant` |
+| `content` | `string` | — |
+| `style` | `LayoutStyle` | — |
+| `testID` | `string` | — |

package/lib/module/modules/message-bubble/MessageBubble.js

@@ -0,0 +1,55 @@
+"use strict";
+
+/**
+ * MessageBubble — a single chat turn bubble. User variant uses accent fill; assistant uses surface
+ * card with border. Plain-text `content` only (rich assistant replies compose Markdown/RichText
+ * upstream).
+ *
+ * The accessible label names the sender ("You" / "Assistant") ahead of the content: alignment and
+ * fill colour are the only things that say who spoke, and neither reaches a screen reader.
+ *
+ * No mount animation, by rule 5 of `core/motion/MODULE.md`: bubbles are list cells, and `FlatList`
+ * unmounts and remounts them as they leave and re-enter its window — a "plays once per mount" enter
+ * therefore replays for every bubble scrolled back into view, which is exactly the per-row motion
+ * during scroll that rule forbids. A "new message arrived" reveal would have to be keyed off the
+ * message's own identity (an id/timestamp high-water mark the consumer owns), never off mounting.
+ */
+
+import { memo, useMemo } from "react";
+import { Text, View } from "react-native";
+import { useTheme } from "../../theme/hooks.js";
+import { messageBubbleStructure, resolveMessageBubbleAccessibility, resolveMessageBubbleColors } from "./MessageBubble.variants.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+export const MessageBubble = /*#__PURE__*/memo(function MessageBubble({
+  variant = "assistant",
+  content,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const colors = resolveMessageBubbleColors(theme.colors, variant);
+  const a11y = resolveMessageBubbleAccessibility(content, variant);
+  const bubbleStyle = useMemo(() => [messageBubbleStructure(theme, {
+    variant
+  }), {
+    backgroundColor: colors.background,
+    borderColor: colors.border
+  }, style], [theme, variant, colors.background, colors.border, style]);
+  const textStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize: theme.fontSizes.md,
+    lineHeight: theme.fontSizes.md * 1.45,
+    color: colors.text
+  }], [theme, colors.text]);
+  return /*#__PURE__*/_jsx(View, {
+    testID: testID,
+    accessible: a11y.accessible,
+    accessibilityRole: a11y.accessibilityRole,
+    accessibilityLabel: a11y.accessibilityLabel,
+    style: bubbleStyle,
+    children: /*#__PURE__*/_jsx(Text, {
+      style: textStyle,
+      children: content
+    })
+  });
+});
+//# sourceMappingURL=MessageBubble.js.map

package/lib/module/modules/message-bubble/MessageBubble.variants.js

@@ -0,0 +1,57 @@
+"use strict";
+
+import { createThemedVariants } from "../../core/style/index.js";
+export function resolveMessageBubbleColors(colors, variant) {
+  if (variant === "user") {
+    return {
+      background: colors.accent.solid,
+      text: colors.accent.onSolid
+    };
+  }
+  return {
+    background: colors.bg.surface,
+    text: colors.fg.default,
+    border: colors.border.default
+  };
+}
+export const messageBubbleStructure = createThemedVariants(theme => ({
+  base: {
+    maxWidth: "85%",
+    paddingHorizontal: theme.space[3],
+    paddingVertical: theme.space[2],
+    borderRadius: theme.radii.lg
+  },
+  variants: {
+    variant: {
+      user: {
+        alignSelf: "flex-end",
+        borderBottomRightRadius: theme.radii.sm
+      },
+      assistant: {
+        alignSelf: "flex-start",
+        borderBottomLeftRadius: theme.radii.sm,
+        borderWidth: theme.borderWidths.thin
+      }
+    }
+  },
+  defaultVariants: {
+    variant: "assistant"
+  }
+}));
+const SENDER = {
+  user: "You",
+  assistant: "Assistant"
+};
+
+/**
+ * Who sent a turn is carried only by `alignSelf` and the bubble fill on screen, so the label has to
+ * name the sender for it to reach assistive tech at all (WCAG 1.3.1).
+ */
+export function resolveMessageBubbleAccessibility(content, variant) {
+  return {
+    accessible: true,
+    accessibilityRole: "text",
+    accessibilityLabel: `${SENDER[variant]}: ${content}`
+  };
+}
+//# sourceMappingURL=MessageBubble.variants.js.map

package/lib/module/modules/message-bubble/index.js

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

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

@@ -20,6 +20,7 @@ VoiceOver's escape gesture via `onAccessibilityEscape`).
 | `__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. |
 
 ## Props
 
@@ -107,6 +108,21 @@ mechanism below.
 - `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.
+
 ## Patterns copied from Button / Select (the reference modules)
 
 1. **Structure vs colour split** — sizing/spacing/radius via `createThemedVariants`; colour
@@ -121,11 +137,15 @@ mechanism below.
 
 ## Known gaps
 
-- **No full focus trap.** iOS gets `accessibilityViewIsModal` (constrains VoiceOver to the panel).
-  Android has no JS-level equivalent for marking background siblings
+- **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
-  focus trap needs the app root to cooperate. Out of scope for v1.
+  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.)
+- **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.
@@ -136,3 +156,9 @@ mechanism below.
 ## 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)
+
+- 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.