app/kb/procedures/marks.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/components/procedure-materials.tsx, app/kb/procedures/json-ld.mjs, app/kb/procedures/parse.mjs, app/kb/procedures/recipe-views.mjs, app/kb/procedures/render.mjs, app/kb/step-marks.mjs.

Source

1// The inline marks a procedure step carries, in Cooklang's syntax (https://cooklang.org/docs/spec/):
2// `@material{20%µl}`, `#equipment{}`, `~{10%minutes}`, plus the cooklang-rs alias form
3// `@material|shown words{20%µl}` and its fixed-amount form `{=20%µl}`. The official parser
4// (@cooklang/cooklang) is a pre-1.0 WASM build whose model is recipes only, so the site reads the marks
5// itself and keeps Cooklang's spelling, so a file stays readable by Cooklang tools.
6//
7// Temperatures and spin speeds are read from the words, not marked, so a step stays the sentence a
8// person wrote: "Incubate at 55 to 60 °C" is both.
9
10/** A mark starts at the start of the text or after whitespace, so `(#refs)` and `a@b.c` are text. */
11const MARK_START = /[@#~]/g;
12
13/** A multi-word name runs to its `{`; it cannot cross another mark, a brace or a line. */
14const BRACED = /^([@#])([^@#~{}\n]{1,160}?)\{([^{}\n]*)\}/u;
15const SINGLE = /^([@#])([\p{L}\p{N}_-]+)/u;
16const TIMER = /^~([^@#~{}\n]{0,60}?)\{([^{}\n]*)\}/u;
17
18/**
19 * Stretches of the text where a mark is never read: inline code, a link's target, an autolink.
20 *
21 * @param {string} text
22 * @returns {Array<[number, number]>}
23 */
24function protectedRanges(text) {
25  /** @type {Array<[number, number]>} */
26  const ranges = [];
27  for (const pattern of [/`[^`\n]*`/g, /\]\([^)\n]*\)/g, /<[a-z]+:[^>\n]*>/gi]) {
28    for (const match of text.matchAll(pattern)) ranges.push([match.index, match.index + match[0].length]);
29  }
30  return ranges;
31}
32
33/**
34 * A number as written: "20", "1.25", "10,000", "1/2", "1 1/2".
35 *
36 * @param {string} raw
37 * @returns {number | null}
38 */
39export function parseNumber(raw) {
40  const s = raw.trim().replaceAll(",", "");
41  let m = /^(\d+) (\d+)\/(\d+)$/.exec(s);
42  if (m) return Number(m[1]) + Number(m[2]) / Number(m[3]);
43  m = /^(\d+)\/(\d+)$/.exec(s);
44  if (m) return Number(m[1]) / Number(m[2]);
45  return /^-?\d+(?:\.\d+)?$/.test(s) ? Number(s) : null;
46}
47
48/**
49 * The inside of a mark's braces: `20%µl`, `=20%µl`, `1.25 to 5%µl`, `2`, or empty.
50 *
51 * @param {string} inner
52 * @returns {{ raw: string, amount: string, unit: string, fixed: boolean, min: number | null, max: number | null } | null}
53 */
54export function parseQuantity(inner) {
55  let body = inner.trim();
56  if (!body) return null;
57  const fixed = body.startsWith("=");
58  if (fixed) body = body.slice(1).trim();
59  const at = body.indexOf("%");
60  const amount = (at < 0 ? body : body.slice(0, at)).trim();
61  const unit = at < 0 ? "" : body.slice(at + 1).trim();
62  const range = /^(.+?)\s*(?:-|to)\s*(.+)$/.exec(amount);
63  const min = parseNumber(range ? range[1] ?? "" : amount);
64  const max = range ? parseNumber(range[2] ?? "") : min;
65  return { raw: inner, amount, unit, fixed, min, max: min === null ? null : max };
66}
67
68/**
69 * @typedef {{ type: "text", value: string }} TextSegment
70 * @typedef {ReturnType<typeof parseQuantity>} Quantity
71 * @typedef {{ type: "material", name: string, display: string, quantity: Quantity }} MaterialSegment
72 * @typedef {{ type: "equipment", name: string, display: string }} EquipmentSegment
73 * @typedef {{ type: "timer", label: string, quantity: Quantity }} TimerSegment
74 * @typedef {TextSegment | MaterialSegment | EquipmentSegment | TimerSegment} Segment
75 */
76
77/**
78 * Where each mark sits in the text, with the parts it was written with: the one reading of the marks, which tokenize turns
79 * into words and the admin editor turns into chips (app/kb/step-marks.mjs), so the two can never split a step differently.
80 *
81 * @param {string} text
82 * @returns {Array<{ start: number, end: number, sign: "@" | "#" | "~", name: string, shown: string, braces: string | null }>}
83 */
84export function markSpans(text) {
85  const ranges = protectedRanges(text);
86  const inRange = (/** @type {number} */ i) => ranges.some(([a, b]) => i >= a && i < b);
87  /** @type {Array<{ start: number, end: number, sign: "@" | "#" | "~", name: string, shown: string, braces: string | null }>} */
88  const out = [];
89  let last = 0;
90  for (const hit of text.matchAll(MARK_START)) {
91    const i = hit.index;
92    if (i < last || inRange(i)) continue;
93    const before = i === 0 ? "" : (text[i - 1] ?? "");
94    if (before && !/\s/.test(before)) continue;
95    const rest = text.slice(i);
96    if (rest[0] === "~") {
97      const m = TIMER.exec(rest);
98      if (!m) continue;
99      out.push({ start: i, end: i + m[0].length, sign: "~", name: (m[1] ?? "").trim(), shown: "", braces: m[2] ?? "" });
100      last = i + m[0].length;
101      continue;
102    }
103    const m = BRACED.exec(rest) ?? SINGLE.exec(rest);
104    if (!m) continue;
105    const [name, shown] = (m[2] ?? "").split("|").map((part) => part.trim());
106    out.push({ start: i, end: i + m[0].length, sign: /** @type {"@" | "#"} */ (m[1]), name: name ?? "", shown: shown ?? "", braces: m[3] === undefined ? null : m[3] });
107    last = i + m[0].length;
108  }
109  return out;
110}
111
112/**
113 * The text split into words and marks.
114 *
115 * @param {string} text
116 * @returns {Segment[]}
117 */
118export function tokenize(text) {
119  /** @type {Segment[]} */
120  const out = [];
121  let last = 0;
122  for (const span of markSpans(text)) {
123    if (span.start > last) out.push({ type: "text", value: text.slice(last, span.start) });
124    if (span.sign === "~") out.push({ type: "timer", label: span.name, quantity: parseQuantity(span.braces ?? "") });
125    else if (span.sign === "@") {
126      out.push({ type: "material", name: span.name, display: span.shown || span.name, quantity: span.braces === null ? null : parseQuantity(span.braces) });
127    } else out.push({ type: "equipment", name: span.name, display: span.shown || span.name });
128    last = span.end;
129  }
130  if (text.length > last) out.push({ type: "text", value: text.slice(last) });
131  return out;
132}
133
134/**
135 * A number printed the way the file would write it: no trailing zeros, thousands with commas.
136 *
137 * @param {number} n
138 */
139export function formatNumber(n) {
140  const rounded = Math.round(n * 1000) / 1000;
141  return rounded.toLocaleString("en-US", { maximumFractionDigits: 3 });
142}
143
144/**
145 * A quantity as words, scaled by `factor` unless it is fixed or not a number.
146 *
147 * @param {NonNullable<Quantity>} q
148 * @param {number} [factor]
149 */
150export function formatQuantity(q, factor = 1) {
151  let amount = q.amount;
152  if (factor !== 1 && !q.fixed && q.min !== null) {
153    amount =
154      q.max !== null && q.max !== q.min
155        ? `${formatNumber(q.min * factor)} to ${formatNumber(q.max * factor)}`
156        : formatNumber(q.min * factor);
157  }
158  return q.unit ? `${amount} ${q.unit}` : amount;
159}
160
161/**
162 * The words a segment stands for on the page.
163 *
164 * @param {Segment} segment
165 * @param {number} [factor]
166 */
167export function segmentText(segment, factor = 1) {
168  switch (segment.type) {
169    case "text":
170      return segment.value;
171    case "material":
172      return segment.quantity ? `${formatQuantity(segment.quantity, factor)} of ${segment.display}` : segment.display;
173    case "equipment":
174      return segment.display;
175    case "timer":
176      return segment.quantity ? formatQuantity(segment.quantity) : segment.label;
177  }
178}
179
180/** "37 °C", "55 to 60 °C", "-80 °C", "55-60 °C". Exported for the editor, which shows each as a chip. */
181export const TEMPERATURE = /(-?\d+(?:\.\d+)?)(?:\s*(?:to|-)\s*(-?\d+(?:\.\d+)?))?\s*°C/g;
182/** "10,000 rpm", "12,000 x g", "10,000 to 15,000 x g". */
183const SPIN = /(?<![\d.,])(\d[\d,]*(?:\s*to\s*\d[\d,]*)?)\s*(rpm|x g)\b/g;
184
185/**
186 * The temperatures and spins a step's words state.
187 *
188 * @param {string} text the step with its marks already turned into words
189 */
190export function readConditions(text) {
191  const temperatures = [...text.matchAll(TEMPERATURE)].map((m) => ({
192    min: Number(m[1]),
193    max: m[2] === undefined ? Number(m[1]) : Number(m[2]),
194    text: m[0],
195  }));
196  const spins = [...text.matchAll(SPIN)].map((m) => ({
197    speed: (m[1] ?? "").trim(),
198    unit: m[2] === "rpm" ? "rpm" : "x g",
199    text: m[0],
200  }));
201  return { temperatures, spins };
202}