@react-navigation/lynx 0.3.0 → 0.4.0-canary-20260909-fa1c06ba

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-navigation/lynx",
-  "version": "0.3.0",
+  "version": "0.4.0-canary-20260909-fa1c06ba",
   "description": "Lynx integration for React Navigation",
   "keywords": [
     "react",
@@ -33,7 +33,7 @@
   ],
   "dependencies": {
     "escape-string-regexp": "^5.0.0",
-    "@react-navigation/core": "^8.0.0-alpha.33"
+    "@react-navigation/core": "^8.0.0-alpha.34"
   },
   "peerDependencies": {
     "@lynx-js/react": "*",

package/src/stack/types.ts

@@ -16,11 +16,25 @@ export type LynxStackPresentation = 'card' | 'formSheet';
 export type LynxStackNavigationOptions = {
   presentation?: LynxStackPresentation | undefined;
   contentStyle?: Lynx.CSSProperties | undefined;
+  /**
+   * Heights the sheet can rest at, as fractions of the screen, or
+   * `'fitToContents'` to measure the content. `formSheet` only, as is every
+   * option below. Names follow `@react-navigation/native-stack`.
+   */
+  sheetAllowedDetents?: number[] | 'fitToContents' | undefined;
+  sheetInitialDetentIndex?: number | 'last' | undefined;
+  /** Detents up to this one leave the content behind the sheet undimmed. */
+  sheetLargestUndimmedDetentIndex?: number | 'none' | 'last' | undefined;
+  sheetGrabberVisible?: boolean | undefined;
+  sheetCornerRadius?: number | 'systemDefault' | undefined;
+  sheetExpandsWhenScrolledToEdge?: boolean | undefined;
 };
 
 export type LynxStackNavigationEventMap = {
   transitionStart: { data: { closing: boolean } };
   transitionEnd: { data: { closing: boolean } };
+  /** The detent a `formSheet` settled at, as an index into its detents. */
+  sheetDetentChange: { data: { index: number } };
 };
 
 export type LynxStackNavigationProp<

package/src/stack/views/LynxStackView.tsx

@@ -11,6 +11,7 @@ import type {
   LynxStackNavigationHelpers,
 } from '../types';
 import { CardScreen } from './CardScreen';
+import { SheetScreen } from './SheetScreen';
 import {
   type LynxStackViewState,
   type LynxStackViewStateAction,
@@ -44,7 +45,13 @@ function LynxStackViewContent({
     dispatch({ type: 'REMOVE_POPPED_ROUTE', key });
   };
 
-  const onNativeDismiss = (key: string) => {
+  const onNativeDismiss = ({
+    key,
+    markNativelyDismissed,
+  }: {
+    key: string;
+    markNativelyDismissed: boolean;
+  }) => {
     const currentState = navigation.getState();
     const index = currentState.routes.findIndex((route) => route.key === key);
 
@@ -59,13 +66,16 @@ function LynxStackViewContent({
     }
 
     // The native side has already taken these screens off the stack, so the
-    // reducer must not keep them rendered waiting for a pop animation.
-    dispatch({
-      type: 'ADD_NATIVELY_DISMISSED_ROUTES',
-      keys: currentState.routes
-        .slice(index, currentState.index + 1)
-        .map((route) => route.key),
-    });
+    // reducer must not keep them rendered waiting for a pop animation. A sheet
+    // whose dismissal was prevented is the exception: it is still there.
+    if (markNativelyDismissed) {
+      dispatch({
+        type: 'ADD_NATIVELY_DISMISSED_ROUTES',
+        keys: currentState.routes
+          .slice(index, currentState.index + 1)
+          .map((route) => route.key),
+      });
+    }
 
     navigation.dispatch({
       ...StackActions.pop(dismissCount),
@@ -86,7 +96,12 @@ function LynxStackViewContent({
     });
   };
 
-  const cards = renderedRoutes.reduce<ReactElement[]>((result, route) => {
+  const cards: ReactElement[] = [];
+  // The native sheet is its own host, so these render outside the stack host
+  // rather than as screens in it.
+  const sheets: ReactElement[] = [];
+
+  renderedRoutes.forEach((route) => {
     const index = routeIndexByKey.get(route.key);
     const popped = poppedByKey.get(route.key);
     const descriptor = descriptors[route.key] ?? popped?.descriptor;
@@ -99,13 +114,38 @@ function LynxStackViewContent({
 
     const presentation = descriptor.options.presentation ?? 'card';
 
-    if (presentation !== 'card') {
+    if (presentation !== 'card' && presentation !== 'formSheet') {
       throw new Error(
-        `The route '${route.name}' uses the '${presentation}' presentation, which the Lynx stack does not support yet. Only 'card' is available while form sheet support lands in lynx-screens.`
+        `The route '${route.name}' uses the '${presentation}' presentation, which the Lynx stack does not support. Only 'card' and 'formSheet' are available.`
+      );
+    }
+
+    if (presentation === 'formSheet') {
+      if (index === 0) {
+        throw new Error(
+          `The route '${route.name}' cannot use the 'formSheet' presentation because it is the first route in the stack. Add a screen with the 'card' presentation before it.`
+        );
+      }
+
+      sheets.push(
+        <SheetScreen
+          key={route.key}
+          descriptor={descriptor}
+          navigation={navigation}
+          isFocused={index === state.index}
+          isPopped={popped != null}
+          onRemovePoppedRoute={onRemovePoppedRoute}
+          onNativeDismiss={(markNativelyDismissed) =>
+            onNativeDismiss({ key: route.key, markNativelyDismissed })
+          }
+          onNativeDismissPrevented={() => onNativeDismissPrevented(route.key)}
+        />
       );
+
+      return;
     }
 
-    result.push(
+    cards.push(
       <CardScreen
         key={route.key}
         descriptor={descriptor}
@@ -115,15 +155,20 @@ function LynxStackViewContent({
         isPopped={popped != null}
         isDetached={index != null && index > state.index}
         onRemovePoppedRoute={onRemovePoppedRoute}
-        onNativeDismiss={() => onNativeDismiss(route.key)}
+        onNativeDismiss={() =>
+          onNativeDismiss({ key: route.key, markNativelyDismissed: true })
+        }
         onNativeDismissPrevented={() => onNativeDismissPrevented(route.key)}
       />
     );
+  });
 
-    return result;
-  }, []);
-
-  return <StackHostNativeComponent>{cards}</StackHostNativeComponent>;
+  return (
+    <>
+      <StackHostNativeComponent>{cards}</StackHostNativeComponent>
+      {sheets}
+    </>
+  );
 }
 
 export function LynxStackView({ state, navigation, descriptors }: Props) {

package/src/stack/views/SheetScreen.tsx

@@ -0,0 +1,120 @@
+import {
+  NavigationProvider,
+  usePreventRemoveContext,
+} from '@react-navigation/core';
+import { FormSheetNativeComponent } from 'lynx-screens';
+
+import type { LynxStackDescriptor, LynxStackNavigationHelpers } from '../types';
+
+type Props = {
+  descriptor: LynxStackDescriptor;
+  navigation: LynxStackNavigationHelpers;
+  isFocused: boolean;
+  isPopped: boolean;
+  onRemovePoppedRoute: (key: string) => void;
+  onNativeDismiss: (markNativelyDismissed: boolean) => void;
+  onNativeDismissPrevented: () => void;
+};
+
+/**
+ * A `formSheet` route. The native sheet is its own host rather than a screen
+ * inside the stack, so this renders as a sibling of the stack host and opens
+ * and closes with focus instead of taking an activity mode.
+ */
+export function SheetScreen({
+  descriptor,
+  navigation,
+  isFocused,
+  isPopped,
+  onRemovePoppedRoute,
+  onNativeDismiss,
+  onNativeDismissPrevented,
+}: Props) {
+  const { preventedRoutes } = usePreventRemoveContext();
+
+  const { route, options } = descriptor;
+  const { contentStyle } = options;
+
+  // Prevention comes from `usePreventRemove` and nothing else, for the reason
+  // `CardScreen` spells out: a static option would have the native side block
+  // the gesture and the `onNativeDismissPrevented` round-trip pop the route
+  // anyway, since only a `beforeRemove` listener can cancel that dispatch.
+  const isRemovePrevented = preventedRoutes[route.key]?.preventRemove === true;
+
+  return (
+    <FormSheetNativeComponent
+      isOpen={isFocused}
+      detents={options.sheetAllowedDetents}
+      initialDetentIndex={options.sheetInitialDetentIndex}
+      largestUndimmedDetentIndex={options.sheetLargestUndimmedDetentIndex}
+      prefersGrabberVisible={options.sheetGrabberVisible}
+      preferredCornerRadius={options.sheetCornerRadius}
+      prefersScrollingExpandsWhenScrolledToEdge={
+        options.sheetExpandsWhenScrolledToEdge
+      }
+      preventNativeDismiss={isRemovePrevented}
+      nativeContainerStyle={{ backgroundColor: contentStyle?.backgroundColor }}
+      onWillAppear={() =>
+        navigation.emit({
+          type: 'transitionStart',
+          data: { closing: false },
+          target: route.key,
+        })
+      }
+      onDidAppear={() =>
+        navigation.emit({
+          type: 'transitionEnd',
+          data: { closing: false },
+          target: route.key,
+        })
+      }
+      onWillDisappear={() =>
+        navigation.emit({
+          type: 'transitionStart',
+          data: { closing: true },
+          target: route.key,
+        })
+      }
+      onDidDisappear={() => {
+        navigation.emit({
+          type: 'transitionEnd',
+          data: { closing: true },
+          target: route.key,
+        });
+
+        // The route stays rendered while the sheet animates out, which is what
+        // gives it something to animate. This is where it finally goes.
+        if (isPopped) {
+          onRemovePoppedRoute(route.key);
+        }
+      }}
+      onDetentChanged={(index) =>
+        navigation.emit({
+          type: 'sheetDetentChange',
+          data: { index },
+          target: route.key,
+        })
+      }
+      onNativeDismiss={() => onNativeDismiss(!isRemovePrevented)}
+      onNativeDismissPrevented={onNativeDismissPrevented}
+    >
+      <NavigationProvider navigation={descriptor.navigation} route={route}>
+        <view
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            width: '100%',
+            // `fitToContents` measures the content, so it must not be told to
+            // fill the sheet.
+            ...(options.sheetAllowedDetents === 'fitToContents'
+              ? null
+              : { height: '100%' }),
+            ...contentStyle,
+          }}
+        >
+          {descriptor.render()}
+        </view>
+      </NavigationProvider>
+    </FormSheetNativeComponent>
+  );
+}