pixelize-native-library 1.0.7 → 1.2.0

package/lib/module/modules/timeline/Timeline.js

@@ -1,95 +1,169 @@
 "use strict";
 
 /**
- * Timeline — a vertical list of dated/ordered events. Each row is a marker (a plain dot, or an
- * icon in a filled circle) connected to the next row's marker by a line. Purely informational: no
- * press handling, no per-item emphasis, no animation. The marker + connecting line are decorative
- * (removing them changes spacing, not meaning — same reasoning `Divider` documents for its own
- * hairline), so they are hidden from assistive tech; the title/description/timestamp stay in the
- * normal accessibility tree, read in order, exactly like the plain `View` container `Card.tsx`
- * documents ("nothing here for `accessibilityRole` to announce — children carry their own
- * semantics").
+ * Timeline — a vertical list of dated/ordered events.
+ *
+ * The reveal is ONE animated value on the outer container, never one per row: rows are recycled
+ * cells in a `VirtualList`, so a per-cell animation would fire on every scroll-in. It is gated on
+ * `motion.decorative` (high-tier only) since a reveal is pure decoration.
+ *
+ * A row's title, description and timestamp form ONE accessible node — see
+ * `resolveTimelineItemAccessibility` for why three loose `Text` siblings were a 1.3.1 failure.
  */
 
-import { memo } from "react";
-import { Text, View } from "react-native";
+import { memo, useCallback, useEffect, useMemo, useRef } from "react";
+import { Animated, Text, View } from "react-native";
 import { Icon } from "../../core/icon/index.js";
-import { useTheme } from "../../theme/index.js";
-import { resolveTimelineColors, timelineConnectorLineStructure, timelineConnectorStructure, timelineContentStructure, timelineMarkerStructure, timelineRowStructure, TIMELINE_MARKER } from "./Timeline.variants.js";
+import { VirtualList } from "../../core/list/index.js";
+import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { resolveTimelineColors, resolveTimelineItemAccessibility, timelineConnectorLineStructure, timelineConnectorStructure, timelineContentStructure, timelineMarkerStructure, timelineRowStructure, TIMELINE_MARKER } from "./Timeline.variants.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const VIRTUALIZE_THRESHOLD = 20;
 const ICON_STROKE = 2;
+const TimelineRow = /*#__PURE__*/memo(function TimelineRow({
+  model,
+  theme,
+  colors,
+  testID
+}) {
+  const {
+    item,
+    index,
+    isLast
+  } = model;
+  const position = isLast ? "last" : "middle";
+  const rowTestID = testID === undefined ? undefined : `${testID}-item-${index}`;
+  const a11y = resolveTimelineItemAccessibility(item);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: rowTestID,
+    style: timelineRowStructure(),
+    children: [/*#__PURE__*/_jsxs(View, {
+      testID: rowTestID === undefined ? undefined : `${rowTestID}-connector`,
+      style: timelineConnectorStructure(),
+      accessibilityElementsHidden: true,
+      importantForAccessibility: "no-hide-descendants",
+      children: [item.leading !== undefined ? /*#__PURE__*/_jsx(View, {
+        testID: rowTestID === undefined ? undefined : `${rowTestID}-marker`,
+        children: item.leading
+      }) : /*#__PURE__*/_jsx(View, {
+        testID: rowTestID === undefined ? undefined : `${rowTestID}-marker`,
+        style: [timelineMarkerStructure(theme, {
+          kind: item.icon === undefined ? "dot" : "icon"
+        }), {
+          backgroundColor: colors.markerFill
+        }],
+        children: item.icon !== undefined && /*#__PURE__*/_jsx(Icon, {
+          name: item.icon,
+          size: TIMELINE_MARKER.glyph,
+          color: colors.markerIcon,
+          strokeWidth: ICON_STROKE
+        })
+      }), !isLast && /*#__PURE__*/_jsx(View, {
+        testID: rowTestID === undefined ? undefined : `${rowTestID}-line`,
+        style: [timelineConnectorLineStructure(theme), {
+          backgroundColor: colors.connector
+        }]
+      })]
+    }), /*#__PURE__*/_jsxs(View, {
+      testID: rowTestID === undefined ? undefined : `${rowTestID}-content`,
+      accessible: a11y.accessible,
+      accessibilityRole: a11y.accessibilityRole,
+      accessibilityLabel: a11y.accessibilityLabel,
+      style: timelineContentStructure(theme, {
+        position
+      }),
+      children: [/*#__PURE__*/_jsx(Text, {
+        style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+          fontSize: theme.fontSizes.md,
+          color: colors.title
+        }],
+        children: item.title
+      }), item.description !== undefined && /*#__PURE__*/_jsx(Text, {
+        style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
+          fontSize: theme.fontSizes.sm,
+          color: colors.description,
+          marginTop: theme.space[1]
+        }],
+        children: item.description
+      }), item.timestamp !== undefined && /*#__PURE__*/_jsx(Text, {
+        style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
+          fontSize: theme.fontSizes.xs,
+          color: colors.timestamp,
+          marginTop: theme.space[1]
+        }],
+        children: item.timestamp
+      })]
+    })]
+  });
+});
 export const Timeline = /*#__PURE__*/memo(function Timeline({
   items,
   style,
   testID
 }) {
   const theme = useTheme();
-  const colors = resolveTimelineColors(theme.colors);
-  return /*#__PURE__*/_jsx(View, {
+  const motion = useMotion();
+  const colors = useMemo(() => resolveTimelineColors(theme.colors), [theme.colors]);
+  const reveal = useAnimatedValue(motion.decorative ? 0 : 1);
+  const running = useRef(null);
+  useEffect(() => {
+    running.current?.stop();
+    if (!motion.decorative) {
+      reveal.setValue(1);
+      return;
+    }
+    running.current = motion.timing(reveal, 1, {
+      easing: "decelerate"
+    });
+    running.current.start();
+    return () => running.current?.stop();
+  }, [motion, reveal]);
+  useEffect(() => () => running.current?.stop(), []);
+  const revealStyle = useMemo(() => ({
+    opacity: reveal,
+    transform: [{
+      translateY: reveal.interpolate({
+        inputRange: [0, 1],
+        outputRange: [motion.transform.offsetY, 0]
+      })
+    }]
+  }), [reveal, motion.transform.offsetY]);
+  const rootStyle = useMemo(() => [revealStyle, style], [revealStyle, style]);
+  const rows = useMemo(() => items.map((item, index) => ({
+    item,
+    index,
+    isLast: index === items.length - 1
+  })), [items]);
+  const keyExtractor = useCallback(row => row.item.id ?? `timeline-index-${row.index}`, []);
+  const renderItem = useCallback(({
+    item: row
+  }) => /*#__PURE__*/_jsx(TimelineRow, {
+    model: row,
+    theme: theme,
+    colors: colors,
+    testID: testID
+  }), [theme, colors, testID]);
+  if (items.length >= VIRTUALIZE_THRESHOLD) {
+    return /*#__PURE__*/_jsx(Animated.View, {
+      testID: testID,
+      style: rootStyle,
+      children: /*#__PURE__*/_jsx(VirtualList, {
+        data: rows,
+        keyExtractor: keyExtractor,
+        renderItem: renderItem
+      })
+    });
+  }
+  return /*#__PURE__*/_jsx(Animated.View, {
     testID: testID,
-    style: style,
-    children: items.map((item, index) => {
-      const isLast = index === items.length - 1;
-      const position = isLast ? "last" : "middle";
-      const rowTestID = testID === undefined ? undefined : `${testID}-item-${index}`;
-      return /*#__PURE__*/_jsxs(View, {
-        testID: rowTestID,
-        style: timelineRowStructure(),
-        children: [/*#__PURE__*/_jsxs(View, {
-          testID: rowTestID === undefined ? undefined : `${rowTestID}-connector`,
-          style: timelineConnectorStructure(),
-          accessibilityElementsHidden: true,
-          importantForAccessibility: "no-hide-descendants",
-          children: [item.leading !== undefined ? /*#__PURE__*/_jsx(View, {
-            testID: rowTestID === undefined ? undefined : `${rowTestID}-marker`,
-            children: item.leading
-          }) : /*#__PURE__*/_jsx(View, {
-            testID: rowTestID === undefined ? undefined : `${rowTestID}-marker`,
-            style: [timelineMarkerStructure(theme, {
-              kind: item.icon === undefined ? "dot" : "icon"
-            }), {
-              backgroundColor: colors.markerFill
-            }],
-            children: item.icon !== undefined && /*#__PURE__*/_jsx(Icon, {
-              name: item.icon,
-              size: TIMELINE_MARKER.glyph,
-              color: colors.markerIcon,
-              strokeWidth: ICON_STROKE
-            })
-          }), !isLast && /*#__PURE__*/_jsx(View, {
-            testID: rowTestID === undefined ? undefined : `${rowTestID}-line`,
-            style: [timelineConnectorLineStructure(theme), {
-              backgroundColor: colors.connector
-            }]
-          })]
-        }), /*#__PURE__*/_jsxs(View, {
-          style: timelineContentStructure(theme, {
-            position
-          }),
-          children: [/*#__PURE__*/_jsx(Text, {
-            style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
-              fontSize: theme.fontSizes.md,
-              color: colors.title
-            }],
-            children: item.title
-          }), item.description !== undefined && /*#__PURE__*/_jsx(Text, {
-            style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-              fontSize: theme.fontSizes.sm,
-              color: colors.description,
-              marginTop: theme.space[1]
-            }],
-            children: item.description
-          }), item.timestamp !== undefined && /*#__PURE__*/_jsx(Text, {
-            style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-              fontSize: theme.fontSizes.xs,
-              color: colors.timestamp,
-              marginTop: theme.space[1]
-            }],
-            children: item.timestamp
-          })]
-        })]
-      }, `${index}-${item.title}`);
-    })
+    style: rootStyle,
+    children: rows.map(row => /*#__PURE__*/_jsx(TimelineRow, {
+      model: row,
+      theme: theme,
+      colors: colors,
+      testID: testID
+    }, keyExtractor(row)))
   });
 });
 //# sourceMappingURL=Timeline.js.map

package/lib/module/modules/timeline/Timeline.variants.js

@@ -115,6 +115,19 @@ export const timelineConnectorLineStructure = createThemedVariants(theme => ({
     width: theme.borderWidths.thick
   }
 }));
+/**
+ * One event's title, description and timestamp collapse into ONE accessible node (WCAG 1.3.1) — as
+ * three loose `Text` siblings, only their visual grouping said which timestamp belonged to which
+ * title. The same composition `resolveBannerAccessibility` does for its title + message.
+ */
+export function resolveTimelineItemAccessibility(item) {
+  const parts = [item.title, item.description, item.timestamp].filter(part => part !== undefined);
+  return {
+    accessible: true,
+    accessibilityRole: "text",
+    accessibilityLabel: parts.join(". ")
+  };
+}
 
 /**
  * The text column beside the connector. A `middle` row (one with a following item) reserves the

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

@@ -8,11 +8,15 @@ anywhere beneath it.
 
 | File | Role |
 |------|------|
-| `Toast.tsx` | `ToastProvider`, the internal `ToastCard`, and `useToast()`. State machine, timers, animation, a11y wiring. |
-| `Toast.variants.ts` | Pure resolver (`resolveToastTone`) + the themed structural resolvers (`toastCardStructure`, `toastAccentBarStructure`, `toastOverlayStructure`, including the overlay's `zIndex`). No React, no lucide. |
-| `index.ts` | Public surface: `ToastProvider`, `useToast`, `ToastOptions`, `ToastContextValue`, `ToastProviderProps`, the closed unions. No `IconName` re-export — the dismiss glyph is a fixed internal choice. |
-| `__tests__/Toast.test.ts` | Pure: WCAG contrast (all brands × modes, including the close icon vs the card background) + touch target + the tone→role contract + every resolved colour is a solid 6-digit hex (never an alpha token). |
+| `Toast.tsx` | `ToastProvider`, the internal `ToastCard`, and `useToast()`. State machine, timers, animation, a11y wiring, hover/focus pause. |
+| `Toast.variants.ts` | Pure resolver (`resolveToastTone`) + `resolveAutoDismissDelay` (WCAG 2.2.1 — see below) + the themed structural resolvers (`toastCardStructure`, `toastAccentBarStructure`, `toastOverlayStructure`, including the overlay's `zIndex`). No React, no lucide. |
+| `toastScreenReader.ts` | `useScreenReaderEnabled()` — module-local store, `useReducedMotion`'s shape, tracking `AccessibilityInfo.isScreenReaderEnabled()`. Belongs in `core/a11y` (see Known gaps). |
+| `index.ts` | Public surface: `ToastProvider`, `useToast`, `ToastOptions`, `ToastContextValue`, `ToastProviderProps`, the closed unions incl. `ToastDuration`. No `IconName` re-export — the dismiss glyph is a fixed internal choice. |
+| `__tests__/Toast.motion.test.tsx` | Motion: reduce-motion zero duration, the real entrance/exit tween, the shared surface offset, and the device tier's `durationScale` reaching both the tween and the unmount timer. |
+| `__tests__/Toast.test.ts` | Pure: WCAG contrast (all brands × modes, including the close icon vs the card background) + touch target + the tone→role contract + every resolved colour is a solid 6-digit hex (never an alpha token) + `resolveAutoDismissDelay` (WCAG 2.2.1, incl. the `duration: 0` / `duration: Infinity` regressions). |
 | `__tests__/Toast.render.test.tsx` | Render: show/auto-dismiss/dismiss, replace-while-visible, the cross-platform announce call, missing-provider error, the REAL rendered card background (flattened style, not just the token). |
+| `__tests__/Toast.timing.test.tsx` | Render-level WCAG 2.2.1: persistent mode, the two shipped traps as explicit regressions, hover/focus pause + re-arm, the `danger` persistent default (and an explicit `duration` overriding it), screen-reader suppression. |
+| `__tests__/toastScreenReader.test.ts` | The screen-reader store: pre-probe seed, probe result, `screenReaderChanged` subscription, process cache, one-listener-per-process, cleanup. |
 
 ## Why not `<Modal>`
 
@@ -28,7 +32,7 @@ system, so it floats over anything without competing for the same presentation s
 |--------|-------|-------|
 | `ToastProvider` | `{ children, position?: "top" \| "bottom" }` | Mount once near the app root. `position` defaults to `top`; it is provider-level (one overlay), not per-toast. No `style` prop — same as `PixelizeProvider`, the only other provider in this catalogue: it wraps the whole app rather than being laid out by one. |
 | `useToast()` | `{ show(options), dismiss() }` | Throws outside a `ToastProvider`, same contract as `useTheme()`. |
-| `ToastOptions` | `{ message: string, tone?: ToastTone, duration?: number }` | `tone` defaults to `neutral`; `duration` defaults to `DEFAULT_TOAST_DURATION` (~3000ms). |
+| `ToastOptions` | `{ message: string, tone?: ToastTone, duration?: ToastDuration }` | `tone` defaults to `neutral`. `duration` (`number \| "persistent"`) defaults to `DEFAULT_TOAST_DURATION` (~3000ms) — **except `tone: "danger"`, which defaults to `"persistent"`** (see "Auto-dismiss timing" below). |
 | `ToastTone` | `success \| warning \| danger \| info \| neutral` | Closed union — colour from `colors.status.<role>`, never a `color` prop. |
 
 Single-slot by design: calling `show()` while a toast is visible replaces its message/tone, restarts
@@ -36,8 +40,52 @@ the auto-dismiss timer, and restarts the entrance animation (a fresh message rea
 There is no stacking queue in v1 — see Known gaps. `dismiss()` always targets that one slot and is a
 safe no-op when nothing is showing.
 
+## Motion
+
+Entrance and exit go through **`useMotion()`** at the shared `fast` duration; the card's travel is
+`MOTION_TRANSFORM.surfaceOffsetY`. The old module-local `ANIMATION_MS = 200` / `TRANSLATE_DISTANCE =
+24` are gone — this module was skipped by the earlier motion refactor, so until now neither the
+device tier's `durationScale` nor `MOTION_SCALE`/`MOTION_ENABLED` reached it. The unmount timer reads
+the SAME resolved `motion.duration("fast")` as the tween, keeping the removal deterministic (see
+`Toast.tsx`'s note on why the timer, not the animation callback, drives it).
+
+## Auto-dismiss timing (WCAG 2.2.1 — Timing Adjustable)
+
+`resolveAutoDismissDelay(duration, tone, screenReaderEnabled)` (`Toast.variants.ts`) is the ONLY
+place that decides whether a toast's timer gets armed. `Toast.tsx` branches on its `null` result
+*before* calling `setTimeout` — nothing else in the module computes a delay.
+
+- **`duration: "persistent"`** — never auto-dismisses. The spelled-out sentinel, not `0` or
+  `Infinity`: at a call site, `duration: 0` reads as "no delay" and `Infinity` overflows
+  `setTimeout`'s 32-bit signed delay and fires in ~1ms — both were shipped traps that looked like a
+  persistent mode and were actually instant-dismiss. `resolveAutoDismissDelay` now treats `0`,
+  negative numbers, `NaN` and anything past the 32-bit ceiling the same as `"persistent"` (fail
+  towards "stays up" — the card always has a close button) — `Toast.test.ts` locks both former traps
+  down as explicit regressions.
+- **Hover and focus pause the timer; leaving re-arms the FULL delay.** `ToastCard` wires
+  `onPointerEnter`/`onPointerLeave`/`onFocus`/`onBlur` (on both the card `Animated.View` and the
+  close button, so focus reaching the close button also pauses); `ToastProvider` tracks
+  `hovered`/`focused` in refs (not state — pausing must not re-render the card) and re-arms through
+  one `armDismissTimer()` choke point. This is deliberately a restart, not a countdown resume: a
+  toast the user stopped reading mid-sentence should get the whole message again, not whatever was
+  left on the clock.
+- **A running screen reader (`useScreenReaderEnabled`, `toastScreenReader.ts`) suppresses
+  auto-dismiss for every tone**, explicit `duration` included. ~3s is not enough for VoiceOver/
+  TalkBack to finish speaking a message, and there is no way to replay a toast that's gone — this is
+  the DEFAULT behaviour, not an opt-in prop, because a consumer has no way to know per-toast whether
+  a reader is running.
+- **`tone: "danger"` with no explicit `duration` defaults to persistent**, unlike every other tone.
+  **Consumer-visible behaviour change:** an existing `show({ message, tone: "danger" })` call that
+  relied on the ~3000ms default now stays up until dismissed. An explicit `duration` on a `danger`
+  toast is still honoured — only the *default* changed. Judgement call: a 3-second error message is
+  the exact failure WCAG 2.2.1 exists to prevent, and this catalogue has no toast history a user
+  could scroll back to recover a missed one from. Every other tone keeps the ~3000ms default
+  unchanged — success/info/neutral/warning messages are lower-stakes and the existing default reads
+  fine for them.
+
 ## Accessibility contract (WCAG)
 
+- **2.2.1 (timing adjustable)** — see "Auto-dismiss timing" above.
 - **4.1.3 (status messages)** — `show()` calls `AccessibilityInfo.announceForAccessibility(message)`,
   the real cross-platform imperative API (VoiceOver + TalkBack). The message `Text` deliberately does
   NOT also carry `accessibilityLiveRegion`: that RN prop is Android-only, and since `show()` always
@@ -57,8 +105,9 @@ safe no-op when nothing is showing.
   below), measured ≥ 3:1 against the card's own background for every tone × brand × mode. The close
   icon (`fg.muted`, constant across tones — not resolved via `resolveToastTone`) is measured the same
   way against every tone's card background in the same file.
-- **2.3.3** — the slide/fade entrance and exit are suppressed (`duration: 0`) when
-  `useReducedMotion()` is true; the toast still appears/disappears, just without the animated motion.
+- **2.3.3** — the slide/fade entrance and exit resolve to `duration: 0` under reduce motion; the
+  toast still appears/disappears, just without the animated motion. The check is `useMotion()`'s,
+  never a second `useReducedMotion()` call (`core/motion/MODULE.md` rule 6).
 - The close button is icon-only: `accessibilityRole="button"` with a fixed, always-present
   `accessibilityLabel="Dismiss notification"` (not a consumer-configurable prop, so there is no
   unlabelled-icon-button state to make unrepresentable here — unlike `Button`'s icon-only shape).
@@ -90,6 +139,10 @@ change can't silently reintroduce the gap.
 
 ## Known gaps
 
+- **`toastScreenReader.ts` duplicates `core/a11y`'s store shape instead of living there.** It is a
+  general a11y concern (any timed UI could use it), but `core/a11y/` was mid-edit by another change
+  in flight when this was built. Move `useScreenReaderEnabled`/`resetScreenReaderCache` into
+  `core/a11y` and re-export, once that edit lands, rather than leaving two near-identical stores.
 - **No stacking queue.** `show()` while visible replaces the current toast; there is no multi-toast
   queue in v1. Flagging for a future version if a consumer needs concurrent toasts.
 - **No safe-area inset awareness.** The overlay's edge inset is a fixed `theme.space[4]`; it does not
@@ -102,3 +155,9 @@ change can't silently reintroduce the gap.
 ## Performance
 
 `ToastProvider` (exported) and `ToastCard` (internal, non-exported) are both wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`) — mirrors the repo convention (e.g. `AccordionRow`) of memoizing library-internal child components too. No new `useCallback`/`useMemo` needed: the props handed to `ToastCard` (`toast`, `theme`, `position`, `progress`, `onDismiss={hide}`) were already stable — the file already used `useCallback`/`useMemo` throughout.
+
+## 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/toast/Toast.js

@@ -15,31 +15,38 @@
  * restarts the auto-dismiss timer (and, since a fresh message reads as a new event, restarts the
  * entrance animation) rather than queueing a second one. `dismiss()` always dismisses that one slot,
  * and is a safe no-op when nothing is showing.
+ *
+ * Auto-dismiss is WCAG 2.2.1 (Timing Adjustable) territory: how long a toast lives is decided ONLY
+ * by `resolveAutoDismissDelay` (persistent mode, the screen-reader suppression, the `danger`
+ * default), and the timer is only armed while the user is neither hovering nor focused inside the
+ * card. Hover/focus pause and re-arm, they never dismiss.
  */
 
 import { createContext, memo, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import { AccessibilityInfo, Animated, Pressable, StyleSheet, Text, View } from "react-native";
-import { useReducedMotion } from "../../core/a11y/index.js";
+import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
 import { Icon } from "../../core/icon/index.js";
-import { useTheme } from "../../theme/index.js";
-import { CLOSE_BUTTON_SIZE, CLOSE_HIT_SLOP, CLOSE_ICON_SIZE, DEFAULT_TOAST_DURATION, resolveToastTone, toastAccentBarStructure, toastCardStructure, toastOverlayStructure } from "./Toast.variants.js";
+import { useTheme } from "../../theme/hooks.js";
+import { CLOSE_BUTTON_SIZE, CLOSE_HIT_SLOP, CLOSE_ICON_SIZE, resolveAutoDismissDelay, resolveToastTone, toastAccentBarStructure, toastCardStructure, toastOverlayStructure } from "./Toast.variants.js";
+import { useScreenReaderEnabled } from "./toastScreenReader.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-// The entrance/exit fade+slide duration, and how far the card travels while animating in. Component
-// design constants — not on the theme's numeric scale, same status `PRESS_FADE_MS` etc. have in
-// `Button.tsx`.
-const ANIMATION_MS = 200;
-const TRANSLATE_DISTANCE = 24;
 const ToastContext = /*#__PURE__*/createContext(undefined);
 export const ToastProvider = /*#__PURE__*/memo(function ToastProvider({
   children,
   position = "top"
 }) {
   const theme = useTheme();
-  const reducedMotion = useReducedMotion();
+  const motion = useMotion();
+  const screenReaderEnabled = useScreenReaderEnabled();
   const [toast, setToast] = useState(null);
-  const progress = useRef(new Animated.Value(0)).current;
+  const progress = useAnimatedValue(0);
   const dismissTimer = useRef(null);
   const unmountTimer = useRef(null);
+  /** The visible toast's resolved delay; `null` = persistent, so no timer is ever armed for it. */
+  const delay = useRef(null);
+  // Refs, not state: pausing must not re-render the card mid-hover, and nothing renders from them.
+  const hovered = useRef(false);
+  const focused = useRef(false);
   const clearTimers = useCallback(() => {
     if (dismissTimer.current !== null) clearTimeout(dismissTimer.current);
     if (unmountTimer.current !== null) clearTimeout(unmountTimer.current);
@@ -53,31 +60,67 @@ export const ToastProvider = /*#__PURE__*/memo(function ToastProvider({
   // a second timer of the same duration keeps the removal deterministic everywhere.
   const hide = useCallback(() => {
     clearTimers();
-    Animated.timing(progress, {
-      toValue: 0,
-      duration: reducedMotion ? 0 : ANIMATION_MS,
-      useNativeDriver: true
+    // Stops a hover/focus that lands after the exit began from re-arming a timer for a gone toast.
+    delay.current = null;
+    motion.timing(progress, 0, {
+      duration: "fast",
+      easing: "accelerate"
     }).start();
-    unmountTimer.current = setTimeout(() => setToast(null), reducedMotion ? 0 : ANIMATION_MS);
-  }, [clearTimers, progress, reducedMotion]);
+    unmountTimer.current = setTimeout(() => setToast(null), motion.duration("fast"));
+  }, [clearTimers, progress, motion]);
+
+  /**
+   * The single place a dismiss timer is armed. Idempotent and safe to call from either pause
+   * source: it always clears first, then re-arms only if the toast auto-dismisses at all and the
+   * user is neither hovering nor focused inside it.
+   */
+  const armDismissTimer = useCallback(() => {
+    if (dismissTimer.current !== null) clearTimeout(dismissTimer.current);
+    dismissTimer.current = null;
+    if (delay.current === null || hovered.current || focused.current) return;
+    dismissTimer.current = setTimeout(hide, delay.current);
+  }, [hide]);
   const show = useCallback(options => {
     clearTimers();
+    // A replacement toast is a new event: whatever the pointer/focus did to the last one is spent.
+    hovered.current = false;
+    focused.current = false;
     progress.setValue(0);
+    const tone = options.tone ?? "neutral";
     setToast({
       message: options.message,
-      tone: options.tone ?? "neutral"
+      tone
     });
     // The real cross-platform screen-reader announcement: `accessibilityLiveRegion` (see
     // `ToastCard`'s Text) is Android-only, so it alone leaves iOS VoiceOver silent. This
     // imperative call reaches both VoiceOver and TalkBack.
     AccessibilityInfo.announceForAccessibility(options.message);
-    Animated.timing(progress, {
-      toValue: 1,
-      duration: reducedMotion ? 0 : ANIMATION_MS,
-      useNativeDriver: true
+    motion.timing(progress, 1, {
+      duration: "fast",
+      easing: "decelerate"
     }).start();
-    dismissTimer.current = setTimeout(hide, options.duration ?? DEFAULT_TOAST_DURATION);
-  }, [clearTimers, hide, progress, reducedMotion]);
+    delay.current = resolveAutoDismissDelay(options.duration, tone, screenReaderEnabled);
+    armDismissTimer();
+  }, [armDismissTimer, clearTimers, progress, motion, screenReaderEnabled]);
+
+  // Pause while the user is reading (WCAG 2.2.1): leaving re-arms the FULL delay rather than the
+  // remainder — the message effectively restarts, which is the generous direction.
+  const handleHoverIn = useCallback(() => {
+    hovered.current = true;
+    armDismissTimer();
+  }, [armDismissTimer]);
+  const handleHoverOut = useCallback(() => {
+    hovered.current = false;
+    armDismissTimer();
+  }, [armDismissTimer]);
+  const handleFocus = useCallback(() => {
+    focused.current = true;
+    armDismissTimer();
+  }, [armDismissTimer]);
+  const handleBlur = useCallback(() => {
+    focused.current = false;
+    armDismissTimer();
+  }, [armDismissTimer]);
 
   // Unmount-only cleanup: `clearTimers` is referentially stable (empty deps), so this never re-fires.
   useEffect(() => clearTimers, [clearTimers]);
@@ -97,7 +140,12 @@ export const ToastProvider = /*#__PURE__*/memo(function ToastProvider({
         theme: theme,
         position: position,
         progress: progress,
-        onDismiss: hide
+        offsetY: motion.transform.surfaceOffsetY,
+        onDismiss: hide,
+        onHoverIn: handleHoverIn,
+        onHoverOut: handleHoverOut,
+        onFocusIn: handleFocus,
+        onFocusOut: handleBlur
       })
     })]
   });
@@ -110,16 +158,30 @@ const ToastCard = /*#__PURE__*/memo(function ToastCard({
   theme,
   position,
   progress,
-  onDismiss
+  offsetY,
+  onDismiss,
+  onHoverIn,
+  onHoverOut,
+  onFocusIn,
+  onFocusOut
 }) {
   const toneColors = resolveToastTone(theme.colors, toast.tone);
   const translateY = progress.interpolate({
     inputRange: [0, 1],
-    outputRange: position === "top" ? [-TRANSLATE_DISTANCE, 0] : [TRANSLATE_DISTANCE, 0]
+    outputRange: position === "top" ? [-offsetY, 0] : [offsetY, 0]
   });
   return /*#__PURE__*/_jsxs(Animated.View, {
     testID: "pixelize-toast",
-    accessibilityRole: "alert",
+    accessibilityRole: "alert"
+    // W3C pointer events, not a `Pressable` wrapper: hovering to read must not turn the card into
+    // a touch responder that competes with the close button for the tap. `onFocus`/`onBlur` on a
+    // View catch focus BUBBLING out of the close button (react-native-web), which is the only
+    // focusable thing in here; the button repeats them for native, where focus does not bubble.
+    ,
+    onPointerEnter: onHoverIn,
+    onPointerLeave: onHoverOut,
+    onFocus: onFocusIn,
+    onBlur: onFocusOut,
     style: [toastCardStructure(theme), {
       backgroundColor: toneColors.background
     }, theme.elevation.lg, {
@@ -145,6 +207,10 @@ const ToastCard = /*#__PURE__*/memo(function ToastCard({
       accessibilityLabel: "Dismiss notification",
       hitSlop: CLOSE_HIT_SLOP,
       onPress: onDismiss,
+      onHoverIn: onHoverIn,
+      onHoverOut: onHoverOut,
+      onFocus: onFocusIn,
+      onBlur: onFocusOut,
       style: styles.closeButton,
       children: /*#__PURE__*/_jsx(Icon, {
         name: "x",

package/lib/module/modules/toast/Toast.variants.js

@@ -27,8 +27,44 @@ export const CLOSE_BUTTON_SIZE = 24;
 export const CLOSE_ICON_SIZE = 16;
 export const CLOSE_HIT_SLOP = slopFor(CLOSE_BUTTON_SIZE);
 
-/** `duration?: number` on `ToastOptions` defaults to this when omitted. */
+/** `duration` on `ToastOptions` defaults to this when omitted — except for `danger` (see below). */
 export const DEFAULT_TOAST_DURATION = 3000;
+
+/**
+ * How long a toast stays up. `"persistent"` = until the user dismisses it (or a later `show()`
+ * replaces it) — spelled out rather than encoded as a number, because a bare `0` at a call site
+ * reads as "no delay", not "forever".
+ */
+
+/** `setTimeout`'s delay is a 32-bit signed int; a larger value wraps and fires almost immediately. */
+export const MAX_TIMEOUT_MS = 2_147_483_647;
+
+/**
+ * WCAG 2.2.1 (Timing Adjustable) — resolves a requested duration into a real `setTimeout` delay, or
+ * `null` for "never auto-dismiss". `Toast.tsx` branches on `null` BEFORE arming the timer; nothing
+ * else in the module decides how long a toast lives.
+ *
+ * Three rules, in order:
+ *
+ * 1. **`"persistent"`, and every unusable number, mean forever.** `0`, negatives and `NaN` used to
+ *    slip past a `?? DEFAULT_TOAST_DURATION` fallback (only `null`/`undefined` are nullish) and
+ *    became `setTimeout(hide, 0)`; `Infinity` overflowed the 32-bit delay above and fired in ~1ms.
+ *    Both looked like a persistent mode and were an instant-dismiss mode. Failing towards "stays
+ *    up" is the safe direction: the card always has a close button.
+ * 2. **A running screen reader suppresses auto-dismiss entirely.** 3s is not enough to finish
+ *    speaking a message, and there is no way to replay a toast that has gone.
+ * 3. **`danger` with no explicit duration is persistent.** An error the user never finished reading
+ *    is the exact failure 2.2.1 exists to prevent, and this catalogue has no toast history to
+ *    recover it from. An explicit `duration` is still honoured — that is a deliberate caller
+ *    decision, not the default falling on an error message.
+ */
+export function resolveAutoDismissDelay(duration, tone, screenReaderEnabled) {
+  if (duration === "persistent") return null;
+  if (screenReaderEnabled) return null;
+  if (duration === undefined) return tone === "danger" ? null : DEFAULT_TOAST_DURATION;
+  if (!Number.isFinite(duration) || duration <= 0 || duration > MAX_TIMEOUT_MS) return null;
+  return duration;
+}
 /**
  * Maps `tone` onto the theme's role colours. The whole reason the prop is a closed union and not
  * `color?: string`: every colour a Toast can show is one of these role lookups, so it can never be