@gtkx/navigation 2.0.0-beta.11 → 2.0.0-beta.13

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

@@ -70,7 +70,17 @@ 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,
+>(): TypedNavigator<TypeBag, undefined>;
+/** 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> = StaticConfig<TypeBag>,
+>(config: Config): TypedNavigator<TypeBag, Config>;
+function createStackNavigator<
+    const TypeBag extends NavigatorTypeBagBase,
+    const Config extends StaticConfig<TypeBag> | undefined,
 >(config?: Config): TypedNavigator<TypeBag, Config> {
     return createNavigatorFactory(StackNavigator)(config) as TypedNavigator<TypeBag, Config>;
 }

package/src/stack/stack-pages.ts

@@ -100,27 +100,29 @@ const useStackPages = (
 ): StackPages => {
     const [tracking, setTracking] = useState<PageTracking>(() => initialTracking(state, descriptors, offset));
 
-    if (!hasSameMembers(tracking.order, neededKeys(state, tracking.closing, offset)) ||
+    if (
+        !hasSameMembers(tracking.order, neededKeys(state, tracking.closing, offset)) ||
         tracking.focusedKey !== getFocusedKey(state, offset) ||
-        tracking.descriptors !== descriptors) {
+        tracking.descriptors !== 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]),
-                }));
+        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);
+    const pages = tracking.order.map((key) => resolvePage(key, sources, describe)).filter((page) => page !== undefined);
 
     return { pages, release };
 };

package/src/stack/stack-view.tsx

@@ -2,6 +2,7 @@ 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 { useLatestRef } from "@gtkx/react/internal";
 import { useCallback, useEffect, useRef } from "react";
 import type { Describe } from "./stack-pages.js";
 import type { OptionsByKey } from "./sync-navigation-stack.js";
@@ -47,16 +48,6 @@ const previousDescriptor = (
     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 useStackSync = (
     viewRef: ViewRef,
     state: StackNavigationState<ParamListBase>,
@@ -84,7 +75,7 @@ const usePoppedHandler = (
     options: RefObject<OptionsByKey>,
     offset: number,
 ): (() => void) => {
-    const navigationRef = useLatest(navigation);
+    const navigationRef = useLatestRef(navigation);
     const isScheduledRef = useRef(false);
 
     return useCallback(() => {
@@ -114,11 +105,14 @@ const StackPageContent = ({ descriptor, previous }: Omit<StackPageProps, "naviga
 
     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 })}</>;
+    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>;
+    return <AdwToolbarView top={topBar}>{descriptor.render()}</AdwToolbarView>;
 };
 
 const StackPage = ({ descriptor, previous, navigation, onHidden }: StackPageProps): ReactNode => {
@@ -166,7 +160,7 @@ const StackView = (props: StackViewProps): ReactNode => {
     const { state, navigation, descriptors, describe, popOnEscape, offset = 0 } = props;
     const viewRef = useRef<Adw.NavigationView | null>(null);
     const { pages, release } = useStackPages(state, descriptors, describe, offset);
-    const options = useLatest<OptionsByKey>(Object.fromEntries(pages.map((page) => [page.route.key, page.options])));
+    const options = useLatestRef<OptionsByKey>(Object.fromEntries(pages.map((page) => [page.route.key, page.options])));
     const onPopped = usePoppedHandler(viewRef, navigation, options, offset);
     useStackSync(viewRef, state, options, offset);
 

package/src/stack/types.ts

@@ -68,7 +68,8 @@ type StackNavigationProp<
     StackNavigationState<ParamList>,
     StackNavigationOptions,
     StackNavigationEventMap
-> & StackActionHelpers<ParamList>;
+> &
+    StackActionHelpers<ParamList>;
 
 /** Props a stack screen component receives. */
 type StackScreenProps<
@@ -112,8 +113,8 @@ type StackNavigatorProps = DefaultNavigatorOptions<
     StackNavigationEventMap,
     StackNavigationProp<ParamListBase>
 > &
-StackRouterOptions &
-StackNavigationConfig;
+    StackRouterOptions &
+    StackNavigationConfig;
 
 export type {
     StackDescriptor,

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

@@ -0,0 +1,122 @@
+import type {
+    NavigatorTypeBagBase,
+    ParamListBase,
+    StaticConfig,
+    StaticScreenFactory,
+    TypedNavigator,
+} from "@react-navigation/core";
+import type { ReactNode } from "react";
+import * as Adw from "@gtkx/gi/adw";
+import { createNavigatorFactory, createScreenFactory, useNavigationBuilder } from "@react-navigation/core";
+import { useState } from "react";
+import type {
+    TabViewActionHelpers,
+    TabViewNavigationEventMap,
+    TabViewNavigationOptions,
+    TabViewNavigationProp,
+    TabViewNavigationState,
+    TabViewNavigatorProps,
+    TabViewRouterOptions,
+} from "./types.js";
+import { readExistingTabs } from "./page-registry.js";
+import { TabViewHost } from "./tab-view-host.js";
+import { createTabViewRouter } from "./tab-view-router.js";
+
+/** Type bag describing the tab view navigator to React Navigation's typed APIs. */
+type TabViewTypeBag<
+    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: TabViewNavigationState<ParamList>;
+    /** Per-screen options. */
+    ScreenOptions: TabViewNavigationOptions;
+    /** Events the navigator emits. */
+    EventMap: TabViewNavigationEventMap;
+    /** Navigation object per route. */
+    NavigationList: {
+        [RouteName in keyof ParamList]: TabViewNavigationProp<ParamList, RouteName, NavigatorID>;
+    };
+    /** The navigator component. */
+    Navigator: typeof TabViewNavigator;
+};
+
+/** Declares a typed screen of a tab view navigator for the static configuration API. */
+const createTabViewScreen: StaticScreenFactory<TabViewTypeBag> = createScreenFactory<TabViewTypeBag>();
+
+/** Renders each open route of a {@link createTabViewNavigator} as a page of an `Adw.TabView`. */
+function TabViewNavigator({
+    view: providedView,
+    tabBarVisible,
+    tabBarAutohide,
+    tabBarExpand,
+    tabBarInverted,
+    overview,
+    menuModel,
+    renderMenu,
+    extraDropTarget,
+    onExtraDragDrop,
+    onCreateWindow,
+    onSetupMenu,
+    shortcuts,
+    defaultIcon,
+    ...options
+}: TabViewNavigatorProps): ReactNode {
+    const [view] = useState(() => providedView ?? new Adw.TabView());
+    const [router] = useState(() => createTabViewRouter(() => readExistingTabs(view)));
+    const { state, descriptors, navigation, render } = useNavigationBuilder<
+        TabViewNavigationState<ParamListBase>,
+        TabViewRouterOptions,
+        TabViewActionHelpers<ParamListBase>,
+        TabViewNavigationOptions,
+        TabViewNavigationEventMap
+    >(router, options);
+
+    return render(
+        <TabViewHost
+            view={view}
+            state={state}
+            navigation={navigation}
+            descriptors={descriptors}
+            tabBarVisible={tabBarVisible}
+            tabBarAutohide={tabBarAutohide}
+            tabBarExpand={tabBarExpand}
+            tabBarInverted={tabBarInverted}
+            overview={overview}
+            menuModel={menuModel}
+            renderMenu={renderMenu}
+            extraDropTarget={extraDropTarget}
+            onExtraDragDrop={onExtraDragDrop}
+            onCreateWindow={onCreateWindow}
+            onSetupMenu={onSetupMenu}
+            shortcuts={shortcuts}
+            defaultIcon={defaultIcon}
+        />,
+    );
+}
+
+/** Creates a navigator whose routes are the pages of an `Adw.TabView`, with a tab bar and an optional overview. */
+function createTabViewNavigator<
+    const ParamList extends ParamListBase,
+    const NavigatorID extends string | undefined = string | undefined,
+    const TypeBag extends NavigatorTypeBagBase = TabViewTypeBag<ParamList, NavigatorID>,
+>(): TypedNavigator<TypeBag, undefined>;
+/** Creates a navigator whose routes are the pages of an `Adw.TabView`, with a tab bar and an optional overview. */
+function createTabViewNavigator<
+    const ParamList extends ParamListBase,
+    const NavigatorID extends string | undefined = string | undefined,
+    const TypeBag extends NavigatorTypeBagBase = TabViewTypeBag<ParamList, NavigatorID>,
+    const Config extends StaticConfig<TypeBag> = StaticConfig<TypeBag>,
+>(config: Config): TypedNavigator<TypeBag, Config>;
+function createTabViewNavigator<
+    const TypeBag extends NavigatorTypeBagBase,
+    const Config extends StaticConfig<TypeBag> | undefined,
+>(config?: Config): TypedNavigator<TypeBag, Config> {
+    return createNavigatorFactory(TabViewNavigator)(config) as TypedNavigator<TypeBag, Config>;
+}
+
+export { createTabViewNavigator, createTabViewScreen, TabViewNavigator, type TabViewTypeBag };

package/src/tab-view/page-registry.ts

@@ -0,0 +1,139 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import * as Adw from "@gtkx/gi/adw";
+import type { ParamListBase } from "@react-navigation/core";
+import type { ExistingTab } from "./tab-view-router.js";
+import type { TabViewNavigationOptions, TabViewNavigationState } from "./types.js";
+
+type Route = TabViewNavigationState<ParamListBase>["routes"][number];
+
+/** Page property values last written from a route's options. */
+type AppliedOptions = Pick<
+    TabViewNavigationOptions,
+    | "icon"
+    | "indicatorActivatable"
+    | "indicatorIcon"
+    | "indicatorTooltip"
+    | "keyword"
+    | "liveThumbnail"
+    | "loading"
+    | "needsAttention"
+    | "thumbnailXalign"
+    | "thumbnailYalign"
+    | "tooltip"
+> & { title?: string };
+
+/** A native page a tab view navigator created or adopted, with the host its content renders into. */
+type PageRecord = {
+    route: Route;
+    page: Adw.TabPage;
+    host: Adw.Bin;
+    applied: AppliedOptions;
+};
+
+/** The pages of one navigator by route key, notifying React when the set changes. */
+type PageStore = {
+    get: (key: string) => PageRecord | undefined;
+    set: (record: PageRecord) => void;
+    delete: (key: string) => void;
+    keys: () => string[];
+    subscribe: (listener: () => void) => () => void;
+    getVersion: () => number;
+    /** Key of the route whose page was selected by the last sync, so native selection changes are not undone. */
+    lastFocus: string | undefined;
+};
+
+const records = new WeakMap<Adw.TabPage, PageRecord>();
+
+const recordOf = (page: Adw.TabPage): PageRecord | undefined => records.get(page);
+
+const registerPage = (record: PageRecord): void => {
+    records.set(record.page, record);
+};
+
+const ownerOf = (page: Adw.TabPage): Adw.TabView | null => {
+    let widget: Gtk.Widget | null = page.getChild();
+
+    while (widget !== null) {
+        if (widget instanceof Adw.TabView) {
+            return widget;
+        }
+
+        widget = widget.getParent();
+    }
+
+    return null;
+};
+
+const readExistingTabs = (view: Adw.TabView): ExistingTab[] => {
+    const selected = view.getSelectedPage();
+    const tabs: ExistingTab[] = [];
+
+    for (let position = 0; position < view.getNPages(); position += 1) {
+        const page = view.getNthPage(position);
+        const record = records.get(page);
+
+        if (record === undefined) {
+            continue;
+        }
+
+        const parent = page.getParent();
+        const parentRecord = parent === null ? undefined : records.get(parent);
+
+        tabs.push({
+            route: record.route,
+            pinned: page.getPinned(),
+            parent: parentRecord?.route.key,
+            selected: page === selected,
+        });
+    }
+
+    return tabs;
+};
+
+const createPageStore = (): PageStore => {
+    const byKey = new Map<string, PageRecord>();
+    const listeners = new Set<() => void>();
+    let version = 0;
+
+    const notify = (): void => {
+        version += 1;
+
+        for (const listener of listeners) {
+            listener();
+        }
+    };
+
+    return {
+        get: (key) => byKey.get(key),
+        set: (record) => {
+            byKey.set(record.route.key, record);
+            notify();
+        },
+        delete: (key) => {
+            if (byKey.delete(key)) {
+                notify();
+            }
+        },
+        keys: () => [...byKey.keys()],
+        subscribe: (listener) => {
+            listeners.add(listener);
+
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        getVersion: () => version,
+        lastFocus: undefined,
+    };
+};
+
+export {
+    type AppliedOptions,
+    createPageStore,
+    ownerOf,
+    type PageRecord,
+    type PageStore,
+    readExistingTabs,
+    recordOf,
+    registerPage,
+};