@natsuneko-laboratory/react-native-desktop-navigation 0.1.0-alpha.12

package/src/native/sidebar.tsx

@@ -0,0 +1,230 @@
+import React from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type {
+  ParamListBase,
+  RouteName,
+  SelectionNavigationState,
+} from '../routers';
+import {
+  useNavigator,
+  readScreens,
+  resolveOptions,
+  NavigatorStateContext,
+  type ScreenConfig,
+} from '../core/builder';
+import { Scene } from '../core/Scene';
+import { createNavigation } from '../core/navigation';
+import type {
+  CommonScreenOptions,
+  SidebarFooterProps,
+  SidebarNavigation,
+} from '../core/types';
+import { NativeSurface, type NativeAppearance } from './host';
+import { resolveNativeIcon, type NativeSidebarIconOption } from './icons';
+
+export interface NativeSidebarScreenOptions extends CommonScreenOptions {
+  label?: string;
+  icon?: NativeSidebarIconOption;
+  /** Square slot size for React icons, in points / DIPs (default 24). */
+  iconSize?: number;
+  hidden?: boolean;
+  disabled?: boolean;
+  /** Native item badge. Numbers <= 0 and empty strings hide it. */
+  badge?: number | string;
+}
+export interface NativeSidebarNavigatorProps {
+  children: React.ReactNode;
+  id?: string;
+  initialRouteName?: string;
+  defaultCollapsed?: boolean;
+  width?: number;
+  style?: StyleProp<ViewStyle>;
+  appearance?: NativeAppearance;
+  screenOptions?: NativeSidebarScreenOptions;
+  /** React content below the native item list. `children` is always null. */
+  renderSidebarFooter?: (props: SidebarFooterProps) => React.ReactNode;
+}
+function resolveBadge(badge: number | string | undefined) {
+  if (typeof badge === 'number')
+    return Number.isFinite(badge) && badge > 0 ? String(badge) : undefined;
+  return typeof badge === 'string' && badge !== '' ? badge : undefined;
+}
+export function createSidebarNavigator<
+  P extends ParamListBase = ParamListBase,
+>() {
+  function Screen<N extends RouteName<P>>(
+    _props: ScreenConfig<
+      P,
+      N,
+      NativeSidebarScreenOptions,
+      SidebarNavigation<P>
+    >,
+  ) {
+    return null;
+  }
+  function Section(_props: { title?: string; children: React.ReactNode }) {
+    return null;
+  }
+  function Navigator(
+    props: Omit<NativeSidebarNavigatorProps, 'initialRouteName'> & {
+      initialRouteName?: RouteName<P>;
+    },
+  ) {
+    if (
+      props.width !== undefined &&
+      (!Number.isFinite(props.width) || props.width < 100)
+    )
+      throw new Error(
+        'Native sidebar width must be a finite number of at least 100.',
+      );
+    const definitions = readScreens<NativeSidebarScreenOptions>(
+      props.children,
+      Screen,
+      Section,
+    );
+    const { id, state, store, navigation } =
+      useNavigator<SelectionNavigationState>(
+        'sidebar',
+        {
+          routes: definitions.map((d) => ({
+            ...d,
+            ...props.screenOptions,
+            ...(typeof d.options === 'object' ? d.options : {}),
+          })),
+          initialRouteName: props.initialRouteName,
+          defaultCollapsed: props.defaultCollapsed,
+        },
+        props.id,
+      );
+    const [footerHeight, setFooterHeight] = React.useState(0);
+    const collapseSidebar = () =>
+      store.dispatch({ target: id, type: 'collapseSidebar' });
+    const expandSidebar = () =>
+      store.dispatch({ target: id, type: 'expandSidebar' });
+    const footer = props.renderSidebarFooter?.({
+      collapsed: state.collapsed,
+      collapseSidebar,
+      expandSidebar,
+      toggleSidebar: () =>
+        state.collapsed ? expandSidebar() : collapseSidebar(),
+      children: null,
+    });
+    const hasFooter = footer != null && footer !== false;
+    const items = state.routes.map((route) => {
+      const definition = definitions.find((d) => d.name === route.name);
+      if (!definition)
+        throw new Error(
+          `Missing Screen: ${route.name}. Remount to change the screen list.`,
+        );
+      const options = resolveOptions(
+        definition,
+        route,
+        createNavigation(store, id, route.key),
+        props.screenOptions,
+      );
+      const iconState = {
+        focused: route.key === state.activeRouteKey,
+        disabled: options.disabled ?? false,
+      };
+      const icon =
+        typeof options.icon === 'function'
+          ? options.icon(iconState)
+          : options.icon;
+      return {
+        route,
+        definition,
+        options,
+        icon,
+        nativeIcon: resolveNativeIcon(icon, iconState, options.iconSize),
+      };
+    });
+    React.useLayoutEffect(() => {
+      store.updateOptions(id, {
+        key: id,
+        routes: items.map((i) => ({ name: i.route.name, ...i.options })),
+      });
+      const active = items.find((i) => i.route.key === state.activeRouteKey);
+      if (active?.options.disabled || active?.options.hidden) {
+        const next = items.find(
+          (i) => !i.options.disabled && !i.options.hidden,
+        );
+        if (next) navigation.select(next.route.name);
+      }
+    });
+    return (
+      <NavigatorStateContext.Provider value={state}>
+        <NativeSurface
+          style={props.style}
+          configuration={{
+            mode: 'sidebar',
+            items: items.map((i) => ({
+              key: i.route.key,
+              title: i.options.label ?? i.options.title ?? i.route.name,
+              hidden: i.options.hidden,
+              disabled: i.options.disabled,
+              section: i.definition.section?.title,
+              icon: i.nativeIcon,
+              badge: resolveBadge(i.options.badge),
+            })),
+            activeKey: state.activeRouteKey,
+            collapsed: state.collapsed,
+            paneWidth: props.width ?? 240,
+            footerHeight:
+              hasFooter && footerHeight > 0 ? footerHeight : undefined,
+            appearance: props.appearance,
+          }}
+          footer={hasFooter ? footer : undefined}
+          onFooterHeight={(height) =>
+            setFooterHeight((previous) =>
+              // Sub-point changes would only churn native revisions.
+              Math.abs(previous - height) < 0.5 ? previous : Math.ceil(height),
+            )
+          }
+          icons={items.flatMap((i) =>
+            React.isValidElement(i.icon) && !i.options.hidden
+              ? [{ key: i.route.key, content: i.icon }]
+              : [],
+          )}
+          onRequest={(request) => {
+            if (request.type === 'collapse')
+              request.collapsed ? collapseSidebar() : expandSidebar();
+            if (request.type === 'select') {
+              const item = items.find(
+                (i) =>
+                  i.route.key === request.key &&
+                  !i.options.hidden &&
+                  !i.options.disabled,
+              );
+              if (item) {
+                store.setFocusedNode(id);
+                navigation.select(item.route.name);
+              }
+            }
+          }}
+          slots={items.map(({ route, definition, options }) => ({
+            key: route.key,
+            visible:
+              route.key === state.activeRouteKey &&
+              !options.hidden &&
+              !options.disabled,
+            content: (ready) => (
+              <Scene
+                focusReady={ready}
+                nodeId={id}
+                route={route}
+                component={definition.component}
+                visible={
+                  route.key === state.activeRouteKey &&
+                  !options.hidden &&
+                  !options.disabled
+                }
+                options={options}
+              />
+            ),
+          }))}
+        />
+      </NavigatorStateContext.Provider>
+    );
+  }
+  return { Navigator, Screen, Section };
+}

package/src/native/specs/DesktopNavigationHostNativeComponent.ts

@@ -0,0 +1,12 @@
+import type { HostComponent, ViewProps } from 'react-native';
+import { codegenNativeComponent } from 'react-native';
+import type { DirectEventHandler } from 'react-native/Libraries/Types/CodegenTypes';
+
+export interface NativeProps extends ViewProps {
+  configuration: string;
+  onNavigationEvent?: DirectEventHandler<Readonly<{ payload: string }>>;
+}
+
+export default codegenNativeComponent<NativeProps>(
+  'DesktopNavigationHost',
+) as HostComponent<NativeProps>;

package/src/native/split.tsx

@@ -0,0 +1,160 @@
+import React from 'react';
+import { View, type StyleProp, type ViewStyle } from 'react-native';
+import { splitColumnConfig, type SplitNavigationState } from '../routers';
+import { useNavigator, NavigatorStateContext } from '../core/builder';
+import { Scene } from '../core/Scene';
+import { ScopeContext, SplitColumnContext } from '../core/context';
+import { NativeSurface, type NativeAppearance } from './host';
+
+export interface NativeSplitColumnProps {
+  id: string;
+  component: React.ComponentType;
+  defaultWidth?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  style?: StyleProp<ViewStyle>;
+  contentStyle?: StyleProp<ViewStyle>;
+}
+export interface NativeSplitNavigatorProps {
+  children: React.ReactNode;
+  id?: string;
+  style?: StyleProp<ViewStyle>;
+  appearance?: NativeAppearance;
+  layout?: (size: { width: number; height: number }) => string[];
+  onColumnResize?: (id: string, width: number) => void;
+}
+export function createSplitNavigator() {
+  function Column(_props: NativeSplitColumnProps) {
+    return null;
+  }
+  function Navigator(props: NativeSplitNavigatorProps) {
+    const columns: NativeSplitColumnProps[] = [];
+    React.Children.forEach(props.children, (child) => {
+      if (child == null || typeof child === 'boolean') return;
+      if (!React.isValidElement(child) || child.type !== Column)
+        throw new Error(
+          'Split.Navigator children must be Split.Column elements.',
+        );
+      columns.push(child.props as NativeSplitColumnProps);
+    });
+    const { id, state, store } = useNavigator<SplitNavigationState>(
+      'split',
+      { routes: columns.map((c) => ({ ...c, name: c.id })) },
+      props.id,
+    );
+    const [size, setSize] = React.useState<{
+      width: number;
+      height: number;
+    } | null>(null);
+    React.useLayoutEffect(() => {
+      if (!size) return;
+      const ids = props.layout ? props.layout(size) : columns.map((c) => c.id);
+      store.dispatch({ type: 'layout', target: id, payload: { ids } });
+    });
+    return (
+      <NavigatorStateContext.Provider value={state}>
+        <NativeSurface
+          style={props.style}
+          onMeasurements={(frames) => {
+            const before = store.getNode(id)?.state as
+              | SplitNavigationState
+              | undefined;
+            if (!before) return;
+            const widths = Object.fromEntries(
+              before.visibleColumnIds
+                .filter((key) => frames[key]?.width > 0)
+                .map((key) => [key, frames[key].width]),
+            );
+            store.dispatch({
+              type: 'layout',
+              target: id,
+              payload: { ids: before.visibleColumnIds, widths },
+            });
+            const after = store.getNode(id)!.state as SplitNavigationState;
+            for (const key of before.visibleColumnIds)
+              if (after.widths[key] !== before.widths[key])
+                props.onColumnResize?.(key, after.widths[key]);
+          }}
+          onLayout={(event) => {
+            const { width, height } = event.nativeEvent.layout;
+            setSize((previous) =>
+              previous?.width === width && previous.height === height
+                ? previous
+                : { width, height },
+            );
+          }}
+          configuration={{
+            mode: 'split',
+            items: columns.map((c) => ({ key: c.id, title: c.id })),
+            activeKey: state.activeRouteKey,
+            appearance: props.appearance,
+            columns: state.visibleColumnIds.map((key) => {
+              const c = columns.find((c) => c.id === key)!;
+              const constraints = splitColumnConfig(state, {
+                ...c,
+                name: c.id,
+              });
+              return {
+                key,
+                width: state.widths[key],
+                minWidth: constraints.minWidth ?? 100,
+                maxWidth: constraints.maxWidth,
+              };
+            }),
+          }}
+          onRequest={(request) => {
+            if (
+              request.type !== 'resize' ||
+              !state.visibleColumnIds.includes(request.key)
+            )
+              return;
+            const before = store.getNode(id)!.state as SplitNavigationState;
+            store.dispatch({
+              type: 'resize',
+              target: id,
+              payload: { id: request.key, width: request.width },
+            });
+            const after = store.getNode(id)!.state as SplitNavigationState;
+            if (before.widths[request.key] !== after.widths[request.key])
+              props.onColumnResize?.(request.key, after.widths[request.key]);
+          }}
+          slots={state.routes.map((route) => {
+            const column = columns.find((c) => c.id === route.name)!;
+            if (!column)
+              throw new Error(
+                `Missing Column: ${route.name}. Remount to change the column list.`,
+              );
+            const visible = state.visibleColumnIds.includes(route.name);
+            return {
+              key: route.name,
+              visible,
+              content: (ready) => (
+                <SplitColumnContext.Provider value={null}>
+                  <ScopeContext.Provider
+                    value={{ nodeId: id, routeKey: route.key }}
+                  >
+                    <View style={[{ flex: 1 }, column.style]}>
+                      <Scene
+                        focusReady={ready}
+                        nodeId={id}
+                        route={route}
+                        component={column.component}
+                        visible={visible}
+                        options={{
+                          focusBehavior: 'none',
+                          inactiveBehavior: 'keep',
+                          contentStyle: column.contentStyle,
+                        }}
+                      />
+                    </View>
+                  </ScopeContext.Provider>
+                </SplitColumnContext.Provider>
+              ),
+            };
+          })}
+        />
+      </NavigatorStateContext.Provider>
+    );
+  }
+  return { Navigator, Column };
+}

package/src/native/stack.tsx

@@ -0,0 +1,157 @@
+import React from 'react';
+import type {
+  HistoryBehavior,
+  ParamListBase,
+  RouteName,
+  StackNavigationState,
+} from '../routers';
+import {
+  useNavigator,
+  readScreens,
+  resolveOptions,
+  NavigatorStateContext,
+  type ScreenConfig,
+} from '../core/builder';
+import { Scene } from '../core/Scene';
+import { createNavigation } from '../core/navigation';
+import type { StackNavigation, StackScreenOptions } from '../core/types';
+import { StackHeader } from '../stack';
+import { NativeSurface, type NativeAppearance } from './host';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+/** Native stacks currently support card presentation without RN entrance animations. */
+export type NativeStackScreenOptions = Omit<
+  StackScreenOptions,
+  'animation' | 'presentation' | 'overlayStyle' | 'dialogStyle'
+>;
+export interface NativeStackNavigatorProps {
+  children: React.ReactNode;
+  id?: string;
+  initialRouteName?: string;
+  historyBehavior?: HistoryBehavior;
+  screenOptions?:
+    | NativeStackScreenOptions
+    | ((context: {
+        navigation: StackNavigation;
+        route: import('../routers').NavigationRoute;
+      }) => NativeStackScreenOptions);
+  style?: StyleProp<ViewStyle>;
+  appearance?: NativeAppearance;
+}
+export function createStackNavigator<
+  P extends ParamListBase = ParamListBase,
+>() {
+  function Screen<N extends RouteName<P>>(
+    _props: ScreenConfig<P, N, NativeStackScreenOptions, StackNavigation<P>>,
+  ) {
+    return null;
+  }
+  function Navigator(
+    props: Omit<NativeStackNavigatorProps, 'initialRouteName'> & {
+      initialRouteName?: RouteName<P>;
+    },
+  ) {
+    const definitions = readScreens<NativeStackScreenOptions>(
+      props.children,
+      Screen,
+    );
+    const { id, state, store } = useNavigator<StackNavigationState>(
+      'stack',
+      {
+        routes: definitions,
+        initialRouteName: props.initialRouteName,
+        historyBehavior: props.historyBehavior,
+      },
+      props.id,
+    );
+    const snapshot = React.useCallback(
+      () => store.canDispatch('back', id),
+      [store, id],
+    );
+    const canGoBack = React.useSyncExternalStore(
+      store.subscribe,
+      snapshot,
+      snapshot,
+    );
+    const scenes = state.routes.map((route) => {
+      const definition = definitions.find((d) => d.name === route.name);
+      if (!definition)
+        throw new Error(
+          `Missing Screen: ${route.name}. Remount to change the screen list.`,
+        );
+      const navigation = createNavigation(store, id, route.key);
+      const options = resolveOptions(
+        definition,
+        route,
+        navigation,
+        props.screenOptions,
+      );
+      // Any RN header customization selects the existing customizable header.
+      const customHeader = Object.keys(options).some(
+        (key) =>
+          key.startsWith('header') &&
+          !['headerShown', 'headerBackTitle'].includes(key),
+      );
+      return { route, definition, navigation, options, customHeader };
+    });
+    const active = scenes.find(
+      (scene) => scene.route.key === state.activeRouteKey,
+    )!;
+    return (
+      <NavigatorStateContext.Provider value={state}>
+        <NativeSurface
+          style={props.style}
+          configuration={{
+            mode: 'stack',
+            items: scenes.map((s) => ({
+              key: s.route.key,
+              title: s.options.title ?? s.route.name,
+            })),
+            activeKey: state.activeRouteKey,
+            appearance: props.appearance,
+            headerShown:
+              active.options.headerShown !== false && !active.customHeader,
+            canGoBack,
+            backTitle: active.options.headerBackTitle ?? 'Back',
+          }}
+          onRequest={(request) => {
+            if (request.type === 'back')
+              store.dispatch({ type: 'back', target: id });
+            if (request.type === 'pop' && request.count < state.routes.length)
+              store.dispatch({
+                type: 'pop',
+                target: id,
+                payload: { count: request.count },
+              });
+          }}
+          slots={scenes.map(
+            ({ route, definition, navigation, options, customHeader }) => ({
+              key: route.key,
+              visible: route.key === state.activeRouteKey,
+              content: (ready) => (
+                <Scene
+                  focusReady={ready}
+                  nodeId={id}
+                  route={route}
+                  component={definition.component}
+                  visible={route.key === state.activeRouteKey}
+                  options={options}
+                >
+                  {customHeader && (
+                    <StackHeader
+                      route={route}
+                      navigation={navigation}
+                      options={options}
+                      canGoBack={canGoBack}
+                    />
+                  )}
+                </Scene>
+              ),
+            }),
+          )}
+        />
+      </NavigatorStateContext.Provider>
+    );
+  }
+  return { Navigator, Screen };
+}

package/src/platform/index.tsx

@@ -0,0 +1,76 @@
+import React from 'react';
+import { Platform, TextInput, View, type ViewProps } from 'react-native';
+import { macosAdapter } from './macos';
+import { windowsAdapter } from './windows';
+export interface KeyboardShortcut {
+  key: string;
+  metaKey?: boolean;
+  ctrlKey?: boolean;
+  altKey?: boolean;
+  shiftKey?: boolean;
+}
+export interface DesktopKeyEvent {
+  nativeEvent: KeyboardShortcut & {
+    handled?: boolean;
+    isTextInput?: boolean;
+    target?: unknown;
+  };
+  defaultPrevented?: boolean;
+  isPropagationStopped?: () => boolean;
+  preventDefault?: () => void;
+  stopPropagation?: () => void;
+}
+export interface TransitionPreset {
+  duration: number;
+  offset: number;
+}
+export interface NavigationPlatformAdapter {
+  defaultTransitions: { push: TransitionPreset; pop: TransitionPreset };
+  keyboardShortcuts: {
+    back: KeyboardShortcut[];
+    forward: KeyboardShortcut[];
+    nextTab: KeyboardShortcut[];
+    previousTab: KeyboardShortcut[];
+  };
+  sidebar: { defaultWidth: number };
+  isTextInputEvent(event: DesktopKeyEvent): boolean;
+}
+export const defaultPlatformAdapter =
+  Platform.OS === 'windows' ? windowsAdapter : macosAdapter;
+export function isTextInputEvent(event: DesktopKeyEvent) {
+  return (
+    event.nativeEvent.isTextInput === true ||
+    TextInput.State.currentlyFocusedInput() != null
+  );
+}
+export function matchesShortcut(
+  event: DesktopKeyEvent,
+  shortcut: KeyboardShortcut,
+) {
+  return (
+    event.nativeEvent.key === shortcut.key &&
+    (['metaKey', 'ctrlKey', 'altKey', 'shiftKey'] as const).every(
+      (key) => !!event.nativeEvent[key] === !!shortcut[key],
+    )
+  );
+}
+export const eventHandled = (event: DesktopKeyEvent) =>
+  !!(
+    event.defaultPrevented ||
+    event.nativeEvent.handled ||
+    event.isPropagationStopped?.()
+  );
+export function consumeKey(event: DesktopKeyEvent) {
+  event.preventDefault?.();
+  event.stopPropagation?.();
+}
+export interface DesktopViewProps extends ViewProps {
+  onKeyDown?: (event: DesktopKeyEvent) => void;
+  keyDownEvents?: KeyboardShortcut[];
+  onFocus?: () => void;
+  focusable?: boolean;
+}
+// RN desktop adds these native View props. Keep the platform type extension in one place.
+export const DesktopView = View as unknown as React.ComponentType<
+  DesktopViewProps & React.RefAttributes<View>
+>;

package/src/platform/macos.ts

@@ -0,0 +1,15 @@
+import { isTextInputEvent, type NavigationPlatformAdapter } from './index';
+export const macosAdapter: NavigationPlatformAdapter = {
+  defaultTransitions: {
+    push: { duration: 160, offset: 12 },
+    pop: { duration: 120, offset: -12 },
+  },
+  keyboardShortcuts: {
+    back: [{ key: '[', metaKey: true }],
+    forward: [{ key: ']', metaKey: true }],
+    nextTab: [{ key: 'Tab', ctrlKey: true }],
+    previousTab: [{ key: 'Tab', ctrlKey: true, shiftKey: true }],
+  },
+  sidebar: { defaultWidth: 220 },
+  isTextInputEvent,
+};

package/src/platform/windows.ts

@@ -0,0 +1,15 @@
+import { isTextInputEvent, type NavigationPlatformAdapter } from './index';
+export const windowsAdapter: NavigationPlatformAdapter = {
+  defaultTransitions: {
+    push: { duration: 160, offset: 16 },
+    pop: { duration: 120, offset: -16 },
+  },
+  keyboardShortcuts: {
+    back: [{ key: 'ArrowLeft', altKey: true }],
+    forward: [{ key: 'ArrowRight', altKey: true }],
+    nextTab: [{ key: 'Tab', ctrlKey: true }],
+    previousTab: [{ key: 'Tab', ctrlKey: true, shiftKey: true }],
+  },
+  sidebar: { defaultWidth: 240 },
+  isTextInputEvent,
+};