pixelize-native-library 1.0.7 → 1.2.1

package/lib/module/modules/bottom-nav/BottomNavTab.js

@@ -0,0 +1,162 @@
+"use strict";
+
+/**
+ * BottomNavTab — PRIVATE sub-component (not exported from `index.ts`, same status as
+ * `BottomNavOverflowSheet` / `BottomNavIconWithBadge`). ONE slot of the bar: icon + badge, label,
+ * focus ring, and the active-indicator dot. Both the core tabs and the trailing More slot render
+ * through it, so the two can never drift apart.
+ *
+ * Split out of `BottomNav.tsx`'s `coreTabs.map()` for two reasons. Rules of Hooks: the indicator's
+ * transition needs a per-tab `useEffect`, which a loop body can't hold. And re-renders: with the
+ * slot memoized, a selection change re-renders the two tabs whose `selected` actually flipped
+ * instead of the whole bar, and the press/focus handlers stop being fresh closures per render.
+ *
+ * Keyboard/AT focus lives here, not in the parent — nothing outside one tab reads it, and holding
+ * it locally keeps a focus change from re-rendering the bar.
+ */
+
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Animated, Platform, Pressable, StyleSheet, Text } from "react-native";
+import Reanimated from "react-native-reanimated";
+import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { usePressState } from "../../core/motion/usePressState.js";
+import { rippleColor, stateLayerScrim } from "../../theme/platform/stateLayer.native.js";
+import { useTheme } from "../../theme/hooks.js";
+import { BOTTOM_NAV_ACTIVE_DOT_SIZE, BOTTOM_NAV_ICON_SIZE, BOTTOM_NAV_SETTLE_SCALE, bottomNavFocusRingStructure, bottomNavTabStructure, resolveBottomNavAccessibility, resolveBottomNavBadge, resolveBottomNavDestinationAccessibilityLabel, resolveBottomNavTabColors } from "./BottomNav.variants.js";
+import { BottomNavIconWithBadge } from "./BottomNavIconWithBadge.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const AnimatedPressable = Reanimated.createAnimatedComponent(Pressable);
+export const BottomNavTab = /*#__PURE__*/memo(function BottomNavTab({
+  id,
+  label,
+  icon,
+  accessibilityLabel,
+  badgeCount,
+  badgeAppearance,
+  selected,
+  expanded,
+  onPress,
+  testID
+}) {
+  const theme = useTheme();
+  const motion = useMotion();
+  const press = usePressState(false);
+  const [focused, setFocused] = useState(false);
+  const colors = resolveBottomNavTabColors(theme.colors, selected);
+  const a11y = resolveBottomNavAccessibility({
+    selected,
+    expanded
+  });
+  const indicator = useAnimatedValue(selected ? 1 : 0);
+  const running = useRef(null);
+  const indicatorMotionStyle = useMemo(() => ({
+    opacity: indicator,
+    transform: [{
+      scale: indicator.interpolate({
+        inputRange: [0, 1],
+        outputRange: [BOTTOM_NAV_SETTLE_SCALE, 1]
+      })
+    }]
+  }), [indicator]);
+  useEffect(() => {
+    const toValue = selected ? 1 : 0;
+    running.current?.stop();
+    if (!motion.enabled) {
+      indicator.setValue(toValue);
+      return;
+    }
+    running.current = motion.timing(indicator, toValue, {
+      duration: "fast",
+      easing: selected ? "decelerate" : "accelerate"
+    });
+    running.current.start();
+    return () => running.current?.stop();
+  }, [selected, motion, indicator]);
+  useEffect(() => () => running.current?.stop(), []);
+  const handlePress = useCallback(() => onPress(id), [onPress, id]);
+  const handleFocus = useCallback(() => setFocused(true), []);
+  const handleBlur = useCallback(() => setFocused(false), []);
+  const overlayStaticStyle = useMemo(() => ({
+    backgroundColor: stateLayerScrim(theme.mode),
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous"
+  }), [theme.mode, theme.radii.md]);
+  const androidRipple = useMemo(() => Platform.OS === "android" ? {
+    color: rippleColor(theme.mode),
+    borderless: false
+  } : undefined, [theme.mode]);
+  return /*#__PURE__*/_jsxs(AnimatedPressable, {
+    testID: testID,
+    accessibilityRole: a11y.accessibilityRole,
+    accessibilityLabel: resolveBottomNavDestinationAccessibilityLabel({
+      label,
+      accessibilityLabel,
+      badge: resolveBottomNavBadge(badgeCount)
+    }),
+    "aria-selected": a11y["aria-selected"],
+    "aria-expanded": a11y["aria-expanded"],
+    "aria-disabled": a11y["aria-disabled"],
+    onPress: handlePress,
+    onPressIn: press.handlers.onPressIn,
+    onPressOut: press.handlers.onPressOut,
+    onLayout: press.onLayout,
+    onFocus: handleFocus,
+    onBlur: handleBlur,
+    android_ripple: androidRipple,
+    style: [bottomNavTabStructure(theme), {
+      overflow: "hidden"
+    }, press.animatedStyle],
+    children: [/*#__PURE__*/_jsx(Reanimated.View, {
+      pointerEvents: "none",
+      testID: testID ? `${testID}-press-overlay` : undefined,
+      style: [StyleSheet.absoluteFill, overlayStaticStyle, press.overlayStyle]
+    }), focused && /*#__PURE__*/_jsx(Animated.View, {
+      pointerEvents: "none",
+      testID: testID ? `${testID}-focus-ring` : undefined,
+      style: [bottomNavFocusRingStructure(theme), {
+        borderColor: theme.colors.border.focus
+      }]
+    }), /*#__PURE__*/_jsx(BottomNavIconWithBadge, {
+      icon: icon,
+      iconSize: BOTTOM_NAV_ICON_SIZE,
+      iconColor: colors.icon,
+      badgeCount: badgeCount,
+      appearance: badgeAppearance,
+      badgeTestID: testID ? `${testID}-badge` : undefined
+    }), /*#__PURE__*/_jsx(Text, {
+      numberOfLines: 1,
+      style: [theme.fontStyleForWeight(selected ? theme.fontWeights.semibold : theme.fontWeights.regular), {
+        fontSize: theme.fontSizes.xs,
+        color: colors.label
+      }],
+      children: label
+    }), /*#__PURE__*/_jsx(Animated.View, {
+      testID: testID ? `${testID}-indicator` : undefined,
+      style: [styles.indicator, {
+        backgroundColor: colors.indicator
+      },
+      // No animation runs under reduce motion, so the resting style is rendered directly.
+      motion.enabled ? indicatorMotionStyle : selected ? styles.indicatorShown : styles.indicatorHidden]
+    })]
+  });
+});
+const styles = StyleSheet.create({
+  indicator: {
+    width: BOTTOM_NAV_ACTIVE_DOT_SIZE,
+    height: BOTTOM_NAV_ACTIVE_DOT_SIZE,
+    borderRadius: BOTTOM_NAV_ACTIVE_DOT_SIZE / 2
+  },
+  indicatorShown: {
+    opacity: 1,
+    transform: [{
+      scale: 1
+    }]
+  },
+  indicatorHidden: {
+    opacity: 0,
+    transform: [{
+      scale: BOTTOM_NAV_SETTLE_SCALE
+    }]
+  }
+});
+//# sourceMappingURL=BottomNavTab.js.map

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

@@ -13,7 +13,8 @@ stability contract" below, the actual deliverable of this module.
 
 | File | Role |
 |------|------|
-| `BottomNav.tsx` | The component. The fixed bar: per-tab focus tracking, the active-indicator render, press → `onDestinationPress` wiring, composing `Drawer` as the sheet's shell. Data types (`BottomNavDestination`, `BottomNavOverflowSection`, `BottomNavActiveState`, `BottomNavEditConfig`) live here, same precedent as Select's `SelectOption`. |
+| `BottomNav.tsx` | The component. The fixed bar's composition only: laying out the slots (`BottomNavTab` for the core tabs AND the More slot), press → `onDestinationPress` wiring, composing `Drawer` as the sheet's shell. Data types (`BottomNavDestination`, `BottomNavOverflowSection`, `BottomNavActiveState`, `BottomNavEditConfig`) live here, same precedent as Select's `SelectOption`. |
+| `BottomNavTab.tsx` | PRIVATE — ONE bar slot (icon + badge, label, focus ring, active-indicator dot), rendered for the core tabs AND the More slot so the two can never drift. Owns the per-tab focus state and the indicator's `core/motion` transition — a `useEffect` per slot, which a `.map()` body can't hold. |
 | `BottomNavOverflowSheet.tsx` | PRIVATE (not exported) — the sheet's content: search (reuses `../input`'s `Input`), pre-search Recent row, grouped sections, edit mode, no-results state. |
 | `BottomNavIconWithBadge.tsx` | PRIVATE — a destination icon + its optional badge (count pill, or the More trigger's presence-only dot), shared by the bar tabs, the More trigger, and every sheet row so the badge renders identically everywhere. |
 | `BottomNav.variants.ts` | Pure resolvers (`resolveBottomNavTabColors`, `resolveBottomNavAccessibility`, `resolveEditRowState`, `resolveBottomNavBottomInset`, `resolveOverflowSheetHeight`; badge: `resolveBottomNavBadge`, `resolveBottomNavBadgeColors`, `resolveBottomNavOverflowBadgeTotal`, `resolveBottomNavDestinationAccessibilityLabel`) + themed structural resolvers (`bottomNavBarStructure`, `bottomNavTabStructure`, `overflowRowStructure`, `overflowSectionHeaderStructure`, `editRowStructure`, `bottomNavBadgePillStructure`). No React, no lucide. |
@@ -21,7 +22,7 @@ stability contract" below, the actual deliverable of this module.
 | `index.ts` | Public surface: `BottomNav`, `BottomNavProps`, `BottomNavActiveState`, `BottomNavDestination`, `BottomNavOverflowSection`, `BottomNavEditConfig`. Re-exports `MenuItem` (from `../menu`) and `IconName`. |
 | `__tests__/BottomNav.test.ts` | Pure: WCAG contrast (8 brands × both modes, tab + badge colours), touch-target floor, accessibility/edit-row/inset/detent/badge resolvers. |
 | `__tests__/BottomNav.search.test.ts` | Pure: levenshtein/typo-budget arithmetic, `fuzzyScore` tiering, `matchDestinations` ranking/stability/empty-query. |
-| `__tests__/BottomNav.render.test.tsx` | Render: press wiring, sheet open/close, live typo-tolerant search, Recent/grouped/no-results, edit-mode flow, opt-in quick-actions trigger, badges (pill / 0 / 99+ cap / sheet rows / More dot / a11y-label override). |
+| `__tests__/BottomNav.render.test.tsx` | Render: press wiring, the active dot (including the reduce-motion snap), sheet open/close, live typo-tolerant search, Recent/grouped/no-results, edit-mode flow, opt-in quick-actions trigger, badges (pill / 0 / 99+ cap / sheet rows / More dot / a11y-label override). |
 
 ## Props
 
@@ -113,8 +114,13 @@ imports `@react-native-async-storage/async-storage` and never reads a value it w
 ## Accessibility contract (WCAG)
 
 - **4.1.2** — bar container `accessibilityRole="tablist"`; each core tab and the More slot
-  `accessibilityRole="tab"` with `accessibilityState={{ selected, expanded }}` (`expanded` on More
-  only, tracking `moreVisible`). Sheet rows are `accessibilityRole="menuitem"`; section headers are
+  `accessibilityRole="tab"` with flat `aria-selected` / `aria-expanded` (`expanded` on More only,
+  tracking `moreVisible`; both React-drop as `undefined` when the caller doesn't pass them, so a
+  plain core tab renders neither attribute). `aria-selected`, not `aria-current`: this is a
+  `tablist`, and `aria-selected` is the signal the `tab` role defines — `aria-current="page"` marks
+  navigation links, a different pattern (`Pagination` uses it for exactly that reason). Flat, never
+  `accessibilityState={{…}}`: react-native-web discards the object form — see
+  `docs/PLATFORM-A11Y-PROPS.md`. Sheet rows are `accessibilityRole="menuitem"`; section headers are
   `accessibilityRole="header"` (same role Modal uses for its title). Badged tabs/rows announce ONE
   folded name (see Badges) — the pill's own text never leaks as a separate announcement.
 - **2.5.x target size** — `BOTTOM_NAV_HEIGHT` (56dp) asserted ≥ 44dp in a pure unit test, same
@@ -126,8 +132,12 @@ imports `@react-native-async-storage/async-storage` and never reads a value it w
 - **1.4.3 / 1.4.11** — `resolveBottomNavTabColors` measured ≥ 4.5:1 (label) and ≥ 3:1 (icon +
   indicator) against the bar's own `bg.surface`, active AND inactive, across all 8 brands × both
   modes, in `BottomNav.test.ts` — never eyeballed.
-- **2.3.3** — the edit-mode slot indicator's fade collapses to an instant `setValue` under
-  `useReducedMotion()`; the sheet's own slide/fade is inherited transitively through Drawer.
+- **2.3.3** — every animation here runs through `core/motion`'s `useMotion()` (opacity + transform
+  only, always native-driver): the active-tab dot, the badge settle, and the edit-mode slot
+  indicator. Tab presses use `usePressState` (scale + state-layer overlay). When `motion.enabled`
+  is false the animated value is `setValue`'d AND the resting style
+  is rendered outright, so the state is correct on the very first frame with no tween at all. The
+  sheet's own slide/fade is inherited transitively through Drawer.
 - **2.4.7 / 2.4.11** — a `border.focus` offset ring on keyboard/AT focus per tab, identical pattern to
   Button/Input's own ring.
 - **2.5.7 (Dragging)** — not applicable: no drag interaction anywhere in this module.
@@ -211,3 +221,17 @@ not a runtime guarantee); core tabs are not independently searchable from the sh
 ## Performance
 
 `BottomNav`, and the internal (non-exported) `BottomNavOverflowSheet`/`EditSlotChip`, are wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`) — the sheet/chip need it too or the callback stabilization below is a no-op. `closeSheet`/`handleSheetPress` and (in the overflow sheet) `handleEditToggle`/`handleSlotPress` are `useCallback`'d; a module-level `EMPTY_RECENT` constant replaces `recent ?? []` (was a fresh array every render); the `Menu` trigger element is `useMemo`'d (was a freshly-created element every render, which would defeat `Menu`'s own memo); `EditSlotChip`'s `onPress` now takes `(index: number) => void` so every chip gets the SAME stable function instead of a per-item closure.
+
+## 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.
+
+## Round 5 tonal
+
+- Bar's top hairline dropped — `floatingBackground`/`floatingSurfaceStyle` already give it a tonal
+  fill plus real shadow/`elevation`, so the extra `borderTopWidth` was redundant decorative chrome.
+- Tabs gained `android_ripple` alongside their existing state-layer overlay (Button's pattern).
+- Overflow-sheet rows and edit-slot chips gained a pressed fill (`bg.sunken`) + `android_ripple` —
+  previously plain `Pressable`s with zero visual press feedback.

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

@@ -0,0 +1,202 @@
+"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, Platform, Pressable, StyleSheet, useWindowDimensions, View } from "react-native";
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import Animated, { useAnimatedStyle, useSharedValue, withSpring, withTiming } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { useMotion } from "../../core/motion/index.js";
+import { elevation, floatingBackground, floatingSurfaceStyle, highlight } from "../../theme/platform/index.js";
+import { elevation as elevationTokens } from "../../theme/tokens/primitives/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { BOTTOM_SHEET_BACKDROP, bottomSheetGrabberStructure, bottomSheetHandleStructure, bottomSheetPanelStructure, resolveBottomSheetBottomInset, 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 bottomInset = useMemo(() => resolveBottomSheetBottomInset(theme.space[5], Platform.OS), [theme.space]);
+  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`.
+      scheduleOnRN(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 floatingStyle = useMemo(() => {
+    highlight("subtle", theme.mode);
+    elevation(elevationTokens.lg);
+    void theme.elevatedSurfaces;
+    return {
+      backgroundColor: floatingBackground(theme, "lg"),
+      ...floatingSurfaceStyle(theme, "lg")
+    };
+  }, [theme]);
+  const rootPanelStyle = useMemo(() => [bottomSheetPanelStructure(theme), floatingStyle, {
+    paddingBottom: bottomInset
+  }, panelStyle, style], [theme, floatingStyle, bottomInset, 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,59 @@
+"use strict";
+
+import { createThemedVariants } from "../../core/style/index.js";
+import { withAlpha } from "../../core/gradient/index.js";
+import { MOTION_TRANSFORM } from "../../core/motion/config.js";
+
+// Shared `scrimOpacity` knob, not a locally-guessed hex suffix — same resting value as Modal/Drawer/Menu.
+export const BOTTOM_SHEET_BACKDROP = withAlpha("#000000", MOTION_TRANSFORM.scrimOpacity);
+
+// Duplicated from Drawer's resolver on purpose — no react-native-safe-area-context peer dependency.
+export const BOTTOM_SHEET_IOS_HOME_INDICATOR_INSET = 20;
+export function resolveBottomSheetBottomInset(basePadding, platformOS) {
+  return platformOS === "ios" ? basePadding + BOTTOM_SHEET_IOS_HOME_INDICATOR_INSET : basePadding;
+}
+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.xl,
+    borderTopRightRadius: theme.radii.xl,
+    borderCurve: "continuous",
+    maxHeight: "92%"
+  }
+}));
+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,64 @@
+# 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** `scheduleOnRN(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 (`BOTTOM_SHEET_BACKDROP`) is
+`withAlpha("#000000", MOTION_TRANSFORM.scrimOpacity)` — the same shared `scrimOpacity` knob as
+Modal/Drawer/Menu's resting scrim, not a locally-guessed hex suffix — still not a palette role.
+
+## Known gaps
+
+- **No `react-native-safe-area-context` wiring** — same gap `Drawer` documents: listed as an
+  optional peer but not a real `peerDependencies` entry. Bottom padding instead uses
+  `resolveBottomSheetBottomInset` (a caller-supplied base padding + a static
+  `BOTTOM_SHEET_IOS_HOME_INDICATOR_INSET` on iOS), duplicated locally rather than sharing `Drawer`'s
+  resolver on purpose — modules never import across `src/modules/*`. Revisit once the package
+  becomes a real peer dependency.
+
+## 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