blend-native 0.0.1-beta.0

package/src/overlay/portal.tsx

@@ -0,0 +1,122 @@
+import React, {
+    createContext,
+    useCallback,
+    useContext,
+    useEffect,
+    useId,
+    useMemo,
+    useState,
+} from 'react'
+import { StyleSheet, View } from 'react-native'
+
+/**
+ * Portal — layered rendering above the app's content.
+ *
+ * The native replacement for web's `createPortal`/Radix `Portal`: overlay
+ * components (modal, menu, popover, tooltip, snackbar) mount their surface
+ * through `<Portal>` and it renders in an absolute-fill layer that
+ * `BlendNativeProvider` places *after* the app's children, so it paints on
+ * 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.
+ *
+ * The provider must sit at a screen-filling root (the usual place for a
+ * theme provider): the layers are absolutely positioned siblings of the
+ * app's children, so they cover exactly what the provider's parent covers.
+ *
+ * With no provider mounted, `<Portal>` renders its children in place — an
+ * overlay degrades to inline rendering rather than disappearing.
+ */
+
+type PortalNode = { key: string; node: React.ReactNode }
+
+type PortalRegistry = {
+    mount: (key: string, node: React.ReactNode) => void
+    unmount: (key: string) => void
+}
+
+const PortalRegistryContext = createContext<PortalRegistry | null>(null)
+
+let warnedNoProvider = false
+
+export type PortalProps = { children?: React.ReactNode }
+
+/** Renders `children` into the provider's overlay layer. */
+export function Portal({ children }: PortalProps) {
+    const registry = useContext(PortalRegistryContext)
+    const key = useId()
+
+    useEffect(() => {
+        if (!registry) return
+        registry.mount(key, children)
+        return () => registry.unmount(key)
+    }, [registry, key, children])
+
+    // In an effect, not during render — warning inline would be a
+    // render-phase side effect (breaks under StrictMode double-render, the
+    // same class of bug Pressable's parse memoisation fixed).
+    useEffect(() => {
+        if (registry || warnedNoProvider) return
+        if (typeof __DEV__ !== 'undefined' && __DEV__) {
+            warnedNoProvider = true
+            console.warn(
+                '[blend-native] <Portal> used without BlendNativeProvider — ' +
+                    'rendering inline. Overlays will not layer above the app.'
+            )
+        }
+    }, [registry])
+
+    if (!registry) return <>{children}</>
+
+    return null
+}
+
+Portal.displayName = 'Portal'
+
+/**
+ * Internal — wraps the app's children with the portal registry and renders
+ * the mounted layers after them. Used by `BlendNativeProvider`; not public.
+ */
+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 unmount = useCallback((key: string) => {
+        setPortals((current) => current.filter((p) => p.key !== key))
+    }, [])
+
+    const registry = useMemo<PortalRegistry>(
+        () => ({ mount, unmount }),
+        [mount, unmount]
+    )
+
+    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>
+            ))}
+        </PortalRegistryContext.Provider>
+    )
+}
+
+PortalArea.displayName = 'PortalArea'

package/src/overlay/positioning.ts

@@ -0,0 +1,196 @@
+/**
+ * Anchored-overlay positioning.
+ *
+ * The native replacement for what Radix/floating-ui do on web: place a
+ * floating box (menu, popover, tooltip, select list) against an anchor
+ * rect, flipping to the opposite side when space runs out and clamping
+ * into the viewport.
+ *
+ * Pure and RN-free — rects in, a position out — so the whole placement
+ * matrix is unit-testable under vitest. `useAnchoredPosition` layers the
+ * measurement plumbing on top.
+ */
+
+export type Rect = { x: number; y: number; width: number; height: number }
+export type Size = { width: number; height: number }
+
+/** Which side of the anchor the content prefers. */
+export type Placement = 'top' | 'bottom' | 'left' | 'right'
+
+/** Alignment along the anchor's other axis. */
+export type Alignment = 'start' | 'center' | 'end'
+
+export type AnchoredPositionInput = {
+    /** The anchor's rect in window coordinates (`measureInWindow`). */
+    anchor: Rect
+    /** The floating content's measured size. */
+    content: Size
+    /** The window size (`useWindowDimensions`). */
+    viewport: Size
+    placement?: Placement
+    alignment?: Alignment
+    /** Gap between anchor and content, in points. */
+    offset?: number
+    /** Minimum distance kept from every viewport edge, in points. */
+    viewportPadding?: number
+}
+
+export type AnchoredPosition = {
+    x: number
+    y: number
+    /** The placement actually used, after any flip. */
+    placement: Placement
+    /**
+     * Space available for the content on the resolved side, after padding.
+     * Callers cap scrollable content (menus, select lists) with these so a
+     * long list scrolls instead of overflowing the screen.
+     */
+    maxHeight: number
+    maxWidth: number
+}
+
+const opposite: Record<Placement, Placement> = {
+    top: 'bottom',
+    bottom: 'top',
+    left: 'right',
+    right: 'left',
+}
+
+/** Space between the anchor and the viewport edge on one side. */
+function spaceOn(
+    side: Placement,
+    anchor: Rect,
+    viewport: Size,
+    offset: number,
+    padding: number
+): number {
+    switch (side) {
+        case 'top':
+            return anchor.y - offset - padding
+        case 'bottom':
+            return (
+                viewport.height - (anchor.y + anchor.height) - offset - padding
+            )
+        case 'left':
+            return anchor.x - offset - padding
+        case 'right':
+            return viewport.width - (anchor.x + anchor.width) - offset - padding
+    }
+}
+
+const clamp = (value: number, min: number, max: number) =>
+    // A viewport smaller than the padding produces min > max; the lower
+    // bound wins so content pins to the leading edge instead of NaN-ing.
+    Math.max(min, Math.min(value, Math.max(min, max)))
+
+/**
+ * Compute where to place floating content against an anchor.
+ *
+ * - **Flip**: when the preferred side cannot fit the content but the
+ *   opposite side can fit more of it, the placement flips.
+ * - **Clamp**: the cross-axis position shifts to keep the content inside
+ *   the viewport padding (matching floating-ui's `shift`).
+ * - **Cap**: `maxHeight`/`maxWidth` report the space actually available on
+ *   the resolved side, so scrollable content can cap itself.
+ */
+export function computeAnchoredPosition(
+    input: AnchoredPositionInput
+): AnchoredPosition {
+    const {
+        anchor,
+        content,
+        viewport,
+        placement: preferred = 'bottom',
+        alignment = 'start',
+        offset = 8,
+        viewportPadding = 8,
+    } = input
+
+    const preferredSpace = spaceOn(
+        preferred,
+        anchor,
+        viewport,
+        offset,
+        viewportPadding
+    )
+    const isVertical = preferred === 'top' || preferred === 'bottom'
+    const needed = isVertical ? content.height : content.width
+
+    let placement = preferred
+    if (needed > preferredSpace) {
+        const other = spaceOn(
+            opposite[preferred],
+            anchor,
+            viewport,
+            offset,
+            viewportPadding
+        )
+        if (other > preferredSpace) placement = opposite[preferred]
+    }
+
+    // ---- Main axis ------------------------------------------------------
+    let x = 0
+    let y = 0
+    switch (placement) {
+        case 'top':
+            y = anchor.y - offset - content.height
+            break
+        case 'bottom':
+            y = anchor.y + anchor.height + offset
+            break
+        case 'left':
+            x = anchor.x - offset - content.width
+            break
+        case 'right':
+            x = anchor.x + anchor.width + offset
+            break
+    }
+
+    // ---- Cross axis -----------------------------------------------------
+    const alignAlong = (
+        anchorStart: number,
+        anchorLength: number,
+        contentLength: number
+    ) => {
+        if (alignment === 'start') return anchorStart
+        if (alignment === 'end')
+            return anchorStart + anchorLength - contentLength
+        return anchorStart + (anchorLength - contentLength) / 2
+    }
+
+    if (placement === 'top' || placement === 'bottom') {
+        x = alignAlong(anchor.x, anchor.width, content.width)
+    } else {
+        y = alignAlong(anchor.y, anchor.height, content.height)
+    }
+
+    // ---- Keep inside the viewport ---------------------------------------
+    x = clamp(
+        x,
+        viewportPadding,
+        viewport.width - viewportPadding - content.width
+    )
+    y = clamp(
+        y,
+        viewportPadding,
+        viewport.height - viewportPadding - content.height
+    )
+
+    const available = spaceOn(
+        placement,
+        anchor,
+        viewport,
+        offset,
+        viewportPadding
+    )
+    const maxHeight =
+        placement === 'top' || placement === 'bottom'
+            ? Math.max(0, available)
+            : Math.max(0, viewport.height - 2 * viewportPadding)
+    const maxWidth =
+        placement === 'left' || placement === 'right'
+            ? Math.max(0, available)
+            : Math.max(0, viewport.width - 2 * viewportPadding)
+
+    return { x, y, placement, maxHeight, maxWidth }
+}

package/src/overlay/safeAreaInsets.ts

@@ -0,0 +1,36 @@
+import React, { createContext } from 'react'
+
+/**
+ * Optional `react-native-safe-area-context` integration, shared by every
+ * overlay that must respect the home indicator or notch (BottomSheet, the
+ * toast outlet).
+ *
+ * `useContext` needs *a* context unconditionally, so when the optional peer
+ * is absent — or its provider is not mounted — a null-valued fallback
+ * stands in and insets resolve to zero. Same probe pattern as
+ * expo-linear-gradient.
+ */
+
+export type EdgeInsets = {
+    top: number
+    bottom: number
+    left: number
+    right: number
+}
+
+const FallbackInsetsContext = createContext<EdgeInsets | null>(null)
+
+export let SafeAreaInsetsContext: React.Context<EdgeInsets | null> =
+    FallbackInsetsContext
+try {
+    if (typeof require === 'function') {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const safeArea = require('react-native-safe-area-context') as {
+            SafeAreaInsetsContext?: React.Context<EdgeInsets | null>
+        }
+        SafeAreaInsetsContext =
+            safeArea.SafeAreaInsetsContext ?? FallbackInsetsContext
+    }
+} catch {
+    SafeAreaInsetsContext = FallbackInsetsContext
+}

package/src/overlay/sheet/BottomSheet.tsx

@@ -0,0 +1,276 @@
+import React, { useCallback, useContext, useEffect, useState } from 'react'
+import {
+    BackHandler,
+    Pressable,
+    StyleSheet,
+    useWindowDimensions,
+    View,
+    type LayoutChangeEvent,
+    type ViewStyle,
+} from 'react-native'
+import Animated, {
+    Easing,
+    runOnJS,
+    useAnimatedStyle,
+    useSharedValue,
+    withSpring,
+    withTiming,
+} from 'react-native-reanimated'
+import { Gesture, GestureDetector } from 'react-native-gesture-handler'
+import { Portal } from '../portal'
+import { SafeAreaInsetsContext } from '../safeAreaInsets'
+import { MOTION_DURATION, MOTION_EASING } from '../../motion/motion'
+import { useReduceMotion } from '../../motion/useReduceMotion'
+import {
+    clampSheetDrag,
+    resolveSheetMaxHeight,
+    shouldDismissSheet,
+    SHEET_MAX_HEIGHT_FRACTION,
+} from './sheetMath'
+
+/**
+ * BottomSheet — the gesture-driven sheet foundation.
+ *
+ * The native replacement for `vaul` and the phone presentation web already
+ * prescribes in its Mobile* variants (mobileModalV2, MobileSingleSelectV2,
+ * MobilePopoverV2): DrawerV2 and the phone modes of Select/Menu/Modal
+ * compose this primitive and pass their token values in — the sheet itself
+ * carries structure and physics, not design decisions, which is why its
+ * colour props have plain defaults instead of token lookups.
+ *
+ * Controlled: `open` drives it; every dismiss route (drag, backdrop, the
+ * Android back button) calls `onClose` and the owner flips `open` — the
+ * exit animation runs, then the sheet unmounts from the portal layer.
+ *
+ * Requirements: `react-native-reanimated` and `react-native-gesture-handler`
+ * (required peers), and a `GestureHandlerRootView` at the app root — apps
+ * using react-navigation already have one. `react-native-safe-area-context`
+ * is optional: with it (and its provider) mounted, the sheet pads itself
+ * past the home indicator; without it the bottom inset is 0.
+ *
+ * Reduce-motion: the slide collapses to a fade (`useReduceMotion`).
+ */
+
+export type BottomSheetProps = {
+    /** Whether the sheet is presented. */
+    open: boolean
+    /** Called whenever the sheet asks to close; the owner flips `open`. */
+    onClose: () => void
+    children?: React.ReactNode
+    /** Cap on sheet height as a fraction of the window. Default 0.9. */
+    maxHeightFraction?: number
+    /** Backdrop fill. Defaults to 50% black. */
+    backdropColor?: string
+    /** Sheet surface colour. Component layers pass their token value. */
+    backgroundColor?: string
+    /** Radius of the two top corners. */
+    topRadius?: number
+    /** Show the drag handle. Default true. */
+    showHandle?: boolean
+    handleColor?: string
+    /** Allow drag-down to dismiss. Default true. */
+    dragToDismiss?: boolean
+    /** Dismiss when the backdrop is pressed. Default true. */
+    dismissOnBackdropPress?: boolean
+    accessibilityLabel?: string
+    testID?: string
+    /** Style escape hatch for the sheet surface. */
+    style?: ViewStyle
+}
+
+const ENTER = {
+    duration: MOTION_DURATION.slow,
+    easing: Easing.bezier(...MOTION_EASING.decelerate),
+}
+const EXIT = {
+    duration: MOTION_DURATION.normal,
+    easing: Easing.bezier(...MOTION_EASING.accelerate),
+}
+
+export function BottomSheet({
+    open,
+    onClose,
+    children,
+    maxHeightFraction = SHEET_MAX_HEIGHT_FRACTION,
+    backdropColor = 'rgba(0, 0, 0, 0.5)',
+    backgroundColor = '#FFFFFF',
+    topRadius = 16,
+    showHandle = true,
+    handleColor = 'rgba(0, 0, 0, 0.2)',
+    dragToDismiss = true,
+    dismissOnBackdropPress = true,
+    accessibilityLabel,
+    testID,
+    style,
+}: BottomSheetProps) {
+    // Mounted outlives `open` by one exit animation.
+    const [mounted, setMounted] = useState(open)
+    const progress = useSharedValue(0)
+    const dragY = useSharedValue(0)
+    const sheetHeight = useSharedValue(0)
+    const window = useWindowDimensions()
+    const insets = useContext(SafeAreaInsetsContext)
+    const reduceMotion = useReduceMotion()
+
+    const unmount = useCallback(() => setMounted(false), [])
+
+    useEffect(() => {
+        if (open) {
+            setMounted(true)
+            progress.value = withTiming(1, ENTER)
+        } else {
+            // Drag offset folds into the exit so a gesture-dismissed sheet
+            // continues downward from wherever the finger left it.
+            dragY.value = withTiming(0, EXIT)
+            progress.value = withTiming(0, EXIT, (finished) => {
+                if (finished) runOnJS(unmount)()
+            })
+        }
+    }, [open, progress, dragY, unmount])
+
+    // Android hardware back closes the sheet instead of the screen.
+    useEffect(() => {
+        if (!open) return
+        const subscription = BackHandler.addEventListener(
+            'hardwareBackPress',
+            () => {
+                onClose()
+                return true
+            }
+        )
+        return () => subscription.remove()
+    }, [open, onClose])
+
+    const onSheetLayout = useCallback(
+        (event: LayoutChangeEvent) => {
+            sheetHeight.value = event.nativeEvent.layout.height
+        },
+        [sheetHeight]
+    )
+
+    const pan = Gesture.Pan()
+        .enabled(dragToDismiss)
+        .onChange((event) => {
+            dragY.value = clampSheetDrag(event.translationY)
+        })
+        .onEnd((event) => {
+            if (
+                shouldDismissSheet(
+                    event.translationY,
+                    event.velocityY,
+                    sheetHeight.value
+                )
+            ) {
+                runOnJS(onClose)()
+            } else {
+                dragY.value = withSpring(0, { damping: 22, stiffness: 320 })
+            }
+        })
+
+    const windowHeight = window.height
+    const sheetStyle = useAnimatedStyle(() => {
+        if (reduceMotion) {
+            return {
+                opacity: progress.value,
+                transform: [{ translateY: dragY.value }],
+            }
+        }
+        // Until the first layout lands, the full window height keeps the
+        // sheet parked off-screen instead of flashing in place.
+        const height = sheetHeight.value || windowHeight
+        return {
+            opacity: 1,
+            transform: [
+                { translateY: (1 - progress.value) * height + dragY.value },
+            ],
+        }
+    }, [reduceMotion, windowHeight])
+
+    const backdropStyle = useAnimatedStyle(() => ({
+        opacity: progress.value,
+    }))
+
+    if (!mounted) return null
+
+    const maxHeight = resolveSheetMaxHeight(
+        windowHeight,
+        insets?.top ?? 0,
+        maxHeightFraction
+    )
+
+    return (
+        <Portal>
+            <Animated.View
+                style={[
+                    StyleSheet.absoluteFill,
+                    { backgroundColor: backdropColor },
+                    backdropStyle,
+                ]}
+                testID={testID ? `${testID}-backdrop` : undefined}
+                // The sheet is the modal surface; VoiceOver skips the
+                // backdrop (it could not reach it past
+                // accessibilityViewIsModal anyway).
+                accessible={false}
+                importantForAccessibility="no-hide-descendants"
+            >
+                <Pressable
+                    style={StyleSheet.absoluteFill}
+                    onPress={dismissOnBackdropPress ? onClose : undefined}
+                />
+            </Animated.View>
+
+            <GestureDetector gesture={pan}>
+                <Animated.View
+                    onLayout={onSheetLayout}
+                    accessibilityViewIsModal
+                    accessibilityLabel={accessibilityLabel}
+                    testID={testID}
+                    style={[
+                        styles.sheet,
+                        {
+                            maxHeight,
+                            backgroundColor,
+                            borderTopLeftRadius: topRadius,
+                            borderTopRightRadius: topRadius,
+                            paddingBottom: insets?.bottom ?? 0,
+                        },
+                        sheetStyle,
+                        style,
+                    ]}
+                >
+                    {showHandle ? (
+                        <View
+                            style={[
+                                styles.handle,
+                                { backgroundColor: handleColor },
+                            ]}
+                        />
+                    ) : null}
+                    {children}
+                </Animated.View>
+            </GestureDetector>
+        </Portal>
+    )
+}
+
+BottomSheet.displayName = 'BottomSheet'
+
+const styles = StyleSheet.create({
+    sheet: {
+        position: 'absolute',
+        left: 0,
+        right: 0,
+        bottom: 0,
+        overflow: 'hidden',
+    },
+    handle: {
+        alignSelf: 'center',
+        width: 36,
+        height: 4,
+        borderRadius: 2,
+        marginTop: 8,
+        marginBottom: 4,
+    },
+})
+
+export default BottomSheet

package/src/overlay/sheet/sheetMath.ts

@@ -0,0 +1,58 @@
+/**
+ * Bottom-sheet gesture arithmetic.
+ *
+ * Pure and RN-free (the `theme/breakpoint.ts` pattern) so the dismiss
+ * decision — the part of a sheet that feels wrong when it is wrong — is
+ * unit-testable under vitest. `BottomSheet` wires these into the pan
+ * gesture; they also run as Reanimated worklets, so nothing here may close
+ * over module state.
+ */
+
+/** Dragging past this fraction of the sheet's height dismisses on release. */
+export const SHEET_DISMISS_FRACTION = 0.25
+
+/** A downward fling at or above this velocity (pt/s) dismisses regardless. */
+export const SHEET_DISMISS_VELOCITY = 800
+
+/** Default cap: a sheet covers at most this fraction of the window. */
+export const SHEET_MAX_HEIGHT_FRACTION = 0.9
+
+/**
+ * The sheet follows the finger downward only — upward drag is pinned so the
+ * sheet feels anchored rather than lifting off its resting position.
+ */
+export function clampSheetDrag(translationY: number): number {
+    'worklet'
+    return Math.max(0, translationY)
+}
+
+/**
+ * Whether a released drag should dismiss the sheet: past the distance
+ * threshold, or a genuine downward fling. An upward fling never dismisses,
+ * whatever distance was covered first.
+ */
+export function shouldDismissSheet(
+    translationY: number,
+    velocityY: number,
+    sheetHeight: number
+): boolean {
+    'worklet'
+    if (velocityY <= -SHEET_DISMISS_VELOCITY) return false
+    if (velocityY >= SHEET_DISMISS_VELOCITY) return translationY > 0
+    return (
+        sheetHeight > 0 && translationY >= sheetHeight * SHEET_DISMISS_FRACTION
+    )
+}
+
+/**
+ * The tallest a sheet may grow: the capped fraction of the window, minus
+ * whatever top inset (status bar / notch) must stay visible above it.
+ */
+export function resolveSheetMaxHeight(
+    windowHeight: number,
+    topInset: number = 0,
+    maxHeightFraction: number = SHEET_MAX_HEIGHT_FRACTION
+): number {
+    const capped = windowHeight * maxHeightFraction
+    return Math.max(0, Math.min(capped, windowHeight - topInset))
+}