freezmo/components/homework/HomeworkScreen.tsx
Martin Dvorak 4369ba1a17 Native-feel pass: PWA integration, system back, offline, haptics, undo
Mobile only (<=639px / coarse pointers); desktop keeps its behaviour.

System integration
- Manifest: id, display_override, monochrome icon, Make my homework
  shortcut and a share target (text/URL via GET, files via POST).
  iOS startup images for the common iPhone sizes. Pinch-zoom is allowed
  again (double-tap zoom is disabled via touch-action instead).
- Share target: /share chooser with New deck / Make my homework; POSTed
  files wait in a 10-minute in-memory store, reach the wizard through
  sessionStorage and never touch disk.
- Web Share: Share rows for decks (JSON file where supported) and the
  homework result, with a clipboard fallback and a toast.
- Offline: a quiet pill appears and Freeze / mode cards are disabled
  with a clear reason; input is never lost (error cards keep Retry).
- State: wizard drafts (text, options, photos up to a size budget)
  survive reloads and OS kills and are cleared on success; re-tapping
  the active tab scrolls to the top; the deck page shows a skeleton
  instead of a spinner.

Navigation and gestures
- System Back closes the topmost layer first: a small history-entry
  stack (lib/use-back-close.ts) covers the drawer, Settings sheet,
  install sheet, deck actions panel and one wizard step; navigations
  are never rewound and stale entries are skipped.
- Destructive-but-reversible actions use Undo toasts: deleting a deck
  (no confirm) and removing a file in the wizard. Irreversible ones
  keep their confirm.

Input and feedback
- Every phone input got inputmode / enterkeyhint / autocomplete /
  autocapitalize / spellcheck; Enter on the last field advances the
  wizard; a clipboard-paste button appears where the API exists.
- Haptics behind a Settings toggle (on by default): tab switches,
  toggles, correct/wrong, completion; Vibration API + the iOS hidden
  switch tick, throttled and silent everywhere else.
- Wake lock during the study feed and homework guide, released on
  leave and re-acquired when the tab returns.

Verified: new native suite 35/35 (manifest/head/viewport, offline,
share target GET + POST, back-gesture layers, undo, share fallback,
tab re-tap, haptics persistence, draft restore), regression 74/74,
mobile 52/52, wizard 80/80, declutter 116/116, animation 8/8,
i18n 25/25. Lint + build clean. SW freezmo-v23.

Needs a real device (documented in the README): iOS haptic tick,
system share sheet entry, wake-lock grant, iPhone startup images,
iOS edge-swipe back, install prompts. Pull-to-refresh and the app
badge were skipped on purpose.
2026-10-10 12:16:03 +00:00

199 lines
6.9 KiB
TypeScript

"use client";
import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
import { documentsToText } from "@/lib/documents";
import { ApiError, generateHomework, type HomeworkProgress } from "@/lib/client-api";
import {
deleteHomework,
getHomework,
homeworkStore,
saveHomework,
sortHomework,
updateHomework,
type NewHomeworkResult,
} from "@/lib/homework";
import { useI18n } from "@/lib/i18n";
import type { HomeworkMode, HomeworkRecord } from "@/lib/schemas";
import { useNotesIntake } from "@/lib/use-notes-intake";
import { clearWizardDraft } from "@/lib/wizard-draft";
import { HomeworkGuide } from "./HomeworkGuide";
import { HomeworkInput } from "./HomeworkInput";
import { HomeworkLoading } from "./HomeworkLoading";
import { HomeworkResult } from "./HomeworkResult";
/** Photos + rendered PDF pages + images embedded in documents. */
const MAX_IMAGES_TO_SEND = 12;
const MAX_TEXT_TO_SEND = 100_000;
type View = { kind: "start" } | { kind: "loading" } | { kind: "record"; record: HomeworkRecord };
/** The /homework screen: give it an assignment, pick a mode, get a result. */
export function HomeworkScreen({ initialRecordId }: { initialRecordId?: string }) {
const { t } = useI18n();
const records = useSyncExternalStore(
homeworkStore.subscribe,
homeworkStore.getSnapshot,
homeworkStore.getServerSnapshot,
);
const history = useMemo(() => sortHomework(records), [records]);
const intake = useNotesIntake({
tooManyPhotosKey: "homework.source.tooManyPhotos",
tooManyDocsKey: "homework.source.tooManyDocs",
});
const [mode, setMode] = useState<HomeworkMode>("make");
const [text, setText] = useState("");
const [view, setView] = useState<View>({ kind: "start" });
const [progress, setProgress] = useState<HomeworkProgress>({ stage: "vision", message: "" });
const [error, setError] = useState<{ message: string; kind?: string } | null>(null);
const [againLoading, setAgainLoading] = useState(false);
const abortRef = useRef<AbortController | null>(null);
// Deep link from the library's Homework tab: open the saved result directly.
useEffect(() => {
if (!initialRecordId) return;
const record = getHomework(initialRecordId);
if (record) setView({ kind: "record", record });
}, [initialRecordId]);
/** Everything the API needs, built from the current input. */
const buildPayload = (modeValue: HomeworkMode) => {
const readyDocuments = intake.documents.filter((entry) => entry.status === "ready" && entry.extracted);
const documentImages = readyDocuments.flatMap((entry) => entry.extracted!.images);
const documentText = documentsToText(readyDocuments.map((entry) => entry.extracted!));
const mergedText = [text.trim(), documentText.trim()].filter(Boolean).join("\n\n").slice(0, MAX_TEXT_TO_SEND);
const images = [
...intake.images.map((image) => image.dataUrl),
...documentImages.map((image) => image.dataUrl),
].slice(0, MAX_IMAGES_TO_SEND);
return { mode: modeValue, images, text: mergedText };
};
const run = useCallback(
async (input: { mode: HomeworkMode; images: string[]; text: string; recordId?: string }) => {
setError(null);
setView({ kind: "loading" });
const vision = input.images.length > 0;
setProgress({
stage: vision ? "vision" : "generation",
message: vision
? t("homework.loading.reading")
: input.mode === "make"
? t("homework.loading.writing")
: t("homework.loading.planning"),
});
const controller = new AbortController();
abortRef.current = controller;
try {
const { homework } = await generateHomework(
{
mode: input.mode,
images: input.images.length > 0 ? input.images : undefined,
text: input.text || undefined,
},
{ onProgress: setProgress, signal: controller.signal },
);
// The server hands back the assignment as text (the transcription when
// photos were used), so “Make it again” works without the files.
const sourceText = homework.sourceText ?? input.text;
const result: NewHomeworkResult =
homework.mode === "make"
? {
mode: "make",
title: homework.title,
language: homework.language,
sourceText,
answer: homework.answer,
}
: {
mode: "guide",
title: homework.title,
language: homework.language,
sourceText,
steps: homework.steps,
};
const record = input.recordId ? updateHomework(input.recordId, result) : saveHomework(result);
if (!record) throw new ApiError(t("homework.error.body"), "bad_response");
setView({ kind: "record", record });
} catch (generateError) {
if (generateError instanceof ApiError && generateError.kind === "aborted") {
setView({ kind: "start" });
return;
}
setError({
message: generateError instanceof ApiError ? generateError.message : t("homework.error.body"),
kind: generateError instanceof ApiError ? generateError.kind : undefined,
});
setView({ kind: "start" });
} finally {
abortRef.current = null;
setAgainLoading(false);
}
},
[t],
);
/** `modeOverride` lets the phone flow start straight from a tapped mode card. */
const submit = (modeOverride?: HomeworkMode) => {
const payload = buildPayload(modeOverride ?? mode);
void run(payload);
};
/** Re-run from the stored assignment text (files were never stored). */
const again = (record: HomeworkRecord) => {
setAgainLoading(true);
void run({ mode: record.mode, images: [], text: record.sourceText, recordId: record.id });
};
const newAssignment = () => {
intake.clear();
setText("");
setError(null);
clearWizardDraft("homework");
setView({ kind: "start" });
};
if (view.kind === "loading") {
return <HomeworkLoading progress={progress} mode={mode} onCancel={() => abortRef.current?.abort()} />;
}
if (view.kind === "record") {
return view.record.mode === "make" ? (
<HomeworkResult
record={view.record}
onAgain={() => again(view.record)}
onNew={newAssignment}
againLoading={againLoading}
/>
) : (
<HomeworkGuide
record={view.record}
onClose={() => setView({ kind: "start" })}
onAgain={() => again(view.record)}
onNew={newAssignment}
againLoading={againLoading}
/>
);
}
return (
<HomeworkInput
mode={mode}
onModeChange={setMode}
text={text}
onTextChange={setText}
intake={intake}
onSubmit={submit}
error={error}
history={history}
onOpen={(record) => setView({ kind: "record", record })}
onDelete={deleteHomework}
/>
);
}