@react-navigation/lynx 0.0.0 → 0.1.0

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@react-navigation/lynx",
-  "version": "0.0.0",
-  "main": "index.js",
-  "license": "MIT"
-}
+  "version": "0.1.0",
+  "description": "Lynx integration for React Navigation",
+  "keywords": [
+    "react",
+    "lynx",
+    "react-navigation"
+  ],
+  "homepage": "https://reactnavigation.org",
+  "bugs": {
+    "url": "https://github.com/react-navigation/react-navigation-lynx/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/react-navigation/react-navigation-lynx.git",
+    "directory": "packages/lynx"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./src/index.tsx",
+  "types": "./src/index.tsx",
+  "exports": {
+    ".": "./src/index.tsx",
+    "./stack": "./src/stack/index.tsx",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@react-navigation/core": "^8.0.0-alpha.33"
+  },
+  "peerDependencies": {
+    "@lynx-js/react": "*",
+    "lynx-screens": "*"
+  },
+  "devDependencies": {
+    "@lynx-js/react": "^0.125.0",
+    "@lynx-js/testing-environment": "^0.3.3",
+    "@lynx-js/types": "^4.1.0",
+    "@types/react": "~19.2.17",
+    "jsdom": "^26.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.0",
+    "lynx-screens": "0.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/NavigationContainer.tsx

@@ -0,0 +1,79 @@
+import {
+  BaseNavigationContainer,
+  type NavigationContainerProps,
+  type NavigationContainerRef,
+  type NavigationState,
+  type ParamListBase,
+  type Theme,
+  ThemeProvider,
+} from '@react-navigation/core';
+import * as React from 'react';
+
+import { LightTheme } from './theming/LightTheme';
+
+export type NavigationContainerLynxProps<
+  ParamList extends {} = ParamListBase,
+> = NavigationContainerProps & {
+  /**
+   * Theme handed to `useTheme` and to any navigator that reads colors.
+   */
+  theme?: Theme | undefined;
+  /**
+   * Rendered while persisted state is being restored.
+   */
+  fallback?: React.ReactNode | undefined;
+  ref?: React.Ref<NavigationContainerRef<ParamList>> | undefined;
+};
+
+/**
+ * The Lynx counterpart of `@react-navigation/native`'s `NavigationContainer`.
+ *
+ * It is the platform layer's entry point: everything a navigator needs that is
+ * not navigation state itself - the theme, and eventually deep linking and
+ * state persistence - is wired here rather than in each navigator.
+ *
+ * Not yet ported from React Native:
+ *
+ * - deep linking (`linking`), which needs a Lynx URL source
+ * - state persistence, which needs a Lynx storage binding
+ * - `useDocumentTitle`, which is a browser concern and has no Lynx meaning
+ *
+ * The hardware back button is deliberately absent: on Lynx it is handled by
+ * the native stack per screen, through `preventNativeDismiss` and the dismiss
+ * callbacks, so a container-level handler would fight with it.
+ */
+export function NavigationContainer<ParamList extends {} = ParamListBase>({
+  theme = LightTheme,
+  fallback = null,
+  onStateChange,
+  ref,
+  ...rest
+}: NavigationContainerLynxProps<ParamList>) {
+  const refContainer =
+    React.useRef<NavigationContainerRef<ParamListBase>>(null);
+
+  React.useImperativeHandle(
+    ref,
+    () => refContainer.current as NavigationContainerRef<ParamList>
+  );
+
+  const handleStateChange = (state: Readonly<NavigationState> | undefined) => {
+    onStateChange?.(state);
+  };
+
+  // Kept for parity with React Native, where this renders while persisted
+  // state is being restored. With no persistence yet there is nothing to wait
+  // for, so it only shows if a caller passes `fallback` and no children.
+  if (rest.children == null) {
+    return <ThemeProvider value={theme}>{fallback}</ThemeProvider>;
+  }
+
+  return (
+    <BaseNavigationContainer
+      {...rest}
+      theme={theme}
+      onStateChange={handleStateChange}
+      ref={refContainer}
+    />
+  );
+}

package/src/createStaticNavigation.tsx

@@ -0,0 +1,41 @@
+import {
+  type RootParamList,
+  type StaticNavigation,
+} from '@react-navigation/core';
+import * as React from 'react';
+
+import { NavigationContainer } from './NavigationContainer';
+
+type Props<ParamList extends {}> = Omit<
+  React.ComponentProps<typeof NavigationContainer<ParamList>>,
+  'children'
+>;
+
+/**
+ * Create a navigation component from a static navigation config, the same way
+ * `@react-navigation/native` does. The returned component wraps
+ * `NavigationContainer`.
+ *
+ * React Native's version also derives a linking config from the tree here.
+ * That is left out until the container can act on one - generating paths that
+ * nothing consumes would only look like deep linking works.
+ *
+ * @param tree Static navigation config.
+ * @returns Navigation component to use in your app.
+ */
+export function createStaticNavigation(tree: StaticNavigation<any>) {
+  const Component = tree.getComponent();
+
+  function Navigation<ParamList extends {} = RootParamList>({
+    ref,
+    ...rest
+  }: Props<ParamList>) {
+    return (
+      <NavigationContainer {...rest} ref={ref}>
+        <Component />
+      </NavigationContainer>
+    );
+  }
+
+  return Navigation;
+}

package/src/index.tsx

@@ -0,0 +1,13 @@
+// The platform layer, mirroring what `@react-navigation/native` does for
+// React Native: it owns everything Lynx-specific that every navigator needs,
+// and re-exports core so apps have a single import surface.
+export { createStaticNavigation } from './createStaticNavigation';
+export type { LynxTheme } from './types';
+export {
+  NavigationContainer,
+  type NavigationContainerLynxProps,
+} from './NavigationContainer';
+export { DarkTheme } from './theming/DarkTheme';
+export { LightTheme as DefaultTheme } from './theming/LightTheme';
+
+export * from '@react-navigation/core';

package/src/react-compat.ts

@@ -0,0 +1,40 @@
+// ReactLynx is Preact-based and does not implement every hook that
+// `@react-navigation/core` imports from `react`. The Lynx build aliases
+// `react` to this module (runtime alias in the bundler config, `paths` in
+// tsconfig) so those imports link and both sides share one set of types.
+//
+// Tracking the gaps, counted against core's runtime source:
+//
+// - `use` (4 files): every call site passes a Context, never a promise, so
+//   `useContext` is a faithful stand-in today. Preact 11 ships the real one.
+// - `startTransition` / `useTransition` (2 files): ReactLynx keeps these on
+//   its compat entry rather than the main one.
+// - `useInsertionEffect` (15 files): no equivalent. `useLayoutEffect` is
+//   close but not equal - insertion effects run before layout effects, and
+//   layout effects run bottom-up, so a parent writing a ref in an insertion
+//   effect is guaranteed fresh when a child's layout effect reads it. Twelve
+//   of the fifteen are plain latest-ref writes where that gap is invisible;
+//   `useRegisterNavigator`, `usePreventRemove` and `PreventRemoveProvider`
+//   also register cleanups, and those are the ones to watch.
+import * as ReactLynx from '@lynx-js/react';
+import { useContext, useLayoutEffect } from '@lynx-js/react';
+import { startTransition, useTransition } from '@lynx-js/react/compat';
+
+export * from '@lynx-js/react';
+export { startTransition, useTransition };
+
+export const use = useContext;
+export const useInsertionEffect = useLayoutEffect;
+
+// `@lynx-js/react` declares no default export. Build one that keeps every
+// generic signature intact, otherwise `import React from 'react'` degrades to
+// `any` and callers lose inference (e.g. `React.useState` setter callbacks).
+const React = {
+  ...ReactLynx,
+  use,
+  useInsertionEffect,
+  startTransition,
+  useTransition,
+};
+
+export default React;

package/src/stack/index.tsx

@@ -0,0 +1,23 @@
+/**
+ * Navigators
+ */
+export {
+  createLynxStackNavigator,
+  createLynxStackScreen,
+  type LynxStackTypeBag,
+} from './navigators/createLynxStackNavigator';
+
+/**
+ * Types
+ */
+export type {
+  LynxStackDescriptor,
+  LynxStackDescriptorMap,
+  LynxStackNavigationEventMap,
+  LynxStackNavigationHelpers,
+  LynxStackNavigationOptions,
+  LynxStackNavigationProp,
+  LynxStackNavigatorProps,
+  LynxStackPresentation,
+  LynxStackScreenProps,
+} from './types';

package/src/stack/navigators/createLynxStackNavigator.tsx

@@ -0,0 +1,72 @@
+import {
+  createNavigatorFactory,
+  createScreenFactory,
+  type NavigatorTypeBagBase,
+  type ParamListBase,
+  type StackActionHelpers,
+  type StackNavigationState,
+  StackRouter,
+  type StackRouterOptions,
+  useNavigationBuilder,
+} from '@react-navigation/core';
+
+import type {
+  LynxStackNavigationEventMap,
+  LynxStackNavigationOptions,
+  LynxStackNavigatorProps,
+} from '../types';
+import { LynxStackView } from '../views/LynxStackView';
+
+function LynxStackNavigator({
+  initialRouteName,
+  routeNamesChangeBehavior,
+  children,
+  layout,
+  screenListeners,
+  screenOptions,
+  screenLayout,
+  router,
+  ...rest
+}: LynxStackNavigatorProps) {
+  const { state, descriptors, navigation, NavigationContent } =
+    useNavigationBuilder<
+      StackNavigationState<ParamListBase>,
+      StackRouterOptions,
+      StackActionHelpers<ParamListBase>,
+      LynxStackNavigationOptions,
+      LynxStackNavigationEventMap
+    >(StackRouter, {
+      initialRouteName,
+      routeNamesChangeBehavior,
+      children,
+      layout,
+      screenListeners,
+      screenOptions,
+      screenLayout,
+      router,
+    });
+
+  return (
+    <NavigationContent>
+      <LynxStackView
+        {...rest}
+        state={state}
+        navigation={navigation}
+        descriptors={descriptors}
+      />
+    </NavigationContent>
+  );
+}
+
+export interface LynxStackTypeBag extends NavigatorTypeBagBase {
+  State: StackNavigationState<this['ParamList']>;
+  ScreenOptions: LynxStackNavigationOptions;
+  EventMap: LynxStackNavigationEventMap;
+  ActionHelpers: StackActionHelpers<this['ParamList']>;
+  Navigator: typeof LynxStackNavigator;
+}
+
+export const createLynxStackNavigator =
+  createNavigatorFactory<LynxStackTypeBag>(LynxStackNavigator);
+
+export const createLynxStackScreen = createScreenFactory<LynxStackTypeBag>();

package/src/stack/types.ts

@@ -0,0 +1,66 @@
+import type {
+  DefaultNavigatorOptions,
+  Descriptor,
+  NavigationHelpers,
+  NavigationProp,
+  ParamListBase,
+  RouteProp,
+  StackActionHelpers,
+  StackNavigationState,
+  StackRouterOptions,
+} from '@react-navigation/core';
+import type * as Lynx from '@lynx-js/types';
+
+export type LynxStackPresentation = 'card' | 'formSheet';
+
+export type LynxStackNavigationOptions = {
+  presentation?: LynxStackPresentation | undefined;
+  contentStyle?: Lynx.CSSProperties | undefined;
+};
+
+export type LynxStackNavigationEventMap = {
+  transitionStart: { data: { closing: boolean } };
+  transitionEnd: { data: { closing: boolean } };
+};
+
+export type LynxStackNavigationProp<
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList = string,
+> = NavigationProp<
+  ParamList,
+  RouteName,
+  StackNavigationState<ParamList>,
+  LynxStackNavigationOptions,
+  LynxStackNavigationEventMap,
+  StackActionHelpers<ParamList>
+>;
+
+export type LynxStackScreenProps<
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList = string,
+> = {
+  navigation: LynxStackNavigationProp<ParamList, RouteName>;
+  route: RouteProp<ParamList, RouteName>;
+};
+
+export type LynxStackNavigationHelpers = NavigationHelpers<
+  ParamListBase,
+  LynxStackNavigationEventMap
+>;
+
+export type LynxStackDescriptor = Descriptor<
+  LynxStackNavigationOptions,
+  LynxStackNavigationProp<ParamListBase>,
+  RouteProp<ParamListBase>
+>;
+
+export type LynxStackDescriptorMap = Record<string, LynxStackDescriptor>;
+
+export type LynxStackNavigatorProps = DefaultNavigatorOptions<
+  ParamListBase,
+  StackNavigationState<ParamListBase>,
+  LynxStackNavigationOptions,
+  LynxStackNavigationEventMap,
+  LynxStackNavigationHelpers
+> &
+  StackRouterOptions;

package/src/stack/views/CardScreen.tsx

@@ -0,0 +1,102 @@
+import { NavigationProvider, usePreventRemoveContext } from '@react-navigation/core';
+import { StackScreenNativeComponent } from 'lynx-screens';
+
+import type { LynxStackDescriptor, LynxStackNavigationHelpers } from '../types';
+
+type Props = {
+  descriptor: LynxStackDescriptor;
+  navigation: LynxStackNavigationHelpers;
+  isFocused: boolean;
+  isBeforeLast: boolean;
+  isPopped: boolean;
+  isDetached: boolean;
+  onRemovePoppedRoute: (key: string) => void;
+  onNativeDismiss: () => void;
+  onNativeDismissPrevented: () => void;
+};
+
+export function CardScreen({
+  descriptor,
+  navigation,
+  isFocused,
+  isBeforeLast,
+  isPopped,
+  isDetached,
+  onRemovePoppedRoute,
+  onNativeDismiss,
+  onNativeDismissPrevented,
+}: Props) {
+  const { preventedRoutes } = usePreventRemoveContext();
+
+  const { route, options } = descriptor;
+  const { contentStyle } = options;
+
+  // A screen is kept out of the native hierarchy while it animates out or
+  // while it sits above the focused index (preloaded / retained).
+  const activityMode = isPopped || isDetached ? 'detached' : 'attached';
+
+  // Prevention comes from `usePreventRemove` and nothing else. A static option
+  // would be a trap: the native side would block the gesture, then the
+  // `onNativeDismissPrevented` round-trip below would pop the route anyway,
+  // because only a `beforeRemove` listener can cancel that dispatch.
+  const isRemovePrevented = preventedRoutes[route.key]?.preventRemove;
+
+  // Only the focused screen, the one behind it (so a swipe back reveals fresh
+  // content) and detached screens stay live. `isBeforeLast` and `isFocused`
+  // are read here rather than in the parent so the reasoning stays with the
+  // component that acts on it.
+  const isLive = isFocused || isBeforeLast || isDetached;
+
+  return (
+    <StackScreenNativeComponent
+      screenKey={route.key}
+      activityMode={activityMode}
+      preventNativeDismiss={isRemovePrevented}
+      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,
+        })
+      }
+      onDismiss={onRemovePoppedRoute}
+      onNativeDismiss={onNativeDismiss}
+      onNativeDismissPrevented={onNativeDismissPrevented}
+    >
+      <NavigationProvider navigation={descriptor.navigation} route={route}>
+        <view
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            width: '100%',
+            height: '100%',
+            ...contentStyle,
+          }}
+        >
+          {isLive ? descriptor.render() : null}
+        </view>
+      </NavigationProvider>
+    </StackScreenNativeComponent>
+  );
+}

package/src/stack/views/LynxStackView.tsx

@@ -0,0 +1,145 @@
+import {
+  type ParamListBase,
+  StackActions,
+  type StackNavigationState,
+} from '@react-navigation/core';
+import { StackHostNativeComponent } from 'lynx-screens';
+import type { Dispatch, ReactElement } from 'react';
+
+import type {
+  LynxStackDescriptorMap,
+  LynxStackNavigationHelpers,
+} from '../types';
+import { CardScreen } from './CardScreen';
+import {
+  type LynxStackViewState,
+  type LynxStackViewStateAction,
+  useViewState,
+} from './LynxStackViewState';
+
+type Props = {
+  state: StackNavigationState<ParamListBase>;
+  navigation: LynxStackNavigationHelpers;
+  descriptors: LynxStackDescriptorMap;
+};
+
+type ContentProps = Props &
+  Pick<LynxStackViewState, 'renderedRoutes' | 'poppedByKey'> & {
+    dispatch: Dispatch<LynxStackViewStateAction>;
+  };
+
+function LynxStackViewContent({
+  state,
+  navigation,
+  descriptors,
+  renderedRoutes,
+  poppedByKey,
+  dispatch,
+}: ContentProps) {
+  const routeIndexByKey = new Map(
+    state.routes.map((route, index) => [route.key, index])
+  );
+
+  const onRemovePoppedRoute = (key: string) => {
+    dispatch({ type: 'REMOVE_POPPED_ROUTE', key });
+  };
+
+  const onNativeDismiss = (key: string) => {
+    const currentState = navigation.getState();
+    const index = currentState.routes.findIndex((route) => route.key === key);
+
+    if (index === -1) {
+      return;
+    }
+
+    const dismissCount = currentState.index - index + 1;
+
+    if (dismissCount < 1) {
+      return;
+    }
+
+    // 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),
+    });
+
+    navigation.dispatch({
+      ...StackActions.pop(dismissCount),
+      source: key,
+      target: currentState.key,
+    });
+  };
+
+  // A prevented dismiss still has to reach the router: that is what gives
+  // `usePreventRemove` its `beforeRemove` event to act on.
+  const onNativeDismissPrevented = (key: string) => {
+    const currentState = navigation.getState();
+
+    navigation.dispatch({
+      ...StackActions.pop(),
+      source: key,
+      target: currentState.key,
+    });
+  };
+
+  const cards = renderedRoutes.reduce<ReactElement[]>((result, route) => {
+    const index = routeIndexByKey.get(route.key);
+    const popped = poppedByKey.get(route.key);
+    const descriptor = descriptors[route.key] ?? popped?.descriptor;
+
+    if (descriptor == null) {
+      throw new Error(
+        `Couldn't find descriptor for route ${route.name} (${route.key}). This is likely a bug.`
+      );
+    }
+
+    const presentation = descriptor.options.presentation ?? 'card';
+
+    if (presentation !== 'card') {
+      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.`
+      );
+    }
+
+    result.push(
+      <CardScreen
+        key={route.key}
+        descriptor={descriptor}
+        navigation={navigation}
+        isFocused={index === state.index}
+        isBeforeLast={index === state.index - 1}
+        isPopped={popped != null}
+        isDetached={index != null && index > state.index}
+        onRemovePoppedRoute={onRemovePoppedRoute}
+        onNativeDismiss={() => onNativeDismiss(route.key)}
+        onNativeDismissPrevented={() => onNativeDismissPrevented(route.key)}
+      />
+    );
+
+    return result;
+  }, []);
+
+  return <StackHostNativeComponent>{cards}</StackHostNativeComponent>;
+}
+
+export function LynxStackView({ state, navigation, descriptors }: Props) {
+  const [{ renderedRoutes, poppedByKey }, dispatch] = useViewState({
+    state,
+    descriptors,
+  });
+
+  return (
+    <LynxStackViewContent
+      state={state}
+      navigation={navigation}
+      descriptors={descriptors}
+      renderedRoutes={renderedRoutes}
+      poppedByKey={poppedByKey}
+      dispatch={dispatch}
+    />
+  );
+}