@shivaedev/work-board 0.12.0 → 0.13.0

package/src/client/react/readingState.ts

@@ -0,0 +1,133 @@
+import { Schema } from "effect";
+
+const Selection = Schema.Struct({ a: Schema.Int, anchor: Schema.Array(Schema.Int), f: Schema.Int, focus: Schema.Array(Schema.Int) });
+export const ReadingState = Schema.Struct({
+	context: Schema.optional(Schema.Boolean),
+	details: Schema.optional(Schema.Array(Schema.Boolean)),
+	keyedDetails: Schema.optional(Schema.Record(Schema.String, Schema.Boolean)),
+	scroll: Schema.Tuple([Schema.Finite, Schema.Finite]),
+	selection: Schema.NullOr(Selection),
+	sidebar: Schema.optional(Schema.Number),
+});
+export type ReadingState = typeof ReadingState.Type;
+const MISSING_PASSAGE = "This passage is no longer in the document.";
+let releaseScroll: (() => void) | undefined;
+function pathOf(node: Node, root: Node) {
+	const path: number[] = [];
+	for (let child: Node | null = node; child !== root; child = child.parentNode) {
+		if (!child?.parentNode) {
+			return undefined;
+		}
+		const nodes: readonly Node[] = [...child.parentNode.childNodes];
+		path.unshift(nodes.indexOf(child));
+	}
+	return path;
+}
+function nodeAt(path: readonly number[], root: Node): Node | undefined {
+	return path.reduce<Node | undefined>((node, index) => node?.childNodes[index], root);
+}
+function details(root: Element) {
+	const counts = new Map<string, number>();
+	return [...root.querySelectorAll<HTMLDetailsElement>("details:not(.item-context)")].map((detail) => {
+		const name = detail.dataset.key || detail.querySelector("summary")?.textContent || "details";
+		const occurrence = counts.get(name) ?? 0;
+		counts.set(name, occurrence + 1);
+		return [`${name}:${occurrence}`, detail] as const;
+	});
+}
+function inForm() {
+	return document.activeElement?.closest("#response-form, #handoff-form");
+}
+export function captureReading(): ReadingState | undefined {
+	const root = document.getElementById("doc");
+	if (!root) {
+		return undefined;
+	}
+	const selection = inForm() ? null : document.getSelection();
+	const anchor = selection?.anchorNode && pathOf(selection.anchorNode, root);
+	const focus = selection?.focusNode && pathOf(selection.focusNode, root);
+	return {
+		context: root.querySelector<HTMLDetailsElement>(".item-context")?.open,
+		details: details(root).map(([, detail]) => detail.open),
+		keyedDetails: Object.fromEntries(details(root).map(([key, detail]) => [key, detail.open])),
+		scroll: [scrollX, scrollY],
+		selection: anchor && focus && selection ? { a: selection.anchorOffset, anchor, f: selection.focusOffset, focus } : null,
+		sidebar: document.getElementById("sidebar")?.scrollTop ?? 0,
+	};
+}
+export function restoreReading(state: ReadingState) {
+	const root = document.getElementById("doc");
+	if (!root) {
+		return;
+	}
+	const context = root.querySelector<HTMLDetailsElement>(".item-context");
+	if (context && state.context !== undefined) {
+		context.open = state.context;
+	}
+	details(root).forEach(([key, detail], index) => {
+		const open = state.keyedDetails ? state.keyedDetails[key] : state.details?.[index];
+		if (open !== undefined) {
+			detail.open = open;
+		}
+	});
+	const sidebar = document.getElementById("sidebar");
+	if (sidebar) {
+		sidebar.scrollTop = state.sidebar ?? 0;
+	}
+	if (state.selection && !inForm()) {
+		const { anchor: anchorPath, focus: focusPath, a, f } = state.selection;
+		const anchor = nodeAt(anchorPath, root);
+		const focus = nodeAt(focusPath, root);
+		function limit(node: Node) {
+			return node.nodeType === 3 ? (node.textContent?.length ?? 0) : node.childNodes.length;
+		}
+		if (anchor && focus) {
+			document.getSelection()?.setBaseAndExtent(anchor, Math.max(0, Math.min(a, limit(anchor))), focus, Math.max(0, Math.min(f, limit(focus))));
+		}
+	}
+	restoreScroll(state.scroll);
+}
+function restoreScroll(scroll: readonly [number, number]) {
+	releaseScroll?.();
+	const root = document.documentElement;
+	const anchoring = root.style.overflowAnchor;
+	// Keep the saved offset while the restored passage status changes layout in this frame.
+	root.style.overflowAnchor = "none";
+	window.scrollTo(...scroll);
+	let frame = requestAnimationFrame(() => {
+		frame = requestAnimationFrame(() => releaseScroll?.());
+	});
+	releaseScroll = () => {
+		cancelAnimationFrame(frame);
+		root.style.overflowAnchor = anchoring;
+		releaseScroll = undefined;
+	};
+}
+export function scrollToPassage(hash: string) {
+	if (!hash) {
+		window.scrollTo(0, 0);
+		return "";
+	}
+	const target = passageTarget(hash);
+	if (!target) {
+		return MISSING_PASSAGE;
+	}
+	for (let parent = target.parentElement; parent; parent = parent.parentElement) {
+		if (parent instanceof HTMLDetailsElement) {
+			parent.open = true;
+		}
+	}
+	target.scrollIntoView();
+	target.focus({ preventScroll: true });
+	return "";
+}
+export function passageStatus(hash: string) {
+	return !hash || passageTarget(hash) ? "" : MISSING_PASSAGE;
+}
+function passageTarget(hash: string) {
+	try {
+		return document.getElementById(decodeURIComponent(hash.slice(1)));
+	} catch {
+		return null;
+	}
+}

package/src/client/react/remainingRoute.ts

@@ -0,0 +1,19 @@
+export function remainingRoute(pathname: string) {
+	switch (pathname) {
+		case "/_board/changes":
+			return "changes";
+		case "/_board/diagnostics":
+			return "diagnostics";
+		case "/_board/start":
+			return "start";
+		case "/_board/respond":
+			return "respond";
+		case "/_board/handoff":
+			return "handoff";
+		case "/_board/result":
+			return "result";
+		default:
+			return undefined;
+	}
+}
+export type RemainingRoute = NonNullable<ReturnType<typeof remainingRoute>>;

package/src/client/react/savedViews.ts

@@ -0,0 +1,84 @@
+import { Option, Schema } from "effect";
+import { useRef, useState } from "react";
+
+const Entry = Schema.Struct({ name: Schema.NonEmptyString, url: Schema.String });
+export function localView(value: string) {
+	try {
+		const url = new URL(value, location.href);
+		if (value.length > 8192 || url.origin !== location.origin || url.pathname !== "/_board/work") {
+			return undefined;
+		}
+		for (const name of [...url.searchParams.keys()]) {
+			if (!["view", "board", "owner", "status", "q", "sort"].includes(name)) {
+				url.searchParams.delete(name);
+			}
+		}
+		return url.pathname + url.search;
+	} catch {
+		return undefined;
+	}
+}
+function restore(key: string) {
+	const views: (typeof Entry.Type)[] = [];
+	try {
+		const saved: unknown = JSON.parse(localStorage.getItem(key) ?? "[]");
+		if (Array.isArray(saved)) {
+			for (const raw of saved) {
+				const entry = Option.getOrUndefined(Schema.decodeUnknownOption(Entry)(raw));
+				const url = entry && localView(entry.url);
+				if (!(entry && url && entry.name.trim()) || entry.name.length > 60 || views.some((view) => view.name === entry.name)) {
+					continue;
+				}
+				views.push({ name: entry.name, url });
+				if (views.length === 10) {
+					break;
+				}
+			}
+		}
+		return { notice: "", views };
+	} catch {
+		return { notice: "Saved views could not be restored; new views apply to this page until saved.", views };
+	}
+}
+export function useSavedViews() {
+	const key = `work-board:views:${document.documentElement.dataset.workspace}`;
+	const [saved, setSaved] = useState(() => restore(key));
+	const savedRef = useRef(saved);
+	const [selected, select] = useState("");
+	function persist(views: typeof saved.views) {
+		let notice = "";
+		try {
+			localStorage.setItem(key, JSON.stringify(views));
+		} catch {
+			notice = "Saved views apply to this page only; browser storage is unavailable.";
+		}
+		savedRef.current = { notice, views };
+		setSaved(savedRef.current);
+	}
+	function save(name: string, url: string) {
+		const local = localView(url);
+		if (!(name && local)) {
+			return;
+		}
+		if (savedRef.current.views.length === 10 && !savedRef.current.views.some((view) => view.name === name)) {
+			setSaved({ ...saved, notice: "You have 10 saved views. Remove one or update an existing name." });
+			return;
+		}
+		persist([{ name, url: local }, ...savedRef.current.views.filter((view) => view.name !== name)]);
+		select(name);
+	}
+	return {
+		...saved,
+		clear: () => {
+			persist([]);
+			select("");
+		},
+		remove: () => {
+			persist(saved.views.filter((view) => view.name !== selected));
+			select("");
+		},
+		save,
+		select,
+		selected,
+	};
+}

package/src/client/react/scheduleReading.ts

@@ -0,0 +1,41 @@
+import { flushSync } from "react-dom";
+import { type captureReading, passageStatus, restoreReading, scrollToPassage } from "./readingState.ts";
+export function scheduleReading(
+	doc: HTMLElement,
+	reading: ReturnType<typeof captureReading> | null,
+	hash: string,
+	active: () => boolean,
+	setStatus: (status: string) => void,
+	focus: boolean,
+) {
+	let restored = false;
+	function restore() {
+		if (restored || !active()) {
+			document.removeEventListener("board-reading-ready", restore);
+			return;
+		}
+		const context = doc.querySelector<HTMLElement>(".item-context");
+		if (context && context.dataset.readingReady !== "true") {
+			return;
+		}
+		restored = true;
+		document.removeEventListener("board-reading-ready", restore);
+		if (focus && !document.activeElement?.closest("#response-form, #handoff-form")) {
+			doc.focus({ preventScroll: true });
+		}
+		const passage = hash ? `#${hash}` : "";
+		if (reading) {
+			restoreReading(reading);
+			// Readiness can arrive from a React effect; commit the warning before the next paint.
+			queueMicrotask(() => {
+				if (active()) {
+					flushSync(() => setStatus(passageStatus(passage)));
+				}
+			});
+		} else {
+			setStatus(scrollToPassage(passage));
+		}
+	}
+	document.addEventListener("board-reading-ready", restore);
+	requestAnimationFrame(restore);
+}

package/src/client/react/searchCommands.ts

@@ -0,0 +1,15 @@
+export interface SearchItem {
+	readonly command?: string;
+	readonly file?: string;
+	readonly href?: string;
+	readonly kind: string;
+	readonly line?: number | undefined;
+	readonly snippet?: string;
+	readonly title: string;
+}
+export const searchCommands: readonly SearchItem[] = [
+	{ href: "/", kind: "command", title: "Open workspace" },
+	{ command: "sidebar-toggle", kind: "command", title: "Show or hide files" },
+	{ command: "density", kind: "command", title: "Toggle compact density" },
+	{ command: "theme", kind: "command", title: "Toggle light or dark theme" },
+];

package/src/client/react/searchStatus.ts

@@ -0,0 +1,30 @@
+export function searchStatus(
+	text: string,
+	pending: boolean,
+	failed: boolean,
+	data:
+		| {
+				readonly total: number;
+				readonly results: readonly unknown[];
+				readonly unavailable: readonly string[];
+		  }
+		| undefined,
+) {
+	if (!text) {
+		return "Type to search this workspace, or choose a command.";
+	}
+	if (failed) {
+		return "Search could not be completed. Press Search to retry.";
+	}
+	if (pending || !data) {
+		return "Searching…";
+	}
+	let message = "No document matches.";
+	if (data.total) {
+		message = `${data.total > data.results.length ? `Showing ${data.results.length} of ` : ""}${data.total} matches.`;
+	}
+	if (data.unavailable.length > 0) {
+		message += ` Could not read ${data.unavailable.length} files; results are incomplete.`;
+	}
+	return message;
+}

package/src/client/react/shellIds.ts

@@ -1,19 +1,38 @@
 export const shellIds = {
 	"breadcrumbs": "breadcrumbs",
+	changesContent: "changes-content",
+	clearSavedViews: "clear-saved-views",
 	"density": "density",
 	"doc": "doc",
 	"favoriteToggle": "favorite-toggle",
 	"files": "files",
+	handoffClear: "handoff-clear",
+	handoffForm: "handoff-form",
+	handoffHistory: "handoff-history",
+	handoffPrepared: "handoff-prepared",
+	handoffPreview: "handoff-preview",
+	handoffPreviewContent: "handoff-preview-content",
+	handoffStatus: "handoff-status",
+	handoffSubmit: "handoff-submit",
+	historyClear: "history-clear",
+	historyMark: "history-mark",
+	historyStorage: "history-storage",
 	"homeOpen": "home-open",
 	"inboxCount": "inbox-count",
 	"inboxOpen": "inbox-open",
 	"inboxTopbar": "inbox-topbar",
 	"inboxTopbarCount": "inbox-topbar-count",
+	libraryClose: "library-close",
+	libraryDialog: "library-dialog",
 	"libraryOpen": "library-open",
+	libraryTitle: "library-title",
 	"live": "live",
 	"navigationStatus": "navigation-status",
+	openSavedView: "open-saved-view",
 	"preferenceStatus": "preference-status",
 	"primaryNavigation": "primary-navigation",
+	readingLibrary: "reading-library",
+	removeSavedView: "remove-saved-view",
 	"responseClear": "response-clear",
 	"responseDraftRecovery": "response-draft-recovery",
 	"responseForm": "response-form",
@@ -22,11 +41,51 @@ export const shellIds = {
 	"responsePreviewContent": "response-preview-content",
 	"responseStatus": "response-status",
 	"responseSubmit": "response-submit",
+	resultActions: "result-actions",
+	resultCriteria: "result-criteria",
+	resultFeedback: "result-feedback",
+	resultReport: "result-report",
+	savedView: "saved-view",
+	savedViewStatus: "saved-view-status",
+	savedWorkViews: "saved-work-views",
+	saveWorkView: "save-work-view",
+	searchClose: "search-close",
+	searchDialog: "search-dialog",
+	searchForm: "search-form",
 	"searchOpen": "search-open",
+	searchQuery: "search-query",
+	searchResults: "search-results",
+	searchStatus: "search-status",
+	searchTitle: "search-title",
 	"sidebar": "sidebar",
 	"sidebarBackdrop": "sidebar-backdrop",
 	"sidebarToggle": "sidebar-toggle",
 	"startOpen": "start-open",
 	"theme": "theme",
 	"updatesToggle": "updates-toggle",
+	viewName: "view-name",
+	visualActual: "visual-actual",
+	visualClose: "visual-close",
+	visualContent: "visual-content",
+	visualContext: "visual-context",
+	visualDialog: "visual-dialog",
+	visualDownload: "visual-download",
+	visualFit: "visual-fit",
+	visualFullscreen: "visual-fullscreen",
+	visualIn: "visual-in",
+	visualNext: "visual-next",
+	visualOut: "visual-out",
+	visualPrevious: "visual-previous",
+	visualStage: "visual-stage",
+	visualStatus: "visual-status",
+	visualTitle: "visual-title",
+	visualViewport: "visual-viewport",
+	workBoard: "work-board",
+	workDetail: "work-detail",
+	workFilters: "work-filters",
+	workOwner: "work-owner",
+	workQuery: "work-query",
+	workResults: "work-results",
+	workSort: "work-sort",
+	workStatus: "work-status",
 } as const;

package/src/client/react/useAppearance.ts

@@ -0,0 +1,54 @@
+import { Option, Schema } from "effect";
+import { useEffect, useRef, useState } from "react";
+import { useMedia } from "./useMedia.ts";
+
+const Appearance = Schema.Struct({
+	closed: Schema.optional(Schema.Unknown),
+	density: Schema.optional(Schema.Unknown),
+	theme: Schema.optional(Schema.Unknown),
+});
+function restore(key: string) {
+	try {
+		const saved = Option.getOrUndefined(Schema.decodeUnknownOption(Appearance)(JSON.parse(localStorage.getItem(key) ?? "{}")));
+		return {
+			closed: saved?.closed === true,
+			density: saved?.density === "compact" ? "compact" : "comfortable",
+			notice: "",
+			theme: saved?.theme === "light" || saved?.theme === "dark" ? saved.theme : "system",
+		};
+	} catch {
+		return { closed: false, density: "comfortable", notice: "Preferences apply to this page only.", theme: "system" };
+	}
+}
+export function useAppearance() {
+	const key = `work-board:appearance:${document.documentElement.dataset.workspace}`;
+	const [value, setValue] = useState(() => restore(key));
+	const valueRef = useRef(value);
+	const dark = useMedia("(prefers-color-scheme: dark)");
+	const systemScheme = dark ? "dark" : "light";
+	const scheme = value.theme === "system" ? systemScheme : value.theme;
+	useEffect(() => {
+		const root = document.documentElement;
+		root.dataset.theme = value.theme;
+		root.dataset.density = value.density;
+		root.dataset.scheme = scheme;
+		const doc = document.getElementById("doc");
+		if (doc) {
+			doc.dataset.scheme = scheme;
+		}
+		document.dispatchEvent(new Event("board-theme"));
+	}, [value.theme, value.density, scheme]);
+	function change(next: Partial<Pick<typeof value, "closed" | "density" | "theme">>) {
+		const appearance = { closed: valueRef.current.closed, density: valueRef.current.density, theme: valueRef.current.theme, ...next };
+		let notice = "";
+		try {
+			localStorage.setItem(key, JSON.stringify(appearance));
+		} catch {
+			notice = "Preferences apply to this page only.";
+		}
+		valueRef.current = { ...appearance, notice };
+		setValue(valueRef.current);
+	}
+	return { ...value, change };
+}
+export type AppearanceControls = ReturnType<typeof useAppearance>;

package/src/client/react/useBoardNavigation.ts

@@ -0,0 +1,139 @@
+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 { pageQuery } from "#client/react/pageQuery.ts";
+import { readerLink } from "#client/react/readerLink.ts";
+import { readingEntry, readingHistory } from "#client/react/readingHistory.ts";
+import { captureReading } from "#client/react/readingState.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 = "";
+		function save() {
+			if (!displayed || document.getElementById("doc")?.dataset.route !== route) {
+				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 (sameReadingLocation({ hash, id: displayed, route }, { hash: location.hash, id, route: nextRoute })) {
+				return;
+			}
+			const reading = readings.get(id) ?? entry?.reading;
+			const focus = displayed !== "";
+			displayed = id;
+			route = nextRoute;
+			hash = location.hash;
+			if (shell.client) {
+				recordEntry(router, nextRoute, id);
+			}
+			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 && Number(document.getElementById("doc")?.dataset.status ?? 200) >= 400) {
+				const doc = document.getElementById("doc");
+				shell.registry.refresh(
+					pageQuery(
+						shell.api,
+						doc?.dataset.projection ?? "document",
+						target.pathname + target.search,
+						doc?.querySelector<HTMLElement>("[data-baseline]")?.dataset.baseline || null,
+					),
+				);
+				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) {
+	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,24 @@
+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>(atom: Atom.Atom<A>) {
+	const registry = useContext(RegistryContext);
+	useEffect(() => {
+		function refresh() {
+			const native = session(window);
+			if (!(document.hidden || native.registry.get(native.updates.paused))) {
+				registry.refresh(atom);
+			}
+		}
+		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, 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 type { MainLocation } from "./mainLocation.ts";
 export function useDocumentPage({
 	data,
 	pending,