app/kb/procedures/recipe-views.mjs

Functions

Imports

It imports app/kb/procedures/marks.mjs. Imported by app/components/procedure-materials.tsx, app/components/procedure-steps.tsx, app/components/procedure.tsx, app/kb/procedures/route.ts.

Source

1// A recipe's views (docs/KNOWLEDGE-BASE.md, step 9): its ingredients both ways (R2), metric and imperial (R3) and its
2// mise-en-place (R5), every one computed from the compiled record and the reader's address, never stored. Unit conversion is
3// arithmetic on the record's own amounts; volume becomes weight only for an ingredient whose recipe states `grams_per_cup`
4// (DECIDE 7), never from a table of densities. Pure, so the page, the sheet and a test read the same numbers.
5
6import { formatNumber, formatQuantity } from "./marks.mjs";
7
8/** The unit systems a reader can ask for; absent is the recipe's own units. */
9export const UNIT_SYSTEMS = Object.freeze({ metric: "Metric", imperial: "Imperial (US)" });
10
11/** @typedef {keyof typeof UNIT_SYSTEMS} UnitSystem */
12/** @typedef {{ amount: string, unit: string, fixed: boolean, min: number | null, max: number | null }} Quantity */
13
14/** The system an address asks for (`?units=metric`), or null for the recipe's own. @param {string | null} value @returns {UnitSystem | null} */
15export function readUnits(value) {
16  return value === "metric" || value === "imperial" ? value : null;
17}
18
19/** Grams in one of each mass unit. */
20const GRAMS = /** @type {Record<string, number>} */ ({ g: 1, kg: 1000, oz: 28.349523125, lb: 453.59237 });
21/** Millilitres in one of each volume unit (US customary). */
22const MILLILITRES = /** @type {Record<string, number>} */ ({ ml: 1, l: 1000, tsp: 4.92892159375, tbsp: 14.78676478125, "fl oz": 29.5735295625, cup: 236.5882365 });
23/** The spoons a cook uses in either system, kept as written. */
24const SPOONS = new Set(["tsp", "tbsp"]);
25
26/** A unit's one spelling: "teaspoons" is tsp, "Cups" is cup. @param {string} unit */
27function canonical(unit) {
28  const u = unit.trim().toLowerCase().replace(/\.$/, "");
29  const aliases = /** @type {Record<string, string>} */ ({
30    gram: "g", grams: "g", kilogram: "kg", kilograms: "kg", ounce: "oz", ounces: "oz", pound: "lb", pounds: "lb", lbs: "lb",
31    millilitre: "ml", millilitres: "ml", milliliter: "ml", milliliters: "ml", litre: "l", litres: "l", liter: "l", liters: "l",
32    teaspoon: "tsp", teaspoons: "tsp", tablespoon: "tbsp", tablespoons: "tbsp", cups: "cup", "fluid ounce": "fl oz", "fluid ounces": "fl oz",
33  });
34  return aliases[u] ?? u;
35}
36
37/** A number rounded as a cook reads it in a unit: whole grams, quarter cups, half ounces. @param {number} n @param {string} unit */
38function round(n, unit) {
39  const step = unit === "cup" ? 0.25 : unit === "lb" ? 0.1 : unit === "oz" ? 0.25 : unit === "tsp" || unit === "tbsp" ? 0.25 : n < 10 ? 0.1 : 1;
40  return Math.round(n / step) * step;
41}
42
43/**
44 * One amount in a unit of `system`: grams become ounces and the reverse, millilitres become cups and the reverse, spoons stay. In
45 * metric, a volume of an ingredient with `gramsPerCup` becomes its weight. A unit neither system knows (a pinch, 2 eggs) is
46 * left as written, and so is an amount with no number.
47 *
48 * @param {number} value
49 * @param {string} unit
50 * @param {UnitSystem} system
51 * @param {number | null} gramsPerCup
52 * @returns {{ value: number, unit: string } | null}
53 */
54function convert(value, unit, system, gramsPerCup) {
55  const u = canonical(unit);
56  if (u in GRAMS) {
57    const g = value * /** @type {number} */ (GRAMS[u]);
58    if (system === "metric") return g >= 1000 ? { value: g / 1000, unit: "kg" } : { value: g, unit: "g" };
59    const oz = g / /** @type {number} */ (GRAMS.oz);
60    return oz >= 16 ? { value: oz / 16, unit: "lb" } : { value: oz, unit: "oz" };
61  }
62  if (u in MILLILITRES) {
63    if (SPOONS.has(u)) return null;
64    const ml = value * /** @type {number} */ (MILLILITRES[u]);
65    if (system === "metric") {
66      if (gramsPerCup) return { value: (ml / /** @type {number} */ (MILLILITRES.cup)) * gramsPerCup, unit: "g" };
67      return ml >= 1000 ? { value: ml / 1000, unit: "l" } : { value: ml, unit: "ml" };
68    }
69    if (ml < 15) return { value: ml / /** @type {number} */ (MILLILITRES.tsp), unit: "tsp" };
70    if (ml < 60) return { value: ml / /** @type {number} */ (MILLILITRES.tbsp), unit: "tbsp" };
71    return { value: ml / /** @type {number} */ (MILLILITRES.cup), unit: "cup" };
72  }
73  return null;
74}
75
76/**
77 * An amount as the reader asked for it: scaled by `factor` (a fixed amount is not), then in `system` when one is asked for.
78 *
79 * @param {Quantity} q
80 * @param {number} factor
81 * @param {UnitSystem | null} system
82 * @param {number | null} [gramsPerCup]
83 */
84export function showQuantity(q, factor, system, gramsPerCup = null) {
85  if (!system || q.min === null) return formatQuantity({ ...q, raw: "" }, factor);
86  const scale = q.fixed ? 1 : factor;
87  const low = convert(q.min * scale, q.unit, system, gramsPerCup);
88  if (!low) return formatQuantity({ ...q, raw: "" }, factor);
89  const high = q.max !== null && q.max !== q.min ? convert(q.max * scale, q.unit, system, gramsPerCup) : null;
90  // A range is shown in the unit of its low end, so "1 to 2 cups" never reads "1 cup to 0.5 quart".
91  const highValue = high ? (high.unit === low.unit ? high.value : (q.max ?? 0) * scale * (low.value / (q.min * scale))) : null;
92  const amount = highValue !== null ? `${formatNumber(round(low.value, low.unit))} to ${formatNumber(round(highValue, low.unit))}` : formatNumber(round(low.value, low.unit));
93  return `${amount} ${low.unit}`;
94}
95
96/** A temperature in the other scale, to the nearest 5 degrees as an oven dial reads. @param {number} t @param {"C" | "F"} to */
97const toScale = (t, to) => Math.round((to === "F" ? (t * 9) / 5 + 32 : ((t - 32) * 5) / 9) / 5) * 5;
98
99/**
100 * A step's words with its temperatures in the asked-for system's scale: "180 °C" reads "355 °F" in imperial, and the reverse in
101 * metric. HTML in, HTML out: only the text of a temperature changes.
102 *
103 * @param {string} html
104 * @param {UnitSystem | null} system
105 */
106export function showTemperatures(html, system) {
107  if (!system) return html;
108  const from = system === "imperial" ? "C" : "F";
109  const to = system === "imperial" ? "F" : "C";
110  return html.replace(new RegExp(`(-?\\d+(?:\\.\\d+)?)(?:\\s*(?:to|-)\\s*(-?\\d+(?:\\.\\d+)?))?\\s*°${from}`, "g"), (_all, low, high) =>
111    high !== undefined ? `${toScale(Number(low), to)} to ${toScale(Number(high), to)} °${to}` : `${toScale(Number(low), to)} °${to}`,
112  );
113}
114
115/** The anchor of a step on the page: its list's scope and its number. @param {string} scope @param {number} number */
116export const stepId = (scope, number) => `${scope}step-${number}`;
117
118/**
119 * Every step each ingredient is used in, in the page's order: the other half of R2, read from the marks the compile already
120 * put on each step. Keyed by the ingredient's name, lower-cased, as the record's materials are.
121 *
122 * @param {import("./render.mjs").ProcedureRecord} record
123 */
124export function ingredientSteps(record) {
125  /** @type {Map<string, Array<{ number: number, id: string }>>} */
126  const uses = new Map();
127  for (const section of record.sections) {
128    section.blocks.forEach((block, i) => {
129      if (block.type !== "steps") return;
130      for (const step of block.steps) {
131        for (const m of step.materials) {
132          const key = m.name.toLowerCase();
133          const list = uses.get(key) ?? [];
134          if (!list.some((u) => u.number === step.number && u.id === stepId(`${section.id}-${i}-`, step.number))) {
135            list.push({ number: step.number, id: stepId(`${section.id}-${i}-`, step.number) });
136          }
137          uses.set(key, list);
138        }
139      }
140    });
141  }
142  return uses;
143}
144
145/**
146 * The grams in a cup of each ingredient whose recipe states it, by lower-cased name.
147 *
148 * @param {import("./render.mjs").ProcedureRecord} record
149 */
150export function gramsPerCup(record) {
151  return new Map(record.materials.flatMap((m) => (typeof m.gramsPerCup === "number" ? [[m.name.toLowerCase(), m.gramsPerCup]] : [])));
152}
153
154/**
155 * A step's ingredients, each with its amount as the reader asked for it: the first half of R2.
156 *
157 * @param {import("./render.mjs").ProcedureRecord["sections"][number]["blocks"][number] extends infer B ? B extends { type: "steps", steps: Array<infer S> } ? S : never : never} step
158 * @param {number} factor
159 * @param {UnitSystem | null} system
160 * @param {Map<string, number>} densities
161 * @param {Map<string, string>} [names] the ingredient list's words for each ingredient, which the step's own marks may shorten
162 */
163export function stepIngredients(step, factor, system, densities, names = new Map()) {
164  return step.materials.map((m) => {
165    const q = step.quantities.find((x) => x.name?.toLowerCase() === m.name.toLowerCase());
166    return { name: names.get(m.name.toLowerCase()) ?? m.display, amount: q ? showQuantity(q, factor, system, densities.get(m.name.toLowerCase()) ?? null) : null };
167  });
168}
169
170/** Each ingredient's words in the ingredient list, by lower-cased name. @param {import("./render.mjs").ProcedureRecord} record */
171export function ingredientNames(record) {
172  return new Map(record.materials.map((m) => [m.name.toLowerCase(), m.display]));
173}
174
175/**
176 * The mise-en-place: every ingredient once, with its total amount at the reader's servings and units, in the order of the
177 * ingredient list; and the same as plain lines, a shopping list to copy (R5).
178 *
179 * @param {import("./render.mjs").ProcedureRecord} record
180 * @param {number} factor
181 * @param {UnitSystem | null} system
182 */
183export function miseEnPlace(record, factor, system) {
184  const items = record.materials.map((m) => {
185    const amount = m.amount ? m.amount : m.quantity ? showQuantity(m.quantity, factor, system, m.gramsPerCup ?? null) : null;
186    return { name: m.display, amount };
187  });
188  return { items, text: items.map((i) => `- ${i.amount ? `${i.amount} ` : ""}${i.name}`).join("\n") };
189}