@remit/web-client 0.0.325 → 0.0.326

package/src/routing/fragment.render.test.ts

@@ -1,98 +0,0 @@
-/**
- * `useRetainOpenPanels` reads the tier off the app's own desktop breakpoint
- * (#777), so a navigation below it lands without the rail in the address —
- * which is what keeps the drawer with the thread it was opened for.
- */
-
-import assert from "node:assert/strict";
-import { afterEach, describe, it } from "node:test";
-import {
-	type AnyRouter,
-	createMemoryHistory,
-	createRootRoute,
-	createRoute,
-	createRouter,
-	RouterProvider,
-	useNavigate,
-} from "@tanstack/react-router";
-import { createElement } from "react";
-import { createDomHarness, type DomHarness } from "../test-support/dom";
-import { useRetainOpenPanels } from "./fragment";
-
-const PHONE_WIDTH = 390;
-const DESKTOP_WIDTH = 1440;
-
-let harness: DomHarness | undefined;
-
-afterEach(() => {
-	harness?.close();
-	harness = undefined;
-});
-
-// The router reads `self` at construction; the shared jsdom globals stop at
-// `window`.
-(globalThis as { self?: typeof globalThis }).self ??= globalThis;
-
-function CloseThread() {
-	const navigate = useNavigate();
-	const retainPanels = useRetainOpenPanels();
-	return createElement(
-		"button",
-		{
-			type: "button",
-			onClick: () => {
-				void navigate({ to: "/mail", hash: retainPanels });
-			},
-		},
-		"Back",
-	);
-}
-
-const rootRoute = createRootRoute();
-const listRoute = createRoute({
-	getParentRoute: () => rootRoute,
-	path: "/mail",
-});
-const threadRoute = createRoute({
-	getParentRoute: () => rootRoute,
-	path: "/mail/thread",
-	component: CloseThread,
-});
-
-const openDrawerOverThread = (): AnyRouter =>
-	createRouter({
-		routeTree: rootRoute.addChildren([listRoute, threadRoute]),
-		history: createMemoryHistory({
-			initialEntries: ["/mail/thread#intelligence"],
-		}),
-	}) as unknown as AnyRouter;
-
-const walkUpToTheList = async (viewportWidth: number): Promise<AnyRouter> => {
-	const router = openDrawerOverThread();
-	harness = createDomHarness({ viewportWidth });
-	// Resolve the first match before mounting: `RouterProvider` renders its
-	// pending state until the router has loaded, and nothing here waits for it.
-	await router.load();
-	harness.render(createElement(RouterProvider, { router }));
-	await harness.flush();
-	harness.click(harness.byText("button", "Back"));
-	await harness.flush();
-	await harness.wait(20);
-	return router;
-};
-
-describe("useRetainOpenPanels (#777)", () => {
-	it("leaves the drawer behind on a phone", async () => {
-		const router = await walkUpToTheList(PHONE_WIDTH);
-
-		assert.equal(router.state.location.pathname, "/mail");
-		assert.equal(router.state.location.hash, "");
-	});
-
-	it("carries the rail across on desktop, where it is a pane", async () => {
-		const router = await walkUpToTheList(DESKTOP_WIDTH);
-
-		assert.equal(router.state.location.pathname, "/mail");
-		assert.equal(router.state.location.hash, "intelligence");
-	});
-});

package/src/routing/fragment.test.ts

@@ -1,113 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import {
-	formatOpenPanels,
-	panelFragments,
-	parseOpenPanels,
-	retainOpenPanelsAtTier,
-} from "./fragment.js";
-
-const retainOnDesktop = retainOpenPanelsAtTier(true);
-const retainOnPhone = retainOpenPanelsAtTier(false);
-
-describe("parseOpenPanels", () => {
-	it("reads every panel the union names", () => {
-		for (const panel of panelFragments) {
-			assert.deepEqual(parseOpenPanels(panel), [panel]);
-		}
-	});
-
-	it("reads a pane and an overlay together", () => {
-		assert.deepEqual(parseOpenPanels("intelligence,shortcuts"), [
-			"intelligence",
-			"shortcuts",
-		]);
-	});
-
-	it("spells one set of panels one way", () => {
-		assert.deepEqual(parseOpenPanels("shortcuts,intelligence,shortcuts"), [
-			"intelligence",
-			"shortcuts",
-		]);
-	});
-
-	it("reads an empty, unknown or mis-cased fragment as no panel", () => {
-		assert.deepEqual(parseOpenPanels(""), []);
-		assert.deepEqual(parseOpenPanels("confirm-delete"), []);
-		assert.deepEqual(parseOpenPanels("Intelligence"), []);
-		assert.deepEqual(parseOpenPanels("form:input:to"), []);
-	});
-
-	it("keeps the panels it recognises out of a fragment carrying junk", () => {
-		assert.deepEqual(parseOpenPanels("filters,intelligence"), ["intelligence"]);
-	});
-});
-
-describe("formatOpenPanels", () => {
-	it("writes the address a set of panels is read back from", () => {
-		assert.equal(
-			formatOpenPanels(["shortcuts", "intelligence"]),
-			"intelligence,shortcuts",
-		);
-		assert.equal(formatOpenPanels([]), "");
-	});
-});
-
-describe("retainOpenPanelsAtTier", () => {
-	it("carries a pane across a navigation on the tier that has one", () => {
-		assert.equal(retainOnDesktop("intelligence"), "intelligence");
-	});
-
-	it("leaves the overlays behind, and keeps the pane under them", () => {
-		assert.equal(retainOnDesktop("nav"), "");
-		assert.equal(retainOnDesktop("shortcuts"), "");
-		assert.equal(retainOnDesktop("intelligence,shortcuts"), "intelligence");
-	});
-
-	it("drops a fragment it does not recognise rather than passing it on", () => {
-		assert.equal(retainOnDesktop(), "");
-		assert.equal(retainOnDesktop("confirm-delete"), "");
-		assert.equal(retainOnPhone("confirm-delete"), "");
-	});
-});
-
-/**
- * Below desktop the rail is a full-screen drawer over the open message, so it
- * belongs to the thread it was opened for. Every navigation that handed the
- * fragment on put the drawer over the next message the reader opened.
- *
- * Each case walks the fragment through the navigations of one reachable path,
- * starting from the address the open drawer wrote.
- */
-describe("the drawer stays with its thread below desktop (#777)", () => {
-	const walk = (
-		retain: (hash?: string) => string,
-		hash: string,
-		steps: number,
-	): string => {
-		let current = hash;
-		for (let step = 0; step < steps; step += 1) current = retain(current);
-		return current;
-	};
-
-	// A DKIM mismatch opens the drawer; the reader taps the back arrow instead
-	// of closing it, then taps another row.
-	it("drops the rail between the back arrow and the next row", () => {
-		assert.equal(walk(retainOnPhone, "intelligence", 2), "");
-		assert.equal(walk(retainOnDesktop, "intelligence", 2), "intelligence");
-	});
-
-	// "Report spam" inside the open drawer removes the thread the drawer is
-	// reading, which closes it up to the list — one navigation, no back button.
-	it("drops the rail when a quick action in the drawer removes the thread", () => {
-		assert.equal(retainOnPhone("intelligence"), "");
-		assert.equal(retainOnDesktop("intelligence"), "intelligence");
-	});
-
-	// The brief and the flagged list open a thread from a cross-mailbox row,
-	// and the shortcuts sheet may be up over the drawer when they do.
-	it("drops the rail when the brief or the flagged list opens a thread", () => {
-		assert.equal(retainOnPhone("intelligence,shortcuts"), "");
-		assert.equal(retainOnDesktop("intelligence,shortcuts"), "intelligence");
-	});
-});

package/src/routing/fragment.ts

@@ -1,145 +0,0 @@
-import { useLocation, useNavigate } from "@tanstack/react-router";
-import { useCallback, useMemo } from "react";
-import { z } from "zod";
-import { useIsDesktop } from "@/hooks/useMediaQuery";
-
-/**
- * The fragment tier carries panel visibility and nothing else — no identity, no
- * payload, no selection. A panel qualifies only when its own copy is
- * independent of in-memory data, so a cold load of the URL reproduces it
- * exactly.
- */
-export const panelFragments = ["intelligence", "nav", "shortcuts"] as const;
-
-export type PanelFragment = (typeof panelFragments)[number];
-
-/**
- * The panels that cover the view rather than sit in it. The rail is a pane in
- * the shell's row and the other two are modal over it, so a sheet opening can
- * never take the rail down with it — the address holds the pane and the overlay
- * at once. Two overlays cannot be up together, because the second one hides the
- * first.
- */
-export const overlayPanels = ["nav", "shortcuts"] as const;
-
-export type OverlayPanel = (typeof overlayPanels)[number];
-
-export const isOverlayPanel = (panel: PanelFragment): panel is OverlayPanel =>
-	(overlayPanels as readonly PanelFragment[]).includes(panel);
-
-/**
- * The set an overlay opening or closing leaves behind it.
- *
- * A write states the whole set, so raising the nav slide-over has to say what
- * else is up or it takes it down. The panes stay and the previous overlay goes,
- * because two overlays cannot both be up — which is how a reader crossing from
- * their mail into the calendar and reaching for the folders keeps the rail they
- * arrived with.
- */
-export function panelsWithOverlay(
-	open: readonly PanelFragment[],
-	overlay: OverlayPanel | undefined,
-): PanelFragment[] {
-	return [
-		...open.filter((panel) => !isOverlayPanel(panel)),
-		...(overlay ? [overlay] : []),
-	];
-}
-
-const panelFragmentSchema = z.enum(panelFragments);
-
-/**
- * The panels the address asks for, in the union's own order so one set of open
- * panels has one spelling. A hand-edited or stale URL is a normal thing to
- * receive, so an unrecognised name is dropped instead of throwing.
- */
-export function parseOpenPanels(hash: string): readonly PanelFragment[] {
-	const named = new Set(
-		hash
-			.split(",")
-			.map((token) => panelFragmentSchema.safeParse(token))
-			.filter((parsed) => parsed.success)
-			.map((parsed) => parsed.data),
-	);
-	return panelFragments.filter((panel) => named.has(panel));
-}
-
-/** The address a set of open panels is written as. */
-export function formatOpenPanels(panels: readonly PanelFragment[]): string {
-	return panelFragments.filter((panel) => panels.includes(panel)).join(",");
-}
-
-/** The panels the address currently asks for. */
-export function useOpenPanels(): readonly PanelFragment[] {
-	const hash = useLocation({
-		select: (location) => formatOpenPanels(parseOpenPanels(location.hash)),
-	});
-	return useMemo(() => parseOpenPanels(hash), [hash]);
-}
-
-/**
- * Whether a navigation carries this panel at this tier.
- *
- * A pane is chrome a reader keeps up while they move from one conversation to
- * the next; an overlay is dismissed by going somewhere, which is what closing
- * it means. Below desktop the rail is not a pane at all — it is a full-screen
- * drawer over the open message — so it belongs to the thread it was opened for
- * and a navigation leaves it behind, rather than covering a message nobody
- * asked to cover (#777).
- */
-const isRetainedPanel = (panel: PanelFragment, isDesktop: boolean): boolean =>
-	!isOverlayPanel(panel) && isDesktop;
-
-/**
- * A destination's `hash`, for a navigation that keeps the reader where they
- * are. The router drops the fragment on every navigation unless the destination
- * asks for it, so this is what a link or a `navigate` call passes to state the
- * rule rather than restate it.
- *
- * The tier is bound here rather than passed at the call site, so the updater
- * still has the shape the router hands a previous fragment to. That parameter
- * is optional because the router types it `string | undefined`.
- */
-export function retainOpenPanelsAtTier(
-	isDesktop: boolean,
-): (hash?: string) => string {
-	return (hash = "") =>
-		formatOpenPanels(
-			parseOpenPanels(hash).filter((panel) =>
-				isRetainedPanel(panel, isDesktop),
-			),
-		);
-}
-
-/**
- * The `hash` updater for a navigation from the surface the reader is on. The
- * layout tier is read here, once, so no call site decides for itself what a
- * navigation keeps.
- */
-export function useRetainOpenPanels(): (hash?: string) => string {
-	const isDesktop = useIsDesktop();
-	return useMemo(() => retainOpenPanelsAtTier(isDesktop), [isDesktop]);
-}
-
-/**
- * Puts a set of panels up, replacing whatever was up before.
- *
- * `replace`, because a panel is chrome over the current view rather than a place
- * to go: Back belongs to the message the reader came from, not to the rail they
- * just collapsed. The fragment names panels and never an element, so it is not
- * an anchor to scroll to either.
- */
-export function useSetOpenPanels(): (panels: readonly PanelFragment[]) => void {
-	const navigate = useNavigate();
-	return useCallback(
-		(panels: readonly PanelFragment[]) => {
-			navigate({
-				search: true,
-				hash: formatOpenPanels(panels),
-				replace: true,
-				hashScrollIntoView: false,
-			});
-		},
-		[navigate],
-	);
-}

package/src/routing/index.ts

@@ -1,93 +0,0 @@
-export {
-	type BrowsedList,
-	useBrowsedList,
-	useOpensDetail,
-} from "./browsed-list";
-export {
-	type CalendarAddress,
-	type CalendarNavigation,
-	type OpenCalendarEvent,
-	useCalendarAddress,
-	useCalendarNavigation,
-	useChangeSuggestionOnCalendar,
-	useChangingSuggestionId,
-	useIsWritingEvent,
-	useOpenCalendarEvent,
-	useOpenEventOnCalendar,
-} from "./calendar";
-export {
-	useAdoptComposeDraft,
-	useCloseCompose,
-	useComposeDraftId,
-	useEditDraft,
-	useIsComposing,
-	useOpenCompose,
-} from "./compose";
-export {
-	formatOpenPanels,
-	isOverlayPanel,
-	type OverlayPanel,
-	overlayPanels,
-	type PanelFragment,
-	panelFragments,
-	panelsWithOverlay,
-	parseOpenPanels,
-	retainOpenPanelsAtTier,
-	useOpenPanels,
-	useRetainOpenPanels,
-	useSetOpenPanels,
-} from "./fragment";
-export { NavLink, type NavLinkProps } from "./nav-link";
-export { useSelectedNavId } from "./nav-selection";
-export {
-	type OpenThreadOptions,
-	type OpenThreadPath,
-	type OpenThreadTarget,
-	useCloseThread,
-	useOpenThread,
-	useOpenThreadPath,
-} from "./open-thread";
-export {
-	useCloseOutboxDraft,
-	useOpenOutboxDraft,
-	useOutboxDraftId,
-} from "./outbox-draft";
-export {
-	type ReplyAddress,
-	type ReplyMode,
-	type ReplySurface,
-	type ReplyTarget,
-	replyModes,
-	replyToThread,
-	useAdoptReplyDraft,
-	useCloseReply,
-	useIsReplying,
-	useOpenReply,
-	useReplySurface,
-} from "./reply";
-export { type SearchField, useSearchField } from "./search-field";
-export { type SearchMirrorTarget, useSearchMirror } from "./search-mirror";
-export {
-	useScopeSearchToMailbox,
-	useSearchEverything,
-} from "./search-navigation";
-export {
-	type AppSection,
-	useConfigureAccountSmtp,
-	useGoToSection,
-} from "./sections";
-export {
-	ownedHistoryEntries,
-	type SelectionWizardControl,
-	useOpenWizard,
-	useSelectionWizard,
-	useWizardEntryValue,
-	useWizardStep,
-	useWizardStepValue,
-	type WizardEntry,
-	type WizardStepNavigation,
-	wizardEntryFromParam,
-	wizardEntryValue,
-	wizardStepFromParam,
-	wizardStepValue,
-} from "./wizard-history";

package/src/routing/nav-link.tsx

@@ -1,64 +0,0 @@
-import { NavLinkSurface } from "@remit/ui";
-import type {
-	AnyRouter,
-	CreateLinkProps,
-	LinkComponentProps,
-	RegisteredRouter,
-} from "@tanstack/react-router";
-import { createLink } from "@tanstack/react-router";
-import type { ReactElement } from "react";
-import { type PanelFragment, useRetainOpenPanels } from "./fragment";
-
-const RouterNavLink = createLink(NavLinkSurface);
-
-/**
- * The router's own link props, minus the raw `hash`: the fragment tier is a
- * closed union of panel names, so `fragment` is the only way to write it.
- */
-export type NavLinkProps<
-	TRouter extends AnyRouter = RegisteredRouter,
-	TFrom extends string = string,
-	TTo extends string | undefined = undefined,
-	TMaskFrom extends string = TFrom,
-	TMaskTo extends string = "",
-> = LinkComponentProps<
-	typeof NavLinkSurface,
-	TRouter,
-	TFrom,
-	TTo,
-	TMaskFrom,
-	TMaskTo
-> & {
-	fragment?: PanelFragment;
-	/**
-	 * Closed off rather than omitted: `Omit` over these props is a mapped type,
-	 * and the router's `to` / `params` / `search` inference cannot see through
-	 * one.
-	 */
-	hash?: never;
-};
-
-/**
- * The application's only navigation link. `createLink` keeps the router's `to` /
- * `params` / `search` inference, so a route that does not exist or a param set
- * that does not match it fails to compile instead of rendering a blank pane.
- *
- * A link that names no panel carries the open panes across: the rail is up
- * until the reader puts it down, and every row in a list is a link. Overlays
- * are left behind, because going somewhere is what dismisses one — and below
- * desktop so is the rail, which is a drawer over the message there.
- */
-export function NavLink<
-	TRouter extends AnyRouter = RegisteredRouter,
-	const TFrom extends string = string,
-	const TTo extends string | undefined = undefined,
-	const TMaskFrom extends string = TFrom,
-	const TMaskTo extends string = "",
->(props: NavLinkProps<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>): ReactElement;
-export function NavLink({
-	fragment,
-	...props
-}: CreateLinkProps & { fragment?: PanelFragment }): ReactElement {
-	const retainPanels = useRetainOpenPanels();
-	return <RouterNavLink {...props} hash={fragment ?? retainPanels} />;
-}

package/src/routing/nav-selection.ts

@@ -1,26 +0,0 @@
-import { useLocation, useParams } from "@tanstack/react-router";
-import { locationIsOnList } from "@/lib/mail-route";
-
-/**
- * The nav entry the address selects, or `""` where none does.
- *
- *   - `/settings/*` → "settings"
- *   - `/calendar/*` → "calendar"
- *   - `/mail/outbox`, `/mail/flagged`, `/mail/brief` → that list
- *   - `/mail/$mailboxId` → the mailbox id, which is what the sidebar keys on
- *
- * Read off the pathname rather than the matches: the router commits the new
- * location before it swaps them, so the entry the reader just tapped highlights
- * on the tap instead of when its list finishes loading.
- */
-export function useSelectedNavId(): string {
-	const { pathname } = useLocation();
-	const mailbox = useParams({ from: "/mail/$mailboxId", shouldThrow: false });
-
-	if (locationIsOnList(pathname, "/settings")) return "settings";
-	if (locationIsOnList(pathname, "/calendar")) return "calendar";
-	if (locationIsOnList(pathname, "/mail/outbox")) return "outbox";
-	if (locationIsOnList(pathname, "/mail/flagged")) return "flagged";
-	if (locationIsOnList(pathname, "/mail/brief")) return "brief";
-	return mailbox?.mailboxId ?? "";
-}

package/src/routing/open-thread.ts

@@ -1,157 +0,0 @@
-import { useNavigate, useParams } from "@tanstack/react-router";
-import { useCallback, useMemo } from "react";
-import { useBrowsedList, useNavigateToBrowsedList } from "./browsed-list";
-import { useRetainOpenPanels } from "./fragment";
-
-/** The conversation a list has open, as the address states it. */
-export interface OpenThreadPath {
-	threadId: string;
-	/**
-	 * Which message inside the thread is expanded and scrolled to. Absent on a
-	 * bare thread address, where the newest message answers for the conversation.
-	 */
-	messageId: string | undefined;
-}
-
-/**
- * A conversation to open. The thread is what the pane fetches by; the message is
- * the row the reader pointed at, so a list always knows both.
- */
-export interface OpenThreadTarget {
-	threadId: string;
-	messageId: string;
-}
-
-/**
- * The thread the address has open, whichever list is browsing it.
- *
- * The thread is a child route of the list, and the list layout mounts the pane
- * above the `Outlet` — so it asks the router which of its children matched
- * rather than reading a param it does not own. A path matches one list at a
- * time, so one hook answers for every list rather than each list keeping its
- * own copy of the same question. Each `from` names a real route, so a segment
- * that does not exist fails to compile.
- */
-export function useOpenThreadPath(): OpenThreadPath | undefined {
-	const briefThread = useParams({
-		from: "/mail/brief/$threadId",
-		shouldThrow: false,
-	});
-	const briefMessage = useParams({
-		from: "/mail/brief/$threadId/$messageId",
-		shouldThrow: false,
-	});
-	const flaggedThread = useParams({
-		from: "/mail/flagged/$threadId",
-		shouldThrow: false,
-	});
-	const flaggedMessage = useParams({
-		from: "/mail/flagged/$threadId/$messageId",
-		shouldThrow: false,
-	});
-	const mailboxThread = useParams({
-		from: "/mail/$mailboxId/$threadId",
-		shouldThrow: false,
-	});
-	const mailboxMessage = useParams({
-		from: "/mail/$mailboxId/$threadId/$messageId",
-		shouldThrow: false,
-	});
-
-	const threadId =
-		briefThread?.threadId ?? flaggedThread?.threadId ?? mailboxThread?.threadId;
-	const messageId =
-		briefMessage?.messageId ??
-		flaggedMessage?.messageId ??
-		mailboxMessage?.messageId;
-
-	return useMemo(
-		() => (threadId ? { threadId, messageId } : undefined),
-		[threadId, messageId],
-	);
-}
-
-/** How an open differs from the plain one, where it does. */
-export interface OpenThreadOptions {
-	/** Replace the entry rather than push one, so Back skips the row. */
-	replace?: boolean;
-	/**
-	 * Commit this query with the open. The debounced q-mirror walks back up to
-	 * the list when a query goes active, so a row tapped before the debounce
-	 * settles is closed again a moment later unless the address already says the
-	 * query the conversation was opened under. Omitted, the open carries whatever
-	 * query the address already had.
-	 */
-	query?: string;
-	/**
-	 * Open under this mailbox rather than the one being browsed. A search hit
-	 * carries its own, so a row can never open under a mailbox it does not belong
-	 * to.
-	 */
-	mailboxId?: string;
-}
-
-/**
- * Open a conversation on the list the reader is browsing.
- *
- * The thread is a child route of its list, so the list decides the address and
- * the caller only names the conversation. The brief is the fallback, and legal
- * for any thread: a list with no thread route under it — the outbox — and a
- * mailbox route in the frame before its id resolves both still open the
- * conversation rather than doing nothing, which is the dead row this route shape
- * exists to delete.
- */
-export function useOpenThread(): (
-	target: OpenThreadTarget,
-	options?: OpenThreadOptions,
-) => void {
-	const navigate = useNavigate();
-	const retainPanels = useRetainOpenPanels();
-	const { list, mailboxId: browsedMailboxId } = useBrowsedList();
-
-	return useCallback(
-		(target: OpenThreadTarget, options?: OpenThreadOptions) => {
-			const query = options?.query;
-			const search = (prev: Record<string, unknown>) =>
-				query === undefined ? prev : { ...prev, q: query || undefined };
-			const rest = {
-				search,
-				hash: retainPanels,
-				replace: options?.replace ?? false,
-			};
-			if (list === "flagged") {
-				navigate({
-					to: "/mail/flagged/$threadId/$messageId",
-					params: target,
-					...rest,
-				});
-				return;
-			}
-			const mailboxId = options?.mailboxId ?? browsedMailboxId;
-			if (list === "mailbox" && mailboxId) {
-				navigate({
-					to: "/mail/$mailboxId/$threadId/$messageId",
-					params: { mailboxId, ...target },
-					...rest,
-				});
-				return;
-			}
-			navigate({
-				to: "/mail/brief/$threadId/$messageId",
-				params: target,
-				...rest,
-			});
-		},
-		[navigate, retainPanels, list, browsedMailboxId],
-	);
-}
-
-/**
- * Close the conversation, landing back on the list it was opened from.
- *
- * A navigation up rather than a flag, so nothing is left mounted below the list
- * and Esc unwinds exactly one step.
- */
-export function useCloseThread(): () => void {
-	return useNavigateToBrowsedList();
-}