pixelize-native-library 1.2.0 → 1.3.0

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

@@ -12,10 +12,13 @@
  */
 
 import { memo, useCallback, useEffect, useMemo, useRef } from "react";
-import { Animated, Text, View } from "react-native";
+import { Text, View } from "react-native";
+import Reanimated, { interpolate, useAnimatedStyle } from "react-native-reanimated";
 import { Icon } from "../../core/icon/index.js";
 import { VirtualList } from "../../core/list/index.js";
-import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { Button } from "../button/index.js";
+import { useMotion, useAnimatedValue } from "../../core/motion/index.js";
+import { renderNodeSlot } from "../../core/slot/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";
@@ -25,7 +28,9 @@ const TimelineRow = /*#__PURE__*/memo(function TimelineRow({
   model,
   theme,
   colors,
-  testID
+  testID,
+  onEditNote,
+  onDeleteNote
 }) {
   const {
     item,
@@ -35,6 +40,10 @@ const TimelineRow = /*#__PURE__*/memo(function TimelineRow({
   const position = isLast ? "last" : "middle";
   const rowTestID = testID === undefined ? undefined : `${testID}-item-${index}`;
   const a11y = resolveTimelineItemAccessibility(item);
+  const leadingSlotStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize: theme.fontSizes.sm,
+    color: colors.title
+  }], [theme, colors.title]);
   return /*#__PURE__*/_jsxs(View, {
     testID: rowTestID,
     style: timelineRowStructure(),
@@ -45,7 +54,7 @@ const TimelineRow = /*#__PURE__*/memo(function TimelineRow({
       importantForAccessibility: "no-hide-descendants",
       children: [item.leading !== undefined ? /*#__PURE__*/_jsx(View, {
         testID: rowTestID === undefined ? undefined : `${rowTestID}-marker`,
-        children: item.leading
+        children: renderNodeSlot(item.leading, leadingSlotStyle)
       }) : /*#__PURE__*/_jsx(View, {
         testID: rowTestID === undefined ? undefined : `${rowTestID}-marker`,
         style: [timelineMarkerStructure(theme, {
@@ -93,12 +102,51 @@ const TimelineRow = /*#__PURE__*/memo(function TimelineRow({
           marginTop: theme.space[1]
         }],
         children: item.timestamp
-      })]
+      }), item.notes !== undefined && item.notes.length > 0 ? /*#__PURE__*/_jsx(View, {
+        style: {
+          marginTop: theme.space[2],
+          gap: theme.space[1]
+        },
+        children: item.notes.map(note => /*#__PURE__*/_jsxs(View, {
+          testID: rowTestID === undefined ? undefined : `${rowTestID}-note-${note.id}`,
+          style: {
+            flexDirection: "row",
+            alignItems: "flex-start",
+            gap: theme.space[2]
+          },
+          children: [/*#__PURE__*/_jsx(Text, {
+            style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
+              flex: 1,
+              fontSize: theme.fontSizes.sm,
+              color: colors.description
+            }],
+            children: note.body
+          }), onEditNote !== undefined ? /*#__PURE__*/_jsx(Button, {
+            variant: "ghost",
+            size: "sm",
+            icon: "pencil",
+            accessibilityLabel: "Edit note",
+            onPress: () => onEditNote(note.id),
+            testID: rowTestID === undefined ? undefined : `${rowTestID}-edit-${note.id}`
+          }) : null, onDeleteNote !== undefined ? /*#__PURE__*/_jsx(Button, {
+            variant: "ghost",
+            size: "sm",
+            icon: "trash",
+            accessibilityLabel: "Delete note",
+            onPress: () => onDeleteNote(note.id),
+            testID: rowTestID === undefined ? undefined : `${rowTestID}-delete-${note.id}`
+          }) : null]
+        }, note.id))
+      }) : null]
     })]
   });
 });
 export const Timeline = /*#__PURE__*/memo(function Timeline({
   items,
+  onAddNote,
+  onEditNote,
+  onDeleteNote,
+  notesLoading = false,
   style,
   testID
 }) {
@@ -107,10 +155,11 @@ export const Timeline = /*#__PURE__*/memo(function Timeline({
   const colors = useMemo(() => resolveTimelineColors(theme.colors), [theme.colors]);
   const reveal = useAnimatedValue(motion.decorative ? 0 : 1);
   const running = useRef(null);
+  const offsetY = motion.transform.offsetY;
   useEffect(() => {
     running.current?.stop();
     if (!motion.decorative) {
-      reveal.setValue(1);
+      reveal.value = 1;
       return;
     }
     running.current = motion.timing(reveal, 1, {
@@ -120,15 +169,12 @@ export const Timeline = /*#__PURE__*/memo(function Timeline({
     return () => running.current?.stop();
   }, [motion, reveal]);
   useEffect(() => () => running.current?.stop(), []);
-  const revealStyle = useMemo(() => ({
-    opacity: reveal,
+  const revealStyle = useAnimatedStyle(() => ({
+    opacity: reveal.value,
     transform: [{
-      translateY: reveal.interpolate({
-        inputRange: [0, 1],
-        outputRange: [motion.transform.offsetY, 0]
-      })
+      translateY: interpolate(reveal.value, [0, 1], [offsetY, 0])
     }]
-  }), [reveal, motion.transform.offsetY]);
+  }));
   const rootStyle = useMemo(() => [revealStyle, style], [revealStyle, style]);
   const rows = useMemo(() => items.map((item, index) => ({
     item,
@@ -142,28 +188,39 @@ export const Timeline = /*#__PURE__*/memo(function Timeline({
     model: row,
     theme: theme,
     colors: colors,
-    testID: testID
-  }), [theme, colors, testID]);
+    testID: testID,
+    onEditNote: onEditNote,
+    onDeleteNote: onDeleteNote
+  }), [theme, colors, testID, onEditNote, onDeleteNote]);
+  const addNoteControl = onAddNote !== undefined ? /*#__PURE__*/_jsx(Button, {
+    variant: "outline",
+    label: "Add note",
+    onPress: onAddNote,
+    loading: notesLoading,
+    testID: testID ? `${testID}-add-note` : undefined
+  }) : null;
   if (items.length >= VIRTUALIZE_THRESHOLD) {
-    return /*#__PURE__*/_jsx(Animated.View, {
+    return /*#__PURE__*/_jsxs(Reanimated.View, {
       testID: testID,
       style: rootStyle,
-      children: /*#__PURE__*/_jsx(VirtualList, {
+      children: [/*#__PURE__*/_jsx(VirtualList, {
         data: rows,
         keyExtractor: keyExtractor,
         renderItem: renderItem
-      })
+      }), addNoteControl]
     });
   }
-  return /*#__PURE__*/_jsx(Animated.View, {
+  return /*#__PURE__*/_jsxs(Reanimated.View, {
     testID: testID,
     style: rootStyle,
-    children: rows.map(row => /*#__PURE__*/_jsx(TimelineRow, {
+    children: [rows.map(row => /*#__PURE__*/_jsx(TimelineRow, {
       model: row,
       theme: theme,
       colors: colors,
-      testID: testID
-    }, keyExtractor(row)))
+      testID: testID,
+      onEditNote: onEditNote,
+      onDeleteNote: onDeleteNote
+    }, keyExtractor(row))), addNoteControl]
   });
 });
 //# sourceMappingURL=Timeline.js.map

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

@@ -14,6 +14,7 @@
  * (mocking only `react-native`'s `StyleSheet`, as `core/style` and every sibling module's tests do).
  */
 
+import { MIN_TOUCH_TARGET } from "../../core/a11y/touchTarget.js";
 import { createThemedVariants, createVariants } from "../../core/style/index.js";
 /**
  * Timeline-specific dimensions. Kept a plain constant — no theme dependency — same as
@@ -33,6 +34,7 @@ export const TIMELINE_MARKER = {
  * `tone`/`color` prop to widen: every event reads identically, so every colour Timeline can show is
  * one of these role lookups, guaranteed legible in both modes.
  */
+export { MIN_TOUCH_TARGET };
 export function resolveTimelineColors(colors) {
   return {
     markerFill: colors.accent.solid,

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

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

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

@@ -43,11 +43,14 @@ 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).
+`MOTION_TRANSFORM.surfaceOffsetY`, so the device tier's `durationScale` and `MOTION_SCALE`/
+`MOTION_ENABLED` all reach 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). The card also carries `LinearTransition` (with
+`ReduceMotion.System`) so a replacing toast reflows without a second fade/slide.
+
+`show()` fires `useHaptics().notification("success")` for a `success` toast and
+`notification("error")` for a `danger` one; other tones are silent.
 
 ## Auto-dismiss timing (WCAG 2.2.1 — Timing Adjustable)
 
@@ -74,10 +77,9 @@ place that decides whether a toast's timer gets armed. `Toast.tsx` branches on i
   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
+- **`tone: "danger"` with no explicit `duration` defaults to persistent**, unlike every other tone,
+  so `show({ message, tone: "danger" })` stays up until dismissed. An explicit `duration` on a
+  `danger` toast is still honoured. 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
@@ -145,10 +147,10 @@ change can't silently reintroduce the gap.
   `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
-  read device safe-area insets (notch/home-indicator). `react-native-safe-area-context` is already an
-  optional peer dependency for this catalogue but no module wires it yet — a consumer on a notched
-  device may want to add its own top padding via screen-level layout until this is revisited.
+- **Top position has no safe-area inset awareness.** `position: "bottom"` adds the same static
+  iOS home-indicator approximation Drawer/BottomSheet use (`resolveToastBottomInset`); `top`
+  reads a fixed `theme.space[4]` with no notch awareness — a consumer on a notched device may want
+  its own top padding via screen-level layout until `react-native-safe-area-context` is a real peer.
 - Render tests need `@testing-library/react-native` + a react-native jest preset (same
   dependency-pending note as `Button.render.test.tsx`).
 
@@ -156,8 +158,3 @@ change can't silently reintroduce the gap.
 
 `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

@@ -23,11 +23,15 @@
  */
 
 import { createContext, memo, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
-import { AccessibilityInfo, Animated, Pressable, StyleSheet, Text, View } from "react-native";
-import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { AccessibilityInfo, Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import Reanimated, { interpolate, LinearTransition, ReduceMotion, useAnimatedStyle } from "react-native-reanimated";
+import { useMotion, useAnimatedValue } from "../../core/motion/index.js";
+import { useHaptics } from "../../core/haptics/index.js";
 import { Icon } from "../../core/icon/index.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 { elevation, floatingSurfaceStyle, highlight } from "../../theme/platform/index.js";
+import { elevation as elevationTokens } from "../../theme/tokens/primitives/index.js";
+import { CLOSE_BUTTON_SIZE, CLOSE_HIT_SLOP, CLOSE_ICON_SIZE, resolveAutoDismissDelay, resolveToastBottomInset, resolveToastTone, toastAccentBarStructure, toastCardStructure, toastOverlayStructure } from "./Toast.variants.js";
 import { useScreenReaderEnabled } from "./toastScreenReader.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const ToastContext = /*#__PURE__*/createContext(undefined);
@@ -37,6 +41,7 @@ export const ToastProvider = /*#__PURE__*/memo(function ToastProvider({
 }) {
   const theme = useTheme();
   const motion = useMotion();
+  const haptics = useHaptics();
   const screenReaderEnabled = useScreenReaderEnabled();
   const [toast, setToast] = useState(null);
   const progress = useAnimatedValue(0);
@@ -85,12 +90,17 @@ export const ToastProvider = /*#__PURE__*/memo(function ToastProvider({
     // 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);
+    progress.value = 0;
     const tone = options.tone ?? "neutral";
     setToast({
       message: options.message,
       tone
     });
+    if (tone === "success") {
+      haptics.notification("success");
+    } else if (tone === "danger") {
+      haptics.notification("error");
+    }
     // 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.
@@ -101,7 +111,7 @@ export const ToastProvider = /*#__PURE__*/memo(function ToastProvider({
     }).start();
     delay.current = resolveAutoDismissDelay(options.duration, tone, screenReaderEnabled);
     armDismissTimer();
-  }, [armDismissTimer, clearTimers, progress, motion, screenReaderEnabled]);
+  }, [armDismissTimer, clearTimers, progress, motion, screenReaderEnabled, haptics]);
 
   // 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.
@@ -128,13 +138,19 @@ export const ToastProvider = /*#__PURE__*/memo(function ToastProvider({
     show,
     dismiss: hide
   }), [show, hide]);
+  const overlayStyle = useMemo(() => position === "bottom" ? [toastOverlayStructure(theme, {
+    position
+  }), {
+    bottom: resolveToastBottomInset(theme.space[4], Platform.OS)
+  }] : toastOverlayStructure(theme, {
+    position
+  }), [theme, position]);
   return /*#__PURE__*/_jsxs(ToastContext.Provider, {
     value: contextValue,
     children: [children, /*#__PURE__*/_jsx(View, {
-      pointerEvents: "box-none",
-      style: toastOverlayStructure(theme, {
-        position
-      }),
+      style: [overlayStyle, {
+        pointerEvents: 'box-none'
+      }],
       children: toast !== null && /*#__PURE__*/_jsx(ToastCard, {
         toast: toast,
         theme: theme,
@@ -166,59 +182,63 @@ const ToastCard = /*#__PURE__*/memo(function ToastCard({
   onFocusOut
 }) {
   const toneColors = resolveToastTone(theme.colors, toast.tone);
-  const translateY = progress.interpolate({
-    inputRange: [0, 1],
-    outputRange: position === "top" ? [-offsetY, 0] : [offsetY, 0]
-  });
-  return /*#__PURE__*/_jsxs(Animated.View, {
+
+  // Shadow/elevation only — `toneColors.background` is the one painted background.
+  const floatingStyle = useMemo(() => {
+    highlight("subtle", theme.mode);
+    elevation(elevationTokens.sm);
+    void theme.elevatedSurfaces;
+    return floatingSurfaceStyle(theme, "sm");
+  }, [theme]);
+  const cardMotion = useAnimatedStyle(() => ({
+    opacity: progress.value,
+    transform: [{
+      translateY: interpolate(progress.value, [0, 1], position === "top" ? [-offsetY, 0] : [offsetY, 0])
+    }]
+  }));
+  return /*#__PURE__*/_jsx(Reanimated.View, {
     testID: "pixelize-toast",
-    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.
-    ,
+    accessibilityRole: "alert",
     onPointerEnter: onHoverIn,
     onPointerLeave: onHoverOut,
     onFocus: onFocusIn,
     onBlur: onFocusOut,
-    style: [toastCardStructure(theme), {
+    layout: LinearTransition.reduceMotion(ReduceMotion.System),
+    style: [toastCardStructure(theme), floatingStyle, {
       backgroundColor: toneColors.background
-    }, theme.elevation.lg, {
-      opacity: progress,
-      transform: [{
-        translateY
-      }]
     }],
-    children: [/*#__PURE__*/_jsx(View, {
-      style: [toastAccentBarStructure(theme), {
-        backgroundColor: toneColors.accent
-      }]
-    }), /*#__PURE__*/_jsx(Text, {
-      numberOfLines: 3,
-      style: [theme.fontStyleForWeight(theme.fontWeights.medium), styles.message, {
-        fontSize: theme.fontSizes.sm,
-        color: toneColors.text
-      }],
-      children: toast.message
-    }), /*#__PURE__*/_jsx(Pressable, {
-      testID: "pixelize-toast-close",
-      accessibilityRole: "button",
-      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",
-        size: CLOSE_ICON_SIZE,
-        color: theme.colors.fg.muted,
-        strokeWidth: 2
-      })
-    })]
+    children: /*#__PURE__*/_jsxs(Reanimated.View, {
+      style: cardMotion,
+      children: [/*#__PURE__*/_jsx(View, {
+        style: [toastAccentBarStructure(theme), {
+          backgroundColor: toneColors.accent
+        }]
+      }), /*#__PURE__*/_jsx(Text, {
+        numberOfLines: 3,
+        style: [theme.fontStyleForWeight(theme.fontWeights.medium), styles.message, {
+          fontSize: theme.fontSizes.sm,
+          color: toneColors.text
+        }],
+        children: toast.message
+      }), /*#__PURE__*/_jsx(Pressable, {
+        testID: "pixelize-toast-close",
+        accessibilityRole: "button",
+        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",
+          size: CLOSE_ICON_SIZE,
+          color: theme.colors.fg.muted,
+          strokeWidth: 2
+        })
+      })]
+    })
   });
 });
 

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

@@ -15,12 +15,9 @@
  * `react-native`'s `StyleSheet`, as `core/style` does).
  */
 
+import { MIN_TOUCH_TARGET, slopFor } from "../../core/a11y/touchTarget.js";
 import { createThemedVariants } from "../../core/style/index.js";
-/** Same floor as Button/Input/Checkbox — 44dp (WCAG 2.5.5 / HIG). Duplicated, not imported: modules
- * stay isolated. */
-export const MIN_TOUCH_TARGET = 44;
-const slopFor = size => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - size) / 2));
-
+export { MIN_TOUCH_TARGET };
 /** The close button's own visual box + glyph. Toast takes no `size` prop, so this is a fixed pair,
  * not a scale — mirrors `BUTTON_SIZES`' shape for exactly one size. */
 export const CLOSE_BUTTON_SIZE = 24;
@@ -29,6 +26,10 @@ export const CLOSE_HIT_SLOP = slopFor(CLOSE_BUTTON_SIZE);
 
 /** `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()`
@@ -108,6 +109,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/tooltip/MODULE.md

@@ -24,6 +24,7 @@ modules, it exposes no `style` prop.
 | `label` | `string` | — | The tip's text. Also what gets merged into the trigger's `accessibilityHint`. |
 | `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. |
+| `onlyShowWhenTruncated` | `boolean` | `false` | When true, the tip opens only if the trigger's text is ellipsized (web: `scrollWidth > clientWidth`; native: `numberOfLines` truncation probe). |
 | `testID` | `string` | — | On the host `View`; also seeds `${testID}-bubble` on the visible bubble. |
 
 No `style` prop (see the file-header note) and no `tone`/`variant`/`size` — the bubble always
@@ -31,11 +32,15 @@ reads `bg.raised` / `fg.default`, so there is nothing appearance-wise for a call
 
 ## Accessibility contract (WCAG)
 
-- **1.4.13 Content on Hover or Focus — 2 of 3.** *Persistent* ✅ (no auto-dismiss on the hover/focus
+- **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* ❌
-  — see "Known gaps".
+  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
@@ -53,8 +58,9 @@ reads `bg.raised` / `fg.default`, so there is nothing appearance-wise for a call
 - **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."
+- **2.3.3** — show/hide runs through `useEnterExit` + `useMotion()`; the tween collapses to
+  `duration: 0` when motion is off, so the bubble still appears immediately — reduced motion never
+  means "no tip."
 - **Touch target** — Tooltip renders no interactive control of its own; the trigger child owns its
   own touch target (e.g. an icon `Button` already enforces ≥ 44dp via `hitSlop`).
 
@@ -65,8 +71,8 @@ reads `bg.raised` / `fg.default`, so there is nothing appearance-wise for a call
 2. **Pure, testable resolvers** in `Tooltip.variants.ts` — no React/lucide, so the WCAG measurement
    and the hint-merge contract are unit-tested against real palettes, never eyeballed.
 3. **No `{...rest}`** — composition is `React.cloneElement` on the single child (explicitly
-   sanctioned as composition, not a rest spread), injecting three named props only.
-4. **Reduced motion respected**, same `useReducedMotion()` seam as Button's press fade.
+   sanctioned as composition, not a rest spread), injecting the eight named `TooltipTriggerProps`.
+4. **Reduced motion respected**, same `useMotion()` seam as Button's press fade.
 
 ## Design decisions specific to this module
 
@@ -92,26 +98,25 @@ reads `bg.raised` / `fg.default`, so there is nothing appearance-wise for a call
 - **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 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
+  with no error. `Fab` declares all eight; `Button` declares seven — it has no `aria-describedby`,
+  so the web description link never reaches it. 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
@@ -127,10 +132,5 @@ reads `bg.raised` / `fg.default`, so there is nothing appearance-wise for a call
 
 ## Performance
 
-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`).
+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.