@rapidmx/web-client 0.8.0 → 0.10.0

package/dist/apps/shared/mail/useNewMailNotifications.js

@@ -0,0 +1,110 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { desktopPermission, getDesktopOfferDismissed, getNewMailPopupsEnabled, noticeFor, noticeSender, ownAddressesOf, requestDesktopPermission, setDesktopOfferDismissed, shouldAnnounce, } from "./newMailNotifications.js";
+/** The most pop-ups on screen at once; a new one pushes the oldest off. */
+export const MAX_TOASTS = 3;
+/** How long a pop-up stays before it goes by itself (while it is neither hovered nor focused, and the tab is in view). */
+export const TOAST_DURATION_MS = 8000;
+/** At most this many desktop notifications in `DESKTOP_BURST_WINDOW_MS`: a flood of mail is a few notifications, not a hundred. */
+export const DESKTOP_BURST_LIMIT = 5;
+export const DESKTOP_BURST_WINDOW_MS = 30000;
+/** How many announced message uids are remembered, so an event delivered twice is announced once. */
+const ANNOUNCED_LIMIT = 500;
+/** Whether the user is not looking at this tab: it is hidden, or another window has the focus. */
+function tabIsInBackground() {
+    return document.visibilityState === "hidden" || !document.hasFocus();
+}
+function defaultOpen(href) {
+    window.location.href = href;
+}
+/**
+ * New-mail announcements: an in-app pop-up for each message that arrives (`MAX_TOASTS` at most on screen), and - while the tab
+ * is in the background and the user has allowed it - a desktop notification with the same content, one per message however
+ * many events name it. `announce()` is what `useMailLiveUpdates()`'s `onMessageCreated` calls; nothing else feeds it, so a
+ * page load, a list refetch and a reconnect never announce anything.
+ *
+ * Nothing is ever asked of the browser on load: permission is requested only by `enableDesktop()`, from the offer in the
+ * first pop-up, or from Settings. What the user answered is remembered in `localStorage` (see `newMailNotifications.ts`).
+ */
+export function useNewMailNotifications({ mailboxes, mailboxFolders, open = defaultOpen }) {
+    const [toasts, setToasts] = useState([]);
+    const [permission, setPermission] = useState("unsupported");
+    const [offerDismissed, setOfferDismissed] = useState(true);
+    const folders = useMemo(() => mailboxFolders.flatMap((entry) => entry.folders), [mailboxFolders]);
+    const ownAddresses = useMemo(() => ownAddressesOf(mailboxes), [mailboxes]);
+    const latestRef = useRef({ folders, ownAddresses, open });
+    latestRef.current = { folders, ownAddresses, open };
+    const announcedRef = useRef(new Set());
+    const desktopShownRef = useRef([]);
+    // The browser's own state is only read on the client, after hydration, so the server and first client render agree.
+    useEffect(() => {
+        setPermission(desktopPermission());
+        setOfferDismissed(getDesktopOfferDismissed());
+    }, []);
+    const dismiss = useCallback((uid) => {
+        setToasts((previous) => previous.filter((toast) => toast.uid !== uid));
+    }, []);
+    const showDesktop = useCallback((notice) => {
+        const now = Date.now();
+        desktopShownRef.current = desktopShownRef.current.filter((at) => now - at < DESKTOP_BURST_WINDOW_MS);
+        if (desktopShownRef.current.length >= DESKTOP_BURST_LIMIT) {
+            return;
+        }
+        try {
+            const notification = new Notification(noticeSender(notice), {
+                body: [notice.subject, notice.preview].filter(Boolean).join("\n"),
+                // One per message: a duplicate (another tab of this app, a re-delivered event) replaces instead of stacking.
+                tag: notice.uid,
+            });
+            desktopShownRef.current.push(now);
+            notification.onclick = () => {
+                window.focus();
+                notification.close();
+                latestRef.current.open(notice.href);
+            };
+        }
+        catch {
+            // Some browsers refuse `new Notification()` outright (a mobile one wanting a service worker): the pop-up is enough.
+        }
+    }, []);
+    const announce = useCallback((message) => {
+        if (!getNewMailPopupsEnabled() || announcedRef.current.has(message.uid)) {
+            return;
+        }
+        const { folders: knownFolders, ownAddresses: own } = latestRef.current;
+        if (!shouldAnnounce(message, { folders: knownFolders, ownAddresses: own })) {
+            return;
+        }
+        announcedRef.current.add(message.uid);
+        if (announcedRef.current.size > ANNOUNCED_LIMIT) {
+            announcedRef.current.delete(announcedRef.current.values().next().value);
+        }
+        const notice = noticeFor(message);
+        setToasts((previous) => [...previous.filter((toast) => toast.uid !== notice.uid), notice].slice(-MAX_TOASTS));
+        if (desktopPermission() === "granted" && tabIsInBackground()) {
+            showDesktop(notice);
+        }
+    }, [showDesktop]);
+    const enableDesktop = useCallback(async () => {
+        const answer = await requestDesktopPermission();
+        setPermission(answer);
+        // Answered either way, so the offer goes: on granted it has done its job, on denied it can't be made again.
+        setDesktopOfferDismissed(true);
+        setOfferDismissed(true);
+    }, []);
+    const declineDesktop = useCallback(() => {
+        setDesktopOfferDismissed(true);
+        setOfferDismissed(true);
+    }, []);
+    return {
+        toasts,
+        dismiss,
+        offerDesktop: permission === "default" && !offerDismissed,
+        enableDesktop,
+        declineDesktop,
+        announce,
+    };
+}

package/dist/apps/shared/mail/useUnreadTitle.d.ts

@@ -0,0 +1,18 @@
+/** `title` with `count` unread in front - `(3) Acme: Mail` - or as it is when there are none. */
+export declare function titleWithUnread(title: string, count: number): string;
+export interface UseUnreadTitleOptions {
+    /** Does nothing while false - for the one of two owners that isn't. Default true. */
+    enabled?: boolean;
+    /** Changes whenever something else has rewritten the title (the app frame sets it on every page change), so the count is put in front of
+     * the new one. */
+    resetKey?: unknown;
+}
+/**
+ * Keeps the browser tab's title in step with the unread count, as Outlook on the web does - `(3) Acme: Mail` - so mail that
+ * arrives while the tab is in the background can be seen from the tab strip. The count is put in front of whatever the title is
+ * (the page sets its own, from the branding) and taken off again when it drops to zero or the component goes away.
+ *
+ * Order matters when the same component also sets the title: declare this hook after the effect that does, so that on a change of `resetKey`
+ * the count is taken off the old title, the new title is written, and the count goes back in front of it.
+ */
+export declare function useUnreadTitle(count: number, { enabled, resetKey }?: UseUnreadTitleOptions): void;

package/dist/apps/shared/mail/useUnreadTitle.js

@@ -0,0 +1,31 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect } from "react";
+/** A count this hook put in front of the title, so it can be taken off again: `(3) `. */
+const TITLE_PREFIX = /^\(\d+\) /;
+/** `title` with `count` unread in front - `(3) Acme: Mail` - or as it is when there are none. */
+export function titleWithUnread(title, count) {
+    const base = title.replace(TITLE_PREFIX, "");
+    return count > 0 ? `(${count > 99 ? "99+" : count}) ${base}` : base;
+}
+/**
+ * Keeps the browser tab's title in step with the unread count, as Outlook on the web does - `(3) Acme: Mail` - so mail that
+ * arrives while the tab is in the background can be seen from the tab strip. The count is put in front of whatever the title is
+ * (the page sets its own, from the branding) and taken off again when it drops to zero or the component goes away.
+ *
+ * Order matters when the same component also sets the title: declare this hook after the effect that does, so that on a change of `resetKey`
+ * the count is taken off the old title, the new title is written, and the count goes back in front of it.
+ */
+export function useUnreadTitle(count, { enabled = true, resetKey } = {}) {
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        document.title = titleWithUnread(document.title, count);
+        return () => {
+            document.title = titleWithUnread(document.title, 0);
+        };
+    }, [count, enabled, resetKey]);
+}

package/dist/apps/shared/navigation/AppRouter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The web client's client-side router: what lets Mail, Calendar, Contacts, Tasks and Settings replace one another - and a
+ * folder replace a folder - without a page load.
+ *
+ * `@rapidrest/react` has no router of its own: every page is a server-rendered document with its own hydration entry, and
+ * hydrates only the page component (never `_layout.tsx`). So the router is a component the pages render themselves - each
+ * page's default export is `routedPage(path, Page)` (see `apps/www/_routedPage.tsx`), which renders `AppRouter` with the page
+ * as its first content. The first load is unchanged: the server renders the same tree, the browser hydrates it.
+ *
+ * `AppRouter` keeps ONE `AppChrome` (the icon rail, header, user menu, impersonation banner, compose windows, unlock prompt,
+ * idle-key timer, sign-out listener) mounted and swaps only what is inside it. A page's own shell (`MailShell`,
+ * `CalendarShell`, ...) still renders `AppShell` as it always did; inside the frame that renders nothing but its children.
+ *
+ * Navigation:
+ *
+ * Every `<a href>` to a same-origin path in the route table is intercepted (plain left clicks only - not with a modifier key, not
+ * `target`/`download`, not a hash-only link, not one marked `data-full-reload`), so pages just write ordinary links and
+ * middle-click, "open in new tab" and copy-link keep working. Anything not in the table - the admin and escrow consoles, plugin
+ * pages, other sites - is left to the browser. `useNavigate()` does the same for code (`navigate("/contacts")`).
+ *
+ * Back and forward work (`popstate`), and the URL is always the real, shareable one (`?mailboxUid=&folderUid=` and all).
+ *
+ * A route's code is loaded (`route.load()`) before the URL and the page change, so the old page stays up meanwhile (the frame is
+ * `aria-busy`); a route that fails to load falls back to a real navigation, which also picks up a new deploy.
+ *
+ * The next page's code is fetched on hover, focus and pointer-down of a link to it, and for the app rail's pages when the browser
+ * is idle.
+ *
+ * After a page change the frame moves keyboard focus to the content region, scrolls to the top, sets `document.title` and
+ * announces the new page to screen readers.
+ *
+ * The props of every `apps/www` page are the same for all of them (`WwwRoute.fetchProps()`: the user, auth-server URL,
+ * branding, plugin navigation, impersonation) except `params`, which the router recomputes from the URL - so the props of the
+ * page that was loaded are what every later page gets.
+ */
+import React, { ComponentType } from "react";
+import { RouteDefinition } from "./routes.js";
+export { useLocation, useLocationSearch, useNavigate } from "./routerContext.js";
+export type { NavigateFn, NavigateOptions, RouterLocation } from "./routerContext.js";
+/** What `routedPage()` gives the router: the page component itself, without the router around it. */
+export type RoutedPageComponent<P = any> = ComponentType<P> & {
+    page: ComponentType<P>;
+};
+export interface AppRouterProps {
+    routes: readonly RouteDefinition[];
+    /** The template of the route this document was rendered for. */
+    initialPath: string;
+    initialPage: ComponentType<any>;
+    /** The props the server rendered the page with. */
+    pageProps: Record<string, any>;
+}
+export default function AppRouter({ routes, initialPath, initialPage, pageProps }: AppRouterProps): React.JSX.Element;

package/dist/apps/shared/navigation/AppRouter.js

@@ -0,0 +1,242 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The web client's client-side router: what lets Mail, Calendar, Contacts, Tasks and Settings replace one another - and a
+ * folder replace a folder - without a page load.
+ *
+ * `@rapidrest/react` has no router of its own: every page is a server-rendered document with its own hydration entry, and
+ * hydrates only the page component (never `_layout.tsx`). So the router is a component the pages render themselves - each
+ * page's default export is `routedPage(path, Page)` (see `apps/www/_routedPage.tsx`), which renders `AppRouter` with the page
+ * as its first content. The first load is unchanged: the server renders the same tree, the browser hydrates it.
+ *
+ * `AppRouter` keeps ONE `AppChrome` (the icon rail, header, user menu, impersonation banner, compose windows, unlock prompt,
+ * idle-key timer, sign-out listener) mounted and swaps only what is inside it. A page's own shell (`MailShell`,
+ * `CalendarShell`, ...) still renders `AppShell` as it always did; inside the frame that renders nothing but its children.
+ *
+ * Navigation:
+ *
+ * Every `<a href>` to a same-origin path in the route table is intercepted (plain left clicks only - not with a modifier key, not
+ * `target`/`download`, not a hash-only link, not one marked `data-full-reload`), so pages just write ordinary links and
+ * middle-click, "open in new tab" and copy-link keep working. Anything not in the table - the admin and escrow consoles, plugin
+ * pages, other sites - is left to the browser. `useNavigate()` does the same for code (`navigate("/contacts")`).
+ *
+ * Back and forward work (`popstate`), and the URL is always the real, shareable one (`?mailboxUid=&folderUid=` and all).
+ *
+ * A route's code is loaded (`route.load()`) before the URL and the page change, so the old page stays up meanwhile (the frame is
+ * `aria-busy`); a route that fails to load falls back to a real navigation, which also picks up a new deploy.
+ *
+ * The next page's code is fetched on hover, focus and pointer-down of a link to it, and for the app rail's pages when the browser
+ * is idle.
+ *
+ * After a page change the frame moves keyboard focus to the content region, scrolls to the top, sets `document.title` and
+ * announces the new page to screen readers.
+ *
+ * The props of every `apps/www` page are the same for all of them (`WwwRoute.fetchProps()`: the user, auth-server URL,
+ * branding, plugin navigation, impersonation) except `params`, which the router recomputes from the URL - so the props of the
+ * page that was loaded are what every later page gets.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { AppChrome } from "../components/layout/AppShell.js";
+import { AppFrameContext } from "./frameContext.js";
+import { whenIdle, shouldSaveData } from "./idle.js";
+import { matchRoute } from "./routes.js";
+import { RouterContext, UNKNOWN_LOCATION, readWindowLocation } from "./routerContext.js";
+export { useLocation, useLocationSearch, useNavigate } from "./routerContext.js";
+function pickChromeProps(props) {
+    const { userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav } = props;
+    return { userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav };
+}
+/** The anchor a click/pointer event is on or in, if it is a link. */
+function linkOf(event) {
+    const target = event.target;
+    return target instanceof Element ? target.closest("a[href]") : null;
+}
+/** The URL of a link the router may take over, `null` for one the browser must handle itself. */
+function routerUrlOf(link) {
+    if ((link.target && link.target !== "_self") || link.hasAttribute("download") || link.hasAttribute("data-full-reload")) {
+        return null;
+    }
+    const url = new URL(link.href, window.location.href);
+    if (url.origin !== window.location.origin) {
+        return null;
+    }
+    // A link that only moves within the page (`#section`) is the browser's own.
+    if (url.hash !== "" && url.pathname === window.location.pathname && url.search === window.location.search) {
+        return null;
+    }
+    return url;
+}
+export default function AppRouter({ routes, initialPath, initialPage, pageProps }) {
+    const [current, setCurrent] = useState(() => ({
+        Page: initialPage,
+        routePath: initialPath,
+        active: routes.find((route) => route.path === initialPath)?.active ?? "mail",
+        params: pageProps.params ?? {},
+        key: "initial",
+    }));
+    const [location, setLocation] = useState(UNKNOWN_LOCATION);
+    const [pending, setPending] = useState(false);
+    const [takeovers, setTakeovers] = useState(0);
+    const currentRef = useRef(current);
+    currentRef.current = current;
+    /** Identifies the latest navigation; one that finds it changed while loading has been overtaken and does nothing. */
+    const navigationRef = useRef(0);
+    /** The page components loaded or loading, by route template - one request per page however many links are touched. */
+    const pagesRef = useRef(new Map([[initialPath, Promise.resolve(initialPage)]]));
+    const routesRef = useRef(routes);
+    routesRef.current = routes;
+    /** Loads a route's page component (once). Rejects if its code can't be loaded - and then a later attempt tries again. */
+    const pageFor = useCallback((route) => {
+        let loading = pagesRef.current.get(route.path);
+        if (!loading) {
+            loading = route.load().then((module) => {
+                const page = module.default.page;
+                if (!page) {
+                    throw new Error(`The page for ${route.path} is not a routedPage().`);
+                }
+                return page;
+            });
+            pagesRef.current.set(route.path, loading);
+            loading.catch(() => pagesRef.current.delete(route.path));
+        }
+        return loading;
+    }, []);
+    /** The pathname of the page on screen (the address bar's, once a navigation has been committed). */
+    const shownPathRef = useRef(null);
+    /**
+     * Shows `match` (loading its page first if it is a different page from the one on screen), calling `commit` - which puts
+     * the URL in the address bar - at the moment the new page replaces the old one. Resolves `false` when the page's code
+     * couldn't be loaded, and `true` otherwise, including when a newer navigation overtook this one while it loaded.
+     */
+    const show = useCallback(async (match, target, sequence, commit) => {
+        const pathChanged = target.pathname !== shownPathRef.current;
+        let Page = currentRef.current.Page;
+        if (pathChanged && match.route.path !== currentRef.current.routePath) {
+            try {
+                Page = await pageFor(match.route);
+            }
+            catch {
+                return false;
+            }
+        }
+        if (sequence !== navigationRef.current) {
+            return true;
+        }
+        commit();
+        shownPathRef.current = target.pathname;
+        if (pathChanged) {
+            setCurrent({ Page, routePath: match.route.path, active: match.route.active, params: match.params, key: target.pathname });
+        }
+        setLocation(target);
+        return true;
+    }, [pageFor]);
+    const navigate = useCallback((href, options = {}) => {
+        const url = new URL(href, window.location.href);
+        const leave = () => (options.replace ? window.location.replace(url.href) : (window.location.href = url.href));
+        const match = url.origin === window.location.origin ? matchRoute(routesRef.current, url.pathname) : undefined;
+        if (!match) {
+            leave();
+            return;
+        }
+        const target = { pathname: url.pathname, search: url.search, hash: url.hash };
+        const now = readWindowLocation();
+        if (target.pathname === now.pathname && target.search === now.search && target.hash === now.hash) {
+            return;
+        }
+        const sequence = ++navigationRef.current;
+        setPending(true);
+        void show(match, target, sequence, () => {
+            window.history[options.replace ? "replaceState" : "pushState"](null, "", target.pathname + target.search + target.hash);
+        }).then((ok) => {
+            if (!ok) {
+                leave();
+            }
+            if (sequence === navigationRef.current) {
+                setPending(false);
+            }
+        });
+    }, [show]);
+    // The browser's own location is read after the first render, never during it: the server can't know the query string.
+    useEffect(() => {
+        const here = readWindowLocation();
+        shownPathRef.current = here.pathname;
+        setLocation(here);
+    }, []);
+    // Back and forward.
+    useEffect(() => {
+        function handlePopState() {
+            const here = readWindowLocation();
+            const match = matchRoute(routesRef.current, here.pathname);
+            if (!match) {
+                window.location.reload();
+                return;
+            }
+            const sequence = ++navigationRef.current;
+            setPending(true);
+            void show(match, here, sequence, () => undefined).then((ok) => {
+                if (!ok) {
+                    window.location.reload();
+                }
+                if (sequence === navigationRef.current) {
+                    setPending(false);
+                }
+            });
+        }
+        window.addEventListener("popstate", handlePopState);
+        return () => window.removeEventListener("popstate", handlePopState);
+    }, [show]);
+    // Plain links, and fetching what they lead to before they are clicked.
+    useEffect(() => {
+        function handleClick(event) {
+            if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+                return;
+            }
+            const link = linkOf(event);
+            const url = link && routerUrlOf(link);
+            if (!url || !matchRoute(routesRef.current, url.pathname)) {
+                return;
+            }
+            event.preventDefault();
+            navigate(url.pathname + url.search + url.hash);
+        }
+        function handleIntent(event) {
+            const link = linkOf(event);
+            const url = link && routerUrlOf(link);
+            const match = url && matchRoute(routesRef.current, url.pathname);
+            if (match) {
+                pageFor(match.route).catch(() => undefined);
+            }
+        }
+        document.addEventListener("click", handleClick);
+        document.addEventListener("pointerover", handleIntent);
+        document.addEventListener("pointerdown", handleIntent);
+        document.addEventListener("focusin", handleIntent);
+        return () => {
+            document.removeEventListener("click", handleClick);
+            document.removeEventListener("pointerover", handleIntent);
+            document.removeEventListener("pointerdown", handleIntent);
+            document.removeEventListener("focusin", handleIntent);
+        };
+    }, [navigate, pageFor]);
+    // The app rail's other pages, once the browser has nothing else to do - so that the likeliest next click is instant.
+    useEffect(() => {
+        if (shouldSaveData()) {
+            return;
+        }
+        const cancels = routesRef.current
+            .filter((route) => route.idlePrefetch)
+            .map((route) => whenIdle(() => void pageFor(route).catch(() => undefined)));
+        return () => cancels.forEach((cancel) => cancel());
+    }, [pageFor]);
+    const enterTakeover = useCallback(() => {
+        setTakeovers((n) => n + 1);
+        return () => setTakeovers((n) => n - 1);
+    }, []);
+    const frame = useMemo(() => ({ enterTakeover }), [enterTakeover]);
+    const router = useMemo(() => ({ location, navigate }), [location, navigate]);
+    const Page = current.Page;
+    return (_jsx(RouterContext.Provider, { value: router, children: _jsx(AppFrameContext.Provider, { value: frame, children: _jsx(AppChrome, { active: current.active, routeKey: current.key, busy: pending, hideChrome: takeovers > 0, ...pickChromeProps(pageProps), children: _jsx(Page, { ...pageProps, params: current.params }, current.key) }) }) }));
+}

package/dist/apps/shared/navigation/appHrefs.d.ts

@@ -0,0 +1,14 @@
+/** Where each of the four rail apps lives - what the icon rail links to and what the keyboard's "Go to ..." shortcuts navigate to. */
+export declare const APP_HREFS: {
+    readonly mail: "/";
+    readonly calendar: "/calendar";
+    readonly contacts: "/contacts";
+    readonly tasks: "/tasks";
+};
+/**
+ * Settings is reached from the account menu, not the rail. It links straight to the first settings section, the only one that always
+ * exists - repoint this at a real `/settings` landing page once there is one.
+ */
+export declare const SETTINGS_HREF = "/settings/auto-reply";
+/** Whether `pathname` is a page of Settings (any section), which is what "already there" means for it. */
+export declare function isSettingsPath(pathname: string): boolean;

package/dist/apps/shared/navigation/appHrefs.js

@@ -0,0 +1,20 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** Where each of the four rail apps lives - what the icon rail links to and what the keyboard's "Go to ..." shortcuts navigate to. */
+export const APP_HREFS = {
+    mail: "/",
+    calendar: "/calendar",
+    contacts: "/contacts",
+    tasks: "/tasks",
+};
+/**
+ * Settings is reached from the account menu, not the rail. It links straight to the first settings section, the only one that always
+ * exists - repoint this at a real `/settings` landing page once there is one.
+ */
+export const SETTINGS_HREF = "/settings/auto-reply";
+/** Whether `pathname` is a page of Settings (any section), which is what "already there" means for it. */
+export function isSettingsPath(pathname) {
+    return pathname === "/settings" || pathname.startsWith("/settings/");
+}

package/dist/apps/shared/navigation/frameContext.d.ts

@@ -0,0 +1,19 @@
+import React, { PropsWithChildren } from "react";
+/**
+ * What the persistent app frame (`AppRouter`'s one mounted `AppShell` chrome) offers to what is rendered inside it. `null`
+ * outside a frame - a page not shown by the router (an admin page, a plugin page, a test) renders its own chrome.
+ */
+export interface AppFrameContextValue {
+    /** Hides the frame's chrome (icon rail, header, footer) until the returned function is called - see `FrameTakeover`. */
+    enterTakeover: () => () => void;
+}
+export declare const AppFrameContext: React.Context<AppFrameContextValue | null>;
+/** `true` inside the persistent app frame. */
+export declare function useInAppFrame(): boolean;
+/**
+ * Wraps a screen that takes over the whole window - first-time key setup, "your mailbox is being set up" - which used to
+ * replace the page's shell entirely. Inside the persistent frame the shell can't be replaced (it stays mounted), so the frame
+ * hides its chrome for as long as this is mounted instead (and gives the screen the full width); outside a frame it renders its children as they are. A layout effect, so the chrome
+ * is gone before the screen is first painted.
+ */
+export declare function FrameTakeover({ children }: PropsWithChildren): React.JSX.Element;

package/dist/apps/shared/navigation/frameContext.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { createContext, useContext, useLayoutEffect } from "react";
+export const AppFrameContext = createContext(null);
+/** `true` inside the persistent app frame. */
+export function useInAppFrame() {
+    return useContext(AppFrameContext) !== null;
+}
+/**
+ * Wraps a screen that takes over the whole window - first-time key setup, "your mailbox is being set up" - which used to
+ * replace the page's shell entirely. Inside the persistent frame the shell can't be replaced (it stays mounted), so the frame
+ * hides its chrome for as long as this is mounted instead (and gives the screen the full width); outside a frame it renders its children as they are. A layout effect, so the chrome
+ * is gone before the screen is first painted.
+ */
+export function FrameTakeover({ children }) {
+    const frame = useContext(AppFrameContext);
+    useLayoutEffect(() => frame?.enterTakeover(), [frame]);
+    // The frame puts a page in `#app-content`, a flex row: a full-window screen there would shrink to its content and sit at the left
+    // edge instead of centring, so inside the frame it is given the whole row, as a block its own root fills.
+    return frame ? _jsx("div", { className: "flex-1 min-w-0", children: children }) : _jsx(_Fragment, { children: children });
+}

package/dist/apps/shared/navigation/idle.d.ts

@@ -0,0 +1,14 @@
+/** How long an idle callback may be held back on a busy page before it runs anyway. */
+export declare const IDLE_TIMEOUT_MS = 3000;
+/** The delay used where the browser has no `requestIdleCallback` (Safari). */
+export declare const IDLE_FALLBACK_DELAY_MS = 200;
+/**
+ * Runs `callback` once the page has finished loading (the window `load` event, which waits for every script and image the page
+ * asked for) and the browser has nothing better to do (`requestIdleCallback`), or shortly after where there is no such thing.
+ * For work that only makes later things faster - fetching a code chunk, warming a cache - and must never compete with what
+ * the user is waiting for. Returns a function that cancels it if it hasn't run yet.
+ */
+export declare function whenIdle(callback: () => void): () => void;
+/** `true` when the user has asked the browser to save data (or is on a very slow connection): work that only speculates
+ * about what will be needed - prefetching - should not run then. */
+export declare function shouldSaveData(): boolean;

package/dist/apps/shared/navigation/idle.js

@@ -0,0 +1,43 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** How long an idle callback may be held back on a busy page before it runs anyway. */
+export const IDLE_TIMEOUT_MS = 3000;
+/** The delay used where the browser has no `requestIdleCallback` (Safari). */
+export const IDLE_FALLBACK_DELAY_MS = 200;
+/**
+ * Runs `callback` once the page has finished loading (the window `load` event, which waits for every script and image the page
+ * asked for) and the browser has nothing better to do (`requestIdleCallback`), or shortly after where there is no such thing.
+ * For work that only makes later things faster - fetching a code chunk, warming a cache - and must never compete with what
+ * the user is waiting for. Returns a function that cancels it if it hasn't run yet.
+ */
+export function whenIdle(callback) {
+    let cancelIdle = () => undefined;
+    function schedule() {
+        if (typeof window.requestIdleCallback === "function") {
+            const handle = window.requestIdleCallback(callback, { timeout: IDLE_TIMEOUT_MS });
+            cancelIdle = () => window.cancelIdleCallback(handle);
+        }
+        else {
+            const timer = setTimeout(callback, IDLE_FALLBACK_DELAY_MS);
+            cancelIdle = () => clearTimeout(timer);
+        }
+    }
+    if (document.readyState === "complete") {
+        schedule();
+    }
+    else {
+        window.addEventListener("load", schedule, { once: true });
+    }
+    return () => {
+        window.removeEventListener("load", schedule);
+        cancelIdle();
+    };
+}
+/** `true` when the user has asked the browser to save data (or is on a very slow connection): work that only speculates
+ * about what will be needed - prefetching - should not run then. */
+export function shouldSaveData() {
+    const connection = navigator.connection;
+    return connection?.saveData === true || connection?.effectiveType === "slow-2g" || connection?.effectiveType === "2g";
+}

package/dist/apps/shared/navigation/routerContext.d.ts

@@ -0,0 +1,37 @@
+export interface RouterLocation {
+    pathname: string;
+    /** With the leading `?`, or `""`. */
+    search: string;
+    /** With the leading `#`, or `""`. */
+    hash: string;
+}
+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 route of the app, else as an ordinary navigation. */
+export type NavigateFn = (href: string, options?: NavigateOptions) => void;
+export interface RouterContextValue {
+    location: RouterLocation;
+    navigate: NavigateFn;
+}
+export declare const RouterContext: import("react").Context<RouterContextValue | null>;
+/** Before the browser's own location has been read (the server render and the first client render, which must match). */
+export declare const UNKNOWN_LOCATION: RouterLocation;
+export declare function readWindowLocation(): RouterLocation;
+/**
+ * The function to go somewhere with. `navigate("/calendar")` and `navigate("/?mailboxUid=a&folderUid=b")` change the page and
+ * the URL without a page load when the router knows the route (Mail, Calendar, Contacts, Tasks, Settings and their subpages),
+ * and load the page normally otherwise; outside the router it is always a normal navigation. Prefer a plain `<a href>` for
+ * anything the user clicks - the router intercepts it, and it stays a real link - and this for what code decides (after a
+ * save, a delete, a select). The returned function is stable across renders.
+ */
+export declare function useNavigate(): NavigateFn;
+/**
+ * Where the app is now, as `{ pathname, search, hash }`, updating as the router navigates (folder changes are `search`
+ * changes, not page changes). Empty until the browser's location has been read in an effect after the first render, so that
+ * the server render and the first client render agree - read query parameters from it in an effect, not during render.
+ */
+export declare function useLocation(): RouterLocation;
+/** `useLocation().search` - what the shells read `?mailboxUid=` and the like from. */
+export declare function useLocationSearch(): string;