@isoline-ui/react-native 0.0.0-stage → 1.0.0

package/src/components/sheet-frame.tsx

@@ -0,0 +1,250 @@
+import * as React from 'react';
+import {
+  ScrollView,
+  View,
+  type LayoutChangeEvent,
+  type NativeScrollEvent,
+  type NativeSyntheticEvent,
+  type ScrollViewProps,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+import Animated, { type AnimatedStyle } from 'react-native-reanimated';
+
+import { Text } from './text.tsx';
+import { Pressable } from './pressable.tsx';
+import type { Sheet, SheetScrollContextValue } from './sheet-transition.ts';
+import {
+  Surface,
+  type MaterialOptions,
+  useLabels,
+  useIsolineTheme,
+  useIsolinePlatform,
+} from '../provider.tsx';
+import { elevation, useThemeColors } from '../provider.tsx';
+
+/** M3's scrim: black at 32%, enough to set the sheet apart, not to hide the photo under it. */
+const SCRIM = 'rgba(0, 0, 0, 0.32)';
+/** M3's widest bottom sheet; on a tablet or in landscape it stands centred. */
+const MAX_WIDTH = 640;
+
+const SheetScrollContext = React.createContext<SheetScrollContextValue | null>(null);
+
+/**
+ * What a sheet shows while it leaves: the content it had when it was last
+ * visible. A sheet's content is often built from the very thing closing it
+ * clears (the pin that was tapped, the spec being edited), and without this
+ * the panel would empty out and collapse on its way down.
+ */
+function useKeptChildren(visible: boolean, children: React.ReactNode) {
+  const [kept, setKept] = React.useState(children);
+  if (visible && kept !== children) setKept(children);
+  return visible ? children : kept;
+}
+
+/**
+ * The scrim, the panel and its handle — everything `BottomSheet` and
+ * `PanelSheet` share, so the two look and move as one kind of sheet. Each
+ * places it differently: one in a `Modal`, one inside the screen, lifted by
+ * the keyboard (`lift`).
+ */
+export function SheetFrame({
+  sheet,
+  visible,
+  onClose,
+  lift,
+  panelStyle,
+  children,
+  dragFrom,
+  material = 'solid',
+  glassStyle,
+  tintColor,
+  fallbackColor,
+  interactive = false,
+}: {
+  dragFrom?: 'handle' | 'panel';
+  sheet: Sheet;
+  visible: boolean;
+  onClose: () => void;
+  lift?: StyleProp<AnimatedStyle<ViewStyle>>;
+  panelStyle?: StyleProp<AnimatedStyle<ViewStyle>>;
+  children: React.ReactNode;
+} & MaterialOptions) {
+  const labels = useLabels();
+  const theme = useIsolineTheme();
+  const ios = useIsolinePlatform() === 'ios';
+  const glass = ios && material !== 'solid';
+  const colors = useThemeColors();
+  const shown = useKeptChildren(visible, children);
+
+  const wholePanel = (dragFrom ?? theme.sheetGesture ?? 'handle') === 'panel';
+  return (
+    // Once closed it takes no more touches, though it is still sliding away.
+    <View className="flex-1" pointerEvents={visible ? 'auto' : 'none'}>
+      <Animated.View
+        style={[sheet.scrimStyle, { backgroundColor: SCRIM }]}
+        className="absolute inset-0"
+      >
+        <Pressable className="flex-1" onPress={onClose} accessibilityLabel={labels.close} />
+      </Animated.View>
+
+      {/* The scrim is a sibling, never a parent: its opacity would fade the panel with it. */}
+      <Animated.View
+        style={lift}
+        pointerEvents="box-none"
+        className="absolute inset-0 items-center justify-end"
+      >
+        <GestureDetector gesture={wholePanel ? sheet.pull : Gesture.Native()}>
+          <Animated.View
+            onLayout={sheet.onPanelLayout}
+            accessibilityViewIsModal
+            onAccessibilityEscape={onClose}
+            className={
+              ios
+                ? 'w-full rounded-t-[20px] bg-surfaceContainerLow px-4 pt-2'
+                : 'w-full rounded-t-4xl bg-surfaceContainerLow px-4 pt-3'
+            }
+            style={[
+              sheet.panelStyle,
+              {
+                maxWidth: MAX_WIDTH,
+                elevation: elevation.level1,
+                ...(glass ? { backgroundColor: 'transparent' } : {}),
+              },
+              panelStyle,
+            ]}
+          >
+            {glass ? (
+              <Surface
+                material={material}
+                glassStyle={glassStyle}
+                tintColor={tintColor}
+                fallbackColor={fallbackColor}
+                interactive={interactive}
+                pointerEvents="none"
+                style={{
+                  position: 'absolute',
+                  top: 0,
+                  left: 0,
+                  right: 0,
+                  bottom: 0,
+                  borderTopLeftRadius: ios ? 20 : 32,
+                  borderTopRightRadius: ios ? 20 : 32,
+                }}
+              />
+            ) : null}
+            {/* Below the panel, out of sight until a pull up lifts it off the edge. */}
+            <View
+              pointerEvents="none"
+              className="absolute left-0 right-0 top-full h-24 bg-surfaceContainerLow"
+            />
+
+            {/* The handle closes the sheet when tapped, and is how TalkBack does. */}
+            <GestureDetector gesture={wholePanel ? Gesture.Native() : sheet.pull}>
+              <Pressable
+                onPress={onClose}
+                accessibilityRole="button"
+                accessibilityLabel={labels.close}
+                className="-mx-4 -mt-3 items-center py-3"
+              >
+                <View
+                  className="h-1 w-8 rounded-full"
+                  style={{ backgroundColor: colors.onSurfaceVariant, opacity: 0.4 }}
+                />
+              </Pressable>
+            </GestureDetector>
+
+            {ios ? (
+              <Pressable
+                onPress={onClose}
+                accessibilityRole="button"
+                accessibilityLabel={labels.close}
+                className="min-h-11 self-end justify-center px-2"
+              >
+                <Text style={{ color: colors.primary, fontWeight: '600' }}>{labels.close}</Text>
+              </Pressable>
+            ) : null}
+            <SheetScrollContext.Provider value={sheet.scrollContext}>
+              {shown}
+            </SheetScrollContext.Provider>
+          </Animated.View>
+        </GestureDetector>
+      </Animated.View>
+    </View>
+  );
+}
+
+/**
+ * A vertical list inside a sheet. It scrolls first and lets the sheet's pull
+ * take over at its top, as Android's own sheets do; a plain `ScrollView`
+ * would fight the pull for every vertical swipe. Sideways rows of chips can
+ * stay plain `ScrollView`s: the pull gives way to a sideways swipe.
+ */
+export function SheetScrollView({
+  onScroll,
+  onLayout,
+  onContentSizeChange,
+  ...props
+}: ScrollViewProps) {
+  const context = React.useContext(SheetScrollContext);
+  const id = React.useId();
+  const viewport = React.useRef(0);
+  const content = React.useRef(0);
+  const native = React.useMemo(
+    () =>
+      context
+        ? Gesture.Native().simultaneousWithExternalGesture(context.pull)
+        : Gesture.Native(),
+    [context],
+  );
+
+  const report = React.useCallback(
+    (patch: Partial<{ y: number; scrollable: boolean }>) => {
+      if (!context) return;
+      context.scrolls.modify((scrolls) => {
+        'worklet';
+        const previous = scrolls[id] ?? { y: 0, scrollable: false };
+        scrolls[id] = { ...previous, ...patch };
+        return scrolls;
+      });
+    },
+    [context, id],
+  );
+
+  React.useEffect(() => {
+    if (!context) return;
+    return () => {
+      context.scrolls.modify((scrolls) => {
+        'worklet';
+        delete scrolls[id];
+        return scrolls;
+      });
+    };
+  }, [context, id]);
+
+  return (
+    <GestureDetector gesture={native}>
+      <ScrollView
+        scrollEventThrottle={16}
+        // The sheet moving is the feedback; a stretch on the list as well would be two.
+        overScrollMode="never"
+        onScroll={(event: NativeSyntheticEvent<NativeScrollEvent>) => {
+          report({ y: event.nativeEvent.contentOffset.y });
+          onScroll?.(event);
+        }}
+        onLayout={(event: LayoutChangeEvent) => {
+          viewport.current = event.nativeEvent.layout.height;
+          report({ scrollable: content.current > viewport.current + 1 });
+          onLayout?.(event);
+        }}
+        onContentSizeChange={(width: number, height: number) => {
+          content.current = height;
+          report({ scrollable: content.current > viewport.current + 1 });
+          onContentSizeChange?.(width, height);
+        }}
+        {...props}
+      />
+    </GestureDetector>
+  );
+}

package/src/components/sheet-lifecycle.ts

@@ -0,0 +1,233 @@
+import * as React from 'react';
+import { Dimensions, type ViewStyle, type LayoutChangeEvent } from 'react-native';
+import { Gesture } from 'react-native-gesture-handler';
+import {
+  runOnJS,
+  useAnimatedReaction,
+  useAnimatedStyle,
+  useSharedValue,
+  withSpring,
+  type SharedValue,
+  type AnimatedStyle,
+} from 'react-native-reanimated';
+
+import { spatial } from '../motion.ts';
+import { useReducedMotion } from '../reduced-motion.ts';
+import {
+  anyScrollable,
+  listsAtTop,
+  releaseCloses,
+  rubberBand,
+  scrimShare,
+  type SheetScroll,
+} from '../sheet-physics.ts';
+
+/** Arrives without overshooting: see `spatialStandard`. */
+const SHEET_SPRING = { ...spatial.default, overshootClamping: true };
+
+/** What a `SheetScrollView` needs from the sheet it scrolls in. */
+export interface SheetScrollContextValue {
+  pull: ReturnType<typeof Gesture.Pan>;
+  scrolls: SharedValue<Record<string, SheetScroll>>;
+}
+
+/**
+ * A bottom sheet's whole life: in, under the finger, and out again.
+ *
+ * Driven by shared values rather than Reanimated's `entering` layout
+ * animations, and that is the point. On Android a layout animation on a view
+ * inside a `Modal` leaves the view's *layout* where the animation started even
+ * though it is drawn where the animation ended, so presses inside the panel
+ * are hit-tested against whatever is behind it — here the scrim, whose one job
+ * is to close the panel. A picker built that way looks like it snaps back the
+ * instant an option is tapped (software-mansion/react-native-reanimated#4422).
+ * An animated transform moves the native view, and Android hit-tests against
+ * where the view actually is.
+ *
+ * The sheet stays `mounted` after `visible` turns false, until the panel has
+ * slid out: however it was closed — the scrim, back, a row that acts, a pull —
+ * it leaves the way it came. The scrim is not on a clock of its own; it is
+ * worked out from where the panel is, so the two always move as one.
+ */
+export interface Sheet {
+  mounted: boolean;
+  scrimStyle: AnimatedStyle<ViewStyle>;
+  panelStyle: AnimatedStyle<ViewStyle>;
+  onPanelLayout: (event: LayoutChangeEvent) => void;
+  pull: ReturnType<typeof Gesture.Pan>;
+  scrollContext: SheetScrollContextValue;
+}
+export function useSheet(visible: boolean, onClose: () => void): Sheet {
+  /*
+   * Under "Remove animations" the panel still travels — it has to, for the
+   * hit-testing reason above — but it gets there at once.
+   */
+  const reducedMotion = useReducedMotion();
+  const [mounted, setMounted] = React.useState(visible);
+  if (visible && !mounted) setMounted(true);
+
+  // How far below its rest the panel is: parked off-screen until it has been
+  // measured, so the first frame never shows it before the spring has begun.
+  const offset = useSharedValue(Dimensions.get('window').height);
+  // How far a finger has moved it on top of that (negative: lifted).
+  const drag = useSharedValue(0);
+  // The panel's height, 0 until measured.
+  const height = useSharedValue(0);
+  // Set once a pull has sent the panel on its way out, so the close that
+  // follows does not start the leaving over from rest.
+  const leaving = useSharedValue(false);
+  // Where the finger was when every list reached its top; NaN while a list
+  // still has room to scroll back up.
+  const anchor = useSharedValue(0);
+  const scrolls = useSharedValue<Record<string, SheetScroll>>({});
+
+  // Set by a pull that closed the sheet; the reaction below tells the owner.
+  const pulledShut = useSharedValue(false);
+
+  /** Rearms everything for the next time the sheet opens. */
+  const rearm = React.useCallback(() => {
+    offset.set(Dimensions.get('window').height);
+    drag.set(0);
+    height.set(0);
+    leaving.set(false);
+    pulledShut.set(false);
+  }, [drag, height, leaving, offset, pulledShut]);
+
+  /** Ends the sheet's life, once the panel is out of sight. */
+  const unmount = React.useCallback(() => {
+    setMounted(false);
+    rearm();
+  }, [rearm]);
+
+  // With nothing to watch leave, the sheet is gone as soon as it is closed.
+  if (!visible && mounted && reducedMotion) setMounted(false);
+
+  useAnimatedReaction(
+    () => pulledShut.value,
+    (shut, before) => {
+      if (shut && !before) runOnJS(onClose)();
+    },
+    [onClose],
+  );
+
+  React.useEffect(() => {
+    if (visible) {
+      leaving.set(false);
+      pulledShut.set(false);
+      // Opened again while it was still leaving: back up from where it is.
+      if (height.get() > 0) offset.set(reducedMotion ? 0 : withSpring(0, SHEET_SPRING));
+      return;
+    }
+    if (reducedMotion) {
+      rearm();
+      return;
+    }
+    if (!mounted || leaving.get()) return;
+    leaving.set(true);
+    offset.set(offset.get() + drag.get());
+    drag.set(0);
+    // Not measured yet, it is still parked off-screen and only has to stop.
+    const out = height.get() > 0 ? height.get() : offset.get();
+    offset.set(
+      withSpring(out, SHEET_SPRING, (finished) => {
+        if (finished) runOnJS(unmount)();
+      }),
+    );
+  }, [
+    drag,
+    height,
+    leaving,
+    mounted,
+    offset,
+    pulledShut,
+    reducedMotion,
+    rearm,
+    unmount,
+    visible,
+  ]);
+
+  /**
+   * Starts the slide, once the panel's height is known: the travel is the
+   * panel's own height, so it rises from the screen edge rather than flying in
+   * from an arbitrary distance. Later layouts only keep the height current.
+   */
+  const onPanelLayout = React.useCallback(
+    (event: LayoutChangeEvent) => {
+      const measured = Math.max(1, event.nativeEvent.layout.height);
+      const first = height.get() === 0;
+      height.set(measured);
+      if (!first) return;
+      offset.set(measured);
+      offset.set(reducedMotion ? 0 : withSpring(0, SHEET_SPRING));
+    },
+    [height, offset, reducedMotion],
+  );
+
+  /*
+   * The whole panel takes the pull, as Android's own sheets do: it starts
+   * only once a finger has moved, so a tap still reaches the row under it;
+   * it gives way to a sideways swipe (a row of chips, a calendar's months);
+   * and a list inside scrolls first, handing over to the sheet once it is at
+   * its top. Letting go carries the finger's speed into the spring.
+   */
+  const pull = React.useMemo(
+    () =>
+      Gesture.Pan()
+        .activeOffsetY([-10, 10])
+        .failOffsetX([-12, 12])
+        .onStart(() => {
+          anchor.set(listsAtTop(scrolls.get()) ? 0 : NaN);
+        })
+        .onUpdate((event) => {
+          if (leaving.get()) return;
+          if (Number.isNaN(anchor.get())) {
+            if (!listsAtTop(scrolls.get())) return;
+            anchor.set(event.translationY);
+          }
+          const moved = event.translationY - anchor.get();
+          if (moved >= 0) drag.set(moved);
+          else drag.set(anyScrollable(scrolls.get()) ? 0 : -rubberBand(-moved));
+        })
+        .onFinalize((_event, success) => {
+          if (!success && !leaving.get())
+            drag.set(reducedMotion ? 0 : withSpring(0, SHEET_SPRING));
+        })
+        .onEnd((event) => {
+          if (leaving.get()) return;
+          const pulled = drag.get();
+          if (!releaseCloses(pulled, event.velocityY, height.get())) {
+            drag.set(withSpring(0, { ...SHEET_SPRING, velocity: event.velocityY }));
+            return;
+          }
+          leaving.set(true);
+          offset.set(offset.get() + pulled);
+          drag.set(0);
+          pulledShut.set(true);
+          if (reducedMotion) return;
+          offset.set(
+            withSpring(
+              height.get(),
+              { ...SHEET_SPRING, velocity: event.velocityY },
+              (finished) => {
+                if (finished) runOnJS(unmount)();
+              },
+            ),
+          );
+        }),
+    [anchor, drag, height, leaving, offset, pulledShut, reducedMotion, scrolls, unmount],
+  );
+
+  const scrimStyle = useAnimatedStyle(() => ({
+    opacity: scrimShare(offset.value + drag.value, height.value),
+  }));
+  const panelStyle = useAnimatedStyle(() => ({
+    transform: [{ translateY: offset.value + drag.value }],
+  }));
+
+  const scrollContext = React.useMemo<SheetScrollContextValue>(
+    () => ({ pull, scrolls }),
+    [pull, scrolls],
+  );
+
+  return { mounted, scrimStyle, panelStyle, onPanelLayout, pull, scrollContext };
+}

package/src/components/sheet-transition.ts

@@ -0,0 +1,105 @@
+import * as React from 'react';
+import { Dimensions, type LayoutChangeEvent } from 'react-native';
+import {
+  type AnimatedStyle,
+  type SharedValue,
+  useAnimatedStyle,
+  useSharedValue,
+  withSpring,
+  withTiming,
+} from 'react-native-reanimated';
+
+import { spatial } from '../motion.ts';
+import { useReducedMotion } from '../reduced-motion.ts';
+
+/** How long the scrim takes to dim — the same 120ms the sheets faded in over before. */
+const SCRIM_FADE_MS = 120;
+
+/**
+ * The open transition for a panel presented inside a `Modal`: the scrim dims,
+ * and the panel springs up from the edge it is anchored to.
+ *
+ * Driven by shared values rather than Reanimated's `entering` layout
+ * animations, and that is the entire point of this hook. On Android a layout
+ * animation on a view inside a `Modal` leaves the view's *layout* where the
+ * animation started even though the view is drawn where the animation ended,
+ * so presses inside the panel are hit-tested against whatever is behind it —
+ * here the scrim, whose one job is to close the panel. A picker built that way
+ * looks like it snaps back the instant an option is tapped: the tap closed the
+ * sheet and never reached the row it landed on. Only Android is affected, and
+ * only inside a `Modal`, which is why it survived review twice
+ * (software-mansion/react-native-reanimated#4422).
+ *
+ * An animated transform has no such problem: it moves the native view, and
+ * Android hit-tests against where the view actually is.
+ */
+export interface SheetTransition {
+  scrimStyle: AnimatedStyle<{ opacity: number }>;
+  panelStyle: AnimatedStyle<{ transform: { translateY: number }[] }>;
+  onPanelLayout: (event: LayoutChangeEvent) => void;
+  drag: SharedValue<number>;
+  height: SharedValue<number>;
+  reducedMotion: boolean;
+}
+
+export function useSheetTransition(visible: boolean): SheetTransition {
+  /*
+   * Under "Remove animations" the panel still travels — it has to, for the
+   * hit-testing reason above — but it gets there at once. The scrim stops
+   * fading for the same reason: a sheet appearing is orientation, not
+   * decoration, and the reader still needs to see where it came from. What
+   * they no longer get is the journey.
+   */
+  const reducedMotion = useReducedMotion();
+  const dim = useSharedValue(0);
+  // Parked off-screen until the panel has been measured, so the first frame
+  // never shows it at its resting place before the spring has begun.
+  const offset = useSharedValue(Dimensions.get('window').height);
+  // How far a finger has pulled the panel down from where it rests, and the
+  // panel's height to weigh that against — the scrim lightens as it goes.
+  const drag = useSharedValue(0);
+  const height = useSharedValue(1);
+  const measured = React.useRef(false);
+
+  React.useEffect(() => {
+    if (visible) {
+      dim.value = reducedMotion ? 1 : withTiming(1, { duration: SCRIM_FADE_MS });
+      return;
+    }
+
+    // `Modal` unmounts its children as it hides, so there is nothing left to
+    // animate out — this only rearms the transition for the next open.
+    measured.current = false;
+    dim.value = 0;
+    drag.value = 0;
+    offset.value = Dimensions.get('window').height;
+  }, [dim, drag, offset, reducedMotion, visible]);
+
+  /**
+   * Starts the slide, once the panel's height is known: the travel is the
+   * panel's own height, so it rises from the screen edge rather than flying in
+   * from an arbitrary distance.
+   */
+  const onPanelLayout = React.useCallback(
+    (event: LayoutChangeEvent) => {
+      // Keyboard and window-size changes also change the dismiss distance.
+      height.set(Math.max(1, event.nativeEvent.layout.height));
+      if (measured.current) return;
+      measured.current = true;
+      offset.set(event.nativeEvent.layout.height);
+      offset.set(reducedMotion ? 0 : withSpring(0, spatial.default));
+    },
+    [height, offset, reducedMotion],
+  );
+
+  const scrimStyle = useAnimatedStyle(() => ({
+    opacity: dim.value * (1 - Math.min(1, drag.value / height.value)),
+  }));
+  const panelStyle = useAnimatedStyle(() => ({
+    transform: [{ translateY: offset.value + drag.value }],
+  }));
+
+  return { scrimStyle, panelStyle, onPanelLayout, drag, height, reducedMotion };
+}
+
+export { useSheet, type Sheet, type SheetScrollContextValue } from './sheet-lifecycle.ts';