@shivaedev/work-board 0.12.0 → 0.14.0

package/src/client/react/useBoardNavigation.ts

@@ -0,0 +1,134 @@
+import { useRouter } from "@tanstack/react-router";
+import { useEffect, useState } from "react";
+import type { RouterShell } from "#client/react/loadBoardPage.ts";
+import { currentEntry, navigationFailure, readingKey, sameReadingLocation } from "#client/react/navigationLocation.ts";
+import { readerLink } from "#client/react/readerLink.ts";
+import { readingEntry, readingHistory } from "#client/react/readingHistory.ts";
+import { captureReading } from "#client/react/readingState.ts";
+import { retryPage } from "#client/react/retryPage.ts";
+import { scheduleReading } from "#client/react/scheduleReading.ts";
+
+export function useBoardNavigation(shell: RouterShell) {
+	const router = useRouter();
+	const [status, setStatus] = useState("");
+	useEffect(() => {
+		const readings = readingHistory();
+		const initial = readingEntry(shell.reading ?? window.history.state?.workBoard);
+		const aliases = new Map<string, string>();
+		let displayed = "";
+		let route = "";
+		let hash = "";
+		let failure = "";
+		let interrupted = false;
+		function save() {
+			if (!displayed || document.getElementById("doc")?.dataset.route !== route) {
+				interrupted ||= displayed !== "";
+				return;
+			}
+			const reading = captureReading();
+			if (reading) {
+				readings.save(displayed, reading);
+			}
+		}
+		function page() {
+			const location = router.state.resolvedLocation ?? router.state.location;
+			const nextRoute = location.pathname + location.searchStr;
+			const doc = document.getElementById("doc");
+			if (doc?.dataset.route !== nextRoute) {
+				return;
+			}
+			const previousFailure = failure;
+			failure = navigationFailure(doc.dataset.status);
+			if (failure) {
+				setStatus(failure);
+				return;
+			}
+			setStatus((current) => (current === previousFailure ? "" : current));
+			const key = location.state.key ?? nextRoute;
+			const entry = currentEntry(location.state, displayed, initial);
+			const id = readingKey(key, entry, aliases);
+			if (!interrupted && sameReadingLocation({ hash, id: displayed, route }, { hash: location.hash, id, route: nextRoute })) {
+				return;
+			}
+			interrupted = false;
+			const reading = readings.get(id) ?? entry?.reading;
+			const focus = displayed !== "";
+			displayed = id;
+			route = nextRoute;
+			hash = location.hash;
+			recordEntry(router, nextRoute, id, shell.client !== undefined);
+			scheduleReading(doc, reading, hash, () => displayed === id && doc.dataset.route === nextRoute, setStatus, focus);
+		}
+		async function open(target: URL) {
+			save();
+			document.dispatchEvent(new Event("board-navigate"));
+			const url = target.pathname + target.search + target.hash;
+			if (url === router.state.location.href && retryPage(shell.api, shell.registry, target.pathname + target.search)) {
+				await router.invalidate();
+			} else if (url !== router.state.location.href) {
+				await router.navigate({ to: url });
+			}
+			page();
+		}
+		function click(event: MouseEvent) {
+			const link = event.target instanceof Element ? event.target.closest<HTMLAnchorElement>("a[href]") : null;
+			if (
+				!link
+				|| event.defaultPrevented
+				|| event.button !== 0
+				|| event.ctrlKey
+				|| event.metaKey
+				|| event.shiftKey
+				|| event.altKey
+				|| link.hasAttribute("download")
+				|| (link.target && link.target !== "_self")
+			) {
+				return;
+			}
+			const target = new URL(link.href, location.href);
+			if (!readerLink(target)) {
+				return;
+			}
+			event.preventDefault();
+			void open(target);
+		}
+		function submit(event: SubmitEvent) {
+			const form = event.target;
+			if (!(form instanceof HTMLFormElement) || form.id !== "work-filters") {
+				return;
+			}
+			event.preventDefault();
+			const target = new URL(form.action, location.href);
+			target.search = new URLSearchParams([...new FormData(form)].map(([key, value]) => [key, String(value)])).toString();
+			void open(target);
+		}
+		document.addEventListener("submit", submit);
+		const before = router.subscribe("onBeforeNavigate", save);
+		const resolved = router.subscribe("onResolved", page);
+		window.history.scrollRestoration = "manual";
+		document.addEventListener("click", click);
+		document.addEventListener("board-page", page);
+		window.addEventListener("pagehide", save);
+		page();
+		return () => {
+			before();
+			resolved();
+			document.removeEventListener("submit", submit);
+			document.removeEventListener("click", click);
+			document.removeEventListener("board-page", page);
+			window.removeEventListener("pagehide", save);
+		};
+	}, [router, shell.api, shell.registry, shell.reading, shell.client]);
+	return status;
+}
+
+function recordEntry(router: ReturnType<typeof useRouter>, route: string, id: string, native: boolean) {
+	if (!native) {
+		return;
+	}
+	router.history.flush?.();
+	if (window.location.pathname + window.location.search !== route || window.history.state?.workBoard?.id === id) {
+		return;
+	}
+	window.history.replaceState({ ...window.history.state, workBoard: { id } }, "");
+}

package/src/client/react/useDiagnosticsPolling.ts

@@ -0,0 +1,27 @@
+import { RegistryContext } from "@effect/atom-react";
+import type * as Atom from "effect/reactivity/Atom";
+import { useContext, useEffect } from "react";
+import { session } from "#client/entry.ts";
+
+export function useDiagnosticsPolling<A, TFleet>(atom: Atom.Atom<A>, fleet?: Atom.Atom<TFleet>) {
+	const registry = useContext(RegistryContext);
+	useEffect(() => {
+		function refresh() {
+			const native = session(window);
+			if (!(document.hidden || native.registry.get(native.updates.paused))) {
+				registry.refresh(atom);
+				if (fleet) {
+					registry.refresh(fleet);
+				}
+			}
+		}
+		const timer = setInterval(refresh, 15_000);
+		document.addEventListener("board-updates-resumed", refresh);
+		document.addEventListener("visibilitychange", refresh);
+		return () => {
+			clearInterval(timer);
+			document.removeEventListener("board-updates-resumed", refresh);
+			document.removeEventListener("visibilitychange", refresh);
+		};
+	}, [atom, fleet, registry]);
+}

package/src/client/react/useDocumentPage.ts

@@ -3,7 +3,7 @@ import { flushSync } from "react-dom";
 import type { Document } from "#browser/document/schema.ts";
 import { documentSourceId } from "#client/document/layout.ts";
 import { fileUrl } from "#files/url.ts";
-import type { MainLocation } from "./legacyPage.ts";
+import { displayedLocation, type MainLocation } from "./mainLocation.ts";
 export function useDocumentPage({
 	data,
 	pending,
@@ -25,6 +25,9 @@ export function useDocumentPage({
 		}
 		const main = element;
 		main.dataset.scheme = document.documentElement.dataset.scheme ?? "";
+		if (main.dataset.route !== url) {
+			delete main.dataset.route;
+		}
 		let active = true;
 		let scheduled = false;
 		function announce() {
@@ -69,7 +72,7 @@ function publishPage(main: HTMLElement, data: Document | undefined, status: stri
 	} else {
 		delete main.dataset.identity;
 	}
-	flushSync(() => onPage({ file: data?.file ?? "", view: "" }));
+	flushSync(() => onPage(displayedLocation(main)));
 	main.dataset.route = url;
 	main.dataset.status = status;
 	document.dispatchEvent(new Event("board-page"));

package/src/client/react/useFormFocus.ts

@@ -0,0 +1,52 @@
+import { Schema } from "effect";
+import { type FocusEvent, useCallback, useEffect, useLayoutEffect, useRef } from "react";
+import { captureFocus, restoreFocus } from "#client/formFocus.ts";
+
+const Selection = Schema.Struct({
+	direction: Schema.NullOr(Schema.Literals(["forward", "backward", "none"])),
+	end: Schema.NullOr(Schema.Number),
+	name: Schema.String,
+	prompt: Schema.optional(Schema.String),
+	start: Schema.NullOr(Schema.Number),
+});
+
+export function useFormFocus(key: string) {
+	const ref = useRef<HTMLFormElement>(null);
+
+	const remember = useCallback(
+		(control: Element | null = document.activeElement) => {
+			const selection = ref.current && captureFocus(ref.current, control);
+			if (!selection) {
+				return false;
+			}
+			try {
+				window.localStorage.setItem(`${key}:focus`, JSON.stringify(selection));
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		[key],
+	);
+	useLayoutEffect(() => {
+		try {
+			const stored: unknown = JSON.parse(window.localStorage.getItem(`${key}:focus`) ?? "null");
+			if (ref.current && window.localStorage.getItem(key) && Schema.is(Selection)(stored)) {
+				restoreFocus(ref.current, { ...stored, prompt: stored.prompt });
+			}
+		} catch {
+			// Draft input remains usable when browser storage is unavailable.
+		}
+		return () => {
+			remember();
+		};
+	}, [key, remember]);
+	useEffect(() => {
+		function hide() {
+			remember();
+		}
+		window.addEventListener("pagehide", hide);
+		return () => window.removeEventListener("pagehide", hide);
+	}, [remember]);
+	return { onBlurCapture: (event: FocusEvent<HTMLFormElement>) => remember(event.target), onSelect: () => remember(), ref };
+}

package/src/client/react/useHandoffForm.ts

@@ -0,0 +1,105 @@
+import { useAtomRef } from "@effect/atom-react";
+import { Effect, Equal, Layer, Option, Schema } from "effect";
+import * as Atom from "effect/reactivity/Atom";
+import { useEffect, useRef, useState } from "react";
+import { useCreate } from "@shivaedev/effect-react/create.ts";
+import { HandoffInput, type HandoffPreview } from "#browser/handoffs/schema.ts";
+import type { HandoffProjection } from "#browser/views/remaining.ts";
+import { session } from "#client/entry.ts";
+import { formDraft } from "#client/formDraft.ts";
+import { failureStatus } from "#client/handoffs/failureStatus.ts";
+import { sourceChanged } from "#client/sourceChanged.ts";
+
+const runtime = Atom.runtime(Layer.empty);
+export function useHandoffForm(data: HandoffProjection, source: HandoffPreview) {
+	const [preview, setPreview] = useState<HandoffInput>();
+	const [status, setStatus] = useState("Draft ready. Review and preview before preparing the file.");
+	const modelRef = useRef<HandoffInput | undefined>(undefined);
+	const draft = formDraft("handoff", source.item);
+	const created = useCreate({
+		create: (input) =>
+			Effect.tryPromise({
+				catch: (error) => error,
+				try: async () => {
+					const native = session(window);
+					setStatus("Pending: preparing the local handoff file…");
+					try {
+						const saved = await native.mutate(native.handoffs.prepareHandoff.run(input));
+						const newer = !Equal.equals(modelRef.current, input);
+						setStatus(
+							`Prepared: ${saved.file}. Receipt: ${saved.handoff.state}; execution and acceptance remain separate.${newer ? " Your newer draft remains unsaved." : ""}`,
+						);
+						return saved;
+					} catch (error) {
+						setStatus(failureStatus(error));
+						throw error;
+					}
+				},
+			}),
+		fields: HandoffInput,
+		initialValues: {
+			constraints: "",
+			goal: data.goal,
+			id: "",
+			item: source.item,
+			nextAction: data.nextAction,
+			recipient: "",
+			revision: "",
+			source: source.source,
+		},
+		persistedDraft: draft,
+		runtime,
+	});
+	const form = created.form;
+	const values = useAtomRef(form.values);
+	useEffect(() => {
+		if (created.dirty && Option.isSome(created.created) && !form.values.value.id) {
+			form.change("id", `handoff.${crypto.randomUUID()}`);
+			form.change("revision", created.created.value.handoff.reviewedRevision);
+			form.change("source", created.created.value.handoff.source);
+		}
+	}, [form, created.dirty, created.created]);
+	modelRef.current = values;
+	const stale = Boolean(values.id) && (values.revision !== source.reviewedRevision || values.source !== source.source);
+	function edit() {
+		if (!form.values.value.id) {
+			form.change("id", `handoff.${crypto.randomUUID()}`);
+			form.change("revision", source.reviewedRevision);
+		}
+		setPreview(undefined);
+		if (!created.saving) {
+			setStatus("Draft ready. Review and preview before preparing the file.");
+		}
+	}
+	function showPreview() {
+		if (!values.id || stale) {
+			form.change("id", `handoff.${crypto.randomUUID()}`);
+		}
+		form.change("revision", source.reviewedRevision);
+		form.change("source", source.source);
+		for (const name of ["constraints", "goal", "id", "item", "nextAction", "recipient", "revision", "source"] as const) {
+			form.blur(name);
+		}
+		setPreview(form.values.value);
+	}
+	function clear() {
+		created.revert();
+		setPreview(undefined);
+		setStatus("Draft cleared. Saved handoffs are unchanged.");
+	}
+	const previewed = preview !== undefined && !stale && Equal.equals(preview, values);
+	return {
+		clear,
+		created,
+		draft,
+		edit,
+		form,
+		preview: previewed ? handoffPreview(values) : undefined,
+		showPreview,
+		status: stale ? sourceChanged() : status,
+		valid: Schema.is(HandoffInput)(values),
+	};
+}
+function handoffPreview(input: HandoffInput) {
+	return `New file: handoffs/${input.id}.md\nPrepared time and reviewed snapshot are assigned by the server.\n\n---\n${JSON.stringify({ handoff: { constraints: input.constraints, goal: input.goal, item: input.item, "next_action": input.nextAction, recipient: input.recipient, "reviewed_revision": input.revision, source: input.source, state: "requested" }, id: input.id, kind: "handoff" }, null, 2)}\n---\nThe complete reviewed source is preserved below the frontmatter.`;
+}

package/src/client/react/useMedia.ts

@@ -0,0 +1,19 @@
+import { useEffect, useState } from "react";
+
+export function useMedia(query: string) {
+	const [matches, setMatches] = useState(() => matchMedia(query).matches);
+	useEffect(() => {
+		const media = matchMedia(query);
+		function sync() {
+			setMatches(media.matches);
+		}
+		media.addEventListener("change", sync);
+		window.addEventListener("resize", sync);
+		sync();
+		return () => {
+			media.removeEventListener("change", sync);
+			window.removeEventListener("resize", sync);
+		};
+	}, [query]);
+	return matches;
+}

package/src/client/react/useProjectionData.ts

@@ -0,0 +1,26 @@
+import { Cause, Option, Predicate } from "effect";
+import type * as AsyncResult from "effect/reactivity/AsyncResult";
+import type * as Atom from "effect/reactivity/Atom";
+import { useEffect, useState } from "react";
+import { useQuery } from "@shivaedev/effect-react/result-state.ts";
+import type { ProjectionRoute } from "./projectionRoute.ts";
+import type { RemainingRoute } from "./remainingRoute.ts";
+
+type Route = ProjectionRoute | RemainingRoute;
+export function useProjectionData<A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>, route: Route, url: string) {
+	const query = useQuery(atom);
+	const fresh = Option.getOrUndefined(query.data);
+	const [retained, setRetained] = useState<{ readonly data: A; readonly route: Route; readonly url: string }>();
+	useEffect(() => {
+		if (fresh !== undefined) {
+			setRetained({ data: fresh, route, url });
+		}
+	}, [fresh, route, url]);
+	const failure = Option.getOrUndefined(Option.flatMap(query.cause, Cause.findErrorOption));
+	const missing = Predicate.isTagged(failure, "NotFound");
+	const conflict = Predicate.isTagged(failure, "Conflict");
+	const terminal = missing || conflict;
+	const data = terminal ? undefined : (fresh ?? (retained?.url === url ? retained.data : undefined));
+	const content = terminal ? undefined : (data ?? (retained?.route === route ? retained.data : undefined));
+	return { conflict, content, data, failure, missing, query };
+}

package/src/client/react/useResponseForm.ts

@@ -0,0 +1,145 @@
+import { useAtomRef } from "@effect/atom-react";
+import { Equal, Layer, Option, Schema } from "effect";
+import * as Atom from "effect/reactivity/Atom";
+import { useEffect, useRef, useState } from "react";
+import { useCreate } from "@shivaedev/effect-react/create.ts";
+import type { Prompt } from "#browser/responses/Prompt.ts";
+import type { PromptAnswer, QuestionPreview } from "#browser/responses/schema.ts";
+import { formDraft } from "#client/formDraft.ts";
+import { answerRecovery, recoveryText } from "#client/responses/answerRecovery.ts";
+import { authorLabel } from "#client/responses/authorLabel.ts";
+import { type ResponseInput, responseFormSchema } from "#client/responses/formSchema.ts";
+import { responsePreview } from "#client/responses/preview.ts";
+import { retainContext } from "#client/responses/retainContext.ts";
+import { responseFeedback, responseSummary } from "#client/responses/summary.ts";
+import { sourceChanged } from "#client/sourceChanged.ts";
+import { createResponse } from "./createResponse.ts";
+
+const runtime = Atom.runtime(Layer.empty);
+
+export function useResponseForm(source: QuestionPreview, prompts: readonly Prompt[]) {
+	const schema = responseFormSchema(prompts.length > 0);
+	const [preview, setPreview] = useState<ResponseInput>();
+	const [outcome, setOutcome] = useState<string>();
+	const [status, setStatus] = useState("");
+	const [attempted, setAttempted] = useState(false);
+	const [label] = useState(() =>
+		authorLabel(() => window.localStorage, typeof document === "undefined" ? undefined : document.documentElement.dataset.workspace),
+	);
+	const [initial] = useState<ResponseInput>(() => ({
+		answerContext: undefined,
+		answers: prompts.length > 0 ? prompts.map((prompt) => ({ prompt: prompt.id, selected: [], text: "" })) : undefined,
+		author: label.read("") || "maintainer",
+		body: "",
+		id: "",
+		question: "",
+		recovery: undefined,
+		revision: "",
+		supersedes: undefined,
+		type: "answer",
+	}));
+	const draft = formDraft("response", source.item, source.request);
+	const modelRef = useRef<ResponseInput | undefined>(undefined);
+	const created = useCreate({
+		create: (submission) => createResponse(source, submission, () => modelRef.current, setOutcome, setStatus),
+		fields: schema,
+		initialValues: initial,
+		persistedDraft: draft,
+		runtime,
+	});
+	const form = created.form;
+	const values = useAtomRef(form.values);
+	useEffect(() => {
+		if (Option.isSome(created.created)) {
+			form.receive({ ...initial, author: label.read("") || "maintainer" });
+			if (created.dirty) {
+				retainContext(form, created.created.value);
+			}
+		}
+	}, [form, created.created, created.dirty, initial, label]);
+	modelRef.current = values;
+	const same = values.question === source.id && values.revision === source.reviewedRevision;
+	const stale = Boolean(values.id) && !same;
+	const recovery = answerRecovery(values, !stale || values.answerContext === JSON.stringify([source.id, source.reviewedRevision]));
+	useEffect(() => {
+		if (!Equal.equals(values.recovery, recovery)) {
+			form.change("recovery", recovery);
+		}
+	}, [form, values.recovery, recovery]);
+	function answers(snapshot = form.values.value) {
+		const changedSource =
+			snapshot.answerContext !== JSON.stringify([source.id, source.reviewedRevision])
+			&& (snapshot.question !== source.id || snapshot.revision !== source.reviewedRevision);
+		return prompts.length > 0
+			? prompts.map((prompt) => {
+					const answer = snapshot.answers?.find((entry) => entry.prompt === prompt.id);
+					return { prompt: prompt.id, selected: changedSource ? [] : (answer?.selected ?? []), text: answer?.text ?? "" };
+				})
+			: undefined;
+	}
+	function editAnswers(index: number, next: PromptAnswer) {
+		form.change(
+			"answers",
+			answers()?.map((answer, position) => (position === index ? next : answer)),
+		);
+		form.change("answerContext", JSON.stringify([source.id, source.reviewedRevision]));
+		edit();
+	}
+	function showPreview() {
+		setOutcome(undefined);
+		if (!form.values.value.id || form.values.value.question !== source.id || form.values.value.revision !== source.reviewedRevision) {
+			form.change("id", `response.${crypto.randomUUID()}`);
+		}
+		form.change("answers", answers());
+		form.change("answerContext", JSON.stringify([source.id, source.reviewedRevision]));
+		form.change("question", source.id);
+		form.change("revision", source.reviewedRevision);
+		for (const name of ["answerContext", "answers", "author", "body", "id", "question", "recovery", "revision", "supersedes", "type"] as const) {
+			form.blur(name);
+		}
+		setPreview(form.values.value);
+		setStatus("");
+	}
+	function edit() {
+		if (!form.values.value.id) {
+			form.change("id", `response.${crypto.randomUUID()}`);
+			form.change("question", source.id);
+			form.change("revision", source.reviewedRevision);
+		}
+		label.save(form.values.value.author);
+		setPreview(undefined);
+		if (!created.saving) {
+			setOutcome(undefined);
+			setStatus("");
+		}
+	}
+	function clear() {
+		setAttempted(false);
+		setOutcome(undefined);
+		created.revert();
+		setPreview(undefined);
+		setStatus("Draft cleared. Saved responses are unchanged.");
+	}
+	const previewed = preview !== undefined && same && Equal.equals(preview, values);
+	const summary = responseSummary(values, prompts, answers(values), attempted);
+	return {
+		answers: answers(values),
+		attempt: () => {
+			setAttempted(true);
+			showPreview();
+			return Schema.is(schema)(form.values.value);
+		},
+		attempted,
+		clear,
+		created,
+		draft,
+		edit,
+		editAnswers,
+		form,
+		outcome,
+		preview: previewed ? responsePreview(values, source.id, prompts) : undefined,
+		recovery: recoveryText(recovery),
+		showPreview,
+		status: [stale ? sourceChanged() : "", responseFeedback(status, outcome, summary)].filter(Boolean).join(" "),
+	};
+}

package/src/client/react/useSearchDialog.ts

@@ -0,0 +1,25 @@
+import { useCallback, useEffect, useState } from "react";
+
+export function useSearchDialog() {
+	const [state, setState] = useState<{ readonly open: boolean; readonly returnFocus?: HTMLElement | undefined }>({ open: false });
+	const open = useCallback(() => {
+		const active = document.activeElement;
+		setState({ open: true, returnFocus: active instanceof HTMLElement ? active : undefined });
+	}, []);
+	const close = useCallback(() => setState((current) => ({ ...current, open: false })), []);
+	useEffect(() => {
+		function key(event: KeyboardEvent) {
+			if ((event.ctrlKey || event.metaKey) && !event.altKey && event.key.toLowerCase() === "k") {
+				event.preventDefault();
+				if (state.open) {
+					close();
+				} else {
+					open();
+				}
+			}
+		}
+		document.addEventListener("keydown", key);
+		return () => document.removeEventListener("keydown", key);
+	}, [state.open, open, close]);
+	return { ...state, close, show: open };
+}

package/src/client/react/useSidebar.ts

@@ -0,0 +1,81 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import type { AppearanceControls } from "./useAppearance.ts";
+import { useMedia } from "./useMedia.ts";
+
+export function useSidebar(appearance: AppearanceControls) {
+	const narrow = useMedia("(max-width: 767px)");
+	const [drawer, setDrawer] = useState(false);
+	const open = narrow ? drawer : !appearance.closed;
+	const returnFocusRef = useRef(false);
+	const close = useCallback(() => {
+		returnFocusRef.current = true;
+		setDrawer(false);
+	}, []);
+	useLayoutEffect(() => {
+		if (!open && returnFocusRef.current) {
+			returnFocusRef.current = false;
+			document.getElementById("sidebar-toggle")?.focus({ preventScroll: true });
+		}
+	}, [open]);
+
+	function toggle() {
+		if (narrow) {
+			setDrawer(!drawer);
+		} else {
+			appearance.change({ closed: !appearance.closed });
+		}
+	}
+	useEffect(() => {
+		setDrawer(false);
+		if (narrow && document.getElementById("sidebar")?.contains(document.activeElement)) {
+			close();
+		}
+	}, [narrow, close]);
+	useEffect(() => {
+		document.documentElement.dataset.sidebar = open ? "open" : "closed";
+		if (narrow && open) {
+			document.querySelector<HTMLElement>("#sidebar a")?.focus({ preventScroll: true });
+		}
+	}, [narrow, open]);
+	useEffect(() => {
+		if (!(narrow && open)) {
+			return;
+		}
+		function key(event: KeyboardEvent) {
+			if (document.querySelector("dialog[open]")) {
+				return;
+			}
+			if (event.key === "Escape") {
+				event.preventDefault();
+				close();
+			}
+			if (event.key !== "Tab") {
+				return;
+			}
+			trapTab(event);
+		}
+		document.addEventListener("keydown", key);
+		document.addEventListener("board-navigate", close);
+		return () => {
+			document.removeEventListener("keydown", key);
+			document.removeEventListener("board-navigate", close);
+		};
+	}, [narrow, open, close]);
+	return { close, narrow, open, toggle };
+}
+export type SidebarControls = ReturnType<typeof useSidebar>;
+
+function trapTab(event: KeyboardEvent) {
+	const items = [...document.querySelectorAll<HTMLElement>("#sidebar a[href], #sidebar button:not(:disabled), #sidebar summary")].filter(
+		(element) => element.getClientRects().length > 0,
+	);
+	const first = items[0];
+	const last = items.at(-1);
+	if (event.shiftKey && document.activeElement === first) {
+		event.preventDefault();
+		last?.focus();
+	} else if (!event.shiftKey && document.activeElement === last) {
+		event.preventDefault();
+		first?.focus();
+	}
+}

package/src/client/react/useVirtualRows.ts

@@ -0,0 +1,14 @@
+import { type UIEvent, useState } from "react";
+
+export function useVirtualRows(count: number, rowHeight: number, enabled = count > 200) {
+	const [scroll, setScroll] = useState({ height: 600, top: 0 });
+	const start = enabled ? Math.min(Math.floor(scroll.top / rowHeight), Math.max(0, count - 1)) : 0;
+	const end = enabled ? Math.min(count, start + Math.ceil(scroll.height / rowHeight) + 4) : count;
+	return {
+		bottom: (count - end) * rowHeight,
+		end,
+		onScroll: (event: UIEvent<HTMLElement>) => setScroll({ height: event.currentTarget.clientHeight, top: event.currentTarget.scrollTop }),
+		start,
+		top: start * rowHeight,
+	};
+}

package/src/client/react/visualDimensions.ts

@@ -0,0 +1,20 @@
+export function graphicWidth(graphic: Element | null | undefined) {
+	if (graphic instanceof HTMLImageElement) {
+		return graphic.naturalWidth;
+	}
+	if (graphic instanceof SVGSVGElement) {
+		return graphic.viewBox?.baseVal?.width;
+	}
+	return undefined;
+}
+
+export function visualFilename(local: string | undefined) {
+	if (!local) {
+		return "work-board-diagram.svg";
+	}
+	try {
+		return decodeURIComponent(new URL(local, location.href).pathname.split("/").at(-1) ?? "work-board-image");
+	} catch {
+		return "work-board-image";
+	}
+}