@rapidmx/web-client 0.15.1 → 0.17.0

package/apps/shared/navigation/index.ts

@@ -0,0 +1,43 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * What the web client's code uses to go somewhere. The client-side router is `@rapidrest/react`'s (`router = true` on the
+ * route, the app's `_shell.tsx` as the persistent frame - see `apps/www/_shell.tsx`); this is the one thing on top of it: a
+ * `navigate()` that keeps the page when only the query string changes.
+ */
+import { useCallback, useRef } from "react";
+import { useRouter } from "@rapidrest/react/client";
+
+export interface NavigateOptions {
+    /** Replaces the current history entry instead of adding one (a redirect, or a state change that isn't a "place"). */
+    replace?: boolean;
+}
+
+/** Goes to `href`: without a page load when it is a page of the app, else as an ordinary navigation. */
+export type NavigateFn = (href: string, options?: NavigateOptions) => void;
+
+/**
+ * The function to go somewhere with, for what code decides (after a save, a select, a folder change). `navigate("/calendar")`
+ * changes the page and the URL without a page load when the router knows the page (Mail, Calendar, Contacts, Tasks, Settings
+ * and their subpages), and loads it normally otherwise (another app, a plugin's page); outside a router it is always a
+ * normal navigation. A destination with the path the page is at - only its query string is different (`/?mailboxUid=a&folderUid=b`,
+ * `/tasks?mailboxUid=b`) - is a shallow navigation: the page instance keeps its state, and what reads the location follows. Prefer
+ * a plain `<a href>` for anything the user clicks - the router takes it over, and it stays a real link. The returned function is
+ * stable across renders.
+ */
+export function useNavigate(): NavigateFn {
+    const { navigate, pathname } = useRouter();
+    // The latest, through a ref: the router value is replaced whenever the location or a navigation's pending state changes, and
+    // callers keep this function in effect dependencies (the mail connection's `open`).
+    const latest = useRef({ navigate, pathname });
+    latest.current = { navigate, pathname };
+    return useCallback<NavigateFn>((href, options = {}) => {
+        const { navigate: go, pathname: here } = latest.current;
+        // A relative or absolute-path destination is resolved against the page's own address, and only ever compared by path.
+        const destination = new URL(href, `http://router.invalid${here}`);
+        const shallow = destination.origin === "http://router.invalid" && destination.pathname === here;
+        void go(href, { replace: options.replace, shallow });
+    }, []);
+}

package/apps/shared/navigation/pageTitle.ts

@@ -0,0 +1,19 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
+
+/** The name the deployment goes by in the browser tab: its branding title, else its company name, else RapidMX. */
+export function brandName(branding?: Pick<Branding, "title" | "companyName"> | null): string {
+    return branding?.title || branding?.companyName || "RapidMX";
+}
+
+/**
+ * The `title` export of a webmail page: `export const title = pageTitle("Calendar")`. `@rapidrest/react` renders it into the
+ * document's `<title>` on the server - so the tab is right from the first byte, and a crawler sees it - and sends it with every
+ * client navigation, so the tab follows the page. `label` is the app's name (`Acme: Calendar`), the same for all of an app's pages.
+ */
+export function pageTitle(label: string): (props: { branding?: Pick<Branding, "title" | "companyName"> | null }) => string {
+    return ({ branding }) => `${brandName(branding)}: ${label}`;
+}