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

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

@@ -48,6 +48,7 @@ const createSplitViewScreen: StaticScreenFactory<SplitViewTypeBag> = createScree
 /** Renders the screens of a {@link createSplitViewNavigator} in an `AdwNavigationSplitView`. */
 function SplitViewNavigator({
     collapsed,
+    collapseCondition,
     contentPlaceholder,
     sidebarPosition,
     minSidebarWidth,
@@ -71,6 +72,7 @@ function SplitViewNavigator({
             descriptors={descriptors}
             describe={describe}
             collapsed={collapsed}
+            collapseCondition={collapseCondition}
             contentPlaceholder={contentPlaceholder}
             sidebarPosition={sidebarPosition}
             minSidebarWidth={minSidebarWidth}
@@ -89,7 +91,20 @@ 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,
+>(): TypedNavigator<TypeBag, undefined>;
+/**
+ * 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> = StaticConfig<TypeBag>,
+>(config: Config): TypedNavigator<TypeBag, Config>;
+function createSplitViewNavigator<
+    const TypeBag extends NavigatorTypeBagBase,
+    const Config extends StaticConfig<TypeBag> | undefined,
 >(config?: Config): TypedNavigator<TypeBag, Config> {
     return createNavigatorFactory(SplitViewNavigator)(config) as TypedNavigator<TypeBag, Config>;
 }

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

@@ -0,0 +1,21 @@
+import { type Context, createContext, useContext } from "react";
+
+const SplitViewCollapsedContext: Context<boolean | null> = createContext<boolean | null>(null);
+
+/**
+ * Returns whether the surrounding split view navigator shows one pane at a time, for its sidebar and content
+ * screens. It follows the split view's `collapsed` property, so it holds for both the `collapsed` prop and
+ * `collapseCondition`, and changes after libadwaita has laid out the collapsed or widened panes. Use it to
+ * adapt a screen's presentation, such as switching an `AdwSidebar` to `Adw.SidebarMode.PAGE`.
+ */
+const useSplitViewCollapsed = (): boolean => {
+    const isCollapsed = useContext(SplitViewCollapsedContext);
+
+    if (isCollapsed === null) {
+        throw new Error("useSplitViewCollapsed must be called inside a split view navigator.");
+    }
+
+    return isCollapsed;
+};
+
+export { SplitViewCollapsedContext, useSplitViewCollapsed };

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

@@ -1,12 +1,21 @@
-import type * as Adw from "@gtkx/gi/adw";
 import type { ParamListBase, RouteProp, StackNavigationState } from "@react-navigation/core";
 import type { ReactNode } from "react";
+import * as Adw from "@gtkx/gi/adw";
 import * as Gdk from "@gtkx/gi/gdk";
+import * as GObject from "@gtkx/gi/gobject";
 import * as Gtk from "@gtkx/gi/gtk";
-import { AdwNavigationPage, AdwNavigationSplitView, AdwToolbarView } from "@gtkx/jsx/adw";
+import {
+    AdwBreakpoint,
+    AdwBreakpointBin,
+    AdwHeaderBar,
+    AdwNavigationPage,
+    AdwNavigationSplitView,
+    AdwToolbarView,
+} from "@gtkx/jsx/adw";
 import { GtkEventControllerKey } from "@gtkx/jsx/gtk";
+import { useProperty } from "@gtkx/react";
 import { StackActions } from "@react-navigation/core";
-import { useCallback, useRef } from "react";
+import { useCallback, useLayoutEffect, useMemo, useState } from "react";
 import type {
     SplitViewDescriptor,
     SplitViewDescriptorMap,
@@ -16,8 +25,7 @@ import type {
 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 };
+import { SplitViewCollapsedContext } from "./split-view-collapsed.js";
 
 type SplitViewProps = SplitViewNavigationConfig & {
     state: StackNavigationState<ParamListBase>;
@@ -47,14 +55,43 @@ const popContent = (navigation: SplitViewNavigationHelpers): void => {
     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 collapsedValue = (): GObject.Value => {
+    const value = new GObject.Value();
+    value.init(GObject.TYPE_BOOLEAN);
+    value.setBoolean(true);
+
+    return value;
+};
+
+const useCollapseBreakpoint = (
+    view: Adw.NavigationSplitView | null,
+    collapseCondition: string | undefined,
+): ReactNode => {
+    const [breakpoint, setBreakpoint] = useState<Adw.Breakpoint | null>(null);
+    const condition = useMemo(
+        () => (collapseCondition === undefined ? null : Adw.BreakpointCondition.parse(collapseCondition)),
+        [collapseCondition],
+    );
+
+    useLayoutEffect(() => {
+        if (breakpoint === null || view === null) {
+            return;
+        }
+
+        breakpoint.addSetter(view, "collapsed", collapsedValue());
+    }, [view, breakpoint]);
+
+    return condition === null ? null : <AdwBreakpoint ref={setBreakpoint} condition={condition} />;
+};
+
+const settleShowContent = (view: Adw.NavigationSplitView | null, isShown: boolean, isSettled: boolean): void => {
+    if (isSettled !== isShown && view !== null) {
+        view.setShowContent(isSettled);
     }
 };
 
 const useContentSync = (
-    viewRef: ViewRef,
+    view: Adw.NavigationSplitView | null,
     navigation: SplitViewNavigationHelpers,
 ): ((isShown: boolean | null) => void) =>
     useCallback(
@@ -67,9 +104,9 @@ const useContentSync = (
                 popContent(navigation);
             }
 
-            settleShowContent(viewRef, isShown, hasContent(navigation.getState()));
+            settleShowContent(view, isShown, hasContent(navigation.getState()));
         },
-        [viewRef, navigation],
+        [view, navigation],
     );
 
 const EscapeGuard = (): ReactNode => (
@@ -95,48 +132,58 @@ const SidebarPage = ({ descriptor }: { descriptor: SplitViewDescriptor }): React
 
     return (
         <AdwNavigationPage title={options.title ?? route.name}>
-            <AdwToolbarView topBar={topBar}>{descriptor.render()}</AdwToolbarView>
+            <AdwToolbarView top={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 { state, navigation, descriptors, describe, contentPlaceholder, collapseCondition } = props;
+    const { sidebarPosition = "start", minSidebarWidth, maxSidebarWidth } = props;
+    const [view, setView] = useState<Adw.NavigationSplitView | null>(null);
+    const onShowContentChanged = useContentSync(view, navigation);
+    const collapseBreakpoint = useCollapseBreakpoint(view, collapseCondition);
     const sidebar = requireDescriptor(descriptors, state.routes[0]?.key ?? "");
+    const collapsed = collapseCondition === undefined ? (props.collapsed ?? false) : undefined;
+    const isCollapsed = useProperty(view, "collapsed") ?? collapsed ?? false;
 
+    // AdwBreakpointBin warns without a size request; the window's size request sets the smallest supported size.
     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>
+        <SplitViewCollapsedContext value={isCollapsed}>
+            <AdwBreakpointBin widthRequest={1} heightRequest={1} breakpoints={collapseBreakpoint}>
+                <AdwNavigationSplitView
+                    ref={setView}
+                    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={isCollapsed && props.popOnEscape === false ? <EscapeGuard /> : null}
+                    >
+                        {hasContent(state) ? (
+                            <StackView
+                                offset={1}
+                                popOnEscape={props.popOnEscape}
+                                state={state}
+                                navigation={navigation}
+                                descriptors={descriptors}
+                                describe={describe}
+                            />
+                        ) : (
+                            <AdwToolbarView top={<AdwHeaderBar showTitle={false} />}>
+                                {contentPlaceholder}
+                            </AdwToolbarView>
+                        )}
+                    </AdwNavigationPage>
+                </AdwNavigationSplitView>
+            </AdwBreakpointBin>
+        </SplitViewCollapsedContext>
     );
 };
 

package/src/split-view/types.ts

@@ -60,9 +60,16 @@ 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`. */
+    /** Whether the panes stack into one instead of sitting side by side; defaults to `false`. Ignored while `collapseCondition` is set. */
     collapsed?: boolean;
-    /** Fills the content pane while no content route is open; defaults to nothing. */
+    /**
+     * An `Adw.BreakpointCondition` string, such as `"max-width: 500sp"`, measured against the navigator's size.
+     * The panes collapse while it holds. libadwaita applies it during layout, before GTK moves focus, so
+     * widening the window does not reselect the focused sidebar row the way a `collapsed` prop set from a
+     * breakpoint handler can. Give the window a `widthRequest` and `heightRequest`, as for window breakpoints.
+     */
+    collapseCondition?: string;
+    /** Fills the content pane, below an untitled header bar, while no content route is open; defaults to nothing. */
     contentPlaceholder?: ReactNode;
     /** Which side the sidebar sits on; defaults to `"start"`. */
     sidebarPosition?: "start" | "end";

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-view.tsx

@@ -112,7 +112,7 @@ const StackPageContent = ({ descriptor, previous }: Omit<StackPageProps, "naviga
             <>{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 => {

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