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

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

@@ -47,17 +47,19 @@ type DrawerTypeBag<
 /** Declares a typed screen of a drawer navigator for the static configuration API. */
 const createDrawerScreen: StaticScreenFactory<DrawerTypeBag> = createScreenFactory<DrawerTypeBag>();
 
-const useDrawerRouter = (isCollapsed: boolean): DrawerRouterFactory => {
-    const [flag] = useState(() => {
-        let isCurrent = isCollapsed;
+const createFlag = (isInitial: boolean) => {
+    let isCurrent = isInitial;
+
+    return {
+        read: () => isCurrent,
+        update: (isNext: boolean) => {
+            isCurrent = isNext;
+        },
+    };
+};
 
-        return {
-            read: () => isCurrent,
-            update: (isNext: boolean) => {
-                isCurrent = isNext;
-            },
-        };
-    });
+const useDrawerRouter = (isCollapsed: boolean): DrawerRouterFactory => {
+    const [flag] = useState(() => createFlag(isCollapsed));
 
     const [createRouter] = useState(() => createDrawerRouter(flag.read));
 
@@ -111,7 +113,17 @@ function createDrawerNavigator<
     const ParamList extends ParamListBase,
     const NavigatorID extends string | undefined = string | undefined,
     const TypeBag extends NavigatorTypeBagBase = DrawerTypeBag<ParamList, NavigatorID>,
-    const Config extends StaticConfig<TypeBag> | undefined = undefined,
+>(): TypedNavigator<TypeBag, undefined>;
+/** Creates a drawer navigator rendered with `AdwOverlaySplitView`: a sidebar listing the screens beside the content. */
+function createDrawerNavigator<
+    const ParamList extends ParamListBase,
+    const NavigatorID extends string | undefined = string | undefined,
+    const TypeBag extends NavigatorTypeBagBase = DrawerTypeBag<ParamList, NavigatorID>,
+    const Config extends StaticConfig<TypeBag> = StaticConfig<TypeBag>,
+>(config: Config): TypedNavigator<TypeBag, Config>;
+function createDrawerNavigator<
+    const TypeBag extends NavigatorTypeBagBase,
+    const Config extends StaticConfig<TypeBag> | undefined,
 >(config?: Config): TypedNavigator<TypeBag, Config> {
     return createNavigatorFactory(DrawerNavigator)(config) as TypedNavigator<TypeBag, Config>;
 }

package/src/drawer/drawer-item-list.tsx

@@ -3,7 +3,7 @@ import type { ReactNode } from "react";
 import * as Gtk from "@gtkx/gi/gtk";
 import { GtkBox, GtkImage, GtkLabel, GtkListBox, GtkListBoxRow } from "@gtkx/jsx/gtk";
 import { CommonActions, DrawerActions } from "@react-navigation/core";
-import { useCallback, useContext } from "react";
+import { useCallback, useContext, useState } from "react";
 import type { DrawerContentProps, DrawerDescriptor, DrawerNavigationHelpers } from "./types.js";
 import { requireDescriptor } from "../shared/routes.js";
 import { DrawerCollapsedContext } from "./drawer-collapsed-context.js";
@@ -29,27 +29,31 @@ const didNavigateToRow = (navigation: DrawerNavigationHelpers, state: Navigation
 };
 
 const useDrawerItemPress = (navigation: DrawerNavigationHelpers, isCollapsed: boolean): RowActivated =>
-    useCallback((row: Gtk.ListBoxRow) => {
-        const state = navigation.getState();
+    useCallback(
+        (row: Gtk.ListBoxRow) => {
+            const state = navigation.getState();
 
-        if (!didNavigateToRow(navigation, state, row.getIndex())) {
-            return;
-        }
+            if (!didNavigateToRow(navigation, state, row.getIndex())) {
+                return;
+            }
 
-        if (isCollapsed) {
-            navigation.dispatch({ ...DrawerActions.closeDrawer(), target: state.key });
-        }
-    }, [navigation, isCollapsed]);
+            if (isCollapsed) {
+                navigation.dispatch({ ...DrawerActions.closeDrawer(), target: state.key });
+            }
+        },
+        [navigation, isCollapsed],
+    );
 
 const DrawerItem = ({ descriptor }: { descriptor: DrawerDescriptor }): ReactNode => {
     const { route, options } = descriptor;
     const label = options.drawerLabel ?? options.title ?? route.name;
+    const [labelWidget, setLabelWidget] = useState<Gtk.Label | null>(null);
 
     return (
-        <GtkListBoxRow accessibleLabel={label}>
+        <GtkListBoxRow accessibleLabelledBy={labelWidget === null ? undefined : [labelWidget]}>
             <GtkBox spacing={12}>
                 {options.drawerIcon === undefined ? null : <GtkImage iconName={options.drawerIcon} />}
-                <GtkLabel label={label} xalign={0} />
+                <GtkLabel ref={setLabelWidget} label={label} useUnderline={options.useUnderline ?? false} xalign={0} />
             </GtkBox>
         </GtkListBoxRow>
     );

package/src/drawer/drawer-router.ts

@@ -84,7 +84,9 @@ const withShownSidebar = (router: DrawerRouterInstance, isCollapsed: () => boole
         keepSidebarShown(state, router.getStateForRouteFocus(state, key), isCollapsed()),
 });
 
-const createDrawerRouter = (isCollapsed: () => boolean): DrawerRouterFactory => (options) =>
-    withShownSidebar(DrawerRouter(options), isCollapsed);
+const createDrawerRouter =
+    (isCollapsed: () => boolean): DrawerRouterFactory =>
+    (options) =>
+        withShownSidebar(DrawerRouter(options), isCollapsed);
 
 export { createDrawerRouter, type DrawerRouterFactory };

package/src/drawer/drawer-view.tsx

@@ -1,13 +1,7 @@
 import type { DrawerNavigationState, ParamListBase } from "@react-navigation/core";
 import type { ReactNode } from "react";
 import * as Gtk from "@gtkx/gi/gtk";
-import {
-    AdwHeaderBar,
-    AdwOverlaySplitView,
-    AdwToolbarView,
-    AdwViewStack,
-    AdwWindowTitle,
-} from "@gtkx/jsx/adw";
+import { AdwHeaderBar, AdwOverlaySplitView, AdwToolbarView, AdwViewStack, AdwWindowTitle } from "@gtkx/jsx/adw";
 import { GtkButton, GtkScrolledWindow } from "@gtkx/jsx/gtk";
 import { DrawerActions } from "@react-navigation/core";
 import { useCallback, useEffect, useRef } from "react";
@@ -39,20 +33,24 @@ type DrawerHeaderProps = {
 
 type DrawerPageProps = {
     descriptor: DrawerDescriptor;
+    isFocused: boolean;
     isLoaded: boolean;
 };
 
 const PACK_TYPES = { start: Gtk.PackType.START, end: Gtk.PackType.END } as const;
 
 const useSidebarSync = (navigation: DrawerNavigationHelpers): ((isShown: boolean | null) => void) =>
-    useCallback((isShown: boolean | null) => {
-        if (isShown === null) {
-            return;
-        }
-
-        const action = isShown ? DrawerActions.openDrawer() : DrawerActions.closeDrawer();
-        navigation.dispatch({ ...action, target: navigation.getState().key });
-    }, [navigation]);
+    useCallback(
+        (isShown: boolean | null) => {
+            if (isShown === null) {
+                return;
+            }
+
+            const action = isShown ? DrawerActions.openDrawer() : DrawerActions.closeDrawer();
+            navigation.dispatch({ ...action, target: navigation.getState().key });
+        },
+        [navigation],
+    );
 
 const useCloseOnNavigate = (
     state: DrawerNavigationState<ParamListBase>,
@@ -73,7 +71,7 @@ const useCloseOnNavigate = (
 };
 
 const DrawerContent = (props: DrawerContentProps): ReactNode => (
-    <AdwToolbarView topBar={<AdwHeaderBar />}>
+    <AdwToolbarView top={<AdwHeaderBar />}>
         <GtkScrolledWindow hscrollbarPolicy={Gtk.PolicyType.NEVER}>
             <DrawerItemList {...props} />
         </GtkScrolledWindow>
@@ -111,13 +109,14 @@ const DrawerHeader = ({ descriptor, navigation }: DrawerHeaderProps): ReactNode
     );
 };
 
-const DrawerPage = ({ descriptor, isLoaded }: DrawerPageProps): ReactNode => {
+const DrawerPage = ({ descriptor, isFocused, isLoaded }: DrawerPageProps): ReactNode => {
     const { route, options } = descriptor;
 
     return (
         <ScenePage
             name={route.key}
             title={options.title ?? route.name}
+            isFocused={isFocused}
             isLoaded={isLoaded || options.lazy === false}
             render={() => descriptor.render()}
         />
@@ -147,12 +146,13 @@ const DrawerView = ({ state, navigation, descriptors, drawerContent, ...config }
                 onNotifyShowSidebar={onShowSidebarChanged}
                 sidebar={<>{sidebar}</>}
             >
-                <AdwToolbarView topBar={<DrawerHeader descriptor={descriptor} navigation={navigation} />}>
+                <AdwToolbarView top={<DrawerHeader descriptor={descriptor} navigation={navigation} />}>
                     <AdwViewStack visibleChildName={focused.key}>
                         {state.routes.map((route) => (
                             <DrawerPage
                                 key={route.key}
                                 descriptor={requireDescriptor(descriptors, route.key)}
+                                isFocused={route.key === focused.key}
                                 isLoaded={route.key === focused.key || state.preloadedRouteKeys.includes(route.key)}
                             />
                         ))}

package/src/drawer/types.ts

@@ -29,6 +29,8 @@ type DrawerNavigationOptions = HeaderOptions & {
     header?: (props: DrawerHeaderProps) => ReactNode;
     /** Label shown in the sidebar; defaults to `title`, then to the route name. */
     drawerLabel?: string;
+    /** Whether underscores in the sidebar label indicate mnemonics; defaults to `false`. */
+    useUnderline?: boolean;
     /** Icon name shown next to the sidebar label. */
     drawerIcon?: string;
     /** Whether the screen mounts on first focus instead of at startup; defaults to `true`. */
@@ -49,7 +51,8 @@ type DrawerNavigationProp<
     DrawerNavigationState<ParamList>,
     DrawerNavigationOptions,
     DrawerNavigationEventMap
-> & DrawerActionHelpers<ParamList>;
+> &
+    DrawerActionHelpers<ParamList>;
 
 /** Props a drawer screen component receives. */
 type DrawerScreenProps<
@@ -124,8 +127,8 @@ type DrawerNavigatorProps = DefaultNavigatorOptions<
     DrawerNavigationEventMap,
     DrawerNavigationProp<ParamListBase>
 > &
-DrawerRouterOptions &
-DrawerNavigationConfig;
+    DrawerRouterOptions &
+    DrawerNavigationConfig;
 
 export type {
     DrawerContentProps,

package/src/index.ts

@@ -30,6 +30,7 @@ export {
     SplitViewNavigator,
     type SplitViewTypeBag,
 } from "./split-view/create-split-view-navigator.js";
+export { useSplitViewCollapsed } from "./split-view/split-view-collapsed.js";
 export type {
     SplitViewDescriptor,
     SplitViewDescriptorMap,
@@ -61,11 +62,7 @@ export type {
     StackScreenProps,
     StackTransitionData,
 } from "./stack/types.js";
-export {
-    createStaticNavigation,
-    type StaticNavigationProps,
-    type StaticNavigationTree,
-} from "./static-navigation.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,
@@ -79,5 +76,34 @@ export type {
     TabNavigatorProps,
     TabScreenProps,
 } from "./tabs/types.js";
+export {
+    createTabViewNavigator,
+    createTabViewScreen,
+    TabViewNavigator,
+    type TabViewTypeBag,
+} from "./tab-view/create-tab-view-navigator.js";
+export { type TabViewHandle, useTabView } from "./tab-view/tab-view-host.js";
+export { TabViewActions } from "./tab-view/tab-view-router.js";
+export type {
+    TabViewActionHelpers,
+    TabViewActionType,
+    TabViewDescriptor,
+    TabViewDescriptorMap,
+    TabViewExtraDropTarget,
+    TabViewHeaderProps,
+    TabViewIcon,
+    TabViewNavigationConfig,
+    TabViewNavigationEventMap,
+    TabViewNavigationHelpers,
+    TabViewNavigationOptions,
+    TabViewNavigationProp,
+    TabViewNavigationState,
+    TabViewNavigatorProps,
+    TabViewOpenOptions,
+    TabViewOverviewConfig,
+    TabViewRouterOptions,
+    TabViewScreenProps,
+    TabViewTarget,
+} from "./tab-view/types.js";
 export { DarkTheme, DefaultTheme, type Theme } from "./theme.js";
 export * from "@react-navigation/core";

package/src/shared/header-bar.tsx

@@ -21,12 +21,12 @@ const HeaderBar = ({ options, titleWidget, start, showBackButton }: HeaderBarPro
     <AdwHeaderBar
         showBackButton={showBackButton ?? true}
         titleWidget={resolveTitleWidget(options, titleWidget)}
-        start={(
+        start={
             <>
                 {start}
                 {options.headerStart}
             </>
-        )}
+        }
         end={options.headerEnd}
     />
 );

package/src/shared/scene-page.tsx

@@ -1,6 +1,6 @@
 import type { ReactElement, ReactNode } from "react";
 import { AdwBin, AdwViewStackPage } from "@gtkx/jsx/adw";
-import { useState } from "react";
+import { useHasLoaded } from "./use-has-loaded.js";
 
 type ScenePageProps = {
     name: string;
@@ -8,16 +8,14 @@ type ScenePageProps = {
     iconName?: string;
     badgeNumber?: number;
     needsAttention?: boolean;
+    useUnderline?: boolean;
+    isFocused: boolean;
     isLoaded: boolean;
     render: () => ReactElement;
 };
 
-const ScenePage = ({ name, title, isLoaded, render, ...page }: ScenePageProps): ReactNode => {
-    const [hasLoaded, setHasLoaded] = useState(isLoaded);
-
-    if (isLoaded && !hasLoaded) {
-        setHasLoaded(true);
-    }
+const ScenePage = ({ name, title, isFocused, isLoaded, render, ...page }: ScenePageProps): ReactNode => {
+    const hasLoaded = useHasLoaded(isLoaded);
 
     return (
         <AdwViewStackPage
@@ -26,7 +24,8 @@ const ScenePage = ({ name, title, isLoaded, render, ...page }: ScenePageProps):
             iconName={page.iconName}
             badgeNumber={page.badgeNumber}
             needsAttention={page.needsAttention}
-            useUnderline={false}
+            accessibleHidden={!isFocused}
+            useUnderline={page.useUnderline ?? false}
         >
             <AdwBin>{hasLoaded ? render() : null}</AdwBin>
         </AdwViewStackPage>

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

@@ -0,0 +1,13 @@
+import { useState } from "react";
+
+const useHasLoaded = (isLoaded: boolean): boolean => {
+    const [hasLoaded, setHasLoaded] = useState(isLoaded);
+
+    if (isLoaded && !hasLoaded) {
+        setHasLoaded(true);
+    }
+
+    return isLoaded || hasLoaded;
+};
+
+export { useHasLoaded };

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,27 +55,59 @@ 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 useContentSync = (
-    viewRef: ViewRef,
-    navigation: SplitViewNavigationHelpers,
-): ((isShown: boolean | null) => void) =>
-    useCallback((isShown: boolean | null) => {
-        if (isShown === null || isShown === hasContent(navigation.getState())) {
+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;
         }
 
-        if (!isShown) {
-            popContent(navigation);
-        }
+        breakpoint.addSetter(view, "collapsed", collapsedValue());
+    }, [view, breakpoint]);
 
-        settleShowContent(viewRef, isShown, hasContent(navigation.getState()));
-    }, [viewRef, navigation]);
+    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 = (
+    view: Adw.NavigationSplitView | null,
+    navigation: SplitViewNavigationHelpers,
+): ((isShown: boolean | null) => void) =>
+    useCallback(
+        (isShown: boolean | null) => {
+            if (isShown === null || isShown === hasContent(navigation.getState())) {
+                return;
+            }
+
+            if (!isShown) {
+                popContent(navigation);
+            }
+
+            settleShowContent(view, isShown, hasContent(navigation.getState()));
+        },
+        [view, navigation],
+    );
 
 const EscapeGuard = (): ReactNode => (
     <GtkEventControllerKey
@@ -83,42 +123,50 @@ const SidebarPage = ({ descriptor }: { descriptor: SplitViewDescriptor }): React
         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 })}</>;
+    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>
+            <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)
-                    ? (
+        <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}
@@ -127,10 +175,15 @@ const SplitView = (props: SplitViewProps): ReactNode => {
                                 descriptors={descriptors}
                                 describe={describe}
                             />
-                        )
-                    : <>{contentPlaceholder}</>}
-            </AdwNavigationPage>
-        </AdwNavigationSplitView>
+                        ) : (
+                            <AdwToolbarView top={<AdwHeaderBar showTitle={false} />}>
+                                {contentPlaceholder}
+                            </AdwToolbarView>
+                        )}
+                    </AdwNavigationPage>
+                </AdwNavigationSplitView>
+            </AdwBreakpointBin>
+        </SplitViewCollapsedContext>
     );
 };
 

package/src/split-view/types.ts

@@ -29,7 +29,8 @@ type SplitViewNavigationProp<
     StackNavigationState<ParamList>,
     SplitViewNavigationOptions,
     SplitViewNavigationEventMap
-> & StackActionHelpers<ParamList>;
+> &
+    StackActionHelpers<ParamList>;
 
 /** Props a split view screen component receives. */
 type SplitViewScreenProps<
@@ -59,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";
@@ -84,8 +92,8 @@ type SplitViewNavigatorProps = DefaultNavigatorOptions<
     SplitViewNavigationEventMap,
     SplitViewNavigationProp<ParamListBase>
 > &
-StackRouterOptions &
-SplitViewNavigationConfig;
+    StackRouterOptions &
+    SplitViewNavigationConfig;
 
 export type {
     SplitViewDescriptor,