blend-native 0.0.1-beta.0 → 0.0.1-beta.2

package/src/overlay/portal.tsx

@@ -19,7 +19,11 @@ import { StyleSheet, View } from 'react-native'
  * top regardless of where in the tree the overlay was opened.
  *
  * Layers stack in mount order — the overlay opened last paints on top,
- * which matches how web portals appended to `document.body` behave.
+ * which matches how web portals appended to `document.body` behave. A layer
+ * can opt out of that with `priority`: higher-priority layers always paint
+ * above lower ones regardless of mount order (the toast/snackbar stack uses
+ * this so a sheet opened after a toast cannot cover it). Equal priorities
+ * keep mount order — the sort is stable.
  *
  * The provider must sit at a screen-filling root (the usual place for a
  * theme provider): the layers are absolutely positioned siblings of the
@@ -29,10 +33,20 @@ import { StyleSheet, View } from 'react-native'
  * overlay degrades to inline rendering rather than disappearing.
  */
 
-type PortalNode = { key: string; node: React.ReactNode }
+type PortalNode = {
+    key: string
+    node: React.ReactNode
+    priority: number
+    modal: boolean
+}
 
 type PortalRegistry = {
-    mount: (key: string, node: React.ReactNode) => void
+    mount: (
+        key: string,
+        node: React.ReactNode,
+        priority?: number,
+        modal?: boolean
+    ) => void
     unmount: (key: string) => void
 }
 
@@ -40,18 +54,31 @@ const PortalRegistryContext = createContext<PortalRegistry | null>(null)
 
 let warnedNoProvider = false
 
-export type PortalProps = { children?: React.ReactNode }
+export type PortalProps = {
+    children?: React.ReactNode
+    /** Paint above lower-priority layers regardless of mount order. */
+    priority?: number
+    /**
+     * Hide everything painted below this layer from assistive tech while it
+     * is mounted: the app's content and every lower layer get
+     * `importantForAccessibility="no-hide-descendants"` (TalkBack) and
+     * `accessibilityElementsHidden` (VoiceOver). iOS's
+     * `accessibilityViewIsModal` only fences siblings; this is the pair that
+     * actually works on Android. The topmost modal layer wins.
+     */
+    modal?: boolean
+}
 
 /** Renders `children` into the provider's overlay layer. */
-export function Portal({ children }: PortalProps) {
+export function Portal({ children, priority = 0, modal = false }: PortalProps) {
     const registry = useContext(PortalRegistryContext)
     const key = useId()
 
     useEffect(() => {
         if (!registry) return
-        registry.mount(key, children)
+        registry.mount(key, children, priority, modal)
         return () => registry.unmount(key)
-    }, [registry, key, children])
+    }, [registry, key, children, priority, modal])
 
     // In an effect, not during render — warning inline would be a
     // render-phase side effect (breaks under StrictMode double-render, the
@@ -81,16 +108,21 @@ Portal.displayName = 'Portal'
 export function PortalArea({ children }: { children?: React.ReactNode }) {
     const [portals, setPortals] = useState<PortalNode[]>([])
 
-    const mount = useCallback((key: string, node: React.ReactNode) => {
-        setPortals((current) => {
-            const existing = current.findIndex((p) => p.key === key)
-            if (existing === -1) return [...current, { key, node }]
-            // Re-mount with new content keeps its layer position.
-            const next = current.slice()
-            next[existing] = { key, node }
-            return next
-        })
-    }, [])
+    const mount = useCallback(
+        (key: string, node: React.ReactNode, priority = 0, modal = false) => {
+            setPortals((current) => {
+                const existing = current.findIndex((p) => p.key === key)
+                if (existing === -1) {
+                    return [...current, { key, node, priority, modal }]
+                }
+                // Re-mount with new content keeps its layer position.
+                const next = current.slice()
+                next[existing] = { key, node, priority, modal }
+                return next
+            })
+        },
+        []
+    )
 
     const unmount = useCallback((key: string) => {
         setPortals((current) => current.filter((p) => p.key !== key))
@@ -101,22 +133,61 @@ export function PortalArea({ children }: { children?: React.ReactNode }) {
         [mount, unmount]
     )
 
+    // Stable sort: higher priority paints later (on top); equal priorities
+    // keep mount order, preserving the last-opened-on-top behaviour.
+    const ordered = [...portals].sort((a, b) => a.priority - b.priority)
+
+    // The topmost modal layer hides the app content and every layer painted
+    // below it from assistive tech; layers above it (e.g. the toast stack at
+    // its higher priority) stay reachable.
+    let topModalIndex = -1
+    for (let i = ordered.length - 1; i >= 0; i -= 1) {
+        if (ordered[i].modal) {
+            topModalIndex = i
+            break
+        }
+    }
+    const hideApp = topModalIndex >= 0
+
     return (
         <PortalRegistryContext.Provider value={registry}>
-            {children}
-            {portals.map(({ key, node }) => (
-                <View
-                    key={key}
-                    style={StyleSheet.absoluteFill}
-                    // Touches fall through empty layer area to the app;
-                    // the overlay's own views still receive theirs.
-                    pointerEvents="box-none"
-                >
-                    {node}
-                </View>
-            ))}
+            <View
+                style={styles.appContent}
+                collapsable={false}
+                importantForAccessibility={
+                    hideApp ? 'no-hide-descendants' : 'auto'
+                }
+                accessibilityElementsHidden={hideApp}
+            >
+                {children}
+            </View>
+            {ordered.map(({ key, node }, index) => {
+                const hidden = index < topModalIndex
+                return (
+                    <View
+                        key={key}
+                        style={StyleSheet.absoluteFill}
+                        // Touches fall through empty layer area to the app;
+                        // the overlay's own views still receive theirs.
+                        pointerEvents="box-none"
+                        importantForAccessibility={
+                            hidden ? 'no-hide-descendants' : 'auto'
+                        }
+                        accessibilityElementsHidden={hidden}
+                    >
+                        {node}
+                    </View>
+                )
+            })}
         </PortalRegistryContext.Provider>
     )
 }
 
+const styles = StyleSheet.create({
+    // The provider sits at a screen-filling root (its documented contract),
+    // so the app content wrapper fills it; a wrapper View is what the
+    // modality a11y props need to hang on.
+    appContent: { flex: 1 },
+})
+
 PortalArea.displayName = 'PortalArea'

package/src/overlay/positioning.ts

@@ -194,3 +194,116 @@ export function computeAnchoredPosition(
 
     return { x, y, placement, maxHeight, maxWidth }
 }
+
+/**
+ * Arrow-led placement — the tooltip contract: the arrow (“tip”) sits at a
+ * fixed spot on the content per `alignment` (`start` → near the leading
+ * edge, `center` → middle, `end` → near the trailing edge), and the
+ * CONTENT is positioned so that fixed tip lands on the anchor's center.
+ * This is how the established native tooltip libraries behave, and it
+ * keeps the bubble visually attached to its trigger; edge-aligned
+ * placement (`computeAnchoredPosition`) remains the right model for
+ * menus/popovers.
+ *
+ * The main axis (side, flip, offset) reuses `computeAnchoredPosition`;
+ * only the cross axis is arrow-led. Cross-axis clamping keeps the content
+ * on-screen; the arrow stays at its content-local spot by design.
+ */
+export function computeArrowAlignedPosition(
+    input: AnchoredPositionInput & { arrowSize: number }
+): AnchoredPosition & { arrow: { x: number; y: number } } {
+    const {
+        anchor,
+        content,
+        viewport,
+        alignment = 'center',
+        viewportPadding = 8,
+        arrowSize,
+    } = input
+
+    const base = computeAnchoredPosition(input)
+    const vertical = base.placement === 'top' || base.placement === 'bottom'
+    const crossLength = vertical ? content.width : content.height
+
+    // Where the tip sits on the content, per the alignment contract. The
+    // inset keeps the rotated square clear of rounded corners.
+    const inset = Math.max(arrowSize * 2, 12)
+    const arrowLocal =
+        alignment === 'start'
+            ? inset
+            : alignment === 'end'
+              ? crossLength - inset
+              : crossLength / 2
+
+    const anchorCenter = vertical
+        ? anchor.x + anchor.width / 2
+        : anchor.y + anchor.height / 2
+    const crossMax =
+        (vertical ? viewport.width : viewport.height) -
+        viewportPadding -
+        crossLength
+    const cross = clamp(anchorCenter - arrowLocal, viewportPadding, crossMax)
+
+    const arrow = vertical
+        ? {
+              x: arrowLocal,
+              y: base.placement === 'top' ? content.height : 0,
+          }
+        : {
+              x: base.placement === 'left' ? content.width : 0,
+              y: arrowLocal,
+          }
+
+    return vertical
+        ? { ...base, x: cross, arrow }
+        : { ...base, y: cross, arrow }
+}
+
+export type ArrowPositionInput = {
+    /** The anchor's rect in window coordinates. */
+    anchor: Rect
+    /** Where the content ended up (`computeAnchoredPosition`'s x/y). */
+    contentPosition: { x: number; y: number }
+    /** The content's measured size. */
+    content: Size
+    /** The placement actually used, after any flip. */
+    placement: Placement
+    /** Edge length of the square rendered as the arrow (pre-rotation). */
+    arrowSize: number
+}
+
+/**
+ * Where the arrow sits on the content's anchor-facing edge, as the arrow's
+ * **center point in content-local coordinates**: the anchor's center is
+ * projected onto that edge and clamped inward by `arrowSize` so the arrow
+ * never escapes past the rounded corners. The caller renders a 45°-rotated
+ * square centered on the returned point, straddling the edge.
+ */
+export function computeArrowPosition(input: ArrowPositionInput): {
+    x: number
+    y: number
+} {
+    const { anchor, contentPosition, content, placement, arrowSize } = input
+    const anchorCenterX = anchor.x + anchor.width / 2
+    const anchorCenterY = anchor.y + anchor.height / 2
+
+    if (placement === 'top' || placement === 'bottom') {
+        // Arrow on the bottom edge when content sits above the anchor, on
+        // the top edge when below.
+        const y = placement === 'top' ? content.height : 0
+        const x = clamp(
+            anchorCenterX - contentPosition.x,
+            arrowSize,
+            content.width - arrowSize
+        )
+        return { x, y }
+    }
+
+    const x = placement === 'left' ? content.width : 0
+    const y = clamp(
+        anchorCenterY - contentPosition.y,
+        arrowSize,
+        content.height - arrowSize
+    )
+    return { x, y }
+}

package/src/overlay/sheet/BottomSheet.tsx

@@ -1,11 +1,19 @@
-import React, { useCallback, useContext, useEffect, useState } from 'react'
+import React, {
+    useCallback,
+    useContext,
+    useEffect,
+    useMemo,
+    useState,
+} from 'react'
 import {
     BackHandler,
+    Platform,
     Pressable,
     StyleSheet,
     useWindowDimensions,
     View,
     type LayoutChangeEvent,
+    type StyleProp,
     type ViewStyle,
 } from 'react-native'
 import Animated, {
@@ -19,14 +27,19 @@ import Animated, {
 import { Gesture, GestureDetector } from 'react-native-gesture-handler'
 import { Portal } from '../portal'
 import { SafeAreaInsetsContext } from '../safeAreaInsets'
+import { useKeyboardHeight } from '../useKeyboardHeight'
 import { MOTION_DURATION, MOTION_EASING } from '../../motion/motion'
 import { useReduceMotion } from '../../motion/useReduceMotion'
 import {
-    clampSheetDrag,
+    resolveSheetDrag,
     resolveSheetMaxHeight,
+    shouldActivateSheetPan,
     shouldDismissSheet,
+    shouldSheetConsumeDrag,
     SHEET_MAX_HEIGHT_FRACTION,
 } from './sheetMath'
+import { SheetGestureContext } from './sheetGestureContext'
+import type { SheetGestureValue } from './sheetGestureContext'
 
 /**
  * BottomSheet — the gesture-driven sheet foundation.
@@ -68,14 +81,26 @@ export type BottomSheetProps = {
     /** Show the drag handle. Default true. */
     showHandle?: boolean
     handleColor?: string
+    /** Overrides the handle geometry (width/height/margins). */
+    handleStyle?: StyleProp<ViewStyle>
     /** Allow drag-down to dismiss. Default true. */
     dragToDismiss?: boolean
     /** Dismiss when the backdrop is pressed. Default true. */
     dismissOnBackdropPress?: boolean
+    /**
+     * How the sheet reacts to the soft keyboard. `'translate'` slides the
+     * sheet up by the keyboard's height (over the bottom inset) and shrinks
+     * its max height to match. `'auto'` (default) translates on iOS and does
+     * nothing on Android — with the default `adjustResize` soft-input mode
+     * the Android window itself shrinks and the bottom-anchored sheet
+     * already rises, so translating would double-compensate. Android apps
+     * running `adjustPan`/`adjustNothing` should pass `'translate'`.
+     */
+    keyboardAvoidance?: 'auto' | 'translate' | 'none'
     accessibilityLabel?: string
     testID?: string
     /** Style escape hatch for the sheet surface. */
-    style?: ViewStyle
+    style?: StyleProp<ViewStyle>
 }
 
 const ENTER = {
@@ -97,8 +122,10 @@ export function BottomSheet({
     topRadius = 16,
     showHandle = true,
     handleColor = 'rgba(0, 0, 0, 0.2)',
+    handleStyle,
     dragToDismiss = true,
     dismissOnBackdropPress = true,
+    keyboardAvoidance = 'auto',
     accessibilityLabel,
     testID,
     style,
@@ -108,15 +135,43 @@ export function BottomSheet({
     const progress = useSharedValue(0)
     const dragY = useSharedValue(0)
     const sheetHeight = useSharedValue(0)
+    // Scroll offset of a BottomSheetScrollable inside the sheet (0 when none
+    // is registered), and the translation captured at the instant the sheet
+    // starts consuming the drag (-1 = not consuming).
+    const scrollOffsetY = useSharedValue(0)
+    const capturedY = useSharedValue(-1)
+    const keyboardOffset = useSharedValue(0)
     const window = useWindowDimensions()
     const insets = useContext(SafeAreaInsetsContext)
     const reduceMotion = useReduceMotion()
+    const keyboard = useKeyboardHeight()
 
     const unmount = useCallback(() => setMounted(false), [])
 
+    const avoidsKeyboard =
+        keyboardAvoidance === 'translate' ||
+        (keyboardAvoidance === 'auto' && Platform.OS === 'ios')
+    const keyboardHeight = avoidsKeyboard
+        ? Math.max(0, keyboard.height - (insets?.bottom ?? 0))
+        : 0
+
+    useEffect(() => {
+        // Functional motion (the sheet must clear the keyboard), so reduce
+        // motion only skips the easing, not the move.
+        keyboardOffset.value = reduceMotion
+            ? keyboardHeight
+            : withTiming(keyboardHeight, {
+                  duration: MOTION_DURATION.normal,
+                  easing: Easing.bezier(...MOTION_EASING.standard),
+              })
+    }, [keyboardHeight, keyboardOffset, reduceMotion])
+
     useEffect(() => {
         if (open) {
             setMounted(true)
+            // A remount starts the inner list back at its top; without this a
+            // stale offset from the previous session would pin the sheet.
+            scrollOffsetY.value = 0
             progress.value = withTiming(1, ENTER)
         } else {
             // Drag offset folds into the exit so a gesture-dismissed sheet
@@ -126,7 +181,7 @@ export function BottomSheet({
                 if (finished) runOnJS(unmount)()
             })
         }
-    }, [open, progress, dragY, unmount])
+    }, [open, progress, dragY, scrollOffsetY, unmount])
 
     // Android hardware back closes the sheet instead of the screen.
     useEffect(() => {
@@ -148,15 +203,55 @@ export function BottomSheet({
         [sheetHeight]
     )
 
+    // Scroll-aware drag: the pan runs simultaneously with the native scroll
+    // gesture of any BottomSheetScrollable below, but activates MANUALLY —
+    // only once the finger has travelled downward while the inner list sits
+    // at its top. Until then it stays undetermined, so the list scrolls
+    // freely in both directions (an eagerly-activated pan starves the
+    // scroll view of the downward moves). If the list reaches its top
+    // mid-gesture, the pan activates then and the capture logic picks the
+    // sheet up from under the finger. `failOffsetX` hands horizontal swipes
+    // to the content.
+    const touchStartY = useSharedValue(0)
     const pan = Gesture.Pan()
         .enabled(dragToDismiss)
+        .manualActivation(true)
+        .failOffsetX([-16, 16])
+        .onTouchesDown((event) => {
+            touchStartY.value = event.changedTouches[0]?.y ?? 0
+        })
+        .onTouchesMove((event, stateManager) => {
+            const travel = (event.changedTouches[0]?.y ?? 0) - touchStartY.value
+            if (shouldActivateSheetPan(travel, scrollOffsetY.value)) {
+                stateManager.activate()
+            }
+        })
+        .onBegin(() => {
+            capturedY.value = -1
+        })
         .onChange((event) => {
-            dragY.value = clampSheetDrag(event.translationY)
+            if (capturedY.value < 0) {
+                if (
+                    !shouldSheetConsumeDrag(
+                        scrollOffsetY.value,
+                        event.translationY
+                    )
+                ) {
+                    return
+                }
+                capturedY.value = event.translationY
+            }
+            dragY.value = resolveSheetDrag(event.translationY, capturedY.value)
         })
         .onEnd((event) => {
+            if (capturedY.value < 0) return
+            const effectiveDrag = resolveSheetDrag(
+                event.translationY,
+                capturedY.value
+            )
             if (
                 shouldDismissSheet(
-                    event.translationY,
+                    effectiveDrag,
                     event.velocityY,
                     sheetHeight.value
                 )
@@ -167,12 +262,20 @@ export function BottomSheet({
             }
         })
 
+    // The gesture is rebuilt each render (the GestureDetector pattern); the
+    // context value tracks it so scrollables always compose with the current
+    // pan.
+    const gestureValue = useMemo<SheetGestureValue>(
+        () => ({ panGesture: pan, scrollOffsetY }),
+        [pan, scrollOffsetY]
+    )
+
     const windowHeight = window.height
     const sheetStyle = useAnimatedStyle(() => {
         if (reduceMotion) {
             return {
                 opacity: progress.value,
-                transform: [{ translateY: dragY.value }],
+                transform: [{ translateY: dragY.value - keyboardOffset.value }],
             }
         }
         // Until the first layout lands, the full window height keeps the
@@ -181,7 +284,12 @@ export function BottomSheet({
         return {
             opacity: 1,
             transform: [
-                { translateY: (1 - progress.value) * height + dragY.value },
+                {
+                    translateY:
+                        (1 - progress.value) * height +
+                        dragY.value -
+                        keyboardOffset.value,
+                },
             ],
         }
     }, [reduceMotion, windowHeight])
@@ -195,11 +303,12 @@ export function BottomSheet({
     const maxHeight = resolveSheetMaxHeight(
         windowHeight,
         insets?.top ?? 0,
-        maxHeightFraction
+        maxHeightFraction,
+        keyboardHeight
     )
 
     return (
-        <Portal>
+        <Portal modal>
             <Animated.View
                 style={[
                     StyleSheet.absoluteFill,
@@ -223,6 +332,8 @@ export function BottomSheet({
                 <Animated.View
                     onLayout={onSheetLayout}
                     accessibilityViewIsModal
+                    // VoiceOver's two-finger Z scrub dismisses the sheet.
+                    onAccessibilityEscape={onClose}
                     accessibilityLabel={accessibilityLabel}
                     testID={testID}
                     style={[
@@ -243,10 +354,13 @@ export function BottomSheet({
                             style={[
                                 styles.handle,
                                 { backgroundColor: handleColor },
+                                handleStyle,
                             ]}
                         />
                     ) : null}
-                    {children}
+                    <SheetGestureContext.Provider value={gestureValue}>
+                        {children}
+                    </SheetGestureContext.Provider>
                 </Animated.View>
             </GestureDetector>
         </Portal>

package/src/overlay/sheet/SheetScrollable.tsx

@@ -0,0 +1,69 @@
+import { cloneElement, useCallback, useContext } from 'react'
+import type { ReactElement } from 'react'
+import type { NativeScrollEvent, NativeSyntheticEvent } from 'react-native'
+import { Gesture, GestureDetector } from 'react-native-gesture-handler'
+import { SheetGestureContext } from './sheetGestureContext'
+
+/**
+ * Makes one scrollable (ScrollView, FlatList, SectionList) cooperate with
+ * the `BottomSheet` drag: the list scrolls normally, and the sheet takes
+ * over the drag only while the list sits at its top and the finger moves
+ * downward — the vaul behaviour, and what every sheet-hosted list (Menu,
+ * the Selects) needs.
+ *
+ * Wrap the scrollable directly:
+ *
+ * ```tsx
+ * <BottomSheet open={open} onClose={close}>
+ *     <BottomSheetScrollable>
+ *         <FlatList data={rows} renderItem={renderRow} />
+ *     </BottomSheetScrollable>
+ * </BottomSheet>
+ * ```
+ *
+ * The offset reaches the sheet's gesture through a plain JS scroll handler
+ * writing a shared value (a Reanimated `useAnimatedScrollHandler` object
+ * would crash a plain FlatList, whose VirtualizedList internals call
+ * `props.onScroll(e)` directly) — one frame of latency, irrelevant for
+ * at-top detection. The child's own `onScroll` still runs; its
+ * `scrollEventThrottle` is set to 16. Outside a sheet the child renders
+ * unchanged.
+ */
+export function BottomSheetScrollable({
+    children,
+}: {
+    /** Exactly one scrollable element. */
+    children: ReactElement<{
+        onScroll?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void
+        scrollEventThrottle?: number
+    }>
+}) {
+    const sheet = useContext(SheetGestureContext)
+    const childOnScroll = children.props.onScroll
+
+    const onScroll = useCallback(
+        (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+            if (sheet) {
+                sheet.scrollOffsetY.value = event.nativeEvent.contentOffset.y
+            }
+            childOnScroll?.(event)
+        },
+        [sheet, childOnScroll]
+    )
+
+    if (!sheet) return children
+
+    const native = Gesture.Native().simultaneousWithExternalGesture(
+        sheet.panGesture
+    )
+
+    return (
+        <GestureDetector gesture={native}>
+            {cloneElement(children, { onScroll, scrollEventThrottle: 16 })}
+        </GestureDetector>
+    )
+}
+
+BottomSheetScrollable.displayName = 'BottomSheetScrollable'
+
+export default BottomSheetScrollable

package/src/overlay/sheet/sheetGestureContext.ts

@@ -0,0 +1,17 @@
+import { createContext } from 'react'
+import type { PanGesture } from 'react-native-gesture-handler'
+import type { SharedValue } from 'react-native-reanimated'
+
+/**
+ * Published by `BottomSheet` for `BottomSheetScrollable` below it: the
+ * sheet's pan gesture (so the inner scroll gesture can run simultaneously
+ * with it) and the shared scroll offset that gates whether the pan moves the
+ * sheet or lets the list scroll. Internal — the pair only means anything
+ * inside a sheet.
+ */
+export type SheetGestureValue = {
+    panGesture: PanGesture
+    scrollOffsetY: SharedValue<number>
+}
+
+export const SheetGestureContext = createContext<SheetGestureValue | null>(null)