pixelize-native-library 1.0.7 → 1.2.0

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

@@ -2,9 +2,8 @@
 
 `Drawer` is a hand-rolled bottom-sheet: a panel that slides up from the bottom edge over a
 translucent fading backdrop, presented in REACT NATIVE'S OWN `Modal` — the same "transient overlay,
-raw RN Modal" pattern `Select` already established for this library. It is NOT this library's own
-`../modal` (a persistent title/children dialog, centered, a different shape entirely) and it imports
-nothing from it.
+raw RN Modal" pattern `Select` already established. It is NOT this library's own `../modal` (a
+persistent title/children dialog, centered) and imports nothing from it.
 
 ## Files
 
@@ -15,6 +14,7 @@ nothing from it.
 | `index.ts` | Public surface: `Drawer`, `DrawerProps`. |
 | `__tests__/Drawer.test.ts` | Pure: reduced-motion contract, bottom-inset fallback, panel/grabber colour resolution (all brands × modes). |
 | `__tests__/Drawer.render.test.tsx` | Render: visibility, mount-through-exit-animation, dismissal paths, modal semantics, grabber a11y, reduced motion, and the web-portal opt-in branch (mocking `renderWebPortal`). |
+| `__tests__/Drawer.keyboard.test.tsx` | Keyboard avoidance: no listener while closed, subscribe/unsubscribe with `mounted`, the tween's duration source, and the reduce-motion snap. |
 
 ## Props
 
@@ -25,137 +25,109 @@ nothing from it.
 | `children` | `ReactNode` | Required. Arbitrary consumer content below the grabber. |
 | `testID` | `string` | Also seeds `${testID}-backdrop`, `${testID}-panel`, `${testID}-handle`. |
 
-No `style`/`containerStyle` prop — same precedent as this library's own `Modal` (also style-less):
-it's a full-screen transient overlay whose position is fixed by the component, not something an
-app's layout places.
+No `style`/`containerStyle` prop — same precedent as `Modal` (also style-less): a full-screen
+transient overlay whose position is fixed by the component, not something an app's layout places.
 
 ## Animation
 
-One `Animated.Value` (`progress`, 0 → 1) drives BOTH the panel's `translateY` (interpolated from the
-window's own height down to `0`) and the backdrop's `opacity`, so they move in lockstep. This is why
-the underlying RN `<Modal>` is always given `animationType="none"` — RN's native transition is a
-single discrete enum for the whole native surface; it can't also fade a separately-Animated backdrop
-in step with a custom slide, so this module owns the entire transition instead (same reasoning
-`Modal.tsx`'s reduced-motion note documents for its own native-vs-JS boundary, in reverse).
-
-`resolveDrawerAnimationDuration` (WCAG 2.3.3) collapses the duration to `0` under
-`useReducedMotion()` — an instant snap, never a frozen half-slid frame, same contract every other
-animated module in this catalogue holds.
-
-**Exit-animation lifecycle.** RN's `<Modal>` only actually hides its children once native dismissal
-completes or the component unmounts — flipping `visible` straight to the native `Modal`'s own
-`visible` prop would cut the exit slide/fade off before it plays. So Drawer keeps its own `mounted`
-state, distinct from the caller's `visible` prop: on close, the exit animation starts immediately and
-a plain `setTimeout` (matching `duration`, not the `Animated.timing` completion callback — that rides
-`requestAnimationFrame`, which doesn't resolve deterministically under fake timers) unmounts the
-underlying `<Modal>` once the animation has actually finished. Same idiom as `Toast.tsx`'s `hide()`.
+One `Animated.Value` (`progress`, 0 → 1) drives both the panel's `translateY` (window height → `0`)
+and the backdrop's `opacity` in lockstep — why RN `<Modal>` is always given `animationType="none"`:
+RN's native transition is one discrete enum for the whole surface and can't also fade a
+separately-Animated backdrop in step with a custom slide.
+
+`resolveDrawerAnimationDuration` (WCAG 2.3.3) collapses duration to `0` under `useReducedMotion()` —
+an instant snap, never a frozen half-slid frame.
+
+**Exit-animation lifecycle.** RN's `<Modal>` only hides children once native dismissal completes or
+the component unmounts, so Drawer keeps its own `mounted` state distinct from `visible`: on close the
+exit animation starts immediately and a `setTimeout` (matching `duration`, not the `Animated.timing`
+callback, which rides `requestAnimationFrame` and won't resolve deterministically under fake timers)
+unmounts the `<Modal>` once finished — same idiom as `Toast.tsx`'s `hide()`.
+
+## Keyboard avoidance
+
+The panel is bottom-anchored (`translateY` rests at `0`), so `KeyboardAvoidingView` doesn't help —
+shrinking the panel's height moves the top edge up but leaves the bottom under the keyboard. Drawer
+instead grows its OWN `paddingBottom` by the keyboard's height, animated with
+`keyboardWillShow`/`keyboardWillHide` on iOS (`keyboardDidShow`/`keyboardDidHide` on Android, no
+"will" pair there).
+
+**Gated on `mounted`.** The listener effect sits above the `if (!mounted) return null` guard, so
+without a `mounted` check of its own it ran on a closed drawer — and the normal consumer keeps one
+`<Drawer visible={false}>` permanently in the tree, which made every keyboard open anywhere on that
+screen start this JS-driven tween on a hidden panel. Because nothing tracks the keyboard while
+closed, the effect seeds the height from `Keyboard.metrics()` when it re-subscribes — skipped on
+web, since react-native-web's `Keyboard` stub doesn't implement `metrics()` (unlike the other
+`Keyboard` calls here, which it stubs as no-ops).
+
+**Reduce motion (WCAG 2.3.3) applies here too.** This is the library's one raw `Animated.timing`
+(`paddingBottom` can't run on the native driver, so it can't go through `useMotion().timing`), which
+means the gate has to be applied by hand: `!motion.enabled` snaps with `setValue`, and the fallback
+duration is `motion.duration("normal")` — never a hardcoded literal. The file's eslint override
+drops the `Animated.timing` restriction wholesale, so nothing else catches a regression here;
+`__tests__/Drawer.keyboard.test.tsx` does.
+
+**Invariant:** that padding lives on its own inner `Animated.View`, never the panel's transform
+node — RN's native driver claims a node the instant any animated prop on it starts with
+`useNativeDriver: true` (the panel's `translateY`); a JS-driven prop (`paddingBottom`) on that same
+node then throws "Attempting to run JS driven animation on animated node that has been moved to
+'native'" on the next keyboard toggle.
 
 ## Web portal mechanism (opt-in)
 
-Same containment bug, same fix, as `Modal`/`Select`/`Menu`: `react-native-web`'s own `<Modal>`
-unconditionally portals to `document.body` (no `container`/`portalHost` override exists — see
-`../modal/ModalPortalContext.ts`), which breaks visual containment inside a fixed-size preview
-frame (`example/DeviceFrame.tsx`'s 390px phone card) — the sheet rendered full-browser-viewport
-instead of clipped to the frame.
-
-`Drawer.tsx` reads `ModalPortalContext`/`renderWebPortal` straight from `../modal` (the same
-deliberate cross-module exception `Select.tsx`'s own top comment documents — a plain context +
-stateless helper, never this library's own `Modal` component). Gated on
-`Platform.OS === "web" && portalContainer != null`; every other case (native, or web with no
-`ModalPortalProvider`) renders through RN's own `<Modal>`, byte-identical to before this
-mechanism existed. See `../modal/MODULE.md`'s "Web portal mechanism" section for the full
-context/renderer design.
-
-**Unlike `Modal`'s portal branch, Drawer loses no animation fidelity.** Modal's portal path
-skips RN `<Modal>`'s native open/close animation because that's what drives Modal's fade; Drawer
-never relied on RN Modal's `animationType` in the first place (always `"none"` — see Animation
-above) — the slide+fade is 100% driven by the `progress` `Animated.Value` regardless of which
-container the tree renders into, so the portaled tree animates identically to the RNModal path.
-The portal branch is gated on `mounted` (not `visible`), reproducing RN Modal's own
-`visible={mounted}` so the same mount-through-exit-animation lifecycle applies on both paths —
-the exit slide/fade still plays out before the portaled tree unmounts.
-
-**Known minor gap:** `translateY`'s off-screen starting point interpolates from the actual
-browser `useWindowDimensions().height`, not the portal container's height (there's no cheap way
-to read the container's own height from a portal-container ref alone). Inside a frame shorter
-than the full window, the panel starts further off-screen than strictly necessary, animating
-over the same fixed duration — the resting position (`translateY: 0`) and clipping are still
-correct, this only affects how far the panel travels before entering view. Not a visual escape;
-left as-is rather than adding a container-height measurement this component doesn't otherwise
-need.
+Same containment bug, same fix, as `Modal`/`Select`/`Menu`: `react-native-web`'s `<Modal>`
+unconditionally portals to `document.body`, breaking containment inside a fixed-size preview frame.
+`Drawer.tsx` reads `ModalPortalContext`/`renderWebPortal` from `../modal` (the same cross-module
+exception `Select.tsx`'s top comment documents), gated on
+`Platform.OS === "web" && portalContainer != null` — otherwise renders through RN's own `<Modal>`
+unchanged. See `../modal/MODULE.md`'s "Web portal mechanism" section for the full design.
+
+Loses no animation fidelity on the portal path — Drawer never relied on RN Modal's `animationType`
+(always `"none"`, see Animation above), so the tree renders identically either way, gated on
+`mounted` (not `visible`) to keep the same exit-animation lifecycle.
+
+**Known minor gap:** the off-screen start uses the window height, not the portal container's, so a
+shorter frame makes the panel travel further before landing — resting position and clipping are
+still correct.
 
 ## Accessibility contract (WCAG)
 
-- **2.3.3** — see Animation above.
-- `accessibilityViewIsModal` on the panel, same as this library's `Modal`.
-- **iOS VoiceOver escape** — `onAccessibilityEscape` on the panel calls `onRequestClose`, identical
-  wiring to `Modal.tsx`.
-- **Android hardware back** — free: RN `Modal`'s own `onRequestClose` prop is wired straight through.
-- The grabber (a `bg.sunken` pill) is `accessibilityElementsHidden` +
-  `importantForAccessibility="no-hide-descendants"` on its wrapper — purely decorative, so it carries
-  no WCAG 1.4.11 obligation (a decorative graphic is out of that SC's scope entirely, same status the
-  backdrop scrims across this library already have). Its dismiss affordance is real (backdrop press +
-  hardware back + VoiceOver escape); it does not itself act as a control.
-- No owned text (`children` is arbitrary consumer content, same stance `Modal`'s own
-  `resolveModalPanelColors` doc comment takes for its body — Drawer additionally has no `title`
-  either), so there is nothing here for a WCAG 1.4.3 test to measure. `Drawer.test.ts`'s file header
-  records this reasoning explicitly rather than silently omitting the usual `contrastRatio` block.
+- **2.3.3** — see Animation above. `accessibilityViewIsModal` on the panel, same as this library's `Modal`.
+- **iOS VoiceOver escape** — `onAccessibilityEscape` calls `onRequestClose`, identical to `Modal.tsx`.
+  **Android hardware back** is free via RN `Modal`'s own `onRequestClose` prop.
+- The grabber is `accessibilityElementsHidden` + `no-hide-descendants` — purely decorative (no WCAG
+  1.4.11 obligation); its dismiss affordance is real (backdrop press + hardware back + VoiceOver escape).
+- No owned text (`children` is arbitrary, no `title`) — nothing for WCAG 1.4.3 to measure;
+  `Drawer.test.ts`'s file header records that reasoning instead of omitting the usual block.
 
 ## Known gaps
 
-- **No `react-native-safe-area-context` wiring.** It's listed in `peerDependenciesMeta` as an
-  optional peer, but is NOT actually declared in `peerDependencies` in this package's own
-  `package.json` — it only resolves in this repo's dev sandbox because the `example` workspace
-  depends on it directly and npm workspaces hoist it into the root `node_modules`. Importing
-  `useSafeAreaInsets` here would work in this repo and then fail to resolve for a consumer app that
-  installs `pixelize-native-library` without separately installing that package. `Toast.tsx`'s own MODULE.md
-  already flagged the same gap for its overlay inset. Bottom padding instead uses
-  `resolveDrawerBottomInset`: the theme's own `space[5]` plus a static iOS home-indicator
-  approximation (`DRAWER_IOS_HOME_INDICATOR_INSET`, 20dp) on iOS only. Revisit once
-  `react-native-safe-area-context` is added as a REAL peer dependency (a `package.json` change, out of
-  this module's scope) — swap the static constant for a real `useSafeAreaInsets().bottom` read.
-- **No swipe-down-to-dismiss in v1 — a deliberate choice, not an oversight.** The spec allowed this as
-  a documented v1 gap, and three considerations pointed the same way:
-  1. **Testability.** This is the first hand-rolled gesture module in this catalogue — there is no
-     `PanResponder` test precedent anywhere in the other 27 shipped components. `PanResponder`
-     computes `dx`/`dy`/`vx`/`vy` internally from a raw native touch-event history; accurately
-     reproducing that in `@testing-library/react-native` (which has no real touch pipeline) means
-     either hand-crafting synthetic touch streams that only approximate the real responder math, or
-     shipping the gesture path untested. Both fall short of the "measured, never eyeballed" bar the
-     rest of this library holds itself to.
-  2. **Full dismiss parity already exists without it** — backdrop press, Android hardware back, and
-     the iOS VoiceOver escape gesture together already satisfy WCAG 2.5.7's non-drag-alternative
-     requirement; a swipe would be a nice-to-have affordance, not a missing capability.
-  3. **Risk to `children`.** A `PanResponder` broad enough to feel natural on the whole panel risks
-     fighting a `ScrollView`/`FlatList` inside `children` (a scroll gesture starting near the top of
-     scrollable content vs. a sheet-dismiss swipe is a real, easy-to-get-wrong disambiguation); scoping
-     it to only the grabber's small handle strip avoids that fight but makes the gesture much narrower
-     and less discoverable than the "drag anywhere" affordance users expect from a bottom sheet.
-  A future version should revisit this with `PanResponder` scoped to `drawerHandleStructure`'s handle
-  strip only (never the full panel), driving `resolveDrawerAnimationDuration`'s same `progress` value,
-  gated by a real distance/velocity threshold — and, at that point, a way to verify the gesture math
-  deterministically (e.g. extracting the dy/vy → dismiss decision into its own pure, unit-tested
-  function, the same "keep the decision pure, wire the mechanism thin" split this file already uses
-  everywhere else) rather than only relying on `PanResponder`'s live wiring.
-- No `size` prop — v1 is a single shape (content sizes the panel up to a 90% max-height cap), matching
-  the spec this module was built against.
+- **No `react-native-safe-area-context` wiring** — listed as an optional peer but not a real
+  `peerDependencies` entry, so a consumer without it installed separately would fail to resolve it.
+  Bottom padding instead uses `resolveDrawerBottomInset` (theme `space[5]` + a static iOS
+  home-indicator constant). Revisit once the package becomes a real peer dependency.
+- **No swipe-down-to-dismiss in v1** — deliberate: no `PanResponder` test precedent exists in this
+  catalogue (untested gesture math), and backdrop press + Android back + VoiceOver escape already
+  satisfy WCAG 2.5.7's non-drag-alternative requirement. A future version should scope
+  `PanResponder` to `drawerHandleStructure`'s handle only, with the dy/vy → dismiss decision as its
+  own pure, unit-tested function.
+- No `size` prop — v1 is a single shape (content sizes the panel up to a 90% max-height cap).
 
 ## Patterns copied from Modal / Select / Toast
 
-1. **Structure vs colour split.** Structural values (padding, top-corner radius, the grabber's fixed
-   pill) → `createThemedVariants` (or the untethemed `createVariants` where nothing is theme-scaled,
-   same idiom `RadioGroup`'s `radioDotStructure` uses) — never a fresh inline style object per render.
-   Colour → resolved from role tokens, applied inline.
-2. **Pure, testable resolvers** in `Drawer.variants.ts` (no React/lucide) — reduced motion, the
-   bottom-inset fallback, and colour resolution are all unit-tested without rendering React Native.
-3. **RN's raw `Modal`, not this library's own `../modal` COMPONENT** — same isolation contract
-   `Select.tsx`'s own top comment states, so Drawer never depends on a sibling module's rendered
-   output. The one deliberate exception is the web portal mechanism (`ModalPortalContext`/
-   `renderWebPortal` — a plain context + stateless helper, not the `Modal` component) — see "Web
-   portal mechanism" above.
-4. **Mount-through-exit-animation + deterministic timer-based unmount** — copied from `Toast.tsx`'s
-   `hide()`, adapted from a provider's imperative `show`/`hide` to a fully-controlled `visible` prop.
+1. **Structure vs colour split** — structural values via `createThemedVariants`, colour resolved
+   from role tokens and applied inline.
+2. **Pure, testable resolvers** in `Drawer.variants.ts` (no React/lucide).
+3. **RN's raw `Modal`, not this library's own `../modal` component** — same isolation contract
+   `Select.tsx` states. The one exception is the web portal mechanism above.
+4. **Mount-through-exit-animation + timer-based unmount** — copied from `Toast.tsx`'s `hide()`.
 
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). Only renders host primitives (`Pressable`/`View`/`Animated.View`/RN's own `Modal`) — no library child component receives a derived callback/array, so no `useCallback`/`useMemo` was needed.
+
+## 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.

package/lib/module/modules/empty-state/EmptyState.js

@@ -7,18 +7,23 @@
  * composition (the same reasoning `AlertDialog` documents for its own footer buttons) — never a
  * hand-rolled `Pressable` that would duplicate Button's press/focus/disabled/hit-target wiring.
  *
- * No `accessibilityRole` of its own: like `Card`, this is a plain grouping container with no
- * interaction beyond the composed Button, so there is nothing here for assistive tech to announce
- * beyond its children — the title and description read as their own `Text` elements, in order,
- * and the icon (redundant with the title) is hidden from the accessibility tree entirely.
+ * No `accessibilityRole` on the container: like `Card`, this is a plain grouping container with no
+ * interaction beyond the composed Button. The title is the state's heading (`accessibilityRole=
+ * "header"` at level 2, WCAG 1.3.1 / 2.4.6), the description reads as its own `Text` after it, and the icon
+ * (redundant with the title) is hidden from the accessibility tree entirely.
+ *
+ * Appearing is itself the status message (WCAG 4.1.3): a screen swapping its content for this block
+ * moves no focus, so `useAnnounce` speaks the title + description once, on arrival and on change.
  */
 
-import { memo } from "react";
+import { memo, useMemo } from "react";
 import { StyleSheet, Text, View } from "react-native";
+import { useAnnounce } from "../../core/a11y/index.js";
+import { HEADING_LEVEL, HeadingText } from "../../core/heading/index.js";
 import { Icon } from "../../core/icon/index.js";
-import { useTheme } from "../../theme/index.js";
+import { useTheme } from "../../theme/hooks.js";
 import { Button } from "../button/index.js";
-import { EMPTY_STATE_ICON_SIZE, emptyStateStructure, resolveEmptyStateColors } from "./EmptyState.variants.js";
+import { EMPTY_STATE_ICON_SIZE, emptyStateStructure, resolveEmptyStateAnnouncement, resolveEmptyStateColors } from "./EmptyState.variants.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // A lighter stroke than the default 2 — at 48dp a 2px stroke reads heavier than the muted,
 // secondary role this glyph plays next to the title.
@@ -32,10 +37,23 @@ export const EmptyState = /*#__PURE__*/memo(function EmptyState({
   testID
 }) {
   const theme = useTheme();
-  const colors = resolveEmptyStateColors(theme.colors);
+  const colors = useMemo(() => resolveEmptyStateColors(theme.colors), [theme.colors]);
+
+  // No `accessibilityLiveRegion` alongside this — it is Android-only and would announce twice there
+  // (the contract `core/a11y/MODULE.md` states, same as `Input`/`FormField`).
+  useAnnounce(resolveEmptyStateAnnouncement(title, description));
+  const rootStyle = useMemo(() => [emptyStateStructure(theme), style], [theme, style]);
+  const titleStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.bold), styles.text, {
+    fontSize: theme.fontSizes.lg,
+    color: colors.title
+  }], [theme, colors]);
+  const descriptionStyle = useMemo(() => [styles.text, {
+    fontSize: theme.fontSizes.sm,
+    color: colors.description
+  }], [theme, colors]);
   return /*#__PURE__*/_jsxs(View, {
     testID: testID,
-    style: [emptyStateStructure(theme), style],
+    style: rootStyle,
     children: [icon !== undefined &&
     /*#__PURE__*/
     // Decorative — redundant with the visible title below, so it is hidden from assistive
@@ -51,17 +69,13 @@ export const EmptyState = /*#__PURE__*/memo(function EmptyState({
         color: colors.icon,
         strokeWidth: ICON_STROKE
       })
-    }), /*#__PURE__*/_jsx(Text, {
-      style: [theme.fontStyleForWeight(theme.fontWeights.bold), styles.text, {
-        fontSize: theme.fontSizes.lg,
-        color: colors.title
-      }],
+    }), /*#__PURE__*/_jsx(HeadingText, {
+      accessibilityRole: "header",
+      "aria-level": HEADING_LEVEL.section,
+      style: titleStyle,
       children: title
     }), description !== undefined && /*#__PURE__*/_jsx(Text, {
-      style: [styles.text, {
-        fontSize: theme.fontSizes.sm,
-        color: colors.description
-      }],
+      style: descriptionStyle,
       children: description
     }), action !== undefined && /*#__PURE__*/_jsx(Button, {
       label: action.label,

package/lib/module/modules/empty-state/EmptyState.variants.js

@@ -36,6 +36,15 @@ export function resolveEmptyStateColors(colors) {
   };
 }
 
+/**
+ * What a screen reader hears when this state appears (WCAG 4.1.3). The description carries the
+ * recovery step ("Try a different search"), so it is announced with the title rather than left to a
+ * swipe the user has no reason to make.
+ */
+export function resolveEmptyStateAnnouncement(title, description) {
+  return description === undefined ? title : `${title}. ${description}`;
+}
+
 /**
  * Structural styles only — centring, padding, and the vertical rhythm between children. No
  * colours (those are resolved separately and applied inline over this) and no closed union to

package/lib/module/modules/empty-state/MODULE.md

@@ -9,10 +9,11 @@ identity, same reasoning `Divider`/`Avatar` give for theirs.
 | File | Role |
 |------|------|
 | `EmptyState.tsx` | The component. Resolves role colours + the themed structural style, composes the optional icon/description/action, `style` last. |
-| `EmptyState.variants.ts` | Pure resolver (`resolveEmptyStateColors`) + the themed structural variant resolver `emptyStateStructure` + the `EMPTY_STATE_ICON_SIZE` constant. No React, no lucide. |
+| `EmptyState.variants.ts` | Pure resolvers (`resolveEmptyStateColors`, `resolveEmptyStateAnnouncement`) + the themed structural variant resolver `emptyStateStructure` + the `EMPTY_STATE_ICON_SIZE` constant. No React, no lucide. |
 | `index.ts` | Public surface: `EmptyState`, `EmptyStateProps`, `EmptyStateAction`, `IconName` (re-exported from `core/icon`). |
-| `__tests__/EmptyState.test.ts` | Pure: WCAG 1.4.3 (title + description, all brands × modes), the icon's 3:1 non-text floor, the colour-mapping contract, `EMPTY_STATE_ICON_SIZE`. |
-| `__tests__/EmptyState.render.test.tsx` | Render: title/description compose, `testID` forwards, icon absent vs. hidden-from-AT, the composed action `Button` fires `onPress` and carries its label as the accessible name, consumer `style` applies last. |
+| `__tests__/EmptyState.test.ts` | Pure: WCAG 1.4.3 (title + description, all brands × modes), the icon's 3:1 non-text floor, the colour-mapping contract, `EMPTY_STATE_ICON_SIZE`, the announcement string. |
+| `__tests__/EmptyState.render.test.tsx` | Render: title/description compose, the title's heading role + level, the 4.1.3 announcement (once per change, no live region), `testID` forwards, icon absent vs. hidden-from-AT, the composed action `Button` fires `onPress` and carries its label as the accessible name, consumer `style` applies last. |
+| `__tests__/EmptyState.dom.test.tsx` | Real DOM (`jest.web.config.js`): the title renders a real `<h2>`. |
 
 ## Props
 
@@ -39,10 +40,21 @@ composition and `Select`'s reuse of stable siblings.
 
 ## Accessibility contract (WCAG)
 
-- **No `accessibilityRole` of its own.** Like `Card`, this is a plain grouping container — the
-  title and description read as their own `Text` elements, in document order, and the composed
-  `Button` carries its own role/state. There is nothing here for assistive tech to announce beyond
-  its children.
+- **1.3.1 / 2.4.6 — the title is a level-2 heading** (`accessibilityRole="header"`,
+  `aria-level={2}` — `HEADING_LEVEL.section`, `core/heading` — the same role and level
+  `SectionList`'s header and `Section`'s label carry), so an empty state is a stop in rotor heading
+  navigation rather than an unlabelled block of text, nesting under the screen's own `<h1>` rather
+  than restarting the outline. The description stays plain text below it.
+- **4.1.3 — appearing IS the status message.** A screen swapping its content for this block moves
+  no focus, so nothing would be spoken; `useAnnounce` (`core/a11y`) announces
+  `resolveEmptyStateAnnouncement(title, description)` — the description is included because it
+  carries the recovery step ("Try a different search"), which a user has no reason to swipe for.
+  Announced once on arrival and again only when the text actually changes. **No
+  `accessibilityLiveRegion`** alongside it: that prop is Android-only and would announce twice
+  there (the contract `core/a11y/MODULE.md` states, same as `Input`/`FormField`/`FileUpload`).
+- **No `accessibilityRole` on the container.** Like `Card`, this is a plain grouping container —
+  the title and description read as their own `Text` elements, in document order, and the composed
+  `Button` carries its own role/state.
 - **Icon is decorative.** Redundant with the visible title, so its wrapper carries
   `accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"` — the same
   contract `Avatar`/`Skeleton` give their own decorative default — rather than being announced as
@@ -76,3 +88,9 @@ None — no new icon, no new theme token, no new core helper needed for this com
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). Its one library child, `Button`, receives `action.label`/`action.onPress` straight from the consumer's own `action` object, not a freshly-derived closure — nothing to memoize.
+
+## 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.

package/lib/module/modules/fab/Fab.js

@@ -0,0 +1,212 @@
+"use strict";
+
+/**
+ * Fab — a floating action button: an absolutely-positioned, safe-area-aware primary-action circle
+ * (or pill, when `label` is given — the EXTENDED variant, icon + text). It renders one small
+ * wrapper View around its own `Pressable` — `position: "absolute"` for every floating `position`,
+ * plain in-flow `position: "relative"` for `"static"` — so `bottom-center` can center a
+ * variable-width extended Fab via `alignItems` rather than a measured `translateX`
+ * (`resolveFabAnchorStyle`'s own comment has the full reasoning).
+ *
+ * `FabProps` is a discriminated union, the same shape `ButtonProps` already establishes: a labelled
+ * (extended) Fab, or an icon-only Fab whose `accessibilityLabel` is REQUIRED at the type level — the
+ * same unlabelled-icon-button trap `Button.tsx`'s own top comment documents; `label?: never` keeps
+ * the two shapes mutually exclusive.
+ *
+ * Press feedback (one motion-system value driving the state-layer overlay + the press scale, with a
+ * brightness-aware scrim direction) and the offset focus ring are Button's own techniques, copied
+ * here rather than imported — `fab/` stays
+ * free of a cross-module dependency on `button/` internals, the same isolation `Toast.variants.ts`
+ * documents for its own duplicated `MIN_TOUCH_TARGET`.
+ */
+
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { ActivityIndicator, Animated, Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { Icon } from "../../core/icon/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { fabCircleStructure, fabExtendedStructure, FAB_SIZES, resolveFabAccessibility, resolveFabAnchorStyle, resolveFabBottomInset, resolveFabFocusRingStyle, resolveFabHorizontalInset, resolveFabTone } from "./Fab.variants.js";
+
+/** A Fab with a visible text label — the EXTENDED variant (a pill, icon + text). */
+
+/** An icon-only Fab. No visible text, so `accessibilityLabel` is REQUIRED at the type level — the
+ *  same trap `Button`'s icon-only shape closes. `label?: never` keeps the two shapes exclusive. */
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
+const ICON_STROKE = 2;
+// State-layer scrims — direction chosen by the label's brightness so the fill moves AWAY from the
+// label on press (its contrast can only rise), the identical technique `Button.tsx` uses.
+const PRESS_SCRIM_DARK = "#00000026";
+const PRESS_SCRIM_LIGHT = "#ffffff26";
+
+/** Cheap perceived-brightness split; `onFill` is only ever a near-white or near-black role value. */
+function isLight(hex) {
+  const n = parseInt(hex.slice(1, 7), 16);
+  const r = n >> 16 & 0xff;
+  const g = n >> 8 & 0xff;
+  const b = n & 0xff;
+  return r * 0.299 + g * 0.587 + b * 0.114 > 140;
+}
+function FabImpl(props) {
+  const {
+    icon,
+    label,
+    onPress,
+    onLongPress,
+    onPressOut,
+    onHoverIn,
+    onHoverOut,
+    onFocus,
+    onBlur,
+    tone = "accent",
+    size = "lg",
+    position = "bottom-right",
+    disabled = false,
+    loading = false,
+    offset,
+    style,
+    testID,
+    accessibilityLabel,
+    accessibilityHint,
+    "aria-describedby": ariaDescribedBy
+  } = props;
+  const theme = useTheme();
+  const motion = useMotion();
+  // One value drives both the state-layer scrim and the press scale, so they can never desync.
+  const press = useAnimatedValue(0);
+  const pressAnimation = useRef(null);
+  // Keyboard / external-keyboard / assistive-tech focus (no-op on pure touch, correct everywhere else).
+  const [focused, setFocused] = useState(false);
+  const spec = FAB_SIZES[size];
+  const toneColors = resolveFabTone(theme.colors, tone);
+  const a11y = resolveFabAccessibility({
+    label,
+    accessibilityLabel,
+    disabled,
+    loading,
+    onPress
+  });
+  const overlayColor = isLight(toneColors.onFill) ? PRESS_SCRIM_DARK : PRESS_SCRIM_LIGHT;
+  const extended = label !== undefined;
+  const bottomInset = resolveFabBottomInset(theme.space[4], Platform.OS, offset?.bottom ?? 0);
+  const horizontalInset = resolveFabHorizontalInset(theme.space[4], offset?.horizontal ?? 0);
+  const anchor = resolveFabAnchorStyle({
+    position,
+    bottomInset,
+    horizontalInset,
+    zIndex: theme.zIndices.docked
+  });
+  const setPressed = useCallback(pressed => {
+    pressAnimation.current?.stop();
+    const to = pressed ? 1 : 0;
+    if (!motion.enabled) {
+      press.setValue(to);
+      return;
+    }
+    pressAnimation.current = motion.timing(press, to, {
+      duration: "fast"
+    });
+    pressAnimation.current.start();
+  }, [motion, press]);
+  useEffect(() => () => pressAnimation.current?.stop(), []);
+
+  // Own state first, then the incoming handler — an outer handler that throws can never strand the
+  // press/focus ring in its active state.
+  const handlePressIn = useCallback(() => setPressed(true), [setPressed]);
+  const handlePressOut = useCallback(event => {
+    setPressed(false);
+    onPressOut?.(event);
+  }, [setPressed, onPressOut]);
+  const handleFocus = useCallback(event => {
+    setFocused(true);
+    onFocus?.(event);
+  }, [onFocus]);
+  const handleBlur = useCallback(event => {
+    setFocused(false);
+    onBlur?.(event);
+  }, [onBlur]);
+  const pressScale = useMemo(() => press.interpolate({
+    inputRange: [0, 1],
+    outputRange: [1, motion.transform.pressScale]
+  }), [press, motion.transform.pressScale]);
+  const focusRingStyle = useMemo(() => resolveFabFocusRingStyle(theme.colors.border.focus, theme.radii.full), [theme.colors.border.focus, theme.radii.full]);
+
+  // The spinner is never the sole loading signal — `aria-busy` announces it. Hidden from AT so it
+  // isn't read as a separate element, the same contract Button's own spinner has.
+  const content = loading ? /*#__PURE__*/_jsx(ActivityIndicator, {
+    size: "small",
+    color: toneColors.onFill,
+    "aria-hidden": true
+  }) : /*#__PURE__*/_jsx(Icon, {
+    name: icon,
+    size: spec.iconSize,
+    color: toneColors.onFill,
+    strokeWidth: ICON_STROKE
+  });
+  return /*#__PURE__*/_jsx(View, {
+    style: [anchor, style],
+    pointerEvents: "box-none",
+    children: /*#__PURE__*/_jsxs(AnimatedPressable, {
+      testID: testID,
+      accessibilityRole: a11y.accessibilityRole,
+      accessibilityLabel: a11y.accessibilityLabel,
+      accessibilityHint: accessibilityHint,
+      "aria-describedby": ariaDescribedBy,
+      "aria-disabled": a11y["aria-disabled"],
+      "aria-busy": a11y["aria-busy"],
+      disabled: a11y.disabled,
+      onPress: a11y.onPress,
+      onLongPress: onLongPress,
+      onPressIn: handlePressIn,
+      onPressOut: handlePressOut,
+      onHoverIn: onHoverIn,
+      onHoverOut: onHoverOut,
+      onFocus: handleFocus,
+      onBlur: handleBlur,
+      style: [extended ? fabExtendedStructure(theme, {
+        size
+      }) : fabCircleStructure(theme, {
+        size
+      }), {
+        backgroundColor: toneColors.fill,
+        transform: [{
+          scale: pressScale
+        }]
+      }, (disabled || loading) && styles.dimmed, theme.elevation.lg],
+      children: [/*#__PURE__*/_jsx(Animated.View, {
+        pointerEvents: "none"
+        // Matches the control's own radius: the control isn't `overflow: hidden` (that would clip
+        // the focus ring below), so the state layer rounds itself instead of showing square corners.
+        ,
+        style: [StyleSheet.absoluteFill, {
+          backgroundColor: overlayColor,
+          opacity: press,
+          borderRadius: theme.radii.full
+        }]
+      }), focused && /*#__PURE__*/_jsx(View, {
+        pointerEvents: "none",
+        testID: testID ? `${testID}-focus-ring` : undefined,
+        style: focusRingStyle
+      }), content, extended && /*#__PURE__*/_jsx(Text, {
+        numberOfLines: 1,
+        style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+          fontSize: spec.fontSize,
+          color: toneColors.onFill
+        }],
+        children: label
+      })]
+    })
+  });
+}
+const styles = StyleSheet.create({
+  // A disabled/loading control is exempt from the contrast minimum (WCAG 1.4.3), so a uniform dim is
+  // correct — same idiom Button's own `dimmed` style uses.
+  dimmed: {
+    opacity: 0.5
+  }
+});
+
+// A consumer's screen re-renders far more often than Fab's own props change — memo is near-free
+// insurance for a design-system primitive (see CLAUDE.md "Performance" section).
+export const Fab = /*#__PURE__*/memo(FabImpl);
+//# sourceMappingURL=Fab.js.map