@shivaedev/work-board 0.12.0 → 0.13.0

package/src/client/react/useFormFocus.ts

@@ -0,0 +1,46 @@
+import { Schema } from "effect";
+import { 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(() => {
+		const selection = ref.current && captureFocus(ref.current);
+		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(() => {
+		window.addEventListener("pagehide", remember);
+		return () => window.removeEventListener("pagehide", remember);
+	}, [remember]);
+	return { 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/useHistoryComparison.ts

@@ -0,0 +1,142 @@
+import { RegistryContext } from "@effect/atom-react";
+import { Option } from "effect";
+import { useContext, useEffect, useRef, useState } from "react";
+import { useQuery } from "@shivaedev/effect-react/result-state.ts";
+import { loadQuery } from "@shivaedev/effect-react/router.ts";
+import { session } from "#client/entry.ts";
+import { historyStore } from "./historyStore.ts";
+import type { ShellApi } from "./ShellApi.ts";
+export function useHistoryComparison(api: ShellApi) {
+	const registry = useContext(RegistryContext);
+	const [store] = useState(historyStore);
+	const [baseline, setBaseline] = useState(store.read);
+	const [isBusy, setIsBusy] = useState(false);
+	const [failure, setFailure] = useState(() => document.documentElement.dataset.historyNotice ?? "");
+	const controllerRef = useRef<AbortController | undefined>(undefined);
+	const generationRef = useRef(0);
+	const atom = api.history.query({ action: "compare", baseline });
+	const query = useQuery(atom);
+	const data = Option.getOrUndefined(query.data);
+	function cancel() {
+		generationRef.current += 1;
+		controllerRef.current?.abort();
+		setIsBusy(false);
+	}
+	function clear() {
+		delete document.documentElement.dataset.historyNotice;
+		cancel();
+		store.write(null);
+		setBaseline(null);
+		setFailure("");
+		registry.refresh(api.history.query({ action: "compare", baseline: null }));
+	}
+	useEffect(() => {
+		if (data?.discardBaseline && baseline === store.read()) {
+			store.write(null);
+			setBaseline(null);
+			setFailure(data.reason);
+		}
+	}, [baseline, data, store]);
+	useEffect(() => {
+		function refresh() {
+			const native = session(window);
+			if (!(document.hidden || native.registry.get(native.updates.paused) || isBusy)) {
+				registry.refresh(atom);
+			}
+		}
+		function sync(event: StorageEvent) {
+			if (event.key === store.key || event.key === null) {
+				generationRef.current += 1;
+				controllerRef.current?.abort();
+				setIsBusy(false);
+				setBaseline(store.read());
+				setFailure("");
+				refresh();
+			}
+		}
+		const timer = setInterval(refresh, 60_000);
+		document.addEventListener("board-updates-resumed", refresh);
+		document.addEventListener("visibilitychange", refresh);
+		window.addEventListener("storage", sync);
+		return () => {
+			clearInterval(timer);
+			document.removeEventListener("board-updates-resumed", refresh);
+			document.removeEventListener("visibilitychange", refresh);
+			window.removeEventListener("storage", sync);
+		};
+	}, [atom, isBusy, registry, store]);
+	useEffect(() => {
+		async function validate() {
+			const raw = store.read();
+			try {
+				const check = api.history.query({ action: "check", baseline: raw });
+				registry.refresh(check);
+				const result = await loadQuery(registry, check, { abortController: new AbortController() });
+				if (raw !== store.read()) {
+					return;
+				}
+				if (result.discardBaseline) {
+					store.write(null);
+					setBaseline(null);
+					setFailure(result.reason);
+				} else if (raw !== baseline) {
+					setBaseline(raw);
+					registry.refresh(api.history.query({ action: "compare", baseline: raw }));
+				}
+			} catch {
+				setFailure("History validation is unavailable. Your remembered snapshot is preserved.");
+			}
+		}
+		document.addEventListener("board-page", validate);
+		return () => document.removeEventListener("board-page", validate);
+	}, [api, baseline, registry, store]);
+	useEffect(() => {
+		function stop() {
+			generationRef.current += 1;
+			controllerRef.current?.abort();
+		}
+		window.addEventListener("pagehide", stop);
+		return () => {
+			stop();
+			window.removeEventListener("pagehide", stop);
+		};
+	}, []);
+	async function observe() {
+		if (isBusy) {
+			return;
+		}
+		generationRef.current += 1;
+		const mine = generationRef.current;
+		controllerRef.current?.abort();
+		controllerRef.current = new AbortController();
+		setIsBusy(true);
+		try {
+			const native = session(window);
+			const next = await native.run(native.api.history.run({ action: "observe", baseline }), controllerRef.current.signal);
+			if (mine !== generationRef.current) {
+				return;
+			}
+			if (next.snapshot === null) {
+				setFailure(next.reason);
+				return;
+			}
+			delete document.documentElement.dataset.historyNotice;
+			store.write(next.snapshot);
+			setBaseline(next.snapshot);
+			setFailure("");
+			registry.refresh(api.history.query({ action: "compare", baseline: next.snapshot }));
+		} catch {
+			if (mine === generationRef.current) {
+				setFailure("Could not remember the current observation. Your previous baseline is preserved.");
+			}
+		} finally {
+			if (mine === generationRef.current) {
+				setIsBusy(false);
+			}
+		}
+	}
+	const message = Option.isSome(query.cause)
+		? "History is unavailable: the current observation could not be loaded. No comparison or removals are inferred."
+		: failure;
+	return { atom, available: Option.isNone(query.cause), baseline, busy: isBusy, clear, message, notice: store.notice(), observe };
+}

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/useResponseForm.ts

@@ -0,0 +1,147 @@
+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 { responseReadiness, 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 [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(""),
+		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("") });
+			if (created.dirty) {
+				retainContext(form, created.created.value);
+			}
+		}
+		for (const name of ["answerContext", "answers", "author", "body", "id", "question", "recovery", "revision", "supersedes", "type"] as const) {
+			form.blur(name);
+		}
+	}, [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 bind() {
+		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);
+	}
+	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 showPreview() {
+		setOutcome(undefined);
+		bind();
+		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 clear() {
+		setOutcome(undefined);
+		created.revert();
+		setPreview(undefined);
+		setStatus("Draft cleared. Saved responses are unchanged.");
+	}
+	const valid = Schema.is(schema)(values);
+	const previewed = preview !== undefined && same && Equal.equals(preview, values);
+	const summary = responseSummary(values, prompts, answers(values));
+	return {
+		answers: answers(values),
+		clear,
+		created,
+		draft,
+		edit,
+		editAnswers,
+		form,
+		outcome,
+		preview: previewed ? responsePreview(values, source.id, prompts) : undefined,
+		recovery: recoveryText(recovery),
+		showPreview,
+		status: [stale ? sourceChanged() : "", outcome || status.startsWith("Draft cleared") ? status : summary || responseReadiness(valid, previewed)]
+			.filter(Boolean)
+			.join(" "),
+		valid,
+	};
+}

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/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";
+	}
+}