@gtkx/navigation 0.0.1

package/src/stack/types.ts

@@ -0,0 +1,131 @@
+import type {
+    DefaultNavigatorOptions,
+    Descriptor,
+    NavigationHelpers,
+    NavigationProp,
+    ParamListBase,
+    RouteProp,
+    StackActionHelpers,
+    StackNavigationState,
+    StackRouterOptions,
+} from "@react-navigation/core";
+import type { ReactNode } from "react";
+import type { HeaderOptions } from "../shared/types.js";
+
+/** Data carried by the `transitionStart` and `transitionEnd` events. */
+type StackTransitionData = {
+    /** Whether the page is hiding (`true`) or showing (`false`). */
+    closing: boolean;
+};
+
+/** Events the stack navigator emits on top of React Navigation's core events. */
+type StackNavigationEventMap = {
+    /** A page starts showing or hiding. */
+    transitionStart: {
+        /** Which direction the page moves in. */
+        data: StackTransitionData;
+    };
+    /** A page finished showing or hiding. */
+    transitionEnd: {
+        /** Which direction the page moved in. */
+        data: StackTransitionData;
+    };
+};
+
+/** The page below the current one, as handed to a custom `header`. */
+type StackHeaderBack = {
+    /** Title of the page below. */
+    title: string;
+};
+
+/** Per-screen options of the stack navigator. */
+type StackNavigationOptions = HeaderOptions & {
+    /** Renders a custom top bar instead of the default `AdwHeaderBar`. */
+    header?: (props: StackHeaderProps) => ReactNode;
+    /** Whether the default header bar shows Adwaita's back button; defaults to `true`. */
+    headerBackVisible?: boolean;
+    /** Whether the user can pop this page with the back button, Escape, Alt+Left or a swipe; defaults to `true`. */
+    canPop?: boolean;
+    /** Whether pushing and popping this page animates; defaults to `"default"`. */
+    animation?: "default" | "none";
+};
+
+/** Props of the stack navigator beyond the options every navigator shares. */
+type StackNavigationConfig = {
+    /** Whether pressing Escape pops the visible page; defaults to `true`. */
+    popOnEscape?: boolean;
+};
+
+/** Navigation object of a stack screen. */
+type StackNavigationProp<
+    ParamList extends ParamListBase,
+    RouteName extends keyof ParamList = keyof ParamList,
+    NavigatorID extends string | undefined = undefined,
+> = NavigationProp<
+    ParamList,
+    RouteName,
+    NavigatorID,
+    StackNavigationState<ParamList>,
+    StackNavigationOptions,
+    StackNavigationEventMap
+> & StackActionHelpers<ParamList>;
+
+/** Props a stack screen component receives. */
+type StackScreenProps<
+    ParamList extends ParamListBase,
+    RouteName extends keyof ParamList = keyof ParamList,
+    NavigatorID extends string | undefined = undefined,
+> = {
+    /** Navigation object of the screen. */
+    navigation: StackNavigationProp<ParamList, RouteName, NavigatorID>;
+    /** The route the screen renders. */
+    route: RouteProp<ParamList, RouteName>;
+};
+
+/** Arguments of a custom stack `header` renderer. */
+type StackHeaderProps = {
+    /** The route whose header is rendered. */
+    route: RouteProp<ParamListBase>;
+    /** Navigation object of that route. */
+    navigation: StackNavigationProp<ParamListBase>;
+    /** Resolved options of that route. */
+    options: StackNavigationOptions;
+    /** The page below this one in the stack, if any. */
+    back?: StackHeaderBack;
+};
+
+/** Navigation helpers of the stack navigator itself. */
+type StackNavigationHelpers = NavigationHelpers<ParamListBase, StackNavigationEventMap> &
+    StackActionHelpers<ParamListBase>;
+
+/** Descriptor of one stack route. */
+type StackDescriptor = Descriptor<StackNavigationOptions, StackNavigationProp<ParamListBase>, RouteProp<ParamListBase>>;
+/** Descriptors of the stack routes, keyed by route key. */
+type StackDescriptorMap = Record<string, StackDescriptor>;
+
+/** Props of the stack `Navigator` component. */
+type StackNavigatorProps = DefaultNavigatorOptions<
+    ParamListBase,
+    string | undefined,
+    StackNavigationState<ParamListBase>,
+    StackNavigationOptions,
+    StackNavigationEventMap,
+    StackNavigationProp<ParamListBase>
+> &
+StackRouterOptions &
+StackNavigationConfig;
+
+export type {
+    StackDescriptor,
+    StackDescriptorMap,
+    StackHeaderBack,
+    StackHeaderProps,
+    StackNavigationConfig,
+    StackNavigationEventMap,
+    StackNavigationHelpers,
+    StackNavigationOptions,
+    StackNavigationProp,
+    StackNavigatorProps,
+    StackScreenProps,
+    StackTransitionData,
+};

package/src/static-navigation.tsx

@@ -0,0 +1,26 @@
+import type { ComponentType, ReactNode } from "react";
+import { NavigationContainer, type NavigationContainerProps } from "./navigation-container.js";
+
+/** Props of the component returned by {@link createStaticNavigation}. */
+type StaticNavigationProps = Omit<NavigationContainerProps, "children">;
+
+/** The part of a static navigator config {@link createStaticNavigation} consumes. */
+type StaticNavigationTree = {
+    /** Returns the component rendering the configured navigator. */
+    getComponent: () => ComponentType;
+};
+
+/** Turns a static navigator config into a root component: a {@link NavigationContainer} around the tree. */
+function createStaticNavigation(tree: StaticNavigationTree): ComponentType<StaticNavigationProps> {
+    const Tree = tree.getComponent();
+
+    const StaticNavigation = (props: StaticNavigationProps): ReactNode => (
+        <NavigationContainer {...props}>
+            <Tree />
+        </NavigationContainer>
+    );
+
+    return StaticNavigation;
+}
+
+export { createStaticNavigation, type StaticNavigationProps, type StaticNavigationTree };

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

@@ -0,0 +1,69 @@
+import type {
+    NavigatorTypeBagBase,
+    ParamListBase,
+    StaticConfig,
+    StaticScreenFactory,
+    TabActionHelpers,
+    TabNavigationState,
+    TabRouterOptions,
+    TypedNavigator,
+} from "@react-navigation/core";
+import type { ReactNode } from "react";
+import { createNavigatorFactory, createScreenFactory, TabRouter, useNavigationBuilder } from "@react-navigation/core";
+import type { TabNavigationEventMap, TabNavigationOptions, TabNavigationProp, TabNavigatorProps } from "./types.js";
+import { TabView } from "./tab-view.js";
+
+/** Type bag describing the tab navigator to React Navigation's typed APIs. */
+type TabTypeBag<
+    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: TabNavigationState<ParamList>;
+    /** Per-screen options. */
+    ScreenOptions: TabNavigationOptions;
+    /** Events the navigator emits. */
+    EventMap: TabNavigationEventMap;
+    /** Navigation object per route. */
+    NavigationList: {
+        [RouteName in keyof ParamList]: TabNavigationProp<ParamList, RouteName, NavigatorID>;
+    };
+    /** The navigator component. */
+    Navigator: typeof TabNavigator;
+};
+
+/** Declares a typed screen of a tab navigator for the static configuration API. */
+const createTabScreen: StaticScreenFactory<TabTypeBag> = createScreenFactory<TabTypeBag>();
+
+/** Renders the screens of a {@link createTabNavigator} as pages of an `AdwViewStack` with a view switcher. */
+function TabNavigator({ tabBarPosition, ...options }: TabNavigatorProps): ReactNode {
+    const { state, descriptors, navigation, NavigationContent } = useNavigationBuilder<
+        TabNavigationState<ParamListBase>,
+        TabRouterOptions,
+        TabActionHelpers<ParamListBase>,
+        TabNavigationOptions,
+        TabNavigationEventMap
+    >(TabRouter, options);
+
+    return (
+        <NavigationContent>
+            <TabView tabBarPosition={tabBarPosition} state={state} navigation={navigation} descriptors={descriptors} />
+        </NavigationContent>
+    );
+}
+
+/** Creates a tab navigator rendered with `AdwViewStack` and an `AdwViewSwitcher`. */
+function createTabNavigator<
+    const ParamList extends ParamListBase,
+    const NavigatorID extends string | undefined = string | undefined,
+    const TypeBag extends NavigatorTypeBagBase = TabTypeBag<ParamList, NavigatorID>,
+    const Config extends StaticConfig<TypeBag> | undefined = undefined,
+>(config?: Config): TypedNavigator<TypeBag, Config> {
+    return createNavigatorFactory(TabNavigator)(config) as TypedNavigator<TypeBag, Config>;
+}
+
+export { createTabNavigator, createTabScreen, TabNavigator, type TabTypeBag };

package/src/tabs/tab-view.tsx

@@ -0,0 +1,126 @@
+import type { ParamListBase, TabNavigationState } from "@react-navigation/core";
+import type { ReactElement, ReactNode } from "react";
+import * as Adw from "@gtkx/gi/adw";
+import { AdwToolbarView, AdwViewStack, AdwViewSwitcher, AdwViewSwitcherBar, AdwWindowTitle } from "@gtkx/jsx/adw";
+import { CommonActions } from "@react-navigation/core";
+import { useCallback, useState } from "react";
+import type { TabDescriptor, TabDescriptorMap, TabNavigationConfig, TabNavigationHelpers } from "./types.js";
+import { HeaderBar } from "../shared/header-bar.js";
+import { getFocusedRoute, requireDescriptor } from "../shared/routes.js";
+import { ScenePage } from "../shared/scene-page.js";
+import { useLoadedRoutes } from "../shared/use-loaded-routes.js";
+import { usePopToTopOnBlur } from "../shared/use-pop-to-top-on-blur.js";
+
+type TabViewProps = TabNavigationConfig & {
+    state: TabNavigationState<ParamListBase>;
+    navigation: TabNavigationHelpers;
+    descriptors: TabDescriptorMap;
+};
+
+type TabHeaderProps = {
+    descriptor: TabDescriptor;
+    viewSwitcher: ReactElement | undefined;
+};
+
+type TabPageProps = {
+    descriptor: TabDescriptor;
+    isLoaded: boolean;
+};
+
+const useTabSelection = (navigation: TabNavigationHelpers): ((name: string | null) => void) =>
+    useCallback((name: string | null) => {
+        const current = navigation.getState();
+        const focusedKey = getFocusedRoute(current).key;
+        const route = current.routes.find((candidate) => candidate.key === name);
+
+        if (route === undefined || route.key === focusedKey) {
+            return;
+        }
+
+        const event = navigation.emit({ type: "tabPress", target: route.key, canPreventDefault: true });
+
+        if (!event.defaultPrevented) {
+            navigation.dispatch({ ...CommonActions.navigate(route.name, route.params), target: current.key });
+        }
+    }, [navigation]);
+
+const defaultTabHeader = ({ descriptor, viewSwitcher }: TabHeaderProps): ReactElement => (
+    <HeaderBar
+        options={descriptor.options}
+        titleWidget={viewSwitcher ?? <AdwWindowTitle title={descriptor.options.title ?? descriptor.route.name} />}
+    />
+);
+
+const TabHeader = (props: TabHeaderProps): ReactNode => {
+    const { descriptor, viewSwitcher } = props;
+    const { route, options, navigation } = descriptor;
+
+    if (options.headerShown === false) {
+        return <>{viewSwitcher}</>;
+    }
+
+    return (
+        <>
+            {options.header === undefined
+                ? defaultTabHeader(props)
+                : options.header({ route, navigation, options, viewSwitcher })}
+        </>
+    );
+};
+
+const TabPage = ({ descriptor, isLoaded }: TabPageProps): ReactNode => {
+    const { route, options } = descriptor;
+
+    return (
+        <ScenePage
+            name={route.key}
+            title={options.tabBarLabel ?? options.title ?? route.name}
+            iconName={options.tabBarIcon}
+            badgeNumber={options.tabBarBadge}
+            needsAttention={options.needsAttention}
+            isLoaded={isLoaded || options.lazy === false}
+            render={() => descriptor.render()}
+        />
+    );
+};
+
+const TabView = ({ state, navigation, descriptors, tabBarPosition = "top" }: TabViewProps): ReactNode => {
+    const [stack, setStack] = useState<Adw.ViewStack | null>(null);
+    const focused = getFocusedRoute(state);
+    const descriptor = requireDescriptor(descriptors, focused.key);
+    const loaded = useLoadedRoutes(focused.key, state.preloadedRouteKeys);
+    const onVisibleChildChanged = useTabSelection(navigation);
+
+    const viewSwitcher = stack === null
+        ? undefined
+        : <AdwViewSwitcher stack={stack} policy={Adw.ViewSwitcherPolicy.WIDE} />;
+
+    const hasSwitcherBar = tabBarPosition === "bottom" && stack !== null;
+    usePopToTopOnBlur(state, descriptors, navigation);
+
+    return (
+        <AdwToolbarView
+            topBar={(
+                <TabHeader descriptor={descriptor} viewSwitcher={tabBarPosition === "top" ? viewSwitcher : undefined} />
+            )}
+            bottomBar={hasSwitcherBar ? <AdwViewSwitcherBar stack={stack} reveal /> : undefined}
+        >
+            <AdwViewStack
+                ref={setStack}
+                visibleChildName={focused.key}
+                enableTransitions={descriptor.options.animation === "fade"}
+                onNotifyVisibleChildName={onVisibleChildChanged}
+            >
+                {state.routes.map((route) => (
+                    <TabPage
+                        key={route.key}
+                        descriptor={requireDescriptor(descriptors, route.key)}
+                        isLoaded={loaded.has(route.key)}
+                    />
+                ))}
+            </AdwViewStack>
+        </AdwToolbarView>
+    );
+};
+
+export { TabView };

package/src/tabs/types.ts

@@ -0,0 +1,120 @@
+import type {
+    DefaultNavigatorOptions,
+    Descriptor,
+    NavigationHelpers,
+    NavigationProp,
+    ParamListBase,
+    RouteProp,
+    TabActionHelpers,
+    TabNavigationState,
+    TabRouterOptions,
+} from "@react-navigation/core";
+import type { ReactNode } from "react";
+import type { HeaderOptions } from "../shared/types.js";
+
+/** Events the tab navigator emits on top of React Navigation's core events. */
+type TabNavigationEventMap = {
+    /** The user selected a tab in the view switcher. */
+    tabPress: {
+        /** No payload. */
+        data: undefined;
+        /** Calling `preventDefault` keeps the current tab. */
+        canPreventDefault: true;
+    };
+};
+
+/** Per-screen options of the tab navigator. */
+type TabNavigationOptions = HeaderOptions & {
+    /** Renders a custom top bar instead of the default `AdwHeaderBar`. */
+    header?: (props: TabHeaderProps) => ReactNode;
+    /** Label shown in the view switcher; defaults to `title`, then to the route name. */
+    tabBarLabel?: string;
+    /** Icon name shown in the view switcher. */
+    tabBarIcon?: string;
+    /** Badge number shown in the view switcher; `0` hides the badge. */
+    tabBarBadge?: number;
+    /** Whether the view switcher highlights the tab as needing attention. */
+    needsAttention?: boolean;
+    /** Whether the screen mounts on first focus instead of at startup; defaults to `true`. */
+    lazy?: boolean;
+    /** Whether a nested stack pops to its first screen when this tab loses focus; defaults to `false`. */
+    popToTopOnBlur?: boolean;
+    /** Whether switching to this tab crossfades; defaults to `"none"`. */
+    animation?: "fade" | "none";
+};
+
+/** Props of the tab navigator beyond the options every navigator shares. */
+type TabNavigationConfig = {
+    /** Where the view switcher sits: in the header bar or in a bar below the content; defaults to `"top"`. */
+    tabBarPosition?: "top" | "bottom";
+};
+
+/** Navigation object of a tab screen. */
+type TabNavigationProp<
+    ParamList extends ParamListBase,
+    RouteName extends keyof ParamList = keyof ParamList,
+    NavigatorID extends string | undefined = undefined,
+> = NavigationProp<
+    ParamList,
+    RouteName,
+    NavigatorID,
+    TabNavigationState<ParamList>,
+    TabNavigationOptions,
+    TabNavigationEventMap
+> & TabActionHelpers<ParamList>;
+
+/** Props a tab screen component receives. */
+type TabScreenProps<
+    ParamList extends ParamListBase,
+    RouteName extends keyof ParamList = keyof ParamList,
+    NavigatorID extends string | undefined = undefined,
+> = {
+    /** Navigation object of the screen. */
+    navigation: TabNavigationProp<ParamList, RouteName, NavigatorID>;
+    /** The route the screen renders. */
+    route: RouteProp<ParamList, RouteName>;
+};
+
+/** Arguments of a custom tab `header` renderer. */
+type TabHeaderProps = {
+    /** The focused route. */
+    route: RouteProp<ParamListBase>;
+    /** Navigation object of the focused route. */
+    navigation: TabNavigationProp<ParamListBase>;
+    /** Resolved options of the focused route. */
+    options: TabNavigationOptions;
+    /** The view switcher to place in the header when `tabBarPosition` is `"top"`. */
+    viewSwitcher: ReactNode;
+};
+
+/** Navigation helpers of the tab navigator itself. */
+type TabNavigationHelpers = NavigationHelpers<ParamListBase, TabNavigationEventMap> & TabActionHelpers<ParamListBase>;
+/** Descriptor of one tab route. */
+type TabDescriptor = Descriptor<TabNavigationOptions, TabNavigationProp<ParamListBase>, RouteProp<ParamListBase>>;
+/** Descriptors of the tab routes, keyed by route key. */
+type TabDescriptorMap = Record<string, TabDescriptor>;
+
+/** Props of the tab `Navigator` component. */
+type TabNavigatorProps = DefaultNavigatorOptions<
+    ParamListBase,
+    string | undefined,
+    TabNavigationState<ParamListBase>,
+    TabNavigationOptions,
+    TabNavigationEventMap,
+    TabNavigationProp<ParamListBase>
+> &
+TabRouterOptions &
+TabNavigationConfig;
+
+export type {
+    TabDescriptor,
+    TabDescriptorMap,
+    TabHeaderProps,
+    TabNavigationConfig,
+    TabNavigationEventMap,
+    TabNavigationHelpers,
+    TabNavigationOptions,
+    TabNavigationProp,
+    TabNavigatorProps,
+    TabScreenProps,
+};

package/src/theme.ts

@@ -0,0 +1,31 @@
+import * as Adw from "@gtkx/gi/adw";
+import { useProperty } from "@gtkx/react";
+import { useMemo } from "react";
+
+/** Style state handed to `useTheme` and to option callbacks as `theme`, mirroring Adwaita's style manager. */
+type AdwaitaTheme = {
+    /** Whether the application currently uses the dark color scheme. */
+    dark: boolean;
+    /** Whether the system requested high-contrast styling. */
+    highContrast: boolean;
+};
+
+declare module "@react-navigation/core" {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+    interface Theme extends AdwaitaTheme {}
+}
+
+/** The light Adwaita theme. */
+const DefaultTheme: AdwaitaTheme = { dark: false, highContrast: false };
+/** The dark Adwaita theme. */
+const DarkTheme: AdwaitaTheme = { dark: true, highContrast: false };
+
+const useAdwaitaTheme = (): AdwaitaTheme => {
+    const manager = Adw.StyleManager.getDefault();
+    const isDark = useProperty(manager, "dark") ?? manager.getDark();
+    const isHighContrast = useProperty(manager, "highContrast") ?? manager.getHighContrast();
+
+    return useMemo(() => ({ dark: isDark, highContrast: isHighContrast }), [isDark, isHighContrast]);
+};
+
+export { type AdwaitaTheme as Theme, DarkTheme, DefaultTheme, useAdwaitaTheme };