pixelize-native-library 1.0.6 → 1.2.0

package/lib/module/modules/bottom-sheet/BottomSheet.js

@@ -0,0 +1,189 @@
+"use strict";
+
+/**
+ * BottomSheet — gesture-driven snap points on a modal panel. Uses reanimated shared values for
+ * translateY and gesture-handler pan on the grabber.
+ *
+ * Timing, easing and the spring come from the global motion system (`core/motion`): the panel rides
+ * the shared `snappy` spring, the scrim fades over the shared `normal` duration, and a tier that
+ * can't afford springs falls back to a timed slide. Under reduce-motion both values are assigned
+ * outright — no tween, no frozen half-slid frame. The panel is unmounted by a timer, never by an
+ * animation callback: an interrupted animation must still unmount the sheet.
+ *
+ * Every translateY write — mount, exit, snap and swipe-dismiss — goes through `slideTo`, so the
+ * reduce-motion branch cannot be bypassed by one call site. A swipe past the dismiss threshold also
+ * reports through `onRequestClose`; the sheet is controlled, so sliding it away is not closing it.
+ */
+
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Modal as RNModal, Pressable, StyleSheet, useWindowDimensions, View } from "react-native";
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import Animated, { runOnJS, useAnimatedStyle, useSharedValue, withSpring, withTiming } from "react-native-reanimated";
+import { useMotion } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { BOTTOM_SHEET_BACKDROP, bottomSheetGrabberStructure, bottomSheetHandleStructure, bottomSheetPanelStructure, resolveBottomSheetPanelColors, resolveBottomSheetSnapOffset, resolveNearestSnapIndex } from "./BottomSheet.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** Module-level so the default never hands `snapOffsets` a fresh array identity each render. */
+const DEFAULT_SNAP_POINTS = [0.5];
+
+/** Past this fraction of the window the release is read as a dismiss, not a snap. */
+const DISMISS_PROJECTION = 0.85;
+const VELOCITY_PROJECTION = 0.05;
+export const BottomSheet = /*#__PURE__*/memo(function BottomSheet({
+  visible,
+  onRequestClose,
+  children,
+  snapPoints = DEFAULT_SNAP_POINTS,
+  initialSnapIndex = 0,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const motion = useMotion();
+  const {
+    height: windowHeight
+  } = useWindowDimensions();
+  const panelColors = useMemo(() => resolveBottomSheetPanelColors(theme.colors), [theme.colors]);
+  const [mounted, setMounted] = useState(visible);
+  const mountedRef = useRef(mounted);
+  mountedRef.current = mounted;
+  const unmountTimer = useRef(null);
+  const snapOffsets = useMemo(() => snapPoints.map(fraction => resolveBottomSheetSnapOffset(fraction, windowHeight)), [snapPoints, windowHeight]);
+  const translateY = useSharedValue(windowHeight);
+  const scrim = useSharedValue(visible ? 1 : 0);
+  const activeSnap = useSharedValue(snapOffsets[Math.min(initialSnapIndex, snapOffsets.length - 1)] ?? windowHeight);
+  const spring = motion.spring("snappy");
+  // Resolved here because `slideTo` is a worklet the pan calls from the UI thread.
+  const animated = motion.enabled;
+  const slideMs = motion.duration("slow");
+  const slideTo = useCallback(target => {
+    "worklet";
+
+    if (!animated) {
+      translateY.value = target;
+      return;
+    }
+    translateY.value = spring ? withSpring(target, spring) : withTiming(target, {
+      duration: slideMs
+    });
+  }, [animated, spring, slideMs, translateY]);
+  useEffect(() => {
+    const clearUnmount = () => {
+      if (unmountTimer.current !== null) {
+        clearTimeout(unmountTimer.current);
+        unmountTimer.current = null;
+      }
+    };
+    clearUnmount();
+    if (visible) {
+      setMounted(true);
+      const target = snapOffsets[Math.min(initialSnapIndex, snapOffsets.length - 1)] ?? 0;
+      activeSnap.value = target;
+      slideTo(target);
+      scrim.value = motion.enabled ? withTiming(1, {
+        duration: motion.duration("normal")
+      }) : 1;
+      return;
+    }
+    if (!mountedRef.current) return;
+    slideTo(windowHeight);
+    const exitMs = motion.duration("normal");
+    if (!motion.enabled || exitMs === 0) {
+      scrim.value = 0;
+      setMounted(false);
+      return;
+    }
+    scrim.value = withTiming(0, {
+      duration: exitMs
+    });
+    unmountTimer.current = setTimeout(() => {
+      unmountTimer.current = null;
+      setMounted(false);
+    }, exitMs);
+    return clearUnmount;
+  }, [visible, snapOffsets, initialSnapIndex, windowHeight, motion, slideTo, translateY, scrim, activeSnap]);
+  useEffect(() => () => {
+    if (unmountTimer.current !== null) clearTimeout(unmountTimer.current);
+  }, []);
+  const pan = useMemo(() => Gesture.Pan().onChange(e => {
+    const next = activeSnap.value + e.translationY;
+    const min = snapOffsets[snapOffsets.length - 1] ?? 0;
+    translateY.value = Math.max(min, Math.min(windowHeight, next));
+  }).onFinalize(e => {
+    const projected = activeSnap.value + e.translationY + e.velocityY * VELOCITY_PROJECTION;
+    if (projected > windowHeight * DISMISS_PROJECTION) {
+      slideTo(windowHeight);
+      // Sliding away is not closing: the panel stays mounted and `accessibilityViewIsModal`.
+      runOnJS(onRequestClose)();
+      return;
+    }
+    const index = resolveNearestSnapIndex(projected, snapOffsets);
+    const target = snapOffsets[index] ?? 0;
+    activeSnap.value = target;
+    slideTo(target);
+  }), [activeSnap, onRequestClose, slideTo, snapOffsets, translateY, windowHeight]);
+  const panelStyle = useAnimatedStyle(() => ({
+    transform: [{
+      translateY: translateY.value
+    }]
+  }));
+  const scrimStyle = useAnimatedStyle(() => ({
+    opacity: scrim.value
+  }));
+  const rootPanelStyle = useMemo(() => [bottomSheetPanelStructure(theme), {
+    backgroundColor: panelColors.background
+  }, panelStyle, style], [theme, panelColors.background, panelStyle, style]);
+  const grabberStyle = useMemo(() => [bottomSheetGrabberStructure(theme), {
+    backgroundColor: panelColors.grabber
+  }], [theme, panelColors.grabber]);
+  const backdropStyle = useMemo(() => [styles.backdrop, scrimStyle], [scrimStyle]);
+  if (!mounted) return null;
+  return /*#__PURE__*/_jsxs(RNModal, {
+    visible: mounted,
+    transparent: true,
+    animationType: "none",
+    onRequestClose: onRequestClose,
+    children: [/*#__PURE__*/_jsx(Pressable, {
+      testID: testID ? `${testID}-backdrop` : undefined,
+      accessible: false,
+      tabIndex: -1,
+      style: StyleSheet.absoluteFill,
+      onPress: onRequestClose,
+      children: /*#__PURE__*/_jsx(Animated.View, {
+        pointerEvents: "none",
+        style: backdropStyle
+      })
+    }), /*#__PURE__*/_jsx(View, {
+      style: styles.overlay,
+      pointerEvents: "box-none",
+      children: /*#__PURE__*/_jsxs(Animated.View, {
+        testID: testID ? `${testID}-panel` : undefined,
+        accessibilityViewIsModal: true,
+        onAccessibilityEscape: onRequestClose,
+        style: rootPanelStyle,
+        children: [/*#__PURE__*/_jsx(GestureDetector, {
+          gesture: pan,
+          children: /*#__PURE__*/_jsx(View, {
+            testID: testID ? `${testID}-handle` : undefined,
+            style: bottomSheetHandleStructure(theme),
+            accessibilityElementsHidden: true,
+            importantForAccessibility: "no-hide-descendants",
+            children: /*#__PURE__*/_jsx(View, {
+              style: grabberStyle
+            })
+          })
+        }), children]
+      })
+    })]
+  });
+});
+const styles = StyleSheet.create({
+  backdrop: {
+    ...StyleSheet.absoluteFill,
+    backgroundColor: BOTTOM_SHEET_BACKDROP
+  },
+  overlay: {
+    flex: 1
+  }
+});
+//# sourceMappingURL=BottomSheet.js.map

package/lib/module/modules/bottom-sheet/BottomSheet.variants.js

@@ -0,0 +1,49 @@
+"use strict";
+
+import { createThemedVariants } from "../../core/style/index.js";
+export const BOTTOM_SHEET_BACKDROP = "#00000080";
+export function resolveBottomSheetSnapOffset(snapFraction, windowHeight) {
+  const clamped = Math.max(0.1, Math.min(0.95, snapFraction));
+  return windowHeight * (1 - clamped);
+}
+export function resolveNearestSnapIndex(offsetY, snapOffsets) {
+  let best = 0;
+  let bestDist = Number.POSITIVE_INFINITY;
+  snapOffsets.forEach((offset, index) => {
+    const dist = Math.abs(offset - offsetY);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = index;
+    }
+  });
+  return best;
+}
+// The grabber is the panel's only drag target (WCAG 1.4.11); `border.default` measured 1.16–1.43:1.
+export function resolveBottomSheetPanelColors(colors) {
+  return {
+    background: colors.bg.surface,
+    grabber: colors.border.interactive
+  };
+}
+export const bottomSheetPanelStructure = createThemedVariants(theme => ({
+  base: {
+    borderTopLeftRadius: theme.radii.lg,
+    borderTopRightRadius: theme.radii.lg,
+    maxHeight: "92%",
+    paddingBottom: theme.space[5]
+  }
+}));
+export const bottomSheetHandleStructure = createThemedVariants(theme => ({
+  base: {
+    alignItems: "center",
+    paddingVertical: theme.space[3]
+  }
+}));
+export const bottomSheetGrabberStructure = createThemedVariants(() => ({
+  base: {
+    width: 36,
+    height: 4,
+    borderRadius: 999
+  }
+}));
+//# sourceMappingURL=BottomSheet.variants.js.map

package/lib/module/modules/bottom-sheet/MODULE.md

@@ -0,0 +1,53 @@
+# bottom-sheet/
+
+Gesture-driven bottom sheet with configurable `snapPoints` (height fractions). reanimated + gesture-handler.
+
+## Dismissal — the sheet is CONTROLLED
+
+`visible` is owned by the consumer, so sliding the panel away is not the same as closing it. Every
+dismissal path reports through `onRequestClose` and lets the parent flip `visible`:
+
+- backdrop press, and `onAccessibilityEscape` on the panel;
+- a swipe released past `DISMISS_PROJECTION` (0.85 of the window, velocity folded in) — the gesture
+  slides the panel out **and** `runOnJS(onRequestClose)()`.
+
+The panel carries `accessibilityViewIsModal` for as long as it is mounted, so a swipe that only slid
+it off-screen would leave a VoiceOver user sealed inside an invisible modal. That is why the gesture
+reports rather than just animating.
+
+## Keyboard (web)
+
+Nothing is wired here on purpose. BottomSheet always presents through React Native's own `<Modal>`
+— it has no `ModalPortalContext` branch — so on web `react-native-web`'s `ModalContent` /
+`ModalFocusTrap` already supply Escape, Tab confinement and focus restore. Adding
+`core/a11y/keyboard` on top would mean two Escape listeners and two competing traps on one sheet.
+`__tests__/BottomSheet.keyboard.web.test.tsx` asserts that absence so it stays deliberate.
+
+## Motion contract
+
+- Every `translateY` write — mount, exit, snap and swipe-dismiss — goes through **`slideTo`**, a
+  worklet callable from both threads. One call site cannot bypass the reduce-motion branch.
+- `slideTo` reads `motion.enabled` / `motion.duration("slow")` resolved on the JS thread; the UI
+  thread cannot call them.
+- Reduce motion / motion disabled → `translateY` and `scrim` are assigned outright, no tween.
+  **Never** `withSpring(target, spring ?? undefined)`: `motion.spring()` returns `null` exactly when
+  reduce-motion is on, and `?? undefined` hands reanimated its *default* spring — slower and
+  bouncier than the `snappy` preset, i.e. more motion for the user who asked for less (WCAG 2.3.3).
+- Unmount is driven by a timer, never by an animation callback.
+
+## Colour
+
+`resolveBottomSheetPanelColors` → `bg.surface` for the panel, **`border.interactive`** for the
+grabber. The grabber is the sheet's only drag target (the pan is attached to the handle, not the
+panel body), so WCAG 1.4.11 applies: the previous `border.default` is the decorative boundary role
+and measured **1.16–1.43:1** on the surface across all 18 palettes. `border.interactive` clears 3:1
+everywhere (min 3.32, emerald light). The backdrop is a fixed `#00000080` scrim, not a palette role.
+
+## Tests
+
+- `BottomSheet.test.ts` — snap math + contrast measured over all 9 brands × both modes
+  (`AA_TEXT` for content on the panel, `AA_NON_TEXT` for the grabber) + role bindings.
+- `BottomSheet.render.test.tsx` — the swipe-dismiss → `onRequestClose` contract.
+- `BottomSheet.motion.test.tsx` — both halves of the reduce-motion contract. reanimated shared
+  values have no JS driver to force in, so `withSpring`/`withTiming` are mocked and a target written
+  as a plain number is the proof that nothing animated.

package/lib/module/modules/bottom-sheet/index.js

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

package/lib/module/modules/button/Button.js

@@ -7,11 +7,11 @@
  * resolve, how `tone` maps to role colours, how accessibility is wired, and the shape of the tests.
  */
 
-import { memo, useRef, useState } from "react";
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { ActivityIndicator, Animated, Pressable, StyleSheet, Text, View } from "react-native";
-import { useReducedMotion } from "../../core/a11y/index.js";
+import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
 import { Icon } from "../../core/icon/index.js";
-import { useTheme } from "../../theme/index.js";
+import { useTheme } from "../../theme/hooks.js";
 import { BUTTON_SIZES, buttonStructure, resolveButtonAccessibility, resolveButtonTone } from "./Button.variants.js";
 
 /** A button with a visible text label. `accessibilityLabel` defaults to `label`. */
@@ -22,7 +22,6 @@ import { BUTTON_SIZES, buttonStructure, resolveButtonAccessibility, resolveButto
  * files, and tooltips do not exist on touch). `label?: never` makes the two shapes mutually exclusive.
  */
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-const PRESS_FADE_MS = 120;
 const ICON_STROKE = 2;
 // State-layer scrims. Direction is chosen by the label's brightness so the fill moves AWAY from the
 // label on press — its contrast can only rise. 8-digit hex carries the alpha (~15%) directly.
@@ -33,6 +32,9 @@ const PRESS_SCRIM_LIGHT = "#ffffff26";
 const FOCUS_RING_WIDTH = 2;
 const FOCUS_RING_GAP = 2;
 
+// The press scale has to sit on the same node `style` lands on, so the contract's "style last" holds.
+const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
+
 /** Cheap perceived-brightness split; `onFill` is only ever a near-white or near-black role value. */
 function isLight(hex) {
   const n = parseInt(hex.slice(1, 7), 16);
@@ -50,65 +52,131 @@ function ButtonImpl(props) {
     iconPosition = "leading",
     loading = false,
     disabled = false,
+    selected,
     fullWidth = false,
     onPress,
+    onLongPress,
+    onPressOut,
+    onHoverIn,
+    onHoverOut,
+    onFocus,
+    onBlur,
     style,
     testID,
     label,
-    accessibilityLabel
+    accessibilityLabel,
+    accessibilityHint
   } = props;
   const theme = useTheme();
-  const reducedMotion = useReducedMotion();
-  const overlay = useRef(new Animated.Value(0)).current;
+  const motion = useMotion();
+  const pressed = useAnimatedValue(0);
+  const running = useRef(null);
   // Keyboard / external-keyboard / assistive-tech focus (no-op on pure touch, correct everywhere else).
   const [focused, setFocused] = useState(false);
   const spec = BUTTON_SIZES[size];
-  const toneColors = resolveButtonTone(theme.colors, tone);
+  const toneColors = useMemo(() => resolveButtonTone(theme.colors, tone), [theme.colors, tone]);
   const iconOnly = label === undefined;
   const foreground = variant === "solid" ? toneColors.onFill : toneColors.text;
   const overlayColor = variant === "solid" ? isLight(toneColors.onFill) ? PRESS_SCRIM_DARK : PRESS_SCRIM_LIGHT : toneColors.subtle;
-  const a11y = resolveButtonAccessibility({
+  const a11y = useMemo(() => resolveButtonAccessibility({
     label,
     accessibilityLabel,
     disabled,
     loading,
+    selected,
     onPress
-  });
-  const setPressed = pressed => {
-    Animated.timing(overlay, {
-      toValue: pressed ? 1 : 0,
-      duration: reducedMotion ? 0 : PRESS_FADE_MS,
-      useNativeDriver: true
-    }).start();
-  };
-  const glyph = name => /*#__PURE__*/_jsx(Icon, {
+  }), [label, accessibilityLabel, disabled, loading, selected, onPress]);
+  const setPressed = useCallback(isPressed => {
+    running.current?.stop();
+    const toValue = isPressed ? 1 : 0;
+    if (!motion.enabled) {
+      pressed.setValue(toValue);
+      return;
+    }
+    running.current = motion.timing(pressed, toValue, {
+      duration: "fast"
+    });
+    running.current.start();
+  }, [motion, pressed]);
+  useEffect(() => () => running.current?.stop(), []);
+
+  // Own state first, then the incoming handler — an outer handler that throws can never strand the
+  // press/focus ring in its active state.
+  const handlePressIn = useCallback(() => setPressed(true), [setPressed]);
+  const handlePressOut = useCallback(event => {
+    setPressed(false);
+    onPressOut?.(event);
+  }, [setPressed, onPressOut]);
+  const handleFocus = useCallback(event => {
+    setFocused(true);
+    onFocus?.(event);
+  }, [onFocus]);
+  const handleBlur = useCallback(event => {
+    setFocused(false);
+    onBlur?.(event);
+  }, [onBlur]);
+
+  // One value, two consumers: the state-layer opacity and the root's press scale.
+  const scaleStyle = useMemo(() => ({
+    transform: [{
+      scale: pressed.interpolate({
+        inputRange: [0, 1],
+        outputRange: [1, motion.transform.pressScale]
+      })
+    }]
+  }), [pressed, motion.transform.pressScale]);
+  const overlayStyle = useMemo(() => [StyleSheet.absoluteFill, {
+    backgroundColor: overlayColor,
+    opacity: pressed,
+    borderRadius: theme.radii.base,
+    pointerEvents: "none"
+  }], [overlayColor, pressed, theme.radii.base]);
+  const focusRingStyle = useMemo(() => ({
+    position: "absolute",
+    pointerEvents: "none",
+    top: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    left: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    right: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    bottom: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    borderWidth: FOCUS_RING_WIDTH,
+    borderColor: theme.colors.border.focus,
+    borderRadius: theme.radii.base + FOCUS_RING_GAP + FOCUS_RING_WIDTH
+  }), [theme.colors.border.focus, theme.radii.base]);
+  const glyph = useCallback(name => /*#__PURE__*/_jsx(Icon, {
     name: name,
     size: spec.iconSize,
     color: foreground,
     strokeWidth: ICON_STROKE
-  });
+  }), [spec.iconSize, foreground]);
 
   // The spinner is never the sole loading signal — `accessibilityState.busy` announces it, and the
   // label (when present) stays visible. Hidden from AT so it isn't read as a separate element.
-  const spinner = /*#__PURE__*/_jsx(ActivityIndicator, {
+  const spinner = useMemo(() => /*#__PURE__*/_jsx(ActivityIndicator, {
     size: "small",
     color: foreground,
     accessibilityElementsHidden: true,
     importantForAccessibility: "no-hide-descendants"
-  });
+  }), [foreground]);
   const leading = loading ? spinner : icon && (iconPosition === "leading" || iconOnly) ? glyph(icon) : null;
   const trailing = !loading && icon && iconPosition === "trailing" && !iconOnly ? glyph(icon) : null;
-  return /*#__PURE__*/_jsxs(Pressable, {
+  return /*#__PURE__*/_jsxs(AnimatedPressable, {
     testID: testID,
     accessibilityRole: a11y.accessibilityRole,
     accessibilityLabel: a11y.accessibilityLabel,
+    accessibilityHint: accessibilityHint,
+    "aria-disabled": a11y["aria-disabled"],
+    "aria-busy": a11y["aria-busy"],
+    "aria-pressed": a11y["aria-pressed"],
     accessibilityState: a11y.accessibilityState,
     disabled: a11y.disabled,
     onPress: a11y.onPress,
-    onPressIn: () => setPressed(true),
-    onPressOut: () => setPressed(false),
-    onFocus: () => setFocused(true),
-    onBlur: () => setFocused(false),
+    onLongPress: onLongPress,
+    onPressIn: handlePressIn,
+    onPressOut: handlePressOut,
+    onHoverIn: onHoverIn,
+    onHoverOut: onHoverOut,
+    onFocus: handleFocus,
+    onBlur: handleBlur,
     hitSlop: spec.hitSlop,
     style: [buttonStructure(theme, {
       variant,
@@ -120,30 +188,13 @@ function ButtonImpl(props) {
     }, iconOnly && {
       paddingHorizontal: 0,
       minWidth: spec.height
-    }, fullWidth && styles.fullWidth, (disabled || loading) && styles.dimmed, style],
+    }, fullWidth && styles.fullWidth, scaleStyle, (disabled || loading) && styles.dimmed, style],
     children: [/*#__PURE__*/_jsx(Animated.View, {
-      pointerEvents: "none"
-      // Matches the control's own radius: the control isn't `overflow: hidden` (that would clip the
-      // focus ring below), so the state layer rounds itself instead of showing square corners.
-      ,
-      style: [StyleSheet.absoluteFill, {
-        backgroundColor: overlayColor,
-        opacity: overlay,
-        borderRadius: theme.radii.base
-      }]
+      testID: "button-press-overlay",
+      style: overlayStyle
     }), focused && /*#__PURE__*/_jsx(View, {
-      pointerEvents: "none",
       testID: "button-focus-ring",
-      style: {
-        position: "absolute",
-        top: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
-        left: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
-        right: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
-        bottom: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
-        borderWidth: FOCUS_RING_WIDTH,
-        borderColor: theme.colors.border.focus,
-        borderRadius: theme.radii.base + FOCUS_RING_GAP + FOCUS_RING_WIDTH
-      }
+      style: focusRingStyle
     }), leading, label !== undefined && /*#__PURE__*/_jsx(Text, {
       numberOfLines: 1,
       style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {

package/lib/module/modules/button/Button.variants.js

@@ -96,10 +96,13 @@ export function resolveButtonTone(colors, tone) {
  *  - disabled OR loading blocks the press (guarded `onPress` AND the `disabled` prop), so a loading
  *    button is non-interactive while it works.
  *
- * `accessibilityState.disabled` tracks the same `blocked` flag the `Pressable disabled` prop uses, so
- * what a screen reader hears matches what actually renders: a loading button announces `busy` AND
- * `disabled` (RN's `disabled` prop forces `disabled` into the state regardless). Reporting `busy` here
- * while the rendered control forced `disabled` back to true would be a lie to assistive tech.
+ * `aria-disabled` tracks the same `blocked` flag the `Pressable disabled` prop uses, so what a screen
+ * reader hears matches what actually renders: a loading button announces `busy` AND `disabled` (RN's
+ * `disabled` prop forces `disabled` into the state regardless). Reporting `busy` here while the
+ * rendered control forced `disabled` back to true would be a lie to assistive tech.
+ *
+ * `selected` is only exposed when the CALLER passed it, mirroring `resolveChipAccessibility`: an
+ * ordinary button has no toggle state and must not announce "not pressed" as if it had one.
  */
 export function resolveButtonAccessibility(input) {
   const isDisabled = input.disabled === true;
@@ -108,9 +111,11 @@ export function resolveButtonAccessibility(input) {
   return {
     accessibilityRole: "button",
     accessibilityLabel: input.accessibilityLabel ?? input.label,
-    accessibilityState: {
-      disabled: blocked,
-      busy: isLoading
+    "aria-disabled": blocked,
+    "aria-busy": isLoading,
+    "aria-pressed": input.selected,
+    accessibilityState: input.selected === undefined ? undefined : {
+      selected: input.selected
     },
     disabled: blocked,
     onPress: blocked ? undefined : input.onPress

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

@@ -28,7 +28,12 @@ and 195 web usages). It is also the **reference module**: the other 16 component
 | `disabled` | `boolean` | `false` | Dimmed; blocks press. |
 | `fullWidth` | `boolean` | `false` | `alignSelf: stretch`. |
 | `onPress` | `() => void` | — | Gated off while disabled/loading. |
+| `onLongPress` | `(e) => void` | — | Passed straight through. Setting it makes RN's `Pressable` route a long press here instead of `onPress`. |
+| `onPressOut` / `onFocus` / `onBlur` | `(e) => void` | — | Chained AFTER Button's own press/focus ring, never replacing it. |
+| `onHoverIn` / `onHoverOut` | `(e) => void` | — | Passed through; only react-native-web (and desktop RN) emits them. |
 | `accessibilityLabel` | `string` | `label` | **Required** when icon-only (type-enforced). |
+| `accessibilityHint` | `string` | — | On the control. A wrapping `Tooltip` MERGES its label into this rather than clobbering it. |
+| `selected` | `boolean` | — | Toggle state for a button that stays "on", e.g. a rich-text-editor toolbar control (Bold/Italic). ACCESSIBILITY ONLY — appearance stays with `variant`, which the caller already swaps for the active look. Omitted entirely, an ordinary button announces no pressed state at all. |
 | `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
 
 `ButtonProps` is a discriminated union: a labelled button OR an icon-only button (`label?: never` +
@@ -36,6 +41,10 @@ required `accessibilityLabel`). It is impossible to ship an unlabelled icon butt
 worst a11y trap (its tooltip was the only label on icon-only buttons in 22 files; tooltips don't
 exist on touch).
 
+The seven props above the `style` row are exactly what `Tooltip` injects via `cloneElement`. They are
+declared explicitly because `{...rest}` is banned repo-wide — an undeclared prop is silently dropped,
+so without them a tooltip on a Button never opens.
+
 ## Accessibility contract (WCAG)
 
 - **2.5.x target size** — every size reaches ≥ 44 dp; short sizes keep their height and grow the
@@ -47,10 +56,17 @@ exist on touch).
 - **2.4.7 / 2.4.11** — a visible focus ring (`border.focus`) appears on keyboard / external-keyboard /
   AT focus (`onFocus`/`onBlur`). It sits a small gap OUTSIDE the control, on the canvas, because
   `border.focus` is the role token proven ≥ 3:1 against the canvas (over a solid fill it could fail).
-- **1.4.1** — `loading` is announced via `accessibilityState.busy`, not conveyed by the spinner alone
-  (the label stays visible; the spinner is hidden from AT).
+- **1.4.1** — `loading` is announced via `aria-busy`, not conveyed by the spinner alone (the label
+  stays visible; the spinner is hidden from AT).
 - **2.3.3** — the press fade is suppressed when the OS reduce-motion setting is on.
-- `accessibilityRole="button"`, `accessibilityState` for disabled/busy, `accessibilityLabel ?? label`.
+- `accessibilityRole="button"`, flat `aria-disabled` / `aria-busy` (never `accessibilityState={{…}}`
+  — react-native-web discards the object form, see `docs/PLATFORM-A11Y-PROPS.md`),
+  `accessibilityLabel ?? label`.
+- **`selected` (toggle state)** — emits BOTH `aria-pressed` (web; the correct ARIA for a toggle
+  button, unlike `aria-selected`, which is invalid on `role="button"`) and
+  `accessibilityState={{ selected }}` (native; RNW discards this object, so it never collides with
+  the flat prop). Neither is emitted when `selected` is omitted — an ordinary button has no toggle
+  state and must not announce "not pressed".
 
 ## Why `tone` is a union, not a `color`
 
@@ -85,3 +101,9 @@ label); `accent`/`danger` map to the accent and danger roles.
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`) — renamed to `ButtonImpl` internally, exported as `Button = memo(ButtonImpl)`. Its one child, `Icon`, only ever receives primitives — nothing to memoize.
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
+- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.