@gtkx/navigation 0.0.1

package/src/index.ts

@@ -0,0 +1,83 @@
+export {
+    createDrawerNavigator,
+    createDrawerScreen,
+    DrawerNavigator,
+    type DrawerTypeBag,
+} from "./drawer/create-drawer-navigator.js";
+export { DrawerItemList } from "./drawer/drawer-item-list.js";
+export type {
+    DrawerContentProps,
+    DrawerDescriptor,
+    DrawerDescriptorMap,
+    DrawerHeaderProps,
+    DrawerNavigationConfig,
+    DrawerNavigationEventMap,
+    DrawerNavigationHelpers,
+    DrawerNavigationOptions,
+    DrawerNavigationProp,
+    DrawerNavigatorProps,
+    DrawerScreenProps,
+} from "./drawer/types.js";
+export {
+    NavigationContainer,
+    type NavigationContainerComponent,
+    type NavigationContainerProps,
+} from "./navigation-container.js";
+export type { HeaderOptions } from "./shared/types.js";
+export {
+    createSplitViewNavigator,
+    createSplitViewScreen,
+    SplitViewNavigator,
+    type SplitViewTypeBag,
+} from "./split-view/create-split-view-navigator.js";
+export type {
+    SplitViewDescriptor,
+    SplitViewDescriptorMap,
+    SplitViewNavigationConfig,
+    SplitViewNavigationEventMap,
+    SplitViewNavigationHelpers,
+    SplitViewNavigationOptions,
+    SplitViewNavigationProp,
+    SplitViewNavigatorProps,
+    SplitViewScreenProps,
+} from "./split-view/types.js";
+export {
+    createStackNavigator,
+    createStackScreen,
+    StackNavigator,
+    type StackTypeBag,
+} from "./stack/create-stack-navigator.js";
+export type {
+    StackDescriptor,
+    StackDescriptorMap,
+    StackHeaderBack,
+    StackHeaderProps,
+    StackNavigationConfig,
+    StackNavigationEventMap,
+    StackNavigationHelpers,
+    StackNavigationOptions,
+    StackNavigationProp,
+    StackNavigatorProps,
+    StackScreenProps,
+    StackTransitionData,
+} from "./stack/types.js";
+export {
+    createStaticNavigation,
+    type StaticNavigationProps,
+    type StaticNavigationTree,
+} from "./static-navigation.js";
+export { createTabNavigator, createTabScreen, TabNavigator, type TabTypeBag } from "./tabs/create-tab-navigator.js";
+export type {
+    TabDescriptor,
+    TabDescriptorMap,
+    TabHeaderProps,
+    TabNavigationConfig,
+    TabNavigationEventMap,
+    TabNavigationHelpers,
+    TabNavigationOptions,
+    TabNavigationProp,
+    TabNavigatorProps,
+    TabScreenProps,
+} from "./tabs/types.js";
+export { DarkTheme, DefaultTheme, type Theme } from "./theme.js";
+export * from "@react-navigation/core";

package/src/navigation-container.tsx

@@ -0,0 +1,35 @@
+import type {
+    NavigationContainerProps as CoreContainerProps,
+    NavigationContainerRef,
+    ParamListBase,
+} from "@react-navigation/core";
+import type { ReactNode, Ref } from "react";
+import { BaseNavigationContainer } from "@react-navigation/core";
+import { useAdwaitaTheme } from "./theme.js";
+
+/** Props of {@link NavigationContainer}. */
+type NavigationContainerProps<ParamList extends object = ReactNavigation.RootParamList> = Omit<
+    CoreContainerProps,
+    "navigationInChildEnabled" | "theme"
+> & {
+    /** Theme handed to `useTheme` and option callbacks; defaults to the live Adwaita style state. */
+    theme?: ReactNavigation.Theme;
+    /** Receives the container's imperative navigation API. */
+    ref?: Ref<NavigationContainerRef<ParamList>>;
+};
+
+/** The {@link NavigationContainer} component, generic over the root param list. */
+type NavigationContainerComponent = <ParamList extends object = ReactNavigation.RootParamList>(
+    props: NavigationContainerProps<ParamList>,
+) => ReactNode;
+
+/** Hosts the navigation tree: render it once at the root, around the navigators. */
+const NavigationContainer: NavigationContainerComponent = NavigationContainerInner as NavigationContainerComponent;
+
+function NavigationContainerInner({ ref, theme, ...rest }: NavigationContainerProps<ParamListBase>): ReactNode {
+    const adwaitaTheme = useAdwaitaTheme();
+
+    return <BaseNavigationContainer {...rest} ref={ref} theme={theme ?? adwaitaTheme} />;
+}
+
+export { NavigationContainer, type NavigationContainerComponent, type NavigationContainerProps };

package/src/shared/header-bar.tsx

@@ -0,0 +1,34 @@
+import type { ReactElement, ReactNode } from "react";
+import { AdwHeaderBar, AdwWindowTitle } from "@gtkx/jsx/adw";
+import type { HeaderOptions } from "./types.js";
+
+type HeaderBarProps = {
+    options: HeaderOptions;
+    titleWidget?: ReactElement;
+    start?: ReactNode;
+    showBackButton?: boolean;
+};
+
+const resolveTitleWidget = (options: HeaderOptions, fallback: ReactElement | undefined): ReactElement | undefined => {
+    if (typeof options.headerTitle === "string") {
+        return <AdwWindowTitle title={options.headerTitle} />;
+    }
+
+    return options.headerTitle ?? fallback;
+};
+
+const HeaderBar = ({ options, titleWidget, start, showBackButton }: HeaderBarProps): ReactNode => (
+    <AdwHeaderBar
+        showBackButton={showBackButton ?? true}
+        titleWidget={resolveTitleWidget(options, titleWidget)}
+        start={(
+            <>
+                {start}
+                {options.headerStart}
+            </>
+        )}
+        end={options.headerEnd}
+    />
+);
+
+export { HeaderBar };

package/src/shared/routes.ts

@@ -0,0 +1,25 @@
+import type { NavigationState } from "@react-navigation/core";
+
+type FocusedRoute<State extends NavigationState> = State["routes"][number];
+
+const getFocusedRoute = <State extends NavigationState>(state: State): FocusedRoute<State> => {
+    const route = state.routes[state.index];
+
+    if (route === undefined) {
+        throw new Error(`Navigation state has no route at index ${String(state.index)}`);
+    }
+
+    return route;
+};
+
+const requireDescriptor = <Descriptor>(descriptors: Record<string, Descriptor>, key: string): Descriptor => {
+    const descriptor = descriptors[key];
+
+    if (descriptor === undefined) {
+        throw new Error(`No descriptor for route "${key}"`);
+    }
+
+    return descriptor;
+};
+
+export { getFocusedRoute, requireDescriptor };

package/src/shared/scene-page.tsx

@@ -0,0 +1,27 @@
+import type { ReactElement, ReactNode } from "react";
+import { AdwBin, AdwViewStackPage } from "@gtkx/jsx/adw";
+
+type ScenePageProps = {
+    name: string;
+    title: string;
+    iconName?: string;
+    badgeNumber?: number;
+    needsAttention?: boolean;
+    isLoaded: boolean;
+    render: () => ReactElement;
+};
+
+const ScenePage = ({ name, title, isLoaded, render, ...page }: ScenePageProps): ReactNode => (
+    <AdwViewStackPage
+        name={name}
+        title={title}
+        iconName={page.iconName}
+        badgeNumber={page.badgeNumber}
+        needsAttention={page.needsAttention}
+        useUnderline={false}
+    >
+        <AdwBin>{isLoaded ? render() : null}</AdwBin>
+    </AdwViewStackPage>
+);
+
+export { ScenePage };

package/src/shared/types.ts

@@ -0,0 +1,17 @@
+import type { ReactElement, ReactNode } from "react";
+
+/** Header options shared by every navigator. */
+type HeaderOptions = {
+    /** Title of the screen, shown in the header bar; defaults to the route name. */
+    title?: string;
+    /** Whether to render a header bar above the screen; defaults to `true`. */
+    headerShown?: boolean;
+    /** Replaces the header bar title: a string becomes an `AdwWindowTitle`, an element is used as the title widget. */
+    headerTitle?: string | ReactElement;
+    /** Widgets packed at the start of the header bar. */
+    headerStart?: ReactNode;
+    /** Widgets packed at the end of the header bar. */
+    headerEnd?: ReactNode;
+};
+
+export type { HeaderOptions };

package/src/shared/use-loaded-routes.ts

@@ -0,0 +1,14 @@
+import { useState } from "react";
+
+const useLoadedRoutes = (focusedKey: string, preloadedKeys: readonly string[]): ReadonlySet<string> => {
+    const [loaded, setLoaded] = useState<ReadonlySet<string>>(() => new Set([focusedKey]));
+    const pending = [focusedKey, ...preloadedKeys].filter((key) => !loaded.has(key));
+
+    if (pending.length > 0) {
+        setLoaded(new Set([...loaded, ...pending]));
+    }
+
+    return loaded;
+};
+
+export { useLoadedRoutes };

package/src/shared/use-pop-to-top-on-blur.ts

@@ -0,0 +1,45 @@
+import type { NavigationHelpers, NavigationState, ParamListBase } from "@react-navigation/core";
+import { StackActions } from "@react-navigation/core";
+import { useEffect, useRef } from "react";
+
+type BlurOptions = { popToTopOnBlur?: boolean };
+type BlurDescriptors = Record<string, { options: BlurOptions }>;
+
+const nestedStackKey = (state: NavigationState, routeKey: string): string | null => {
+    const nested = state.routes.find((route) => route.key === routeKey)?.state;
+
+    if (nested?.type === "stack" && typeof nested.key === "string") {
+        return nested.key;
+    }
+
+    return null;
+};
+
+const popToTopTarget = (state: NavigationState, descriptors: BlurDescriptors, blurredKey: string): string | null =>
+    descriptors[blurredKey]?.options.popToTopOnBlur === true ? nestedStackKey(state, blurredKey) : null;
+
+const usePopToTopOnBlur = (
+    state: NavigationState,
+    descriptors: BlurDescriptors,
+    navigation: NavigationHelpers<ParamListBase>,
+): void => {
+    const focusedKey = state.routes[state.index]?.key;
+    const previousKeyRef = useRef(focusedKey);
+
+    useEffect(() => {
+        const previousKey = previousKeyRef.current;
+        previousKeyRef.current = focusedKey;
+
+        if (previousKey === undefined || previousKey === focusedKey) {
+            return;
+        }
+
+        const target = popToTopTarget(state, descriptors, previousKey);
+
+        if (target !== null) {
+            navigation.dispatch({ ...StackActions.popToTop(), target });
+        }
+    }, [focusedKey, descriptors, navigation, state]);
+};
+
+export { usePopToTopOnBlur };

package/src/split-view/create-split-view-navigator.tsx

@@ -0,0 +1,99 @@
+import type {
+    NavigatorTypeBagBase,
+    ParamListBase,
+    StackActionHelpers,
+    StackNavigationState,
+    StackRouterOptions,
+    StaticConfig,
+    StaticScreenFactory,
+    TypedNavigator,
+} from "@react-navigation/core";
+import type { ReactNode } from "react";
+import { createNavigatorFactory, createScreenFactory, useNavigationBuilder } from "@react-navigation/core";
+import type {
+    SplitViewNavigationEventMap,
+    SplitViewNavigationOptions,
+    SplitViewNavigationProp,
+    SplitViewNavigatorProps,
+} from "./types.js";
+import { splitViewRouter } from "./split-view-router.js";
+import { SplitView } from "./split-view.js";
+
+/** Type bag describing the split view navigator to React Navigation's typed APIs. */
+type SplitViewTypeBag<
+    ParamList extends ParamListBase = ParamListBase,
+    NavigatorID extends string | undefined = string | undefined,
+> = {
+    /** Route names and their params. */
+    ParamList: ParamList;
+    /** Optional navigator id. */
+    NavigatorID: NavigatorID;
+    /** Shape of the navigator state. */
+    State: StackNavigationState<ParamList>;
+    /** Per-screen options. */
+    ScreenOptions: SplitViewNavigationOptions;
+    /** Events the navigator emits. */
+    EventMap: SplitViewNavigationEventMap;
+    /** Navigation object per route. */
+    NavigationList: {
+        [RouteName in keyof ParamList]: SplitViewNavigationProp<ParamList, RouteName, NavigatorID>;
+    };
+    /** The navigator component. */
+    Navigator: typeof SplitViewNavigator;
+};
+
+/** Declares a typed screen of a split view navigator for the static configuration API. */
+const createSplitViewScreen: StaticScreenFactory<SplitViewTypeBag> = createScreenFactory<SplitViewTypeBag>();
+
+/** Renders the screens of a {@link createSplitViewNavigator} in an `AdwNavigationSplitView`. */
+function SplitViewNavigator({
+    collapsed,
+    contentPlaceholder,
+    sidebarPosition,
+    minSidebarWidth,
+    maxSidebarWidth,
+    sidebarWidthFraction,
+    popOnEscape,
+    ...options
+}: SplitViewNavigatorProps): ReactNode {
+    const { state, describe, descriptors, navigation, NavigationContent } = useNavigationBuilder<
+        StackNavigationState<ParamListBase>,
+        StackRouterOptions,
+        StackActionHelpers<ParamListBase>,
+        SplitViewNavigationOptions,
+        SplitViewNavigationEventMap
+    >(splitViewRouter, options);
+
+    return (
+        <NavigationContent>
+            <SplitView
+                state={state}
+                navigation={navigation}
+                descriptors={descriptors}
+                describe={describe}
+                collapsed={collapsed}
+                contentPlaceholder={contentPlaceholder}
+                sidebarPosition={sidebarPosition}
+                minSidebarWidth={minSidebarWidth}
+                maxSidebarWidth={maxSidebarWidth}
+                sidebarWidthFraction={sidebarWidthFraction}
+                popOnEscape={popOnEscape}
+            />
+        </NavigationContent>
+    );
+}
+
+/**
+ * Creates a master/detail navigator rendered with `AdwNavigationSplitView`: the first screen fills the sidebar
+ * pane, the rest are a stack in the content pane, and a narrow window collapses the two into one.
+ */
+function createSplitViewNavigator<
+    const ParamList extends ParamListBase,
+    const NavigatorID extends string | undefined = string | undefined,
+    const TypeBag extends NavigatorTypeBagBase = SplitViewTypeBag<ParamList, NavigatorID>,
+    const Config extends StaticConfig<TypeBag> | undefined = undefined,
+>(config?: Config): TypedNavigator<TypeBag, Config> {
+    return createNavigatorFactory(SplitViewNavigator)(config) as TypedNavigator<TypeBag, Config>;
+}
+
+export { createSplitViewNavigator, createSplitViewScreen, SplitViewNavigator, type SplitViewTypeBag };

package/src/split-view/split-view-router.ts

@@ -0,0 +1,73 @@
+import type { ParamListBase, RouterConfigOptions, StackNavigationState } from "@react-navigation/core";
+import { StackRouter } from "@react-navigation/routers";
+
+type StackState = StackNavigationState<ParamListBase>;
+type StackRoute = StackState["routes"][number];
+type StackRouterFactory = typeof StackRouter;
+type StackRouterInstance = ReturnType<StackRouterFactory>;
+type SidebarSlot = { route: StackRoute | undefined; serial: number };
+type RouterAction = Parameters<StackRouterInstance["getStateForAction"]>[1];
+
+const sidebarName = (config: RouterConfigOptions): string | undefined => config.routeNames[0];
+
+const buildSidebarRoute = (slot: SidebarSlot, config: RouterConfigOptions, name: string): StackRoute => {
+    slot.serial += 1;
+
+    return { key: `${name}-sidebar-${String(slot.serial)}`, name, params: config.routeParamList[name] };
+};
+
+const resolveSidebarRoute = (slot: SidebarSlot, state: StackState, config: RouterConfigOptions): StackRoute => {
+    const name = sidebarName(config) ?? "";
+    const existing = state.routes.find((route) => route.name === name);
+    const cached = slot.route?.name === name ? slot.route : undefined;
+
+    return existing ?? cached ?? buildSidebarRoute(slot, config, name);
+};
+
+const pinSidebar = (slot: SidebarSlot, state: StackState, config: RouterConfigOptions): StackState => {
+    const name = sidebarName(config);
+
+    if (name === undefined || state.routes[0]?.name === name) {
+        slot.route = state.routes[0];
+
+        return state;
+    }
+
+    const sidebar = resolveSidebarRoute(slot, state, config);
+    const routes = [sidebar, ...state.routes.filter((route) => route.name !== name)];
+    const focusedKey = state.routes[state.index]?.key;
+    const index = routes.findIndex((route) => route.key === focusedKey);
+    slot.route = sidebar;
+
+    return { ...state, routes, index: index === -1 ? routes.length - 1 : index };
+};
+
+const asSelection = (action: RouterAction): RouterAction => {
+    if (action.type !== "NAVIGATE" || action.payload.pop !== undefined) {
+        return action;
+    }
+
+    return { ...action, payload: { ...action.payload, pop: true } };
+};
+
+const pinActionResult = (
+    slot: SidebarSlot,
+    result: ReturnType<StackRouterInstance["getStateForAction"]>,
+    config: RouterConfigOptions,
+): ReturnType<StackRouterInstance["getStateForAction"]> =>
+    result?.stale === false ? pinSidebar(slot, result, config) : result;
+
+const withPinnedSidebar = (router: StackRouterInstance, slot: SidebarSlot): StackRouterInstance => ({
+    ...router,
+    getInitialState: (config) => pinSidebar(slot, router.getInitialState(config), config),
+    getRehydratedState: (state, config) => pinSidebar(slot, router.getRehydratedState(state, config), config),
+    getStateForRouteNamesChange: (state, config) =>
+        pinSidebar(slot, router.getStateForRouteNamesChange(state, config), config),
+    getStateForAction: (state, action, config) =>
+        pinActionResult(slot, router.getStateForAction(state, asSelection(action), config), config),
+});
+
+const splitViewRouter: StackRouterFactory = (options) =>
+    withPinnedSidebar(StackRouter(options), { route: undefined, serial: 0 });
+
+export { splitViewRouter };

package/src/split-view/split-view.tsx

@@ -0,0 +1,137 @@
+import type * as Adw from "@gtkx/gi/adw";
+import type { ParamListBase, RouteProp, StackNavigationState } from "@react-navigation/core";
+import type { ReactNode } from "react";
+import * as Gdk from "@gtkx/gi/gdk";
+import * as Gtk from "@gtkx/gi/gtk";
+import { AdwNavigationPage, AdwNavigationSplitView, AdwToolbarView } from "@gtkx/jsx/adw";
+import { GtkEventControllerKey } from "@gtkx/jsx/gtk";
+import { StackActions } from "@react-navigation/core";
+import { useCallback, useRef } from "react";
+import type {
+    SplitViewDescriptor,
+    SplitViewDescriptorMap,
+    SplitViewNavigationConfig,
+    SplitViewNavigationHelpers,
+} from "./types.js";
+import { HeaderBar } from "../shared/header-bar.js";
+import { requireDescriptor } from "../shared/routes.js";
+import { StackView } from "../stack/stack-view.js";
+
+type ViewRef = { current: Adw.NavigationSplitView | null };
+
+type SplitViewProps = SplitViewNavigationConfig & {
+    state: StackNavigationState<ParamListBase>;
+    navigation: SplitViewNavigationHelpers;
+    descriptors: SplitViewDescriptorMap;
+    describe: (route: RouteProp<ParamListBase>, isPlaceholder: boolean) => SplitViewDescriptor;
+};
+
+const PACK_TYPES = { start: Gtk.PackType.START, end: Gtk.PackType.END } as const;
+const CONTENT_TITLE = "Content";
+const ESCAPE_KEYVAL = Gdk.KEY_Escape;
+
+const hasContent = (state: { routes: readonly unknown[] }): boolean => state.routes.length > 1;
+
+const contentTitle = (state: StackNavigationState<ParamListBase>, descriptors: SplitViewDescriptorMap): string => {
+    const route = state.routes[state.index];
+
+    if (route === undefined || state.index === 0) {
+        return state.routeNames[1] ?? CONTENT_TITLE;
+    }
+
+    return descriptors[route.key]?.options.title ?? route.name;
+};
+
+const popContent = (navigation: SplitViewNavigationHelpers): void => {
+    const state = navigation.getState();
+    navigation.dispatch({ ...StackActions.pop(state.routes.length - 1), target: state.key });
+};
+
+const settleShowContent = (viewRef: ViewRef, isShown: boolean, isSettled: boolean): void => {
+    if (isSettled !== isShown && viewRef.current !== null) {
+        viewRef.current.setShowContent(isSettled);
+    }
+};
+
+const useContentSync = (
+    viewRef: ViewRef,
+    navigation: SplitViewNavigationHelpers,
+): ((isShown: boolean | null) => void) =>
+    useCallback((isShown: boolean | null) => {
+        if (isShown === null || isShown === hasContent(navigation.getState())) {
+            return;
+        }
+
+        if (!isShown) {
+            popContent(navigation);
+        }
+
+        settleShowContent(viewRef, isShown, hasContent(navigation.getState()));
+    }, [viewRef, navigation]);
+
+const EscapeGuard = (): ReactNode => (
+    <GtkEventControllerKey
+        propagationPhase={Gtk.PropagationPhase.BUBBLE}
+        onKeyPressed={(keyval) => keyval === ESCAPE_KEYVAL}
+    />
+);
+
+const SidebarPage = ({ descriptor }: { descriptor: SplitViewDescriptor }): ReactNode => {
+    const { route, options, navigation } = descriptor;
+
+    if (options.headerShown === false) {
+        return <AdwNavigationPage title={options.title ?? route.name}>{descriptor.render()}</AdwNavigationPage>;
+    }
+
+    const topBar = options.header === undefined
+        ? <HeaderBar options={options} showBackButton={false} />
+        : <>{options.header({ route, navigation, options, back: undefined })}</>;
+
+    return (
+        <AdwNavigationPage title={options.title ?? route.name}>
+            <AdwToolbarView topBar={topBar}>{descriptor.render()}</AdwToolbarView>
+        </AdwNavigationPage>
+    );
+};
+
+const SplitView = (props: SplitViewProps): ReactNode => {
+    const { state, navigation, descriptors, describe, contentPlaceholder } = props;
+    const { collapsed = false, sidebarPosition = "start", minSidebarWidth, maxSidebarWidth } = props;
+    const viewRef = useRef<Adw.NavigationSplitView | null>(null);
+    const onShowContentChanged = useContentSync(viewRef, navigation);
+    const sidebar = requireDescriptor(descriptors, state.routes[0]?.key ?? "");
+
+    return (
+        <AdwNavigationSplitView
+            ref={viewRef}
+            collapsed={collapsed}
+            showContent={hasContent(state)}
+            sidebarPosition={PACK_TYPES[sidebarPosition]}
+            minSidebarWidth={minSidebarWidth}
+            maxSidebarWidth={maxSidebarWidth}
+            sidebarWidthFraction={props.sidebarWidthFraction}
+            onNotifyShowContent={onShowContentChanged}
+            sidebar={<SidebarPage descriptor={sidebar} />}
+        >
+            <AdwNavigationPage
+                title={contentTitle(state, descriptors)}
+                controllers={collapsed && props.popOnEscape === false ? <EscapeGuard /> : null}
+            >
+                {hasContent(state)
+                    ? (
+                            <StackView
+                                offset={1}
+                                popOnEscape={props.popOnEscape}
+                                state={state}
+                                navigation={navigation}
+                                descriptors={descriptors}
+                                describe={describe}
+                            />
+                        )
+                    : <>{contentPlaceholder}</>}
+            </AdwNavigationPage>
+        </AdwNavigationSplitView>
+    );
+};
+
+export { SplitView };