pixelize-native-library 1.0.7 → 1.2.1

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,112 @@ 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.
+
+- **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` wrapper around the handle/children (entrance-only, no exit — purely redundant with `progress`, which already drives panel+backdrop together). `DRAWER_BACKDROP`'s opacity now comes from the shared `MOTION_TRANSFORM.scrimOpacity`.

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

@@ -7,18 +7,25 @@
  * 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 { StyleSheet, Text, View } from "react-native";
+import { memo, useMemo } from "react";
+import { View } from "react-native";
+import Reanimated, { FadeInDown, FadeOut, ReduceMotion } from "react-native-reanimated";
+import { useAnnounce } from "../../core/a11y/index.js";
 import { Icon } from "../../core/icon/index.js";
-import { useTheme } from "../../theme/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { floatingBackground, floatingSurfaceStyle } from "../../theme/platform/index.js";
 import { Button } from "../button/index.js";
-import { EMPTY_STATE_ICON_SIZE, emptyStateStructure, resolveEmptyStateColors } from "./EmptyState.variants.js";
+import { Text, Heading } from "../text/index.js";
+import { EMPTY_STATE_ICON_SIZE, emptyStateFillStructure, 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.
@@ -28,20 +35,26 @@ export const EmptyState = /*#__PURE__*/memo(function EmptyState({
   title,
   description,
   action,
+  fill = false,
   style,
   testID
 }) {
   const theme = useTheme();
-  const colors = resolveEmptyStateColors(theme.colors);
-  return /*#__PURE__*/_jsxs(View, {
+  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), fill && emptyStateFillStructure(theme), fill && {
+    backgroundColor: floatingBackground(theme, "sm"),
+    ...floatingSurfaceStyle(theme, "sm")
+  }, style], [theme, fill, style]);
+  return /*#__PURE__*/_jsxs(Reanimated.View, {
     testID: testID,
-    style: [emptyStateStructure(theme), style],
-    children: [icon !== undefined &&
-    /*#__PURE__*/
-    // Decorative — redundant with the visible title below, so it is hidden from assistive
-    // tech rather than announced as a second, unexplained element (same contract `Avatar` and
-    // `Skeleton` give their own decorative default).
-    _jsx(View, {
+    entering: FadeInDown.springify().reduceMotion(ReduceMotion.System),
+    exiting: FadeOut.reduceMotion(ReduceMotion.System),
+    style: rootStyle,
+    children: [icon !== undefined && /*#__PURE__*/_jsx(View, {
       testID: testID === undefined ? undefined : `${testID}-icon`,
       accessibilityElementsHidden: true,
       importantForAccessibility: "no-hide-descendants",
@@ -51,17 +64,12 @@ 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(Heading, {
+      variant: "h3",
       children: title
     }), description !== undefined && /*#__PURE__*/_jsx(Text, {
-      style: [styles.text, {
-        fontSize: theme.fontSizes.sm,
-        color: colors.description
-      }],
+      variant: "body-sm",
+      color: "muted",
       children: description
     }), action !== undefined && /*#__PURE__*/_jsx(Button, {
       label: action.label,
@@ -71,9 +79,4 @@ export const EmptyState = /*#__PURE__*/memo(function EmptyState({
     })]
   });
 });
-const styles = StyleSheet.create({
-  text: {
-    textAlign: "center"
-  }
-});
 //# sourceMappingURL=EmptyState.js.map

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
@@ -51,4 +60,11 @@ export const emptyStateStructure = createThemedVariants(theme => ({
     rowGap: theme.space[3]
   }
 }));
+export const emptyStateFillStructure = createThemedVariants(_theme => ({
+  base: {
+    flex: 1,
+    alignSelf: "stretch",
+    width: "100%"
+  }
+}));
 //# sourceMappingURL=EmptyState.variants.js.map

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
 
@@ -22,6 +23,7 @@ identity, same reasoning `Divider`/`Avatar` give for theirs.
 | `title` | `string` | — | Required. Rendered bold, `fg.default`, centred. |
 | `description` | `string` | — | Optional. Rendered `fg.muted`, centred, below the title. |
 | `action` | `{ label: string; onPress: () => void }` | — | Optional. Rendered via this library's own `Button` (`tone="accent" variant="solid"`) — a justified composition, same reasoning `AlertDialog` documents for its own footer buttons. |
+| `fill` | `boolean` | `false` | `flex: 1` + centred — fills a list/screen slot without a wrapper. |
 | `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
 | `testID` | `string` | — | Forwarded to the outermost `View`; the icon wrapper (when rendered) gets `${testID}-icon`. |
 
@@ -39,10 +41,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 +89,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.