pixelize-native-library 1.0.7 → 1.2.0

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,28 @@ 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 — 2 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* ❌
+  — see "Known gaps".
+- **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 +70,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 +89,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).
 
 ## 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.
+- **1.4.13 *hoverable* is still unmet, and needs BOTH halves to land at once.** The bubble is
+  `pointerEvents="none"`, so a pointer can never reach the tip; and `handleHoverOut` hides
+  immediately, with no grace period for crossing the `theme.space[1]` gap between trigger and
+  bubble. Fixing only one half delivers nothing — enabling pointer events without a grace delay just
+  makes the tip vanish mid-gap. This is a behavioural redesign (a hover-tracked bubble with its own
+  hover handlers plus a close delay), deliberately not attempted as part of the flat-`aria-*`
+  migration.
+- **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` are `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.

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

@@ -1,22 +1,38 @@
 "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 { 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 +44,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 +64,91 @@ export const Tooltip = /*#__PURE__*/memo(function Tooltip({
     clearHideTimer();
     setVisible(false);
   }, [clearHideTimer]);
-  const show = useCallback(() => {
+
+  // `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;
+    hide();
+  }, [children, hide]);
+  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(() => [tooltipBubbleStructure(theme, {
+    placement
+  }), {
+    backgroundColor: theme.colors.bg.raised,
+    zIndex: theme.zIndices.tooltip
+  }, 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,
+      id: bubbleId,
       pointerEvents: "none",
-      accessibilityElementsHidden: true,
-      importantForAccessibility: "no-hide-descendants",
-      style: [tooltipBubbleStructure(theme, {
-        placement
-      }), {
-        backgroundColor: theme.colors.bg.raised,
-        opacity,
-        zIndex: theme.zIndices.tooltip
-      }],
+      "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,12 +17,11 @@
 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
 };

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.

package/lib/module/modules/typing-indicator/TypingIndicator.js

@@ -0,0 +1,98 @@
+"use strict";
+
+/**
+ * TypingIndicator — three animated dots for "someone is typing". Under reduced motion, and on any
+ * tier that can't afford decorative motion, the dots are static (WCAG 2.3.3) — the accessible
+ * "Typing" label is the real signal, exactly as `Spinner` treats its own frozen glyph.
+ *
+ * The consumer mounts and unmounts this component as typing starts and stops, so "Typing" is spoken
+ * ONCE per mount via `useAnnounce` (WCAG 4.1.3) — not on a timer, and not once per pulse: the effect
+ * fires once per mounted instance, and `useAnnounce`'s own dedup would silence a repeat regardless.
+ * A screen-reader user who is not focused on the thread would otherwise learn someone is typing only
+ * by chance, on their next swipe past this element.
+ *
+ * Each dot loops a BARE `motion.timing` over a 0→1 driver and interpolates that into the
+ * min→max→min opacity pulse. `Animated.loop` only runs natively (`_startNativeLoop`) when the
+ * animation it wraps reports `_isUsingNativeDriver()`, which `Animated.sequence` returns `false`
+ * for unconditionally — a looped sequence therefore restarts every leg from the JS thread, forever.
+ * The stagger is `TimingOptions.delay` (one JS timeout per dot at start-up) rather than
+ * `Animated.delay`, which is itself a `useNativeDriver: false` timing.
+ */
+
+import { memo, useEffect, useMemo, useRef } from "react";
+import { Animated, View } from "react-native";
+import { useAnnounce } from "../../core/a11y/index.js";
+import { useMotion } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { resolveTypingIndicatorAccessibility, TYPING_DOT_MAX_OPACITY, TYPING_DOT_MIN_OPACITY, typingDotStructure, typingIndicatorStructure } from "./TypingIndicator.variants.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+const DOT_COUNT = 3;
+/** The driver's midpoint: the peak of the pulse, and the resting value while motion is off. */
+const PULSE_PEAK = 0.5;
+export const TypingIndicator = /*#__PURE__*/memo(function TypingIndicator({
+  size = "md",
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const motion = useMotion();
+  const a11y = resolveTypingIndicatorAccessibility();
+  useAnnounce(a11y.accessibilityLabel);
+  const drivers = useRef(Array.from({
+    length: DOT_COUNT
+  }, () => new Animated.Value(PULSE_PEAK))).current;
+  const loops = useRef([]);
+  const cycleMs = motion.duration("deliberate");
+  const pulsing = motion.decorative && cycleMs > 0;
+  useEffect(() => {
+    loops.current.forEach(loop => loop.stop());
+    loops.current = [];
+    if (!pulsing) {
+      drivers.forEach(driver => driver.setValue(PULSE_PEAK));
+      return undefined;
+    }
+    loops.current = drivers.map((driver, index) => {
+      // Each iteration replays from wherever the driver sits when the loop starts.
+      driver.setValue(0);
+      const loop = Animated.loop(motion.timing(driver, 1, {
+        duration: "deliberate",
+        delay: index * cycleMs / DOT_COUNT
+      }));
+      loop.start();
+      return loop;
+    });
+    return () => {
+      loops.current.forEach(loop => loop.stop());
+      loops.current = [];
+    };
+  }, [drivers, pulsing, cycleMs, motion]);
+  useEffect(() => () => loops.current.forEach(loop => loop.stop()), []);
+  const dotColor = theme.colors.fg.muted;
+  const dotStyles = useMemo(() => {
+    const base = [typingDotStructure(theme, {
+      size
+    }), {
+      backgroundColor: dotColor
+    }];
+    return drivers.map(driver => [base, {
+      opacity: driver.interpolate({
+        inputRange: [0, PULSE_PEAK, 1],
+        outputRange: [TYPING_DOT_MIN_OPACITY, TYPING_DOT_MAX_OPACITY, TYPING_DOT_MIN_OPACITY]
+      })
+    }]);
+  }, [theme, size, dotColor, drivers]);
+  return /*#__PURE__*/_jsx(View, {
+    testID: testID,
+    accessible: a11y.accessible,
+    accessibilityRole: a11y.accessibilityRole,
+    accessibilityLabel: a11y.accessibilityLabel,
+    style: [typingIndicatorStructure(theme, {
+      size
+    }), style],
+    children: dotStyles.map((dotStyle, index) => /*#__PURE__*/_jsx(Animated.View, {
+      testID: testID === undefined ? undefined : `${testID}-dot-${index}`,
+      style: dotStyle
+    }, index))
+  });
+});
+//# sourceMappingURL=TypingIndicator.js.map

package/lib/module/modules/typing-indicator/TypingIndicator.variants.js

@@ -0,0 +1,55 @@
+"use strict";
+
+import { createThemedVariants } from "../../core/style/index.js";
+export const TYPING_DOT_SIZES = {
+  sm: 6,
+  md: 8
+};
+export const TYPING_DOT_MIN_OPACITY = 0.3;
+export const TYPING_DOT_MAX_OPACITY = 1;
+export const typingIndicatorStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    columnGap: theme.space[1],
+    paddingVertical: theme.space[2],
+    paddingHorizontal: theme.space[3]
+  },
+  variants: {
+    size: {
+      sm: {},
+      md: {}
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+export const typingDotStructure = createThemedVariants(theme => ({
+  base: {
+    borderRadius: theme.radii.full
+  },
+  variants: {
+    size: {
+      sm: {
+        width: TYPING_DOT_SIZES.sm,
+        height: TYPING_DOT_SIZES.sm
+      },
+      md: {
+        width: TYPING_DOT_SIZES.md,
+        height: TYPING_DOT_SIZES.md
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+export function resolveTypingIndicatorAccessibility() {
+  return {
+    accessible: true,
+    accessibilityRole: "text",
+    accessibilityLabel: "Typing"
+  };
+}
+//# sourceMappingURL=TypingIndicator.variants.js.map

package/lib/module/modules/typing-indicator/index.js

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