app/kb/step-marks.mjs

Functions

Imports

It imports app/kb/procedures/marks.mjs. Imported by app/components/admin/kb-step-text.tsx.

Source

1// A step's words as the form editor shows them (docs/KNOWLEDGE-BASE.md): plain text, and each mark as a chip, as
2// protocols.io shows a step's components. A chip keeps the exact text it was read from, so joining the pieces gives the
3// step back byte for byte; an edited chip is written in the procedure format's own spelling (docs/PROCEDURES.md).
4// Pure and small, so the browser can carry it.
5
6import { markSpans, parseQuantity, TEMPERATURE } from "./procedures/marks.mjs";
7
8/**
9 * @typedef {{ kind: "text", raw: string }
10 *   | { kind: "reagent", raw: string, name: string, shown: string, amount: string, unit: string, fixed: boolean, braced: boolean }
11 *   | { kind: "equipment", raw: string, name: string, shown: string, braced: boolean }
12 *   | { kind: "timer", raw: string, label: string, amount: string, unit: string }
13 *   | { kind: "temperature", raw: string, low: string, high: string }} Piece
14 */
15
16/** A temperature's numbers from its words: "37 °C", "55 to 60 °C". @param {string} raw */
17function readTemperature(raw) {
18  const m = /^(-?\d+(?:\.\d+)?)(?:\s*(?:to|-)\s*(-?\d+(?:\.\d+)?))?\s*°C$/.exec(raw);
19  return { low: m?.[1] ?? "", high: m?.[2] ?? "" };
20}
21
22/** The temperatures in a stretch of plain words, as pieces. @param {string} text @returns {Piece[]} */
23function splitTemperatures(text) {
24  /** @type {Piece[]} */
25  const out = [];
26  let last = 0;
27  for (const m of text.matchAll(new RegExp(TEMPERATURE.source, "g"))) {
28    if (m.index > last) out.push({ kind: "text", raw: text.slice(last, m.index) });
29    out.push({ kind: "temperature", raw: m[0], ...readTemperature(m[0]) });
30    last = m.index + m[0].length;
31  }
32  if (text.length > last) out.push({ kind: "text", raw: text.slice(last) });
33  return out;
34}
35
36/**
37 * A step's text as pieces: its words, and a chip for each mark and each temperature. pieces.map(p => p.raw).join("") is
38 * the text.
39 *
40 * @param {string} text
41 * @returns {Piece[]}
42 */
43export function stepPieces(text) {
44  /** @type {Piece[]} */
45  const out = [];
46  let last = 0;
47  for (const span of markSpans(text)) {
48    if (span.start > last) out.push(...splitTemperatures(text.slice(last, span.start)));
49    const raw = text.slice(span.start, span.end);
50    const q = parseQuantity(span.braces ?? "");
51    if (span.sign === "~") out.push({ kind: "timer", raw, label: span.name, amount: q?.amount ?? "", unit: q?.unit ?? "" });
52    else if (span.sign === "@") out.push({ kind: "reagent", raw, name: span.name, shown: span.shown, amount: q?.amount ?? "", unit: q?.unit ?? "", fixed: q?.fixed ?? false, braced: span.braces !== null });
53    else out.push({ kind: "equipment", raw, name: span.name, shown: span.shown, braced: span.braces !== null });
54    last = span.end;
55  }
56  if (text.length > last) out.push(...splitTemperatures(text.slice(last)));
57  return out;
58}
59
60/**
61 * A chip written in the procedure format's spelling: `@name|shown{=amount%unit}`, `#name{}`, `~label{amount%unit}`,
62 * `55 to 60 °C`.
63 *
64 * @param {Piece} piece
65 * @returns {string}
66 */
67export function writePiece(piece) {
68  const quantity = (/** @type {string} */ amount, /** @type {string} */ unit, fixed = false) =>
69    amount.trim() ? `${fixed ? "=" : ""}${amount.trim()}${unit.trim() ? `%${unit.trim()}` : ""}` : "";
70  // A one-word mark written without braces (`#microcentrifuge`) stays that way while it still is one word.
71  const single = (/** @type {{ name: string, shown: string, braced: boolean }} */ p) => !p.braced && !p.shown.trim() && /^[^\s{}|]+$/.test(p.name.trim());
72  switch (piece.kind) {
73    case "text":
74      return piece.raw;
75    case "reagent":
76      if (single(piece) && !piece.amount.trim()) return `@${piece.name.trim()}`;
77      return `@${piece.name.trim()}${piece.shown.trim() ? `|${piece.shown.trim()}` : ""}{${quantity(piece.amount, piece.unit, piece.fixed)}}`;
78    case "equipment":
79      if (single(piece)) return `#${piece.name.trim()}`;
80      return `#${piece.name.trim()}${piece.shown.trim() ? `|${piece.shown.trim()}` : ""}{}`;
81    case "timer":
82      return `~${piece.label.trim()}{${quantity(piece.amount, piece.unit)}}`;
83    case "temperature":
84      return piece.high.trim() ? `${piece.low.trim()} to ${piece.high.trim()} °C` : `${piece.low.trim()} °C`;
85  }
86}
87
88/**
89 * What a chip says on the page, in words: "20 µl zinc chloride", "microcentrifuge tubes", "5 minutes", "55 to 60 °C".
90 *
91 * @param {Piece} piece
92 */
93export function pieceLabel(piece) {
94  const amount = (/** @type {string} */ a, /** @type {string} */ u) => [a.trim(), u.trim()].filter(Boolean).join(" ");
95  switch (piece.kind) {
96    case "text":
97      return piece.raw;
98    case "reagent":
99      return [amount(piece.amount, piece.unit), piece.shown || piece.name].filter(Boolean).join(" ");
100    case "equipment":
101      return piece.shown || piece.name;
102    case "timer":
103      return [piece.label, amount(piece.amount, piece.unit)].filter(Boolean).join(": ") || "timer";
104    case "temperature":
105      return piece.raw;
106  }
107}
108
109/** What each kind of chip is called, for its button's name and its popover's title. */
110export const PIECE_NAMES = Object.freeze({ reagent: "Reagent", equipment: "Equipment", timer: "Timer", temperature: "Temperature" });