pixelize-native-library 1.0.7 → 1.2.1

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

@@ -27,8 +27,48 @@ 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;
+export const TOAST_IOS_HOME_INDICATOR_INSET = 20;
+export function resolveToastBottomInset(basePadding, platformOS) {
+  return platformOS === "ios" ? basePadding + TOAST_IOS_HOME_INDICATOR_INSET : basePadding;
+}
+
+/**
+ * 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
@@ -72,6 +112,7 @@ export const toastCardStructure = createThemedVariants(theme => ({
     alignItems: "center",
     columnGap: theme.space[3],
     borderRadius: theme.radii.md,
+    borderCurve: "continuous",
     paddingVertical: theme.space[3],
     paddingRight: theme.space[3],
     overflow: "hidden"

package/lib/module/modules/toast/toastScreenReader.js

@@ -0,0 +1,69 @@
+"use strict";
+
+/**
+ * Tracks whether a screen reader is running, so `ToastProvider` can stop auto-dismissing a message
+ * the reader has not finished speaking (WCAG 2.2.1 — see `resolveAutoDismissDelay`).
+ *
+ * Shaped exactly like `core/a11y`'s `useReducedMotion`: ONE module-level store read through
+ * `useSyncExternalStore`, so the async probe and the native `screenReaderChanged` listener are
+ * opened by the first subscriber and closed when the last one leaves, however many providers mount.
+ * It lives here rather than in `core/a11y` only because that folder is owned by another change in
+ * flight — it is a `core/a11y` concern and should move there (`MODULE.md` → Known gaps).
+ *
+ * **It seeds `false`, unlike `useReducedMotion`'s pessimistic `true`.** The two hooks are read at
+ * different moments: a reduce-motion gate runs in the same commit as the mount that opens the probe,
+ * so it must assume the worst, whereas this is read by `show()` — a user-initiated event, long after
+ * `ToastProvider` mounted at the app root and the probe answered. Seeding `true` would instead make
+ * every toast in the first frames of an app run persistent for a sighted user, which is the more
+ * visible failure and the less likely one to be true.
+ */
+
+import { useSyncExternalStore } from "react";
+import { AccessibilityInfo } from "react-native";
+let lastKnownScreenReader = false;
+let nativeSubscription = null;
+/** Bumped by the test reset so a probe still in flight from a previous suite cannot land late. */
+let generation = 0;
+const listeners = new Set();
+function publish(value) {
+  if (lastKnownScreenReader === value) return;
+  lastKnownScreenReader = value;
+  for (const listener of listeners) listener();
+}
+function openNativeSubscription() {
+  const opened = generation;
+  const apply = value => {
+    if (opened === generation) publish(value);
+  };
+  void AccessibilityInfo.isScreenReaderEnabled().then(apply);
+  nativeSubscription = AccessibilityInfo.addEventListener("screenReaderChanged", apply);
+}
+function subscribe(onStoreChange) {
+  listeners.add(onStoreChange);
+  if (listeners.size === 1) openNativeSubscription();
+  return () => {
+    listeners.delete(onStoreChange);
+    if (listeners.size === 0) {
+      nativeSubscription?.remove();
+      nativeSubscription = null;
+    }
+  };
+}
+function getSnapshot() {
+  return lastKnownScreenReader;
+}
+
+/** Test-only: drops the process cache and re-probes, so a suite can drive both answers. */
+export function resetScreenReaderCache() {
+  generation += 1;
+  lastKnownScreenReader = false;
+  nativeSubscription?.remove();
+  nativeSubscription = null;
+  if (listeners.size > 0) openNativeSubscription();
+}
+
+/** Live OS screen-reader state (VoiceOver / TalkBack), one probe and one listener per process. */
+export function useScreenReaderEnabled() {
+  return useSyncExternalStore(subscribe, getSnapshot);
+}
+//# sourceMappingURL=toastScreenReader.js.map

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

@@ -1,25 +1,28 @@
-# tooltip/ — a long-press tip that also reaches screen readers without the gesture
+# tooltip/ — a hover/focus/long-press tip that also reaches screen readers without the gesture
 
 `Tooltip` wraps a single trigger element (via `React.cloneElement`, never `{...rest}`) and reveals
-a short themed bubble on long-press. It has no visual node of its own for an app to place — the
-trigger keeps its own layout — so, unlike the other modules, it exposes no `style` prop.
+a short themed bubble on hover (pointer), focus (keyboard) or long-press (touch). It has no visual
+node of its own for an app to place — the trigger keeps its own layout — so, unlike the other
+modules, it exposes no `style` prop.
 
 ## Files
 
 | File | Role |
 |------|------|
-| `Tooltip.tsx` | The component. `cloneElement` composition, show/hide timing, fade-in, a11y hint wiring. |
+| `Tooltip.tsx` | The component. `cloneElement` composition, hover/focus/press wiring, show/hide timing, fade-in, a11y hint wiring. |
 | `Tooltip.variants.ts` | Pure resolvers (`mergeAccessibilityHint`, `TOOLTIP_TIMING`) + the themed structural resolver `tooltipBubbleStructure`. No React, no lucide. |
 | `index.ts` | Public surface: `Tooltip`, `TooltipProps`, `TooltipTriggerProps`, `TooltipPlacement`. |
 | `__tests__/Tooltip.test.ts` | Pure: WCAG contrast (all brands × modes) + the hint-merge contract + timing sanity. |
-| `__tests__/Tooltip.render.test.tsx` | Render: reveal/hide, auto-hide fallback, hint merge, placement. |
+| `__tests__/Tooltip.render.test.tsx` | Render: hover/focus/long-press reveal + hide, handler chaining, auto-hide fallback, hint merge, placement. |
+| `__tests__/Tooltip.trigger.render.test.tsx` | Render, with `Button`/`Fab` as the trigger — a raw `Pressable` accepts every injected prop by construction, so only this file can catch a library trigger dropping them. |
+| `__tests__/Tooltip.escape.dom.test.tsx` | The WEB surface, under `jest.web.config.js` (jsdom + real react-native-web): Escape dismissal without moving focus, and the `aria-describedby`→bubble-`id` link. Neither exists in the default Jest project, which resolves the native no-ops. |
 
 ## Props
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `label` | `string` | — | The tip's text. Also what gets merged into the trigger's `accessibilityHint`. |
-| `children` | `ReactElement<TooltipTriggerProps>` | — | A single element accepting `onLongPress`/`onPressOut`/`accessibilityHint` (e.g. a `Pressable`). |
+| `children` | `ReactElement<TooltipTriggerProps>` | — | A single element accepting `onLongPress`/`onPressOut`/`onHoverIn`/`onHoverOut`/`onFocus`/`onBlur`/`accessibilityHint`/`aria-describedby` — `Button`, `Fab`, or a raw `Pressable`. A `Text` is **not** enough: react-native-web's `Text` handles only `onPress`, so every injected handler is dropped and the tip never opens on web. |
 | `placement` | `top \| bottom` | `bottom` | Which side of the trigger the bubble opens toward. |
 | `testID` | `string` | — | On the host `View`; also seeds `${testID}-bubble` on the visible bubble. |
 
@@ -28,16 +31,32 @@ reads `bg.raised` / `fg.default`, so there is nothing appearance-wise for a call
 
 ## Accessibility contract (WCAG)
 
-- **1.3.1 / no gesture-only content** — the whole point of this module: `accessibilityHint` on
-  the trigger is set to `mergeAccessibilityHint(existingHint, label)`, so a screen-reader user gets
-  the tip's content read out with the trigger itself, with no long-press required. The existing
-  hint (if the trigger already had one) is preserved, never overwritten.
+- **1.4.13 Content on Hover or Focus — 3 of 3.** *Persistent* ✅ (no auto-dismiss on the hover/focus
+  path — only long-press arms `autoHideMs`). *Dismissible* ✅ (Escape hides the tip via
+  `useDismissOnEscape` from `core/a11y/keyboard`, without moving focus; web-only by construction —
+  the native file is a no-op, and native has no hover/keyboard-focus tip to dismiss). *Hoverable* ✅
+  — the bubble accepts pointer events and carries its own `onPointerEnter`/`onPointerLeave` (the
+  same primitive `Toast`'s card uses for a non-`Pressable` hover target); a hover-out on the trigger
+  doesn't hide immediately, it arms `TOOLTIP_TIMING.hoverOutGraceMs` (200ms) so the pointer has time
+  to cross the `theme.space[1]` gap onto the bubble, which cancels the pending hide on entry and
+  re-arms its own grace window on exit.
+- **1.3.1 / no gesture-only content** — the whole point of this module. On **native** the trigger's
+  `accessibilityHint` is set to `mergeAccessibilityHint(existingHint, label)`, so a screen-reader
+  user gets the tip's content with the trigger itself and no long-press. The existing hint is
+  preserved, never overwritten. On **web** that prop reaches nothing (react-native-web has no
+  `accessibilityHint` at all), so the bubble carries an `id` (from `useId`) and the trigger points
+  `aria-describedby` at it for exactly as long as the bubble is mounted.
 - **1.4.3** — the bubble text (`fg.default` on `bg.raised`) is measured ≥ 4.5:1 for every brand ×
   mode. No non-text/interactive boundary to measure — the bubble has no border.
-- **The bubble is hidden from the accessibility tree** (`accessibilityElementsHidden` +
-  `importantForAccessibility="no-hide-descendants"`) once visible — its content already reached
-  assistive tech via the merged hint above, so exposing it too would double-announce the same
-  text (the same pattern as Button hiding its spinner from AT).
+- **The bubble is hidden from the accessibility tree** with `aria-hidden` — the one spelling that
+  works natively (RN maps it to `accessibilityElementsHidden` +
+  `importantForAccessibility="no-hide-descendants"`) and on web, where those two are discarded and
+  left the bubble exposed while the hint reached nothing. Being `aria-hidden` does not silence the
+  description: an `aria-describedby` target is read through the reference even when hidden, so the
+  text is announced with the trigger instead of a second time as its own node.
+- **2.2.1 Timing Adjustable — not engaged on the hover/focus path.** `show(false)` never arms a
+  timer, so a pointer/keyboard tip has no time limit at all. The 2.5s `autoHideMs` is armed only by
+  `onLongPress` — see "Known gaps".
 - **2.3.3** — the fade-in is skipped (`duration: 0`) when `useReducedMotion()` is true; the bubble
   still appears immediately, so reduced motion never means "no tip."
 - **Touch target** — Tooltip renders no interactive control of its own; the trigger child owns its
@@ -55,11 +74,18 @@ reads `bg.raised` / `fg.default`, so there is nothing appearance-wise for a call
 
 ## Design decisions specific to this module
 
-- **`onLongPress`/`onPressOut` chain, `accessibilityHint` merges.** The two gesture callbacks call
-  the child's own handler first (if any) before doing their job, so Tooltip never silently breaks
-  a trigger that already used them. `accessibilityHint` is different: it is a single string, not a
-  callback, so "never clobber" means composing the two strings via `mergeAccessibilityHint`, not
-  chaining.
+- **Six chained callbacks, one merged string.** `onLongPress`/`onPressOut`/`onHoverIn`/`onHoverOut`/
+  `onFocus`/`onBlur` each call the child's own handler first (if any) before doing their job, so
+  Tooltip never silently breaks a trigger that already used them. `accessibilityHint` is different:
+  it is a single string, not a callback, so "never clobber" means composing the two strings via
+  `mergeAccessibilityHint`, not chaining.
+- **Hover/focus are injected on every platform, not behind `Platform.OS === "web"`.** `Pressable`
+  accepts all four props everywhere and only react-native-web (and desktop RN) emits them, so a
+  platform branch would add a code path without adding behaviour.
+- **Only the long-press path arms `autoHideMs`.** A pointer/keyboard tip is closed by the matching
+  hover-out/blur; auto-dismissing it under a resting pointer would fail WCAG 1.4.13's *persistent*.
+- **Press-out does not hide a hovered tip.** A click on a hovered trigger fires `onPressOut` too;
+  hiding there would kill the tip with the pointer still on the trigger and nothing to bring it back.
 - **No measurement library (v1).** The bubble anchors to the trigger's **left edge** with a fixed
   `theme.space[1]` gap above/below (`left: 0`, `top`/`bottom: 100%`), rather than centering under
   the trigger's actual measured width. This is the sanctioned v1 simplification; it can read
@@ -67,20 +93,48 @@ reads `bg.raised` / `fg.default`, so there is nothing appearance-wise for a call
   place to fix that, not a prop added here.
 - **`sizes["3xs"]`** (the smallest step of the shared `sizes` primitive, 224dp) caps the bubble's
   width instead of a newly-invented magic number.
-- **Auto-hide fallback** (`TOOLTIP_TIMING.autoHideMs`, 2.5s) — guards against the tip staying open
-  forever if `onPressOut` never fires (a cancelled gesture, or assistive tech invoking
+- **Auto-hide fallback** (`TOOLTIP_TIMING.autoHideMs`, 2.5s) — guards against a long-press tip
+  staying open forever if `onPressOut` never fires (a cancelled gesture, or assistive tech invoking
   `onLongPress` directly without a matching press-out).
+- **The bubble's own hover pair uses `onPointerEnter`/`onPointerLeave`, not `Pressable`.** Same
+  reason as `Toast`'s card: turning the bubble into a touch responder would buy nothing and could
+  compete for gestures with whatever it's overlapping. A single `hideTimer` ref is shared between
+  the hover-out grace delay and the long-press `autoHideMs` fallback — safe because `show`/`hide`
+  always clear whichever one is pending before arming the other, so the two paths never collide.
 
 ## Known gaps
 
-- **Requires a trigger that forwards `onLongPress`/`onPressOut`/`accessibilityHint`.** A library
-  component with a closed prop contract that doesn't expose those props (e.g. this library's own
-  `Button` today) won't actually receive the gesture or the hint merge — `cloneElement` sets the
-  props on the element, but a component that destructures its own explicit prop list and ignores
-  unknown ones will simply drop them. Works today with a raw RN `Pressable`/`TouchableOpacity`, or
-  any future library component that adds these to its explicit prop list.
+- **Requires a trigger that declares the injected props.** `cloneElement` sets them on the element,
+  but the repo's `{...rest}` ban means a component only receives what its own prop list names — so
+  a trigger that doesn't declare them drops the gesture, the hover/focus reveal and the hint merge
+  with no error. `Button` and `Fab` declare all seven (each chaining Tooltip's handler after its own
+  press/focus ring); a raw RN `Pressable`/`TouchableOpacity` accepts them by construction. **Every
+  other module still drops them** — `Chip`, `CopyButton`, `ListItem`, `Switch`, `Checkbox`, `Select`
+  and the rest are not usable as triggers yet. **A plain `Text` is a trap on web** (react-native-web's
+  `Text` handles only `onPress`) — this is the bug the example app hit.
+- **`Menu` and `Tooltip` cannot nest either way.** `Menu` clones only `onPress` onto its trigger, and
+  `TooltipProps` has no `onPress`, so a Tooltip-wrapped Menu trigger never opens the menu.
+- **2.2.1 on the long-press path** — `TOOLTIP_TIMING.autoHideMs` (2.5s) is a content-set time limit
+  with no turn-off/adjust/extend, and no WCAG exception covers it. It exists as a stuck-tip guard for
+  when `onPressOut` never fires (cancelled gesture, or AT invoking `onLongPress` directly), and in
+  normal use press-out dismisses the tip first — but that does not discharge the SC. Making it
+  adjustable means a new public prop, so it is recorded here rather than changed unilaterally.
+- **Escape is shared with any enclosing overlay.** `useDismissOnEscape` listens on `document` in the
+  capture phase, so one Escape pressed over a tip inside a Drawer/Menu dismisses both. Fixing that
+  needs an opt-out in `core/a11y/keyboard`, not in this module.
+- **A keyboard Enter/Space on a focused trigger dismisses the tip** (press-out hides when not
+  hovered), and only blur-and-refocus brings it back. Judged user-initiated dismissal rather than a
+  *persistent* violation — the tip is not disappearing on its own.
 - No collision/viewport-edge detection — a bubble near a screen edge is not repositioned inward.
 
 ## Performance
 
-Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). `clearHideTimer`/`hide`/`show` are `useCallback`'d, and the `onLongPress`/`onPressOut` handlers `cloneElement` injects into the consumer-supplied `children` trigger are extracted to `handleLongPress`/`handlePressOut` (`useCallback`) instead of inline lambdas — same idiom `Menu.tsx` uses for its own trigger, since a fresh closure there would defeat a memoized trigger (e.g. this library's own `Button`).
+Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). `clearHideTimer`/`hide`/`show`/`scheduleHide` and the bubble's own `handleBubbleHoverIn`/`handleBubbleHoverOut` are all `useCallback`'d, and all six handlers `cloneElement` injects into the consumer-supplied `children` trigger are extracted to `handleLongPress`/`handlePressOut`/`handleHoverIn`/`handleHoverOut`/`handleFocus`/`handleBlur` (`useCallback`) instead of inline lambdas — same idiom `Menu.tsx` uses for its own trigger, since a fresh closure there would defeat a memoized trigger (e.g. this library's own `Button`).
+
+## 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.
+
+Button trigger focus ring is native `outline*` on the pressable (no sibling focus view).

package/lib/module/modules/tooltip/Tooltip.js

@@ -1,22 +1,40 @@
 "use strict";
 
 /**
- * Tooltip — wraps a single trigger element and reveals a short themed tip on long-press, without
- * requiring the trigger to know anything about it. No `style` prop: unlike the other modules,
- * Tooltip renders no sized node of its own for an app to place — the trigger child keeps whatever
- * layout it already has, and the wrapping host below exists only to anchor the bubble.
+ * Tooltip — wraps a single trigger element and reveals a short themed tip on hover (pointer),
+ * focus (keyboard) or long-press (touch), without requiring the trigger to know anything about it.
+ * No `style` prop: unlike the other modules, Tooltip renders no sized node of its own for an app to
+ * place — the trigger child keeps whatever layout it already has, and the wrapping host below
+ * exists only to anchor the bubble.
  *
- * Composition is `React.cloneElement` on the single child, never `{...rest}`: `onLongPress` and
- * `onPressOut` are injected (chaining any handler the child already defined, so Tooltip never
- * silently breaks a trigger that already used them), and `accessibilityHint` is MERGED via
- * `mergeAccessibilityHint` — the one prop that must never be clobbered, since it is how a
- * screen-reader user gets the tip's content without performing the gesture at all.
+ * Composition is `React.cloneElement` on the single child, never `{...rest}`: `onLongPress`,
+ * `onPressOut`, `onHoverIn`, `onHoverOut`, `onFocus` and `onBlur` are injected (each chaining any
+ * handler the child already defined, so Tooltip never silently breaks a trigger that already used
+ * them), and `accessibilityHint` is MERGED via `mergeAccessibilityHint` — the one prop that must
+ * never be clobbered, since it is how a screen-reader user gets the tip's content without
+ * performing the gesture at all.
+ *
+ * That hint reaches NOTHING on web — react-native-web has no `accessibilityHint` at all — so the
+ * bubble additionally carries an `id` and the trigger points `aria-describedby` at it while the tip
+ * is mounted. The bubble stays `aria-hidden` in both worlds: an `aria-describedby` target is read
+ * through the reference even when hidden, so this describes the trigger once instead of twice.
+ *
+ * The hover/focus pair is injected on every platform rather than behind a `Platform.OS === "web"`
+ * branch: `Pressable` accepts all four props everywhere, and only react-native-web actually emits
+ * them, so a branch would buy nothing but a cast.
+ *
+ * The bubble's reveal is the shared `useEnterExit` preset (`core/motion`): fade + a short settle,
+ * kept mounted by a timer rather than an animation callback, so an interrupted fade-out can never
+ * strand the bubble in the tree.
  */
 
-import { cloneElement, memo, useCallback, useEffect, useRef, useState } from "react";
+import { cloneElement, memo, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
 import { Animated, StyleSheet, Text, View } from "react-native";
-import { useReducedMotion } from "../../core/a11y/index.js";
-import { useTheme } from "../../theme/index.js";
+import { useDismissOnEscape } from "../../core/a11y/keyboard";
+import { useEnterExit, useMotion } from "../../core/motion/index.js";
+import { elevation, floatingBackground, floatingSurfaceStyle, highlight } from "../../theme/platform/index.js";
+import { elevation as elevationTokens } from "../../theme/tokens/primitives/index.js";
+import { useTheme } from "../../theme/hooks.js";
 import { mergeAccessibilityHint, TOOLTIP_TIMING, tooltipBubbleStructure } from "./Tooltip.variants.js";
 
 /** The subset of props Tooltip reads from / injects into its trigger child. */
@@ -28,10 +46,16 @@ export const Tooltip = /*#__PURE__*/memo(function Tooltip({
   testID
 }) {
   const theme = useTheme();
-  const reducedMotion = useReducedMotion();
+  const motion = useMotion();
   const [visible, setVisible] = useState(false);
-  const opacity = useRef(new Animated.Value(0)).current;
   const hideTimer = useRef(null);
+  const hovered = useRef(false);
+  const bubbleId = useId();
+
+  // A bubble above the trigger should settle upward, one below it downward — `useEnterExit` enters
+  // from `-offset`, so the sign flips with placement.
+  const offsetY = placement === "top" ? -motion.transform.offsetY : motion.transform.offsetY;
+  const bubble = useEnterExit(visible, offsetY);
   const clearHideTimer = useCallback(() => {
     if (hideTimer.current !== null) {
       clearTimeout(hideTimer.current);
@@ -42,63 +66,121 @@ export const Tooltip = /*#__PURE__*/memo(function Tooltip({
     clearHideTimer();
     setVisible(false);
   }, [clearHideTimer]);
-  const show = useCallback(() => {
+
+  // WCAG 1.4.13 hoverable: a hover-out doesn't hide immediately — it gives the pointer
+  // `hoverOutGraceMs` to cross the gap onto the bubble itself. Reuses `hideTimer`/`hide`: this and
+  // the long-press `autoHideMs` fallback below never overlap, since `show`/`hide` always clear
+  // whichever one is pending before arming the other.
+  const scheduleHide = useCallback(() => {
+    clearHideTimer();
+    hideTimer.current = setTimeout(hide, TOOLTIP_TIMING.hoverOutGraceMs);
+  }, [clearHideTimer, hide]);
+
+  // `autoHide` is the gesture path only: a pointer or keyboard tip must stay up as long as the
+  // trigger is hovered/focused (WCAG 1.4.13), and hover-out/blur are reliable enough not to need
+  // the fallback.
+  const show = useCallback(autoHide => {
     clearHideTimer();
     setVisible(true);
-    opacity.setValue(reducedMotion ? 1 : 0);
-    Animated.timing(opacity, {
-      toValue: 1,
-      duration: reducedMotion ? 0 : TOOLTIP_TIMING.fadeInMs,
-      useNativeDriver: true
-    }).start();
     // Fallback dismiss: guarantees the tip can't get stuck open if `onPressOut` never fires (e.g.
     // the gesture is cancelled by a scroll, or assistive tech triggers `onLongPress` directly).
-    hideTimer.current = setTimeout(hide, TOOLTIP_TIMING.autoHideMs);
-  }, [clearHideTimer, hide, opacity, reducedMotion]);
+    if (autoHide) hideTimer.current = setTimeout(hide, TOOLTIP_TIMING.autoHideMs);
+  }, [clearHideTimer, hide]);
   useEffect(() => clearHideTimer, [clearHideTimer]);
 
+  // WCAG 1.4.13 dismissible: Escape hides the tip without moving focus, so a keyboard user can
+  // uncover what the bubble overlaps. Web-only by construction — the native file is a no-op.
+  useDismissOnEscape(visible, hide);
+
   // Passed to `children` — a consumer-supplied CHILD component (typically this library's own
   // Pressable/Button) — via cloneElement, so it is memoized like any other child-bound callback
   // (same idiom `Menu.tsx` uses for its own trigger).
   const handleLongPress = useCallback(event => {
     children.props.onLongPress?.(event);
-    show();
+    show(true);
   }, [children, show]);
   const handlePressOut = useCallback(event => {
     children.props.onPressOut?.(event);
+    // A click on a hovered trigger fires press-out too; hiding there would kill the tip while the
+    // pointer is still on the trigger, and nothing would bring it back without leaving first.
+    if (!hovered.current) hide();
+  }, [children, hide]);
+  const handleHoverIn = useCallback(event => {
+    children.props.onHoverIn?.(event);
+    hovered.current = true;
+    show(false);
+  }, [children, show]);
+  const handleHoverOut = useCallback(event => {
+    children.props.onHoverOut?.(event);
+    hovered.current = false;
+    // Not an immediate hide: the pointer may be about to land on the bubble (WCAG 1.4.13
+    // hoverable) — `handleBubbleHoverIn` cancels this if it does.
+    scheduleHide();
+  }, [children, scheduleHide]);
+
+  // The bubble's own hover pair, mirroring the trigger's — same `onPointerEnter`/`onPointerLeave`
+  // primitive Toast's card uses for a non-Pressable hover target (see Toast.tsx), since turning the
+  // bubble into a `Pressable` would make it a touch responder for no reason.
+  const handleBubbleHoverIn = useCallback(() => {
+    clearHideTimer();
+  }, [clearHideTimer]);
+  const handleBubbleHoverOut = useCallback(() => {
+    // The pointer left the bubble; if it isn't back on the trigger either, the grace period starts
+    // again rather than hiding outright, since a fast re-entry (bubble -> trigger) is still valid.
+    if (!hovered.current) scheduleHide();
+  }, [scheduleHide]);
+  const handleFocus = useCallback(event => {
+    children.props.onFocus?.(event);
+    show(false);
+  }, [children, show]);
+  const handleBlur = useCallback(event => {
+    children.props.onBlur?.(event);
     hide();
   }, [children, hide]);
   const trigger = /*#__PURE__*/cloneElement(children, {
     onLongPress: handleLongPress,
     onPressOut: handlePressOut,
-    accessibilityHint: mergeAccessibilityHint(children.props.accessibilityHint, label)
+    onHoverIn: handleHoverIn,
+    onHoverOut: handleHoverOut,
+    onFocus: handleFocus,
+    onBlur: handleBlur,
+    accessibilityHint: mergeAccessibilityHint(children.props.accessibilityHint, label),
+    "aria-describedby": bubble.mounted ? bubbleId : undefined
   });
+  const bubbleStyle = useMemo(() => {
+    highlight("subtle", theme.mode);
+    elevation(elevationTokens.md);
+    void theme.elevatedSurfaces;
+    return [tooltipBubbleStructure(theme, {
+      placement
+    }), {
+      backgroundColor: floatingBackground(theme, "md"),
+      zIndex: theme.zIndices.tooltip,
+      ...floatingSurfaceStyle(theme, "md")
+    }, bubble.style];
+  }, [theme, placement, bubble.style]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize: theme.fontSizes.sm,
+    color: theme.colors.fg.default
+  }], [theme]);
   return /*#__PURE__*/_jsxs(View, {
     style: styles.host,
     testID: testID,
-    children: [trigger, visible &&
+    children: [trigger, bubble.mounted &&
     /*#__PURE__*/
-    // Hidden from the accessibility tree on purpose: the tip's content already reached
-    // screen-reader users via the merged `accessibilityHint` above, so surfacing this bubble
-    // too would announce the same text twice (the same "hide the sighted-only echo" pattern
-    // as Button's spinner).
+    // Hidden from the accessibility tree on purpose: the tip's content already reaches
+    // screen-reader users through the trigger — the merged `accessibilityHint` on native, the
+    // `aria-describedby` reference to this `id` on web — so exposing the bubble in reading
+    // order too would announce the same text twice.
     _jsx(Animated.View, {
       testID: testID ? `${testID}-bubble` : undefined,
-      pointerEvents: "none",
-      accessibilityElementsHidden: true,
-      importantForAccessibility: "no-hide-descendants",
-      style: [tooltipBubbleStructure(theme, {
-        placement
-      }), {
-        backgroundColor: theme.colors.bg.raised,
-        opacity,
-        zIndex: theme.zIndices.tooltip
-      }],
+      id: bubbleId,
+      onPointerEnter: handleBubbleHoverIn,
+      onPointerLeave: handleBubbleHoverOut,
+      "aria-hidden": true,
+      style: bubbleStyle,
       children: /*#__PURE__*/_jsx(Text, {
-        style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-          fontSize: theme.fontSizes.sm,
-          color: theme.colors.fg.default
-        }],
+        style: labelStyle,
         children: label
       })
     })]

package/lib/module/modules/tooltip/Tooltip.variants.js

@@ -17,14 +17,20 @@
 import { sizes } from "../../theme/tokens/index.js";
 import { createThemedVariants } from "../../core/style/index.js";
 /**
- * Design constants, not theme tokens — this module's own timing, not a scale other components
- * share.
+ * A dwell time, not a transition: how long a tip may stay up on its own. The fade itself has no
+ * constant here — duration, easing and the reduced-motion contract all come from the global motion
+ * system (`core/motion`).
  */
 export const TOOLTIP_TIMING = {
-  /** Fade-in duration; skipped (duration 0) when the OS reduce-motion setting is on (WCAG 2.3.3). */
-  fadeInMs: 150,
   /** Fallback auto-dismiss so a tip can't stay stuck open if `onPressOut` never fires. */
-  autoHideMs: 2500
+  autoHideMs: 2500,
+  /**
+   * Grace period before a hover-out actually hides the bubble, so a pointer crossing the
+   * `theme.space[1]` gap to the bubble itself doesn't lose the tip mid-transit (WCAG 1.4.13
+   * hoverable). The CSS/UI convention for this exact case; entering the bubble before it elapses
+   * cancels the hide.
+   */
+  hoverOutGraceMs: 200
 };
 
 /**

package/lib/module/modules/typing-indicator/MODULE.md

@@ -0,0 +1,48 @@
+# typing-indicator/
+
+Three-dot typing animation for chat threads. Static dots under reduced motion.
+
+## Motion contract
+
+- Each dot pulses `opacity` only, on the native driver, staggered by a third of the cycle. Duration
+  comes from the global motion config (`useMotion().duration("deliberate")` for a full up-down
+  cycle) — nothing here defines its own timing.
+- **The loop wraps a BARE timing, never a sequence.** `Animated.loop` only hands the loop to the
+  native driver (`_startNativeLoop`) when what it wraps reports `_isUsingNativeDriver()`, and
+  `Animated.sequence` returns `false` for that unconditionally — so a looped sequence restarts every
+  leg from the JS thread, forever (~7-8 wakeups/second on the thread that also handles incoming
+  messages). Each dot therefore loops one timing driving a 0→1 value, interpolated to
+  min→max→min opacity, and the stagger is that timing's own `delay` (one JS timeout at start-up),
+  never `Animated.delay` — which is itself a `useNativeDriver: false` timing.
+- **Gated on `motion.decorative`, not just `motion.enabled`.** Three pulsing dots are decoration;
+  the `accessibilityLabel="Typing"` is the real signal, the same argument `Spinner` makes for its
+  frozen glyph. Low/mid tiers and reduce motion get three static dots at full opacity.
+- The loop is stopped on effect cleanup **and** on unmount; a re-run always stops the previous loops
+  first, so a tier or reduce-motion change can never leave an orphaned loop running.
+
+`__tests__/TypingIndicator.motion.test.tsx` pins the native-loop handoff itself (`_startNativeLoop`
+called with `-1`), not just the rendered opacity.
+
+## Accessibility contract (WCAG)
+
+- **1.3.1 / 4.1.3** — a user not focused on the thread has no other way to learn typing started, so
+  mount speaks "Typing" once via `useAnnounce`. This is deliberately NOT a repeating or `polling`
+  announcement: the consumer mounts/unmounts this component as typing starts/stops, the effect that
+  calls `useAnnounce` fires once per mounted instance (not per pulse frame — the dots animate
+  entirely inside `Animated.Value`, which never re-renders React), and `useAnnounce` itself dedupes
+  an unchanged message. A chat that announced "Typing" every few seconds would be intolerable; this
+  announces once per typing burst, which is not that.
+- Stopping is silent by design, matching every other state swap in the library (`EmptyState`/
+  `ErrorState` don't announce their own removal either) — the ONLY prior state a departing
+  `TypingIndicator` could be compared against is "was typing", which is not itself information a
+  user needs spoken.
+
+## Props
+
+| Prop | Type | Default |
+|------|------|---------|
+| `size` | `sm \| md` | `md` |
+| `style` | `LayoutStyle` | — |
+| `testID` | `string` | — |
+
+Each dot also carries `${testID}-dot-${index}` when `testID` is given.