@remit/web-client 0.0.161 → 0.0.163

package/src/routing/fragment.ts

@@ -1,4 +1,5 @@
-import { useLocation } from "@tanstack/react-router";
+import { useLocation, useNavigate } from "@tanstack/react-router";
+import { useCallback, useMemo } from "react";
 import { z } from "zod";
 
 /**
@@ -7,29 +8,91 @@ import { z } from "zod";
  * independent of in-memory data, so a cold load of the URL reproduces it
  * exactly.
  */
-export const panelFragments = [
-	"intelligence",
-	"nav",
-	"shortcuts",
-	"filters",
-] as const;
+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);
+
 const panelFragmentSchema = z.enum(panelFragments);
 
 /**
- * A hand-edited or stale URL is a normal thing to receive, so an unrecognised
- * fragment reads as "no panel open" instead of throwing.
+ * 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 parsePanelFragment(hash: string): PanelFragment | undefined {
-	const parsed = panelFragmentSchema.safeParse(hash);
-	return parsed.success ? parsed.data : undefined;
+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 panel the URL currently asks for, if any. */
-export function useOpenPanel(): PanelFragment | undefined {
-	return useLocation({
-		select: (location) => parsePanelFragment(location.hash),
+/** 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]);
+}
+
+/**
+ * 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: a pane is chrome a reader keeps up while they
+ * move from one conversation to the next, and an overlay is dismissed by going
+ * somewhere, which is what closing it means.
+ *
+ * The parameter is optional because the router hands a `hash` updater the
+ * previous fragment as `string | undefined`.
+ */
+export function retainOpenPanels(hash = ""): string {
+	return formatOpenPanels(
+		parseOpenPanels(hash).filter((panel) => !isOverlayPanel(panel)),
+	);
+}
+
+/**
+ * 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,8 +1,14 @@
 export {
+	formatOpenPanels,
+	isOverlayPanel,
+	type OverlayPanel,
+	overlayPanels,
 	type PanelFragment,
 	panelFragments,
-	parsePanelFragment,
-	useOpenPanel,
+	parseOpenPanels,
+	retainOpenPanels,
+	useOpenPanels,
+	useSetOpenPanels,
 } from "./fragment";
 export { NavLink, type NavLinkProps } from "./nav-link";
 export {

package/src/routing/nav-link.tsx

@@ -7,7 +7,7 @@ import type {
 } from "@tanstack/react-router";
 import { createLink } from "@tanstack/react-router";
 import type { ReactElement } from "react";
-import type { PanelFragment } from "./fragment";
+import { type PanelFragment, retainOpenPanels } from "./fragment";
 
 const RouterNavLink = createLink(NavLinkSurface);
 
@@ -42,6 +42,10 @@ export type NavLinkProps<
  * 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.
  */
 export function NavLink<
 	TRouter extends AnyRouter = RegisteredRouter,
@@ -54,5 +58,5 @@ export function NavLink({
 	fragment,
 	...props
 }: CreateLinkProps & { fragment?: PanelFragment }): ReactElement {
-	return <RouterNavLink {...props} hash={fragment} />;
+	return <RouterNavLink {...props} hash={fragment ?? retainOpenPanels} />;
 }