@react-navigation/lynx 0.3.0 → 0.4.0-canary-20260910-73bb3f72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-navigation/lynx",
-  "version": "0.3.0",
+  "version": "0.4.0-canary-20260910-73bb3f72",
   "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/LinkingContext.ts

@@ -0,0 +1,16 @@
+import type { ParamListBase } from '@react-navigation/core';
+import * as React from 'react';
+
+import type { LinkingOptions } from './types';
+
+const MISSING_CONTEXT_ERROR = "Couldn't find a LinkingContext context.";
+
+export const LinkingContext = React.createContext<{
+  options?: LinkingOptions<ParamListBase>;
+}>({
+  get options(): any {
+    throw new Error(MISSING_CONTEXT_ERROR);
+  },
+});
+
+LinkingContext.displayName = 'LinkingContext';

package/src/LocaleDirContext.ts

@@ -0,0 +1,7 @@
+import * as React from 'react';
+
+import type { LocaleDirection } from './types';
+
+export const LocaleDirContext = React.createContext<LocaleDirection>('ltr');
+
+LocaleDirContext.displayName = 'LocaleDirContext';

package/src/NavigationContainer.tsx

@@ -1,21 +1,32 @@
 import {
   BaseNavigationContainer,
+  getActionFromState,
+  getPathFromState,
+  getStateFromPath,
   type NavigationContainerProps,
   type NavigationContainerRef,
   type NavigationState,
   type ParamListBase,
   type Theme,
   ThemeProvider,
+  validatePathConfig,
 } from '@react-navigation/core';
 import * as React from 'react';
 
+import { LinkingContext } from './LinkingContext';
+import { LocaleDirContext } from './LocaleDirContext';
 import { LightTheme } from './theming/LightTheme';
-import { type LinkingOptions, useLinking } from './useLinking';
+import type { LinkingOptions, LocaleDirection } from './types';
+import { useLinking } from './useLinking';
+
+const DEFAULT_DIRECTION: LocaleDirection = 'ltr';
 
 export type NavigationContainerLynxProps<
   ParamList extends {} = ParamListBase,
 > = NavigationContainerProps & {
   theme?: Theme | undefined;
+  /** Text direction of the components. Defaults to `'ltr'`. */
+  direction?: LocaleDirection | undefined;
   /** Rendered while persisted state is being restored. */
   fallback?: React.ReactNode | undefined;
   /** Maps URLs handed over by the host onto navigation state. */
@@ -31,6 +42,7 @@ export type NavigationContainerLynxProps<
  */
 export function NavigationContainer<ParamList extends {} = ParamListBase>({
   theme = LightTheme,
+  direction = DEFAULT_DIRECTION,
   fallback = null,
   onStateChange,
   linking,
@@ -52,6 +64,27 @@ export function NavigationContainer<ParamList extends {} = ParamListBase>({
     rest.initialState != null ? undefined : getInitialState()
   );
 
+  const linkingConfig = React.useMemo(() => {
+    if (linking == null) {
+      return { options: { enabled: false } };
+    }
+
+    if (linking.config) {
+      validatePathConfig(linking.config);
+    }
+
+    return {
+      options: {
+        ...linking,
+        enabled: linking.enabled !== false,
+        prefixes: linking.prefixes ?? ['*'],
+        getStateFromPath: linking.getStateFromPath ?? getStateFromPath,
+        getPathFromState: linking.getPathFromState ?? getPathFromState,
+        getActionFromState: linking.getActionFromState ?? getActionFromState,
+      },
+    };
+  }, [linking]);
+
   const { children: _children, ...restWithoutChildren } = rest;
 
   const handleStateChange = (state: Readonly<NavigationState> | undefined) => {
@@ -59,18 +92,26 @@ export function NavigationContainer<ParamList extends {} = ParamListBase>({
   };
 
   if (rest.children == null) {
-    return <ThemeProvider value={theme}>{fallback}</ThemeProvider>;
+    return (
+      <LocaleDirContext.Provider value={direction}>
+        <ThemeProvider value={theme}>{fallback}</ThemeProvider>
+      </LocaleDirContext.Provider>
+    );
   }
 
   return (
-    <BaseNavigationContainer
-      {...restWithoutChildren}
-      initialState={rest.initialState ?? linkingInitialState}
-      theme={theme}
-      onStateChange={handleStateChange}
-      ref={refContainer}
-    >
-      {rest.children}
-    </BaseNavigationContainer>
+    <LocaleDirContext.Provider value={direction}>
+      <LinkingContext.Provider value={linkingConfig}>
+        <BaseNavigationContainer
+          {...restWithoutChildren}
+          initialState={rest.initialState ?? linkingInitialState}
+          theme={theme}
+          onStateChange={handleStateChange}
+          ref={refContainer}
+        >
+          {rest.children}
+        </BaseNavigationContainer>
+      </LinkingContext.Provider>
+    </LocaleDirContext.Provider>
   );
 }

package/src/__tests__/getStateFromHref.test.ts

@@ -0,0 +1,40 @@
+import { expect, test } from 'vitest';
+
+import { getStateFromHref } from '../getStateFromHref';
+
+const config = {
+  screens: {
+    Home: '',
+    Detail: 'detail/:id',
+  },
+};
+
+test('parses an absolute path against the config', () => {
+  expect(getStateFromHref('/detail/42', { config }, undefined)).toEqual({
+    routes: [{ name: 'Detail', params: { id: '42' }, path: '/detail/42' }],
+  });
+});
+
+test('strips a matching prefix before parsing', () => {
+  expect(
+    getStateFromHref('myapp://detail/7', { prefixes: ['myapp://'], config }, undefined)
+  ).toEqual({
+    routes: [{ name: 'Detail', params: { id: '7' }, path: '/detail/7' }],
+  });
+});
+
+test('rejects a URL that no prefix matches', () => {
+  expect(() =>
+    getStateFromHref('other://detail/7', { prefixes: ['myapp://'], config }, undefined)
+  ).toThrow("Got invalid href 'other://detail/7'");
+});
+
+test('rejects a URL the filter refuses', () => {
+  expect(() =>
+    getStateFromHref(
+      'myapp://detail/7',
+      { prefixes: ['myapp://'], config, filter: () => false },
+      undefined
+    )
+  ).toThrow("doesn't match the filter");
+});

package/src/extractPathFromURL.ts

@@ -1,6 +1,6 @@
 import escapeStringRegexp from 'escape-string-regexp';
 
-import type { LinkingPrefix } from './useLinking';
+import type { LinkingPrefix } from './types';
 
 /** Verbatim from `@react-navigation/native`, which cannot be imported here. */
 export function extractPathFromURL(prefixes: LinkingPrefix[], url: string) {

package/src/getStateFromHref.ts

@@ -0,0 +1,49 @@
+import {
+  getStateFromPath,
+  type NavigationState,
+  type ParamListBase,
+} from '@react-navigation/core';
+
+import { extractPathFromURL } from './extractPathFromURL';
+import type { LinkingOptions } from './types';
+
+export function getStateFromHref(
+  href: string,
+  options: LinkingOptions<ParamListBase> | undefined,
+  previous: NavigationState | undefined
+): ReturnType<typeof getStateFromPath> {
+  const {
+    prefixes,
+    filter,
+    config,
+    getStateFromPath: getStateFromPathHelper = getStateFromPath,
+  } = options || {};
+
+  let path;
+
+  if (href.startsWith('/')) {
+    path = href;
+  } else if (href) {
+    if (filter && !filter(href)) {
+      throw new Error(
+        `Failed to parse href '${href}'. It doesn't match the filter specified in linking config.`
+      );
+    }
+
+    if (prefixes == null || prefixes.length === 0) {
+      throw new Error(
+        `Failed to parse href '${href}'. It doesn't start with '/' and no prefixes are defined in linking config.`
+      );
+    }
+
+    path = extractPathFromURL(prefixes, href);
+  }
+
+  if (path == null) {
+    throw new Error(
+      `Got invalid href '${href}'. It must start with '/' or match one of the prefixes: ${options?.prefixes?.map((prefix) => `'${prefix}'`).join(', ')}.`
+    );
+  }
+
+  return getStateFromPathHelper(path, config, previous);
+}

package/src/index.tsx

@@ -2,13 +2,20 @@
 // 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 { LinkingContext } from './LinkingContext';
+export { LocaleDirContext } from './LocaleDirContext';
 export {
   NavigationContainer,
   type NavigationContainerLynxProps,
 } from './NavigationContainer';
 export { DarkTheme } from './theming/DarkTheme';
 export { LightTheme as DefaultTheme } from './theming/LightTheme';
+export { MaterialDarkTheme, MaterialLightTheme } from './theming/MaterialTheme';
+export * from './types';
+export { useLinkBuilder } from './useLinkBuilder';
+export { useLinkTo } from './useLinkTo';
+export { useLocale } from './useLocale';
+export { useRoutePath } from './useRoutePath';
 
 export {
   getInitialURL,
@@ -18,6 +25,5 @@ export {
   URL_EVENT,
   type NavigationInitData,
 } from './linking';
-export type { LinkingOptions, LinkingPrefix } from './useLinking';
 
 export * from '@react-navigation/core';

package/src/stack/index.tsx

@@ -7,17 +7,20 @@ export {
   type LynxStackTypeBag,
 } from './navigators/createLynxStackNavigator';
 
+/**
+ * Views
+ */
+export { LynxStackView } from './views/LynxStackView';
+
 /**
  * Types
  */
 export type {
-  LynxStackDescriptor,
-  LynxStackDescriptorMap,
   LynxStackNavigationEventMap,
-  LynxStackNavigationHelpers,
   LynxStackNavigationOptions,
   LynxStackNavigationProp,
   LynxStackNavigatorProps,
+  LynxStackOptionsArgs,
   LynxStackPresentation,
   LynxStackScreenProps,
 } from './types';

package/src/stack/types.ts

@@ -8,6 +8,7 @@ import type {
   StackActionHelpers,
   StackNavigationState,
   StackRouterOptions,
+  Theme,
 } from '@react-navigation/core';
 import type * as Lynx from '@lynx-js/types';
 
@@ -16,11 +17,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<
@@ -43,6 +58,13 @@ export type LynxStackScreenProps<
   route: RouteProp<ParamList, RouteName>;
 };
 
+export type LynxStackOptionsArgs<
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList = keyof ParamList,
+> = LynxStackScreenProps<ParamList, RouteName> & {
+  theme: Theme;
+};
+
 export type LynxStackNavigationHelpers = NavigationHelpers<
   ParamListBase,
   LynxStackNavigationEventMap

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>
+  );
+}

package/src/theming/MaterialFallbackTheme.ts

@@ -0,0 +1,30 @@
+import type { LynxTheme } from '../types';
+
+import { fonts } from './fonts';
+
+/** Same palette as `@react-navigation/native`'s Material fallback themes. */
+export const MaterialLightFallbackTheme = {
+  dark: false,
+  colors: {
+    primary: '#6750a4',
+    background: '#f3edf7',
+    card: '#fef7ff',
+    text: '#1d1b20',
+    border: '#cac4d0',
+    notification: '#ba1a1a',
+  },
+  fonts,
+} as const satisfies LynxTheme;
+
+export const MaterialDarkFallbackTheme = {
+  dark: true,
+  colors: {
+    primary: '#d0bcff',
+    background: '#211f26',
+    card: '#141218',
+    text: '#e6e0e9',
+    border: '#49454f',
+    notification: '#ffb4ab',
+  },
+  fonts,
+} as const satisfies LynxTheme;

package/src/theming/MaterialTheme.ts

@@ -0,0 +1,4 @@
+export {
+  MaterialDarkFallbackTheme as MaterialDarkTheme,
+  MaterialLightFallbackTheme as MaterialLightTheme,
+} from './MaterialFallbackTheme';

package/src/types.ts

@@ -1,3 +1,9 @@
+import type {
+  getActionFromState as getActionFromStateDefault,
+  getPathFromState as getPathFromStateDefault,
+  getStateFromPath as getStateFromPathDefault,
+} from '@react-navigation/core';
+
 type FontStyle = {
   fontFamily: string;
   fontWeight:
@@ -40,3 +46,31 @@ export interface LynxTheme {
 declare module '@react-navigation/core' {
   interface Theme extends LynxTheme {}
 }
+
+export type LocaleDirection = 'ltr' | 'rtl';
+
+// core keeps its `Options` type internal; derive it from the consumer so it
+// cannot drift.
+type LinkingConfig<ParamList extends {}> = NonNullable<
+  Parameters<typeof getStateFromPathDefault<ParamList>>[1]
+>;
+
+export type LinkingPrefix = '*' | (string & {});
+
+export type LinkingOptions<ParamList extends {}> = {
+  /** Defaults to true when a config is given. */
+  enabled?: boolean | undefined;
+  prefixes?: LinkingPrefix[] | undefined;
+  /** Rejects a URL before its prefix is stripped. */
+  filter?: ((url: string) => boolean) | undefined;
+  config?: LinkingConfig<ParamList> | undefined;
+  /** Overrides where the launch URL comes from. */
+  getInitialURL?: (() => string | undefined) | undefined;
+  /** Overrides how later URLs arrive. */
+  subscribe?:
+    | ((listener: (url: string) => void) => undefined | void | (() => void))
+    | undefined;
+  getStateFromPath?: typeof getStateFromPathDefault | undefined;
+  getPathFromState?: typeof getPathFromStateDefault | undefined;
+  getActionFromState?: typeof getActionFromStateDefault | undefined;
+} & { [key: string]: unknown };

package/src/useLinkBuilder.ts

@@ -0,0 +1,138 @@
+import {
+  CommonActions,
+  getActionFromState,
+  getPathFromState,
+  IsScreenContext,
+  NavigationContainerRefContext,
+  useStateForPath,
+} from '@react-navigation/core';
+import * as React from 'react';
+
+import { getStateFromHref } from './getStateFromHref';
+import { LinkingContext } from './LinkingContext';
+
+type MinimalState = {
+  routes: [
+    {
+      name: string;
+      params?: object | undefined;
+      state?: MinimalState | undefined;
+    },
+  ];
+};
+
+/**
+ * Helper to build a href for a screen based on the linking options.
+ */
+export function useBuildHref() {
+  const isScreen = React.use(IsScreenContext);
+  const { options } = React.use(LinkingContext);
+  const focusedRouteState = useStateForPath();
+
+  const getPathFromStateHelper = options?.getPathFromState ?? getPathFromState;
+
+  const buildHref = React.useCallback(
+    (name: string, params?: object) => {
+      if (options?.enabled === false) {
+        return undefined;
+      }
+
+      const stateForRoute: MinimalState = {
+        routes: [{ name, params }],
+      };
+
+      const constructState = (
+        state: MinimalState | undefined
+      ): MinimalState => {
+        if (state) {
+          const route = state.routes[0];
+
+          // Inside a screen at the innermost route the provided state replaces
+          // it: the target is a sibling.
+          if (isScreen && !route.state) {
+            return stateForRoute;
+          }
+
+          return {
+            routes: [
+              {
+                ...route,
+                state: constructState(route.state),
+              },
+            ],
+          };
+        }
+
+        // No nested state left: the target is a child of this route, which is
+        // the case when a navigator builds hrefs for its own routes.
+        return stateForRoute;
+      };
+
+      const state = constructState(focusedRouteState);
+
+      return getPathFromStateHelper(state, options?.config);
+    },
+    [
+      options?.enabled,
+      options?.config,
+      isScreen,
+      focusedRouteState,
+      getPathFromStateHelper,
+    ]
+  );
+
+  return buildHref;
+}
+
+/**
+ * Helper to build a navigation action from a href based on the linking options.
+ */
+export function useBuildAction() {
+  const navigation = React.use(NavigationContainerRefContext);
+
+  if (navigation === undefined) {
+    throw new Error(
+      "Couldn't find a navigation object. Is your component inside NavigationContainer?"
+    );
+  }
+
+  const { options } = React.use(LinkingContext);
+
+  const getActionFromStateHelper =
+    options?.getActionFromState ?? getActionFromState;
+
+  const buildAction = React.useCallback(
+    (href: string) => {
+      const rootState = navigation.getRootState();
+      const state = getStateFromHref(href, options, rootState);
+
+      if (state) {
+        const action =
+          getActionFromStateHelper(state, options?.config) ??
+          CommonActions.reset(state);
+
+        return { target: rootState?.key, ...action };
+      }
+
+      throw new Error(`Failed to parse href '${href}' to a navigation state.`);
+    },
+    [navigation, options, getActionFromStateHelper]
+  );
+
+  return buildAction;
+}
+
+/**
+ * Helpers to build href or action based on the linking options.
+ *
+ * @returns `buildHref` to build an `href` for screen and `buildAction` to build an action from an `href`.
+ */
+export function useLinkBuilder() {
+  const buildHref = useBuildHref();
+  const buildAction = useBuildAction();
+
+  return {
+    buildHref,
+    buildAction,
+  };
+}

package/src/useLinkTo.ts

@@ -0,0 +1,27 @@
+import { NavigationRootContext } from '@react-navigation/core';
+import * as React from 'react';
+
+import { useBuildAction } from './useLinkBuilder';
+
+export function useLinkTo() {
+  const navigation = React.use(NavigationRootContext);
+
+  if (navigation === undefined) {
+    throw new Error(
+      "Couldn't find a navigation object. Is your component inside NavigationContainer?"
+    );
+  }
+
+  const buildAction = useBuildAction();
+
+  const linkTo = React.useCallback(
+    (href: string) => {
+      const action = buildAction(href);
+
+      navigation.dispatch(action);
+    },
+    [buildAction, navigation]
+  );
+
+  return linkTo;
+}

package/src/useLinking.ts

@@ -9,36 +9,12 @@ import {
 import * as React from 'react';
 
 import { extractPathFromURL } from './extractPathFromURL';
+import type { LinkingOptions, LinkingPrefix } from './types';
 import {
   getInitialURL as getInitialURLDefault,
   subscribe as subscribeDefault,
 } from './linking';
 
-// core keeps its `Options` type internal; derive it from the consumer so it
-// cannot drift.
-type LinkingConfig<ParamList extends {}> = NonNullable<
-  Parameters<typeof getStateFromPathDefault<ParamList>>[1]
->;
-
-export type LinkingPrefix = '*' | (string & {});
-
-export type LinkingOptions<ParamList extends {}> = {
-  /** Defaults to true when a config is given. */
-  enabled?: boolean | undefined;
-  prefixes?: LinkingPrefix[] | undefined;
-  /** Rejects a URL before its prefix is stripped. */
-  filter?: ((url: string) => boolean) | undefined;
-  config?: LinkingConfig<ParamList> | undefined;
-  /** Overrides where the launch URL comes from. */
-  getInitialURL?: (() => string | undefined) | undefined;
-  /** Overrides how later URLs arrive. */
-  subscribe?:
-    | ((listener: (url: string) => void) => undefined | void | (() => void))
-    | undefined;
-  getStateFromPath?: typeof getStateFromPathDefault | undefined;
-  getActionFromState?: typeof getActionFromStateDefault | undefined;
-} & { [key: string]: unknown };
-
 /** The `getStateFromHref` contract of `@react-navigation/native`. */
 function extractPath(
   url: string,

package/src/useLocale.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+
+import { LocaleDirContext } from './LocaleDirContext';
+
+export function useLocale() {
+  const direction = React.use(LocaleDirContext);
+
+  if (direction === undefined) {
+    throw new Error(
+      "Couldn't determine the text direction. Is your component inside NavigationContainer?"
+    );
+  }
+
+  return { direction };
+}

package/src/useRoutePath.ts

@@ -0,0 +1,27 @@
+import { getPathFromState, useStateForPath } from '@react-navigation/core';
+import * as React from 'react';
+
+import { LinkingContext } from './LinkingContext';
+
+export function useRoutePath() {
+  const { options } = React.use(LinkingContext);
+  const state = useStateForPath();
+
+  if (state === undefined) {
+    throw new Error(
+      "Couldn't find a state for the route object. Is your component inside a screen in a navigator?"
+    );
+  }
+
+  const getPathFromStateHelper = options?.getPathFromState ?? getPathFromState;
+
+  const path = React.useMemo(() => {
+    if (options?.enabled === false) {
+      return undefined;
+    }
+
+    return getPathFromStateHelper(state, options?.config);
+  }, [options?.enabled, options?.config, state, getPathFromStateHelper]);
+
+  return path;
+}