@gtkx/navigation 0.0.1

package/src/split-view/types.ts

@@ -0,0 +1,100 @@
+import type {
+    DefaultNavigatorOptions,
+    Descriptor,
+    NavigationHelpers,
+    NavigationProp,
+    ParamListBase,
+    RouteProp,
+    StackActionHelpers,
+    StackNavigationState,
+    StackRouterOptions,
+} from "@react-navigation/core";
+import type { ReactNode } from "react";
+import type { StackNavigationEventMap, StackNavigationOptions } from "../stack/types.js";
+
+/** Events the split view navigator emits: the stack's transition events, from the content pane. */
+type SplitViewNavigationEventMap = StackNavigationEventMap;
+/** Per-screen options of the split view navigator, the same ones a stack screen takes. */
+type SplitViewNavigationOptions = StackNavigationOptions;
+
+/** Navigation object of a split view screen. */
+type SplitViewNavigationProp<
+    ParamList extends ParamListBase,
+    RouteName extends keyof ParamList = keyof ParamList,
+    NavigatorID extends string | undefined = undefined,
+> = NavigationProp<
+    ParamList,
+    RouteName,
+    NavigatorID,
+    StackNavigationState<ParamList>,
+    SplitViewNavigationOptions,
+    SplitViewNavigationEventMap
+> & StackActionHelpers<ParamList>;
+
+/** Props a split view screen component receives. */
+type SplitViewScreenProps<
+    ParamList extends ParamListBase,
+    RouteName extends keyof ParamList = keyof ParamList,
+    NavigatorID extends string | undefined = undefined,
+> = {
+    /** Navigation object of the screen. */
+    navigation: SplitViewNavigationProp<ParamList, RouteName, NavigatorID>;
+    /** The route the screen renders. */
+    route: RouteProp<ParamList, RouteName>;
+};
+
+/** Navigation helpers of the split view navigator itself. */
+type SplitViewNavigationHelpers = NavigationHelpers<ParamListBase, SplitViewNavigationEventMap> &
+    StackActionHelpers<ParamListBase>;
+
+/** Descriptor of one split view route. */
+type SplitViewDescriptor = Descriptor<
+    SplitViewNavigationOptions,
+    SplitViewNavigationProp<ParamListBase>,
+    RouteProp<ParamListBase>
+>;
+
+/** Descriptors of the split view routes, keyed by route key. */
+type SplitViewDescriptorMap = Record<string, SplitViewDescriptor>;
+
+/** Props of the split view navigator beyond the options every navigator shares. */
+type SplitViewNavigationConfig = {
+    /** Whether the panes stack into one instead of sitting side by side; defaults to `false`. */
+    collapsed?: boolean;
+    /** Fills the content pane while no content route is open; defaults to nothing. */
+    contentPlaceholder?: ReactNode;
+    /** Which side the sidebar sits on; defaults to `"start"`. */
+    sidebarPosition?: "start" | "end";
+    /** Minimum sidebar width, in the unit libadwaita uses for the split view. */
+    minSidebarWidth?: number;
+    /** Maximum sidebar width, in the unit libadwaita uses for the split view. */
+    maxSidebarWidth?: number;
+    /** Preferred sidebar width as a fraction of the total width. */
+    sidebarWidthFraction?: number;
+    /** Whether pressing Escape pops the visible content page; defaults to `true`. */
+    popOnEscape?: boolean;
+};
+
+/** Props of the split view `Navigator` component. */
+type SplitViewNavigatorProps = DefaultNavigatorOptions<
+    ParamListBase,
+    string | undefined,
+    StackNavigationState<ParamListBase>,
+    SplitViewNavigationOptions,
+    SplitViewNavigationEventMap,
+    SplitViewNavigationProp<ParamListBase>
+> &
+StackRouterOptions &
+SplitViewNavigationConfig;
+
+export type {
+    SplitViewDescriptor,
+    SplitViewDescriptorMap,
+    SplitViewNavigationConfig,
+    SplitViewNavigationEventMap,
+    SplitViewNavigationHelpers,
+    SplitViewNavigationOptions,
+    SplitViewNavigationProp,
+    SplitViewNavigatorProps,
+    SplitViewScreenProps,
+};

package/src/stack/create-stack-navigator.tsx

@@ -0,0 +1,80 @@
+import type {
+    NavigatorTypeBagBase,
+    ParamListBase,
+    StackActionHelpers,
+    StackNavigationState,
+    StackRouterOptions,
+    StaticConfig,
+    StaticScreenFactory,
+    TypedNavigator,
+} from "@react-navigation/core";
+import type { ReactNode } from "react";
+import { createNavigatorFactory, createScreenFactory, StackRouter, useNavigationBuilder } from "@react-navigation/core";
+import type {
+    StackNavigationEventMap,
+    StackNavigationOptions,
+    StackNavigationProp,
+    StackNavigatorProps,
+} from "./types.js";
+import { StackView } from "./stack-view.js";
+
+/** Type bag describing the stack navigator to React Navigation's typed APIs. */
+type StackTypeBag<
+    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: StackNavigationOptions;
+    /** Events the navigator emits. */
+    EventMap: StackNavigationEventMap;
+    /** Navigation object per route. */
+    NavigationList: {
+        [RouteName in keyof ParamList]: StackNavigationProp<ParamList, RouteName, NavigatorID>;
+    };
+    /** The navigator component. */
+    Navigator: typeof StackNavigator;
+};
+
+/** Declares a typed screen of a stack navigator for the static configuration API. */
+const createStackScreen: StaticScreenFactory<StackTypeBag> = createScreenFactory<StackTypeBag>();
+
+/** Renders the screens of a {@link createStackNavigator} as pages of an `AdwNavigationView`. */
+function StackNavigator({ popOnEscape, ...options }: StackNavigatorProps): ReactNode {
+    const { state, describe, descriptors, navigation, NavigationContent } = useNavigationBuilder<
+        StackNavigationState<ParamListBase>,
+        StackRouterOptions,
+        StackActionHelpers<ParamListBase>,
+        StackNavigationOptions,
+        StackNavigationEventMap
+    >(StackRouter, options);
+
+    return (
+        <NavigationContent>
+            <StackView
+                popOnEscape={popOnEscape}
+                state={state}
+                navigation={navigation}
+                descriptors={descriptors}
+                describe={describe}
+            />
+        </NavigationContent>
+    );
+}
+
+/** Creates a stack navigator rendered with `AdwNavigationView`: pushes and pops animate like native Adwaita pages. */
+function createStackNavigator<
+    const ParamList extends ParamListBase,
+    const NavigatorID extends string | undefined = string | undefined,
+    const TypeBag extends NavigatorTypeBagBase = StackTypeBag<ParamList, NavigatorID>,
+    const Config extends StaticConfig<TypeBag> | undefined = undefined,
+>(config?: Config): TypedNavigator<TypeBag, Config> {
+    return createNavigatorFactory(StackNavigator)(config) as TypedNavigator<TypeBag, Config>;
+}
+
+export { createStackNavigator, createStackScreen, StackNavigator, type StackTypeBag };

package/src/stack/stack-pages.ts

@@ -0,0 +1,140 @@
+import type { ParamListBase, RouteProp, StackNavigationState } from "@react-navigation/core";
+import { useCallback, useState } from "react";
+import type { StackDescriptor, StackDescriptorMap } from "./types.js";
+
+type StackState = StackNavigationState<ParamListBase>;
+type Describe = (route: RouteProp<ParamListBase>, isPlaceholder: boolean) => StackDescriptor;
+
+type PageTracking = {
+    order: readonly string[];
+    focusedKey: string | undefined;
+    descriptors: StackDescriptorMap;
+    closing: StackDescriptorMap;
+};
+
+type StackPages = {
+    pages: readonly StackDescriptor[];
+    release: (key: string) => void;
+};
+
+const getFocusedKey = (state: StackState, offset: number): string | undefined =>
+    state.index < offset ? undefined : state.routes[state.index]?.key;
+
+const mountedKeys = (state: StackState, offset: number): string[] => [
+    ...state.routes.slice(offset).map((route) => route.key),
+    ...state.preloadedRoutes.map((route) => route.key),
+];
+
+const neededKeys = (state: StackState, closing: StackDescriptorMap, offset: number): string[] => [
+    ...mountedKeys(state, offset),
+    ...Object.keys(closing),
+];
+
+const hasSameMembers = (left: readonly string[], right: readonly string[]): boolean =>
+    left.length === right.length && left.every((key) => right.includes(key));
+
+const hasRefreshedFocus = (tracking: PageTracking, descriptors: StackDescriptorMap): boolean => {
+    const { focusedKey } = tracking;
+
+    if (focusedKey === undefined) {
+        return false;
+    }
+
+    const next = descriptors[focusedKey];
+
+    return next !== undefined && tracking.descriptors[focusedKey]?.route !== next.route;
+};
+
+const appendOrder = (previous: readonly string[], needed: readonly string[]): string[] => [
+    ...previous.filter((key) => needed.includes(key)),
+    ...needed.filter((key) => !previous.includes(key)),
+];
+
+const withoutKeys = (map: StackDescriptorMap, keys: readonly string[]): StackDescriptorMap =>
+    Object.fromEntries(Object.entries(map).filter(([key]) => !keys.includes(key)));
+
+const nextClosing = (tracking: PageTracking, state: StackState, offset: number): StackDescriptorMap => {
+    const mounted = mountedKeys(state, offset);
+    const kept = withoutKeys(tracking.closing, mounted);
+    const { focusedKey } = tracking;
+
+    if (focusedKey === undefined || mounted.includes(focusedKey)) {
+        return kept;
+    }
+
+    const descriptor = tracking.descriptors[focusedKey];
+
+    return descriptor === undefined ? kept : { ...kept, [focusedKey]: descriptor };
+};
+
+const advance = (
+    tracking: PageTracking,
+    state: StackState,
+    descriptors: StackDescriptorMap,
+    offset: number,
+): PageTracking => {
+    const closing = nextClosing(tracking, state, offset);
+
+    return {
+        order: appendOrder(tracking.order, neededKeys(state, closing, offset)),
+        focusedKey: getFocusedKey(state, offset),
+        descriptors,
+        closing,
+    };
+};
+
+const initialTracking = (state: StackState, descriptors: StackDescriptorMap, offset: number): PageTracking => ({
+    order: neededKeys(state, {}, offset),
+    focusedKey: getFocusedKey(state, offset),
+    descriptors,
+    closing: {},
+});
+
+const resolvePage = (
+    key: string,
+    sources: { state: StackState; descriptors: StackDescriptorMap; closing: StackDescriptorMap },
+    describe: Describe,
+): StackDescriptor | undefined => {
+    const preloaded = sources.state.preloadedRoutes.find((route) => route.key === key);
+
+    if (preloaded !== undefined) {
+        return describe(preloaded, true);
+    }
+
+    return sources.descriptors[key] ?? sources.closing[key];
+};
+
+const useStackPages = (
+    state: StackState,
+    descriptors: StackDescriptorMap,
+    describe: Describe,
+    offset: number,
+): StackPages => {
+    const [tracking, setTracking] = useState<PageTracking>(() => initialTracking(state, descriptors, offset));
+
+    if (!hasSameMembers(tracking.order, neededKeys(state, tracking.closing, offset)) ||
+        tracking.focusedKey !== getFocusedKey(state, offset) ||
+        hasRefreshedFocus(tracking, descriptors)) {
+        setTracking(advance(tracking, state, descriptors, offset));
+    }
+
+    const release = useCallback((key: string) => {
+        setTracking((current) => (current.closing[key] === undefined
+            ? current
+            : {
+                    ...current,
+                    order: current.order.filter((entry) => entry !== key),
+                    closing: withoutKeys(current.closing, [key]),
+                }));
+    }, []);
+
+    const sources = { state, descriptors, closing: tracking.closing };
+
+    const pages = tracking.order
+        .map((key) => resolvePage(key, sources, describe))
+        .filter((page) => page !== undefined);
+
+    return { pages, release };
+};
+
+export { type Describe, useStackPages };

package/src/stack/stack-view.tsx

@@ -0,0 +1,202 @@
+import type * as Adw from "@gtkx/gi/adw";
+import type { ParamListBase, StackNavigationState } from "@react-navigation/core";
+import type { ReactNode, RefObject } from "react";
+import { AdwNavigationPage, AdwNavigationView, AdwToolbarView } from "@gtkx/jsx/adw";
+import { useCallback, useEffect, useRef } from "react";
+import type { Describe } from "./stack-pages.js";
+import type { OptionsByKey } from "./sync-navigation-stack.js";
+import type {
+    StackDescriptor,
+    StackDescriptorMap,
+    StackNavigationConfig,
+    StackNavigationEventMap,
+    StackNavigationHelpers,
+    StackNavigationOptions,
+} from "./types.js";
+import { HeaderBar } from "../shared/header-bar.js";
+import { useStackPages } from "./stack-pages.js";
+import { reconcilePoppedStack, syncNavigationStack } from "./sync-navigation-stack.js";
+
+type ViewRef = RefObject<Adw.NavigationView | null>;
+type MutableOptions = Record<string, StackNavigationOptions>;
+
+type StackViewProps = StackNavigationConfig & {
+    state: StackNavigationState<ParamListBase>;
+    navigation: StackNavigationHelpers;
+    descriptors: StackDescriptorMap;
+    describe: Describe;
+    offset?: number;
+};
+
+type StackPageProps = {
+    descriptor: StackDescriptor;
+    previous?: StackDescriptor;
+    navigation: StackNavigationHelpers;
+    onHidden: (key: string) => void;
+};
+
+type TransitionEvent = keyof StackNavigationEventMap;
+
+const previousDescriptor = (
+    state: StackNavigationState<ParamListBase>,
+    descriptors: StackDescriptorMap,
+    key: string,
+    offset: number,
+): StackDescriptor | undefined => {
+    const index = state.routes.findIndex((route) => route.key === key);
+    const previousKey = index > offset ? state.routes[index - 1]?.key : undefined;
+
+    return previousKey === undefined ? undefined : descriptors[previousKey];
+};
+
+const useLatest = <T,>(value: T): RefObject<T> => {
+    const ref = useRef(value);
+
+    useEffect(() => {
+        ref.current = value;
+    }, [value]);
+
+    return ref;
+};
+
+const useTrackedOptions = (descriptors: StackDescriptorMap): RefObject<MutableOptions> => {
+    const optionsRef = useRef<MutableOptions>({});
+
+    useEffect(() => {
+        for (const [key, descriptor] of Object.entries(descriptors)) {
+            optionsRef.current[key] = descriptor.options;
+        }
+    }, [descriptors]);
+
+    return optionsRef;
+};
+
+const useStackSync = (
+    viewRef: ViewRef,
+    state: StackNavigationState<ParamListBase>,
+    options: RefObject<OptionsByKey>,
+    offset: number,
+): void => {
+    const isInitialRef = useRef(true);
+
+    useEffect(() => {
+        const view = viewRef.current;
+
+        if (view === null) {
+            return;
+        }
+
+        const desired = state.routes.slice(offset).map((route) => route.key);
+        syncNavigationStack(view, desired, options.current, isInitialRef.current);
+        isInitialRef.current = false;
+    }, [viewRef, state, options, offset]);
+};
+
+const usePoppedHandler = (
+    viewRef: ViewRef,
+    navigation: StackNavigationHelpers,
+    options: RefObject<OptionsByKey>,
+    offset: number,
+): (() => void) => {
+    const navigationRef = useLatest(navigation);
+    const isScheduledRef = useRef(false);
+
+    return useCallback(() => {
+        if (isScheduledRef.current) {
+            return;
+        }
+
+        isScheduledRef.current = true;
+
+        queueMicrotask(() => {
+            isScheduledRef.current = false;
+            const view = viewRef.current;
+
+            if (view !== null) {
+                reconcilePoppedStack(view, navigationRef.current, options.current, offset);
+            }
+        });
+    }, [viewRef, navigationRef, options, offset]);
+};
+
+const StackPageContent = ({ descriptor, previous }: Omit<StackPageProps, "navigation" | "onHidden">): ReactNode => {
+    const { route, options, navigation } = descriptor;
+
+    if (options.headerShown === false) {
+        return descriptor.render();
+    }
+
+    const back = previous === undefined ? undefined : { title: previous.options.title ?? previous.route.name };
+
+    const topBar = options.header === undefined
+        ? <HeaderBar options={options} showBackButton={options.headerBackVisible ?? true} />
+        : <>{options.header({ route, navigation, options, back })}</>;
+
+    return <AdwToolbarView topBar={topBar}>{descriptor.render()}</AdwToolbarView>;
+};
+
+const StackPage = ({ descriptor, previous, navigation, onHidden }: StackPageProps): ReactNode => {
+    const { route, options } = descriptor;
+    const pageRef = useRef<Adw.NavigationPage | null>(null);
+
+    const emit = (type: TransitionEvent, isClosing: boolean): void => {
+        navigation.emit({ type, data: { closing: isClosing }, target: route.key });
+    };
+
+    useEffect(() => {
+        const page = pageRef.current;
+
+        if (page !== null && !page.getMapped()) {
+            onHidden(route.key);
+        }
+    });
+
+    return (
+        <AdwNavigationPage
+            ref={pageRef}
+            tag={route.key}
+            title={options.title ?? route.name}
+            canPop={options.canPop ?? true}
+            onShowing={() => {
+                emit("transitionStart", false);
+            }}
+            onHiding={() => {
+                emit("transitionStart", true);
+            }}
+            onShown={() => {
+                emit("transitionEnd", false);
+            }}
+            onHidden={() => {
+                emit("transitionEnd", true);
+                onHidden(route.key);
+            }}
+        >
+            <StackPageContent descriptor={descriptor} previous={previous} />
+        </AdwNavigationPage>
+    );
+};
+
+const StackView = (props: StackViewProps): ReactNode => {
+    const { state, navigation, descriptors, describe, popOnEscape, offset = 0 } = props;
+    const viewRef = useRef<Adw.NavigationView | null>(null);
+    const options = useTrackedOptions(descriptors);
+    const { pages, release } = useStackPages(state, descriptors, describe, offset);
+    const onPopped = usePoppedHandler(viewRef, navigation, options, offset);
+    useStackSync(viewRef, state, options, offset);
+
+    return (
+        <AdwNavigationView ref={viewRef} popOnEscape={popOnEscape ?? true} onPopped={onPopped}>
+            {pages.map((descriptor) => (
+                <StackPage
+                    key={descriptor.route.key}
+                    descriptor={descriptor}
+                    previous={previousDescriptor(state, descriptors, descriptor.route.key, offset)}
+                    navigation={navigation}
+                    onHidden={release}
+                />
+            ))}
+        </AdwNavigationView>
+    );
+};
+
+export { StackView };

package/src/stack/sync-navigation-stack.ts

@@ -0,0 +1,117 @@
+import * as Adw from "@gtkx/gi/adw";
+import { StackActions } from "@react-navigation/core";
+import type { StackNavigationHelpers, StackNavigationOptions } from "./types.js";
+
+type OptionsByKey = Readonly<Record<string, StackNavigationOptions | undefined>>;
+
+const readNavigationStack = (view: Adw.NavigationView): string[] => {
+    const model = view.getNavigationStack();
+    const count = model.getNItems();
+    const tags: string[] = [];
+
+    for (let index = 0; index < count; index += 1) {
+        const page = model.getItem(index);
+        const tag = page instanceof Adw.NavigationPage ? page.getTag() : null;
+
+        if (tag !== null) {
+            tags.push(tag);
+        }
+    }
+
+    return tags;
+};
+
+const isSameStack = (left: readonly string[], right: readonly string[]): boolean =>
+    left.length === right.length && left.every((tag, index) => right[index] === tag);
+
+const isStrictPrefix = (prefix: readonly string[], list: readonly string[]): boolean =>
+    prefix.length < list.length && prefix.every((tag, index) => list[index] === tag);
+
+const isAnimated = (options: OptionsByKey, key: string | undefined): boolean =>
+    key === undefined || options[key]?.animation !== "none";
+
+const pushOnto = (
+    view: Adw.NavigationView,
+    current: readonly string[],
+    desired: readonly string[],
+    options: OptionsByKey,
+): void => {
+    const base = desired.slice(0, -1);
+    const last = desired.at(-1);
+
+    if (!isSameStack(base, current)) {
+        view.replaceWithTags(base);
+    }
+
+    if (last !== undefined) {
+        view.setAnimateTransitions(isAnimated(options, last));
+        view.pushByTag(last);
+    }
+};
+
+const applyStackChange = (
+    view: Adw.NavigationView,
+    current: readonly string[],
+    desired: readonly string[],
+    options: OptionsByKey,
+): void => {
+    const last = desired.at(-1);
+
+    if (last !== undefined && isStrictPrefix(desired, current)) {
+        view.setAnimateTransitions(isAnimated(options, current.at(-1)));
+        view.popToTag(last);
+    } else if (isStrictPrefix(current, desired)) {
+        pushOnto(view, current, desired, options);
+    } else {
+        view.replaceWithTags([...desired]);
+    }
+};
+
+const syncNavigationStack = (
+    view: Adw.NavigationView,
+    desired: readonly string[],
+    options: OptionsByKey,
+    isInitial: boolean,
+): void => {
+    const current = readNavigationStack(view);
+
+    if (!isSameStack(current, desired)) {
+        if (isInitial) {
+            view.replaceWithTags([...desired]);
+        } else {
+            applyStackChange(view, current, desired, options);
+        }
+    }
+
+    view.setAnimateTransitions(isAnimated(options, desired.at(-1)));
+};
+
+const routeKeys = (state: { routes: readonly { key: string }[] }, offset: number): string[] =>
+    state.routes.slice(offset).map((route) => route.key);
+
+const popToActualStack = (
+    navigation: StackNavigationHelpers,
+    actual: readonly string[],
+    desired: readonly string[],
+): void => {
+    const state = navigation.getState();
+    navigation.dispatch({ ...StackActions.pop(desired.length - actual.length), target: state.key });
+};
+
+const reconcilePoppedStack = (
+    view: Adw.NavigationView,
+    navigation: StackNavigationHelpers,
+    options: OptionsByKey,
+    offset: number,
+): void => {
+    const actual = readNavigationStack(view);
+    const desired = routeKeys(navigation.getState(), offset);
+
+    if (isStrictPrefix(actual, desired)) {
+        popToActualStack(navigation, actual, desired);
+    }
+
+    syncNavigationStack(view, routeKeys(navigation.getState(), offset), options, false);
+};
+
+export { type OptionsByKey, reconcilePoppedStack, syncNavigationStack };