app/enhance/run.ts

Functions

Imports

It imports app/kb/procedures/run.mjs. No module of this repo imports it.

Source

1import {
2  clock,
3  finishRun,
4  newRun,
5  parseRun,
6  pauseTimer,
7  resetTimer,
8  runMarkdown,
9  runProgress,
10  runRecord,
11  setNote,
12  setRunNote,
13  setScale,
14  shownStep,
15  startTimer,
16  stepBeside,
17  tickTimers,
18  timerKey,
19  timerMs,
20  timerRemaining,
21  toggleDone,
22  type Run,
23  type StepTimer,
24} from "~/kb/procedures/run.mjs";
25
26/*
27 * Run mode (docs/PROCEDURES.md): a procedure page, worked at the bench. The page is complete as served; this adds,
28 * for a person who starts a run, a checklist over the steps it already has: a Done check, a note and the stored
29 * timers on each step, the critical and pause flags kept in view, the scale changed in place, and a record that
30 * downloads or prints. The run lives in this browser only (localStorage), and says so if it cannot even do that.
31 *
32 * One step at a time (docs/KNOWLEDGE-BASE.md, R4, the cook view) is a presentation of the same run: only the step being worked
33 * shows, in large type, with its timers and its Done check, and Previous and Next move through the steps. The screen is kept on
34 * as for any run. The choice is remembered in this browser.
35 *
36 * The server stays the one place amounts are computed: a new scale is fetched as the page at that scale and the
37 * materials table and each step's words are swapped in, so nothing here knows a unit conversion. If that fetch
38 * fails the browser navigates to the scaled page, which is what the Scale button does with no script.
39 */
40
41const root = document.querySelector<HTMLElement>(".procedure[data-run-path]");
42if (!root) throw new Error("run: this page has no .procedure[data-run-path] to run");
43const procedure = {
44  path: root.dataset.runPath ?? "",
45  version: root.dataset.runVersion ?? "",
46  title: root.dataset.runTitle ?? "",
47};
48const KEY = `dustinedwards.run:${procedure.path}`;
49const stepItems = Array.from(root.querySelectorAll<HTMLElement>("li.procedure-step[data-step]"));
50if (stepItems.length === 0) throw new Error("run: this procedure has no steps to run");
51// A step is addressed by its section and its number: numbering restarts in a section that starts its own list, so the
52// number alone is not unique ("step 1" is in two places in a procedure with a second method).
53const sectionOf = (li: HTMLElement) => li.closest("section[aria-labelledby]")?.getAttribute("aria-labelledby") ?? "";
54const keyOf = (li: HTMLElement) => `${sectionOf(li)}.${li.dataset.step}`;
55const stepKeys = stepItems.map(keyOf);
56// Where each timer's alert says the step is: its printed number.
57const timerStep = new Map<string, string>();
58const scaleForm = root.querySelector<HTMLFormElement>("form.procedure-scale");
59const scaleField = scaleForm?.querySelector<HTMLInputElement>("input[name]") ?? null;
60
61let run: Run | null = null;
62// One step at a time: whether it is on, remembered in this browser, and which step it shows.
63const VIEW_KEY = `${KEY}:view`;
64let oneAtATime = (() => {
65  try {
66    return localStorage.getItem(VIEW_KEY) === "step";
67  } catch {
68    return false;
69  }
70})();
71let shownKey: string | null = null;
72let storageNote = "";
73let wakeLock: WakeLockSentinel | null = null;
74let audio: AudioContext | null = null;
75let ticker: number | undefined;
76
77// appendChild and insertBefore, not append, before and after: this project also compiles against the Worker's
78// own DOM-like types, which type those three for a different purpose.
79const add = (parent: Node, ...kids: Array<Node | string>) => {
80  for (const kid of kids) parent.appendChild(typeof kid === "string" ? document.createTextNode(kid) : kid);
81};
82const placeBefore = (ref: Node, ...kids: Node[]) => {
83  for (const kid of kids) ref.parentNode?.insertBefore(kid, ref);
84};
85const placeAfter = (ref: Node, ...kids: Node[]) => {
86  let at: Node = ref;
87  for (const kid of kids) {
88    ref.parentNode?.insertBefore(kid, at.nextSibling);
89    at = kid;
90  }
91};
92const el = <K extends keyof HTMLElementTagNameMap>(tag: K, props: Record<string, string> = {}, ...kids: Array<Node | string>) => {
93  const node = document.createElement(tag);
94  for (const [k, v] of Object.entries(props)) node.setAttribute(k, v);
95  add(node, ...kids);
96  return node;
97};
98const button = (label: string, className: string, onClick: () => void) => {
99  const b = el("button", { type: "button", class: className }, label);
100  b.addEventListener("click", onClick);
101  return b;
102};
103const stepText = (li: HTMLElement) => li.querySelector(".procedure-step-text")?.textContent?.replace(/\s+/g, " ").trim() ?? "";
104const sectionTitle = (li: HTMLElement) => {
105  const id = li.closest("section[aria-labelledby]")?.getAttribute("aria-labelledby");
106  return (id ? document.getElementById(id)?.textContent : "")?.replace(/\s+/g, " ").trim() ?? "";
107};
108const stepRecords = () => stepItems.map((li) => ({ key: keyOf(li), number: Number(li.dataset.step), section: sectionTitle(li), text: stepText(li) }));
109
110// ---------------------------------------------------------------- storage
111
112function load(): Run | null {
113  try {
114    const stored = parseRun(localStorage.getItem(KEY));
115    return stored && stored.path === procedure.path ? stored : null;
116  } catch (error) {
117    storageNote = `This run cannot be saved on this device (${error instanceof Error ? error.message : "storage is blocked"}). Download the record before you leave.`;
118    return null;
119  }
120}
121
122function save() {
123  if (!run) return;
124  try {
125    localStorage.setItem(KEY, JSON.stringify(run));
126    storageNote = "";
127  } catch (error) {
128    storageNote = `This run cannot be saved on this device (${error instanceof Error ? error.message : "storage is full"}). Download the record before you leave.`;
129  }
130  renderBar();
131}
132
133function update(next: Run) {
134  run = next;
135  save();
136}
137
138// ---------------------------------------------------------------- the bar and the live regions
139
140const live = el("div", { class: "run-live", role: "status", "aria-live": "polite" });
141const alertRegion = el("div", { class: "run-alert", role: "alert" });
142const bar = el("section", { class: "run-bar", "aria-label": "Run", hidden: "" });
143const start = el("button", { type: "button", class: "run-start" }, "Run this procedure");
144const summary = el("section", { class: "run-summary", "aria-labelledby": "run-summary-h", hidden: "" });
145
146function say(message: string) {
147  live.textContent = "";
148  window.setTimeout(() => (live.textContent = message), 30);
149}
150
151function renderBar() {
152  if (!run) return;
153  const { done, total } = runProgress(run, stepKeys);
154  const current = stepItems.find((li) => !run?.steps[keyOf(li)]?.done);
155  const toggle = button(oneAtATime ? "Show every step" : "One step at a time", "run-view", () => setView(!oneAtATime));
156  toggle.setAttribute("aria-pressed", String(oneAtATime));
157  if (oneAtATime) {
158    shownKey = shownStep(run, stepKeys, shownKey);
159    const shown = stepItems[stepKeys.indexOf(shownKey ?? "")];
160    const before = shownKey ? stepBeside(stepKeys, shownKey, -1) : null;
161    const after = shownKey ? stepBeside(stepKeys, shownKey, 1) : null;
162    const prev = button("Previous step", "run-prev", () => before && showStep(before));
163    const next = button("Next step", "run-step-next", () => after && showStep(after));
164    if (!before) prev.setAttribute("disabled", "");
165    if (!after) next.setAttribute("disabled", "");
166    bar.replaceChildren(
167      el("p", { class: "run-progress" }, `Step ${shown?.dataset.step ?? ""}, ${stepKeys.indexOf(shownKey ?? "") + 1} of ${total}; ${done} done`),
168      prev,
169      next,
170      toggle,
171      button("Finish run", "run-finish", finish),
172      button("Stop", "run-stop", stop),
173    );
174  } else {
175    bar.replaceChildren(
176      el("p", { class: "run-progress" }, `${done} of ${total} steps done`),
177      current ? button(`Go to step ${current.dataset.step}`, "run-next", () => focusStep(current)) : el("span", { class: "run-all" }, "Every step is done."),
178      toggle,
179      button("Finish run", "run-finish", finish),
180      button("Stop", "run-stop", stop),
181    );
182  }
183  applyView();
184  if (storageNote) add(bar, el("p", { class: "run-warning", role: "note" }, storageNote));
185  for (const li of stepItems) {
186    const isCurrent = li === current;
187    if (isCurrent) li.setAttribute("aria-current", "step");
188    else li.removeAttribute("aria-current");
189    li.classList.toggle("run-step-done", run.steps[keyOf(li)]?.done === true);
190  }
191}
192
193/** Shows the page as one step at a time, or every step, as the toggle says. */
194function applyView() {
195  if (oneAtATime && run) root!.dataset.view = "step";
196  else delete root!.dataset.view;
197  for (const li of stepItems) li.classList.toggle("run-step-shown", oneAtATime && keyOf(li) === shownKey);
198}
199
200function setView(on: boolean) {
201  oneAtATime = on;
202  try {
203    if (on) localStorage.setItem(VIEW_KEY, "step");
204    else localStorage.removeItem(VIEW_KEY);
205  } catch {
206    // Not remembered on this device; the view still changes for this visit.
207  }
208  renderBar();
209  const li = stepItems[stepKeys.indexOf(shownStep(run!, stepKeys, shownKey) ?? "")];
210  if (li) focusStep(li);
211  say(on ? "One step at a time." : "Every step shown.");
212}
213
214function showStep(key: string) {
215  shownKey = key;
216  renderBar();
217  const li = stepItems[stepKeys.indexOf(key)];
218  if (li) {
219    focusStep(li);
220    say(`Step ${li.dataset.step}.`);
221  }
222}
223
224function focusStep(li: HTMLElement) {
225  li.scrollIntoView({ block: "center", behavior: window.matchMedia("(prefers-reduced-motion: reduce)").matches ? "auto" : "smooth" });
226  li.querySelector<HTMLElement>(".run-done-check")?.focus({ preventScroll: true });
227}
228
229// ---------------------------------------------------------------- a step's tools
230
231function timerButton(li: HTMLElement, step: number, index: number, timer: StepTimer): HTMLElement {
232  const key = timerKey(keyOf(li), index);
233  timerStep.set(key, String(step));
234  const ms = timerMs(timer);
235  const box = el("div", { class: "run-timer", "data-timer": key });
236  if (ms === null) {
237    add(box, el("span", { class: "run-timer-text" }, `${timer.text} (not a timer I can run)`));
238    return box;
239  }
240  const clockEl = el("span", { class: "run-clock", role: "timer" }, "");
241  const act = el("button", { type: "button", class: "run-timer-act" });
242  const reset = el("button", { type: "button", class: "run-timer-reset" }, "Reset");
243  const label = timer.label ? `${timer.label}, ${timer.text}` : timer.text;
244  const draw = () => {
245    if (!run) return;
246    const t = run.timers[key];
247    const remaining = timerRemaining(run, key, Date.now());
248    box.dataset.state = t?.state ?? "idle";
249    clockEl.textContent = remaining === null ? clock(ms) : clock(remaining);
250    act.textContent = !t ? `Start ${label}` : t.state === "running" ? "Pause" : t.state === "paused" ? "Resume" : "Done: start again";
251    act.setAttribute("aria-label", !t ? `Start timer for step ${step}: ${label}` : t.state === "running" ? `Pause the timer for step ${step}` : t.state === "paused" ? `Resume the timer for step ${step}` : `The timer for step ${step} finished; start it again`);
252    reset.hidden = !t;
253  };
254  act.addEventListener("click", () => {
255    if (!run) return;
256    const t = run.timers[key];
257    ensureAudio();
258    if (t?.state === "running") update(pauseTimer(run, key, Date.now()));
259    else if (t?.state === "done") update(startTimer(resetTimer(run, key), key, ms, Date.now()));
260    else update(startTimer(run, key, ms, Date.now()));
261    drawAllTimers();
262    startTicker();
263  });
264  reset.addEventListener("click", () => {
265    if (run) update(resetTimer(run, key));
266    drawAllTimers();
267  });
268  add(box, clockEl, act, reset);
269  (box as HTMLElement & { draw?: () => void }).draw = draw;
270  draw();
271  return box;
272}
273
274function drawAllTimers() {
275  for (const box of root!.querySelectorAll<HTMLElement & { draw?: () => void }>(".run-timer")) box.draw?.();
276}
277
278function buildTools(li: HTMLElement) {
279  const step = Number(li.dataset.step);
280  const key = keyOf(li);
281  const timers: StepTimer[] = li.dataset.timers ? JSON.parse(li.dataset.timers) : [];
282  const done = el("input", { type: "checkbox", class: "run-done-check", id: `run-done-${key}` }) as HTMLInputElement;
283  done.checked = run?.steps[key]?.done === true;
284  done.addEventListener("change", () => {
285    if (!run) return;
286    update(toggleDone(run, key, Date.now()));
287    say(done.checked ? `Step ${step} done.` : `Step ${step} not done.`);
288  });
289  const note = el("textarea", { class: "run-note-text", rows: "2", id: `run-note-${key}`, maxlength: "2000", "aria-label": `Note for step ${step}` }) as HTMLTextAreaElement;
290  note.value = run?.steps[key]?.note ?? "";
291  let pending: number | undefined;
292  note.addEventListener("input", () => {
293    window.clearTimeout(pending);
294    pending = window.setTimeout(() => run && update(setNote(run, key, note.value)), 400);
295  });
296  note.addEventListener("blur", () => {
297    window.clearTimeout(pending);
298    if (run) update(setNote(run, key, note.value));
299  });
300  const tools = el(
301    "div",
302    { class: "run-tools" },
303    el("label", { class: "run-done", for: done.id }, done, el("span", {}, `Step ${step} done`)),
304    ...timers.map((t, i) => timerButton(li, step, i, t)),
305    el("details", { class: "run-note" }, el("summary", {}, note.value.trim() ? "Note (written)" : "Add a note"), note),
306  );
307  const text = li.querySelector(".procedure-step-text");
308  if (text) placeAfter(text, tools);
309}
310
311function removeTools() {
312  for (const tools of root!.querySelectorAll(".run-tools")) tools.remove();
313  for (const li of stepItems) {
314    li.removeAttribute("aria-current");
315    li.classList.remove("run-step-done");
316  }
317}
318
319// ---------------------------------------------------------------- timers ring
320
321function ensureAudio() {
322  try {
323    audio ??= new AudioContext();
324    if (audio.state === "suspended") void audio.resume();
325  } catch {
326    audio = null;
327  }
328}
329
330function beep() {
331  if (!audio) return;
332  const osc = audio.createOscillator();
333  const gain = audio.createGain();
334  gain.gain.value = 0.15;
335  osc.frequency.value = 880;
336  osc.connect(gain).connect(audio.destination);
337  osc.start();
338  osc.stop(audio.currentTime + 0.35);
339}
340
341function tick() {
342  if (!run) return;
343  const { run: next, rang } = tickTimers(run, Date.now());
344  if (rang.length > 0) {
345    update(next);
346    for (const key of rang) {
347      const step = timerStep.get(key) ?? "";
348      alertRegion.textContent = `The timer for step ${step} has finished.`;
349      document.title = `Timer done, step ${step}: ${procedure.title}`;
350      navigator.vibrate?.([220, 100, 220]);
351      beep();
352    }
353  }
354  drawAllTimers();
355  if (!Object.values(run.timers).some((t) => t.state === "running")) {
356    window.clearInterval(ticker);
357    ticker = undefined;
358  }
359}
360
361function startTicker() {
362  if (ticker === undefined) ticker = window.setInterval(tick, 500);
363}
364
365// ---------------------------------------------------------------- the screen stays on
366
367async function keepAwake() {
368  try {
369    wakeLock = (await navigator.wakeLock?.request("screen")) ?? null;
370  } catch {
371    // Not every browser lets a page hold the screen. Said, not hidden: the bar tells the person.
372    wakeLock = null;
373    add(bar, el("p", { class: "run-warning", role: "note" }, "This browser would not keep the screen on; it may sleep between steps."));
374  }
375}
376
377async function letSleep() {
378  try {
379    await wakeLock?.release();
380  } catch {
381    // Already released by the browser: nothing to undo.
382  }
383  wakeLock = null;
384}
385
386document.addEventListener("visibilitychange", () => {
387  if (document.visibilityState === "visible" && run && !run.finishedAt) {
388    void keepAwake();
389    tick();
390  }
391});
392
393// ---------------------------------------------------------------- the scale, changed in place
394
395async function applyScale(href: string, focus = false) {
396  try {
397    const res = await fetch(href, { headers: { Accept: "text/html" }, credentials: "same-origin" });
398    if (!res.ok) throw new Error(`run: ${href} answered ${res.status}`);
399    const doc = new DOMParser().parseFromString(await res.text(), "text/html");
400    const next = doc.querySelector<HTMLElement>(".procedure[data-run-path]");
401    if (!next) throw new Error(`run: ${href} is not a procedure page`);
402    const table = root!.querySelector('[data-run-swap="materials"]');
403    const nextTable = next.querySelector('[data-run-swap="materials"]');
404    if (table && nextTable) table.innerHTML = nextTable.innerHTML;
405    for (const li of stepItems) {
406      const mine = li.querySelector('[data-run-swap="step"]');
407      const theirs = next.querySelector(`li[data-step="${li.dataset.step}"] [data-run-swap="step"]`);
408      if (mine && theirs) mine.innerHTML = theirs.innerHTML;
409      // A recipe step's own ingredient line carries the same amounts.
410      const mineList = li.querySelector(".procedure-step-ingredients");
411      const theirList = next.querySelector(`li[data-step="${li.dataset.step}"] .procedure-step-ingredients`);
412      if (mineList && theirList) mineList.innerHTML = theirList.innerHTML;
413    }
414    // So does a recipe's mise-en-place.
415    const mise = root!.querySelector(".procedure-mise");
416    const nextMise = next.querySelector(".procedure-mise");
417    if (mise && nextMise) mise.innerHTML = nextMise.innerHTML;
418    const nextField = next.querySelector<HTMLInputElement>("form.procedure-scale input[name]");
419    if (nextField && scaleField) scaleField.value = nextField.defaultValue;
420    history.replaceState(history.state, "", href);
421    if (run && nextField) update(setScale(run, Number(nextField.defaultValue)));
422    if (focus) say(`Amounts now for ${nextField?.defaultValue ?? "the new scale"}.`);
423  } catch (error) {
424    console.error(error);
425    location.assign(href);
426  }
427}
428
429scaleForm?.addEventListener("submit", (e) => {
430  if (!run || !scaleField) return;
431  e.preventDefault();
432  // Every field of the form, as its GET would send them: the scale, and a recipe's units beside it.
433  const url = new URL(scaleForm.action, location.href);
434  for (const [name, value] of new FormData(scaleForm)) if (typeof value === "string" && value !== "") url.searchParams.set(name, value);
435  void applyScale(`${url.pathname}${url.search}`, true);
436});
437
438// ---------------------------------------------------------------- start, finish, stop
439
440function begin(existing: Run | null) {
441  run = existing ?? newRun({ ...procedure, scale: scaleField ? Number(scaleField.value) : null }, Date.now());
442  root!.dataset.run = "on";
443  start.hidden = true;
444  bar.hidden = false;
445  summary.hidden = true;
446  removeTools();
447  for (const li of stepItems) buildTools(li);
448  save();
449  renderBar();
450  drawAllTimers();
451  if (Object.values(run.timers).some((t) => t.state === "running")) startTicker();
452  void keepAwake();
453  say(existing ? "Run resumed." : "Run started.");
454  const stored = run.scale;
455  if (stored !== null && scaleField && Number(scaleField.value) !== stored && scaleForm) {
456    const url = new URL(scaleForm.action, location.href);
457    url.searchParams.set(scaleField.name, String(stored));
458    void applyScale(`${url.pathname}${url.search}`);
459  }
460}
461
462function stop() {
463  const confirmRow = el(
464    "p",
465    { class: "run-confirm", role: "alert" },
466    "Discard this run and its notes? ",
467    button("Discard it", "run-discard", () => {
468      try {
469        localStorage.removeItem(KEY);
470      } catch {
471        // Nothing was saved, so nothing to remove.
472      }
473      run = null;
474      end();
475    }),
476    button("Keep going", "run-keep", () => {
477      confirmRow.remove();
478    }),
479  );
480  add(bar, confirmRow);
481}
482
483function end() {
484  window.clearInterval(ticker);
485  ticker = undefined;
486  void letSleep();
487  removeTools();
488  delete root!.dataset.run;
489  delete root!.dataset.view;
490  shownKey = null;
491  for (const li of stepItems) li.classList.remove("run-step-shown");
492  bar.hidden = true;
493  summary.hidden = true;
494  start.hidden = false;
495  start.textContent = "Run this procedure";
496}
497
498function download(name: string, text: string, type: string) {
499  const url = URL.createObjectURL(new Blob([text], { type }));
500  const a = el("a", { href: url, download: name });
501  add(document.body, a);
502  a.click();
503  a.remove();
504  URL.revokeObjectURL(url);
505}
506
507function finish() {
508  if (!run) return;
509  update(finishRun(run, Date.now()));
510  void letSleep();
511  const current = run;
512  const slug = procedure.path.split("/").pop() ?? "run";
513  const stamp = new Date(current.finishedAt ?? Date.now()).toISOString().slice(0, 10);
514  const runNote = el("textarea", { class: "run-note-text", rows: "3", id: "run-summary-note", "aria-label": "Note on the whole run", maxlength: "4000" }) as HTMLTextAreaElement;
515  runNote.value = current.note;
516  runNote.addEventListener("input", () => run && update(setRunNote(run, runNote.value)));
517  const { done, total } = runProgress(current, stepKeys);
518  summary.replaceChildren(
519    el("h2", { id: "run-summary-h" }, "Run record"),
520    el("p", {}, `${done} of ${total} steps done${current.scale !== null ? `, at scale ${current.scale}` : ""}. Saved on this device only; nothing was sent anywhere.`),
521    el("label", { for: runNote.id }, "Note on the whole run"),
522    runNote,
523    el(
524      "p",
525      { class: "run-actions" },
526      button("Download as text", "run-download", () => run && download(`${slug}-${stamp}.md`, runMarkdown(run, stepRecords()), "text/markdown")),
527      button("Download as JSON", "run-download", () => run && download(`${slug}-${stamp}.json`, `${JSON.stringify(runRecord(run, stepRecords(), location.origin), null, 2)}\n`, "application/json")),
528      button("Print", "run-print", () => window.print()),
529      button("Start over", "run-again", () => {
530        try {
531          localStorage.removeItem(KEY);
532        } catch {
533          // Nothing was saved, so nothing to remove.
534        }
535        run = null;
536        end();
537      }),
538    ),
539  );
540  summary.hidden = false;
541  summary.scrollIntoView({ block: "start" });
542  say("Run finished. The record is ready to download or print.");
543}
544
545// ---------------------------------------------------------------- mount
546
547const links = root.querySelector(".procedure-links");
548start.addEventListener("click", () => begin(load()));
549add(links ?? root, start);
550placeBefore(root, live, alertRegion);
551placeAfter(root, bar, summary);
552
553const existing = load();
554if (existing && !existing.finishedAt) {
555  const { done, total } = runProgress(existing, stepKeys);
556  start.textContent = `Resume your run (${done} of ${total} done)`;
557} else if (storageNote) {
558  placeAfter(start, el("span", { class: "run-warning", role: "note" }, storageNote));
559}