app/components/procedure.tsx

Functions

Imports

It imports app/components/enhance.tsx, app/components/procedure-materials.tsx, app/components/procedure-primers.tsx, app/components/procedure-steps.tsx, app/components/protocol-proof.tsx, app/components/protocol-workflow.tsx, app/kb/procedures/cite.mjs, app/kb/procedures/key-resources.mjs, app/kb/procedures/library.mjs, app/kb/procedures/lineage.mjs, app/kb/procedures/proof.mjs, app/kb/procedures/qr.mjs, app/kb/procedures/recipe-views.mjs, app/kb/procedures/render.mjs, app/lib/seo.ts. Imported by app/routes/admin.kb.preview.tsx, app/routes/procedure.sheet.tsx, app/routes/procedure.tsx, app/routes/procedure.version.sheet.tsx, app/routes/procedure.version.tsx.

Source

1import { Enhance } from "~/components/enhance";
2import { ProcedurePrimers } from "~/components/procedure-primers";
3import { ProtocolProof } from "~/components/protocol-proof";
4import { ProtocolWorkflow } from "~/components/protocol-workflow";
5import type { resolveProof } from "~/kb/procedures/proof.mjs";
6import type { workflowContext } from "~/kb/procedures/library.mjs";
7import { bibtex, citationText, citeFacts, versionPath } from "~/kb/procedures/cite.mjs";
8import { sheetQr } from "~/kb/procedures/qr.mjs";
9import { fixedSectionIds, type ProcedureRecord } from "~/kb/procedures/render.mjs";
10import type { Lineage } from "~/kb/procedures/lineage.mjs";
11import { keyResources } from "~/kb/procedures/key-resources.mjs";
12import { miseEnPlace, type UnitSystem } from "~/kb/procedures/recipe-views.mjs";
13import { SITE, SITE_ORIGIN } from "~/lib/seo";
14import { type Block, EquipmentTable, Heading, KeyResourcesTable, MaterialsTable, ProcedureFacts, ScaleForm, Solutions, html, materialsHeading } from "~/components/procedure-materials";
15import { Bullets, StepItem, Steps } from "~/components/procedure-steps";
16
17/**
18 * Every procedure page is drawn by these components from its D1 record (docs/PROCEDURES.md): the page,
19 * and its printable sheet. The HTML fragments in the record were rendered from the repository's file by
20 * the site's own pipeline, with the URL allowlist applied, so they are set as HTML here as a post's are.
21 */
22
23function TroubleshootingTable({ record }: { record: ProcedureRecord }) {
24  return (
25    <div className="table-scroll">
26      <table className="procedure-trouble">
27        <thead>
28          <tr>
29            <th scope="col">Step</th>
30            <th scope="col">Problem</th>
31            <th scope="col">Possible reason</th>
32            <th scope="col">Solution</th>
33          </tr>
34        </thead>
35        <tbody>
36          {record.troubleshooting.map((row) => (
37            <tr key={row.id} id={`trouble-${row.id}`}>
38              <td>{row.step}</td>
39              <td dangerouslySetInnerHTML={html(row.problem)} />
40              <td dangerouslySetInnerHTML={html(row.reason)} />
41              <td dangerouslySetInnerHTML={html(row.solution)} />
42            </tr>
43          ))}
44        </tbody>
45      </table>
46    </div>
47  );
48}
49
50/**
51 * What a frozen version's page says when it is not the one the site is at: which version is, and where. `current` is
52 * the procedure's live page, with its version (null when none is assigned); null when the procedure is no longer
53 * published.
54 */
55export function VersionNotice({ record, current }: { record: ProcedureRecord; current: { path: string; version: string | null } | null }) {
56  if (current && current.version === record.version) return null;
57  const date = citeFacts(record)?.date;
58  return (
59    <p className="procedure-version-notice" role="note">
60      This is version {record.version}
61      {date ? <>, dated <time dateTime={date}>{date}</time></> : null}, kept as it was published.{" "}
62      {current ? (
63        <>
64          {current.version ? <>The current version is version {current.version}: </> : <>The procedure has since moved on: </>}
65          <a href={current.path}>read the current page</a>.
66        </>
67      ) : (
68        <>The procedure is no longer on the site, so there is no current version.</>
69      )}
70    </p>
71  );
72}
73
74/** What changed in each version, newest first. Nothing is drawn until the file writes a history. */
75function VersionHistory({ record, basePath, frozen }: { record: ProcedureRecord; basePath: string; frozen: string[] }) {
76  // A row compiled before histories existed has no `history` until the next sync rewrites it.
77  if (!record.history?.length) return null;
78  return (
79    <section aria-labelledby="version-history">
80      <Heading id="version-history">Version history</Heading>
81      <ol className="procedure-history" reversed>
82        {record.history.map((h) => (
83          <li key={h.version}>
84            <strong>{frozen.includes(h.version) ? <a href={versionPath(basePath, h.version)}>Version {h.version}</a> : <>Version {h.version}</>}</strong>,{" "}
85            <time dateTime={h.date}>{h.date}</time>: <span dangerouslySetInnerHTML={html(h.summaryHtml)} />
86            {h.doi ? (
87              <>
88                {" "}
89                <a href={`https://doi.org/${h.doi}`}>doi:{h.doi}</a>
90              </>
91            ) : null}
92          </li>
93        ))}
94      </ol>
95    </section>
96  );
97}
98
99/**
100 * How to cite this version, and the BibTeX for it. Drawn only for a version that has been assigned: a procedure with no
101 * version cannot be cited, and a DOI is minted only for a version that is. The citation points at the version's frozen
102 * copy, or its DOI once it has one. The Zenodo deposit metadata is not on the page; `npm run zenodo:metadata -- <slug>`
103 * prints it from the same file.
104 */
105function CiteBlock({ record }: { record: ProcedureRecord }) {
106  const facts = citeFacts(record);
107  if (!facts) return null;
108  const where = { origin: SITE_ORIGIN, creator: { name: SITE.name, affiliation: SITE.affiliation } };
109  return (
110    <section aria-labelledby="cite-this-procedure">
111      <Heading id="cite-this-procedure">Cite this procedure</Heading>
112      <p className="procedure-cite">{citationText(record, facts, where)}</p>
113      <details className="procedure-bibtex">
114        <summary>BibTeX</summary>
115        <pre>
116          <code>{bibtex(record, facts, where)}</code>
117        </pre>
118      </details>
119    </section>
120  );
121}
122
123function commandsOf(record: ProcedureRecord) {
124  return record.sections.flatMap((s) => s.blocks.flatMap((b) => (b.type === "steps" ? b.steps.flatMap((st) => st.commands) : [])));
125}
126
127function hasCalculators(record: ProcedureRecord) {
128  return record.sections.some((section) =>
129    section.blocks.some((block) => block.type === "steps" && block.steps.some((step) => step.calculators?.length)),
130  );
131}
132
133/**
134 * A recipe's mise-en-place (R5): every ingredient once, at the reader's servings and units, as a checklist that works with no
135 * script, and the same as a plain shopping list to copy. Computed from the ingredient list, so it never says another amount.
136 */
137function MiseEnPlace({ record, factor, units }: { record: ProcedureRecord; factor: number; units: UnitSystem | null }) {
138  const { items, text } = miseEnPlace(record, factor, units);
139  if (items.length === 0) return null;
140  return (
141    <div className="procedure-mise">
142      <h3 id="mise-en-place">Mise en place</h3>
143      <ul className="procedure-mise-list">
144        {items.map((item) => (
145          <li key={item.name}>
146            <label>
147              <input type="checkbox" /> {item.amount ? `${item.amount} ` : ""}
148              {item.name}
149            </label>
150          </li>
151        ))}
152      </ul>
153      <label className="procedure-mise-copy">
154        <span>Shopping list, to copy</span>
155        <textarea readOnly rows={Math.min(12, items.length)} value={text} />
156      </label>
157    </div>
158  );
159}
160
161/**
162 * The whole procedure, as its page shows it. `count` is the reader's scale, `factor` the recipe multiplier.
163 * `basePath` is the address the page is at: the procedure's own for the live page, its version's for a frozen copy,
164 * so the scale form, run mode and the twin link stay on the version being read. `sheetPath` is the printable sheet's
165 * address, null when the page has none. `frozen` lists the versions that have a frozen copy, which the history links.
166 */
167export function ProcedureView({
168  record,
169  count,
170  factor,
171  workflow = null,
172  proof = null,
173  basePath = record.path,
174  sheetPath = `${record.path}/sheet`,
175  frozen = [],
176  units = null,
177  lineage = null,
178}: {
179  record: ProcedureRecord;
180  count: number;
181  factor: number;
182  /** The procedure this one is a variant of, resolved from its row (lineage.server.ts). */
183  lineage?: Lineage | null;
184  workflow?: ReturnType<typeof workflowContext>;
185  proof?: ReturnType<typeof resolveProof>;
186  basePath?: string;
187  sheetPath?: string | null;
188  frozen?: string[];
189  /** A recipe's units as the reader asked for them: null is the recipe's own (recipe-views.mjs). */
190  units?: UnitSystem | null;
191}) {
192  const [materialsId, equipmentId, primersId, troubleId, expectedId, limitsId, referencesId] = fixedSectionIds(record.profile);
193  const keyGroups = keyResources(record);
194  return (
195    <div className="prose procedure" data-profile={record.profile} data-run-path={basePath} data-run-version={record.version ?? ""} data-run-title={record.title}>
196      <ProcedureFacts record={record} lineage={lineage} />
197      <p className="procedure-links">
198        {sheetPath ? (
199          <a href={`${sheetPath}${count && record.scale && count !== record.scale.count ? `?n=${count}` : ""}`}>
200            Printable sheet
201          </a>
202        ) : null}
203        <a href={`${basePath}.md`} type="text/markdown">
204          Markdown
205        </a>
206      </p>
207      <ProtocolWorkflow context={workflow} />
208      {record.image ? (
209        <img
210          className="procedure-image"
211          src={record.image.src}
212          alt={record.image.alt}
213          {...(record.image.width && record.image.height ? { width: record.image.width, height: record.image.height } : {})}
214        />
215      ) : null}
216      {(record.questions?.length ?? 0) + (record.objectives?.length ?? 0) > 0 ? (
217        <section className="procedure-overview" aria-labelledby="overview">
218          <Heading id="overview">Overview</Heading>
219          <Bullets id="questions" title="Questions" items={record.questions ?? []} />
220          <Bullets id="objectives" title="Objectives" items={record.objectives ?? []} />
221        </section>
222      ) : null}
223      <div dangerouslySetInnerHTML={html(record.introHtml)} />
224
225      <section aria-labelledby={materialsId}>
226        <Heading id={materialsId!}>{materialsHeading(record)}</Heading>
227        <ScaleForm record={record} count={count} action={basePath} units={units} />
228        <MaterialsTable record={record} count={count} factor={factor} units={units} />
229        {record.profile === "recipe" ? <MiseEnPlace record={record} factor={factor} units={units} /> : null}
230        <Solutions record={record} />
231        {record.substitutions.length ? (
232          <>
233            <h3>Substitutions</h3>
234            <ul>
235              {record.substitutions.map((s) => (
236                <li key={s.for}>
237                  For {s.for}, use {s.use}
238                  {s.noteHtml ? (
239                    <>
240                      : <span dangerouslySetInnerHTML={html(s.noteHtml)} />
241                    </>
242                  ) : null}
243                </li>
244              ))}
245            </ul>
246          </>
247        ) : null}
248      </section>
249
250      {record.primers.length ? (
251        <section aria-labelledby={primersId}>
252          <Heading id={primersId!}>Primers</Heading>
253          <ProcedurePrimers record={record} />
254        </section>
255      ) : null}
256
257      {record.equipment.length ? (
258        <section aria-labelledby={equipmentId}>
259          <Heading id={equipmentId!}>Equipment</Heading>
260          <EquipmentTable record={record} />
261        </section>
262      ) : null}
263
264      {keyGroups.length ? (
265        <section aria-labelledby="key-resources">
266          <Heading id="key-resources">Key resources</Heading>
267          <KeyResourcesTable groups={keyGroups} />
268        </section>
269      ) : null}
270
271      {record.environmentHtml || record.prerequisites.length ? (
272        <section aria-labelledby="environment">
273          <Heading id="environment">Environment</Heading>
274          <div dangerouslySetInnerHTML={html(record.environmentHtml)} />
275          {record.prerequisites.length ? (
276            <ul>
277              {record.prerequisites.map((p) => (
278                <li key={p} dangerouslySetInnerHTML={html(p)} />
279              ))}
280            </ul>
281          ) : null}
282        </section>
283      ) : null}
284
285      {record.sections.map((section) => (
286        <section key={section.id} aria-labelledby={section.id}>
287          <Heading id={section.id}>{section.title}</Heading>
288          {section.blocks.map((block, i) =>
289            block.type === "prose" ? (
290              <div key={i} dangerouslySetInnerHTML={html(block.html)} />
291            ) : (
292              <Steps key={i} steps={block.steps} factor={factor} record={record} scope={`${section.id}-${i}-`} units={units} />
293            ),
294          )}
295        </section>
296      ))}
297
298      {record.keyPoints?.length ? (
299        <section className="procedure-overview" aria-labelledby="key-points">
300          <Heading id="key-points">Key points</Heading>
301          <ul>
302            {record.keyPoints.map((x, i) => (
303              <li key={i} dangerouslySetInnerHTML={html(x)} />
304            ))}
305          </ul>
306        </section>
307      ) : null}
308
309      {record.explanation?.length ? (
310        <section aria-labelledby="explanation">
311          <Heading id="explanation">Explanation</Heading>
312          <ul>
313            {record.explanation.map((e) => (
314              <li key={e.url}>
315                <a href={e.url}>{e.title}</a>
316              </li>
317            ))}
318          </ul>
319        </section>
320      ) : null}
321      {commandsOf(record).some((c) => c.platform) ? <Enhance module="platforms" /> : null}
322
323      {record.troubleshooting.length ? (
324        <section aria-labelledby={troubleId}>
325          <Heading id={troubleId!}>Troubleshooting</Heading>
326          <TroubleshootingTable record={record} />
327        </section>
328      ) : null}
329
330      {record.expectedResultsHtml ? (
331        <section aria-labelledby={expectedId}>
332          <Heading id={expectedId!}>Expected results</Heading>
333          <div dangerouslySetInnerHTML={html(record.expectedResultsHtml)} />
334        </section>
335      ) : null}
336
337      {record.limitationsHtml ? (
338        <section aria-labelledby={limitsId}>
339          <Heading id={limitsId!}>Limitations</Heading>
340          <div dangerouslySetInnerHTML={html(record.limitationsHtml)} />
341        </section>
342      ) : null}
343
344      <ProtocolProof proof={proof} />
345
346      <VersionHistory record={record} basePath={record.path} frozen={frozen} />
347      <CiteBlock record={record} />
348      {hasCalculators(record) ? <Enhance module="tools" /> : null}
349
350      <section aria-labelledby={referencesId}>
351        <Heading id={referencesId!}>References</Heading>
352        {record.basedOn.length ? (
353          <>
354            <h3 id="based-on">Based on</h3>
355            <ul className="procedure-credits">
356              {record.basedOn.map((s) => (
357                <li key={s.citation}>
358                  {s.doi ? <a href={`https://doi.org/${s.doi}`}>{s.citation}</a> : s.url ? <a href={s.url}>{s.citation}</a> : s.citation}
359                  : {s.for}
360                </li>
361              ))}
362            </ul>
363          </>
364        ) : null}
365        {record.references.length ? (
366          <>
367            <h3 id="cited">Cited</h3>
368            <ul className="procedure-references">
369              {record.references.map((r, i) => (
370                <li key={i} dangerouslySetInnerHTML={html(r)} />
371              ))}
372            </ul>
373          </>
374        ) : null}
375      </section>
376    </div>
377  );
378}
379
380/** The bench sheet: the method without the reasoning, compact enough to print and work from. */
381export function ProcedureSheet({
382  record,
383  count,
384  factor,
385  address,
386}: {
387  record: ProcedureRecord;
388  count: number;
389  factor: number;
390  /** What the sheet prints and its QR code opens: the address of the version on it (`sheetAddress`). */
391  address: string;
392}) {
393  // The sheet carries the version id and its date, so a printed copy says which version it is.
394  const facts = citeFacts(record);
395  const stamp = facts
396    ? `Version ${facts.version}, ${facts.date}`
397    : [record.version ? `Version ${record.version}` : "Version not yet assigned", record.updated ? `updated ${record.updated}` : null]
398        .filter(Boolean)
399        .join(", ");
400  return (
401    <article className="procedure-sheet prose">
402      <header className="procedure-sheet-head">
403        <h1>{record.title}</h1>
404        <p>
405          {stamp}. {address}
406        </p>
407        <figure className="procedure-sheet-qr">
408          <div role="img" aria-label={`QR code for ${address}`} dangerouslySetInnerHTML={html(sheetQr(address))} />
409          <figcaption>Scan to open this version online.</figcaption>
410        </figure>
411      </header>
412      <ProcedureFacts record={record} />
413      <h2>{materialsHeading(record)}</h2>
414      <MaterialsTable record={record} count={count} factor={factor} />
415      <Solutions record={record} />
416      {record.equipment.length ? (
417        <>
418          <h2>Equipment</h2>
419          <p>{record.equipment.map((e) => e.name).join("; ")}</p>
420        </>
421      ) : null}
422      {record.primers.length ? (
423        <>
424          <h2>Primers</h2>
425          <ProcedurePrimers record={record} brief />
426        </>
427      ) : null}
428      {record.sections.map((section) => {
429        const lists = section.blocks.filter((b): b is Extract<Block, { type: "steps" }> => b.type === "steps");
430        if (lists.length === 0) return null;
431        return (
432          <section key={section.id}>
433            <h2>{section.title}</h2>
434            {lists.map((block, i) => (
435              <ol key={i} className="procedure-steps" start={block.steps[0]?.number ?? 1}>
436                {block.steps.map((step) => (
437                  <StepItem key={step.number} step={step} factor={factor} troubleshooting={record.troubleshooting} brief />
438                ))}
439              </ol>
440            ))}
441          </section>
442        );
443      })}
444      {record.troubleshooting.length ? (
445        <>
446          <h2>Troubleshooting</h2>
447          <TroubleshootingTable record={record} />
448        </>
449      ) : null}
450    </article>
451  );
452}