app/components/procedure-materials.tsx

Functions

Imports

It imports app/kb/bases.mjs, app/kb/procedures/key-resources.mjs, app/kb/procedures/lineage.mjs, app/kb/procedures/marks.mjs, app/kb/procedures/recipe-views.mjs, app/kb/procedures/render.mjs, app/kb/procedures/validate.mjs, app/kb/registry/catalog.mjs. Imported by app/components/procedure-steps.tsx, app/components/procedure.tsx.

Source

1import { reagentSource, type ProcedureRecord } from "~/kb/procedures/render.mjs";
2import { lineageText, type Lineage } from "~/kb/procedures/lineage.mjs";
3import { HOWTO_TYPES } from "~/kb/procedures/validate.mjs";
4import type { KeyResourceGroup } from "~/kb/procedures/key-resources.mjs";
5import { BASES } from "~/kb/bases.mjs";
6import { itemPath } from "~/kb/registry/catalog.mjs";
7import { UNIT_SYSTEMS, ingredientSteps, showQuantity, type UnitSystem } from "~/kb/procedures/recipe-views.mjs";
8import { formatNumber, parseNumber } from "~/kb/procedures/marks.mjs";
9
10/* The procedure page's parts above the method (procedure.tsx): its facts, the scale form, and the materials, key resources, equipment and solutions tables. */
11
12type Section = ProcedureRecord["sections"][number];
13export type Block = Section["blocks"][number];
14export type Step = Extract<Block, { type: "steps" }>["steps"][number];
15
16export const html = (value: string | null | undefined) => ({ __html: value ?? "" });
17
18/** The words for the materials section, by profile. */
19export function materialsHeading(record: ProcedureRecord) {
20  if (record.profile === "recipe") return "Ingredients";
21  if (record.profile === "computational") return "Software and data";
22  return "Reagents";
23}
24
25/** A heading with the same autolink markup the pipeline gives prose headings. */
26export function Heading({ id, level = 2, children }: { id: string; level?: 2 | 3; children: string }) {
27  const Tag = level === 2 ? "h2" : "h3";
28  return (
29    <Tag id={id}>
30      {children}
31      <a className="heading-anchor" aria-label={`Link to section: ${children}`} href={`#${id}`}>
32        #
33      </a>
34    </Tag>
35  );
36}
37
38/**
39 * "20 µl" scaled to the reader's count: a protocol amount written per unit of its scale (per tube) is
40 * multiplied by the count; any other amount is shown as written.
41 */
42function total(amount: string | null, per: string | null, record: ProcedureRecord, count: number) {
43  if (!amount || !record.scale || per !== record.scale.unit) return null;
44  const m = /^(\d[\d,]*(?:\.\d+)?)(?: to (\d[\d,]*(?:\.\d+)?))? ?(.*)$/.exec(amount);
45  if (!m) return null;
46  const min = parseNumber(m[1] ?? "");
47  const max = m[2] ? parseNumber(m[2]) : null;
48  if (min === null) return null;
49  const range = max !== null ? `${formatNumber(min * count)} to ${formatNumber(max * count)}` : formatNumber(min * count);
50  return m[3] ? `${range} ${m[3]}` : range;
51}
52
53export function ProcedureFacts({ record, lineage = null }: { record: ProcedureRecord; lineage?: Lineage | null }) {
54  const facts: Array<[string, React.ReactNode]> = [];
55  const add = (label: string, value: string | number | null | undefined) => {
56    if (value !== null && value !== undefined && value !== "") facts.push([label, String(value)]);
57  };
58  // A how-to says first whether it is a lesson or a recipe for a task (S1). A row compiled before step 10 has no type.
59  add("Type", record.howtoType ? HOWTO_TYPES[record.howtoType] : null);
60  add("Version", record.version);
61  add("Updated", record.updated);
62  add("First used", record.firstUsed);
63  add("Last run", record.lastRun);
64  add("Status", record.status);
65  add("Biosafety level", record.biosafetyLevel);
66  add("Servings", record.servings);
67  add("Prep time", record.prepTime);
68  add("Cook time", record.cookTime);
69  add("Total time", record.time.total);
70  add("Hands-on time", record.time.handsOn);
71  add("Cuisine", record.cuisine);
72  add("Category", record.category);
73  if (record.diet.length) add("Diet", record.diet.join(", "));
74  // The strains are the lab registry's, so each name links to its record.
75  if (record.hostStrains.length > 0) {
76    facts.push([
77      "Host strain",
78      record.hostStrains.map((s, i) => (
79        <span key={s.id}>
80          {i > 0 ? "; " : null}
81          <a href={s.path}>{s.name}</a>
82        </span>
83      )),
84    ]);
85  }
86  // A variant made with the editor's Duplicate names the procedure it was copied from, as protocols.io shows a fork's
87  // parent (P3): by its title, linked to the frozen copy of the version copied. Where the page is drawn without the
88  // parent's row (the sheet, the admin preview), the parent's address stands in for its title.
89  if (record.forkedFrom) {
90    const root = BASES.find((b) => b.profile === record.profile)?.entryRoot ?? "/research/protocols/";
91    const shown = lineage ?? { title: record.forkedFrom.slug, href: `${root}${record.forkedFrom.slug}`, version: record.forkedFrom.version };
92    facts.push(["Based on", shown.href ? <a key="forked" href={shown.href}>{lineageText(shown)}</a> : lineageText(shown)]);
93  }
94  if (record.biosafety) {
95    add(
96      "Agent",
97      [record.biosafety.organism, record.biosafety.strain, record.biosafety.atcc ? `ATCC ${record.biosafety.atcc}` : null]
98        .filter(Boolean)
99        .join(", "),
100    );
101  }
102  if (facts.length === 0) return null;
103  return (
104    <dl className="procedure-facts">
105      {facts.map(([label, value]) => (
106        <div key={label}>
107          <dt>{label}</dt>
108          <dd>{value}</dd>
109        </div>
110      ))}
111    </dl>
112  );
113}
114
115/**
116 * The scaling form: a plain GET, so it works with script off and the state lives in the URL, where an
117 * agent reading the page sees the same numbers as a person.
118 */
119export function ScaleForm({ record, count, action, units = null }: { record: ProcedureRecord; count: number; action: string; units?: UnitSystem | null }) {
120  if (record.profile === "recipe" && record.servings) {
121    return (
122      <form className="procedure-scale" method="get" action={action}>
123        <label>
124          Servings <input name="servings" type="number" min={1} max={1000} step="any" defaultValue={count} />
125        </label>
126        {/* Metric or imperial (recipe-views.mjs): the same GET, so each state is an address and works with no script. */}
127        <label>
128          Units{" "}
129          <select name="units" defaultValue={units ?? ""}>
130            <option value="">As written</option>
131            {Object.entries(UNIT_SYSTEMS).map(([value, label]) => (
132              <option key={value} value={value}>
133                {label}
134              </option>
135            ))}
136          </select>
137        </label>
138        <button type="submit">Show</button>
139      </form>
140    );
141  }
142  if (record.profile === "protocol" && record.scale) {
143    return (
144      <form className="procedure-scale" method="get" action={action}>
145        <label>
146          {record.scale.unit === "tube" ? "Tubes" : `Count (${record.scale.unit})`}{" "}
147          <input name="n" type="number" min={1} max={1000} step={1} defaultValue={count} />
148        </label>
149        <button type="submit">Scale</button>
150      </form>
151    );
152  }
153  return null;
154}
155
156/** Where a registry reagent comes from: its supplier and catalog number linked to the product, or the lab's recipe for it. */
157function ReagentSource({ reagent }: { reagent: NonNullable<ProcedureRecord["materials"][number]["reagent"]> }) {
158  const source = reagentSource(reagent);
159  return source.href ? <a href={source.href}>{source.text}</a> : <>{source.text}</>;
160}
161
162/** The protocol's Equipment as a table: its own words for each item, and who makes it where the registry says. */
163/**
164 * The Key Resources Table (key-resources.mjs): every strain, reagent, primer and item of equipment the protocol names, with
165 * where it comes from and its identifier, grouped as STAR Methods groups them. Drawn from the record, so it never disagrees
166 * with the tables above it.
167 */
168export function KeyResourcesTable({ groups }: { groups: KeyResourceGroup[] }) {
169  return (
170    <div className="table-scroll">
171      <table className="procedure-materials procedure-key-resources">
172        <thead>
173          <tr>
174            <th scope="col">Reagent or resource</th>
175            <th scope="col">Source</th>
176            <th scope="col">Identifier</th>
177          </tr>
178        </thead>
179        {groups.map((group) => (
180          <tbody key={group.id}>
181            <tr>
182              <th scope="colgroup" colSpan={3}>
183                {group.heading}
184              </th>
185            </tr>
186            {group.rows.map((row) => (
187              <tr key={`${group.id}:${row.resource}`}>
188                <th scope="row">
189                  {row.href ? <a href={row.href}>{row.resource}</a> : row.resource}
190                  {row.sequence ? (
191                    <>
192                      {" "}
193                      <code className="procedure-key-sequence">{row.sequence}</code>
194                    </>
195                  ) : null}
196                </th>
197                <td>{row.source}</td>
198                <td>{row.identifier}</td>
199              </tr>
200            ))}
201          </tbody>
202        ))}
203      </table>
204    </div>
205  );
206}
207
208export function EquipmentTable({ record }: { record: ProcedureRecord }) {
209  const hasMaker = record.equipment.some((e) => e.item);
210  const hasRotor = record.equipment.some((e) => e.item && (e.item.rotor || e.item.rotorGap));
211  const hasNote = record.equipment.some((e) => e.noteHtml);
212  return (
213    <div className="table-scroll">
214      <table className="procedure-materials procedure-equipment">
215        <thead>
216          <tr>
217            <th scope="col">Equipment</th>
218            {hasMaker ? <th scope="col">Manufacturer</th> : null}
219            {hasRotor ? <th scope="col">Rotor</th> : null}
220            {hasNote ? <th scope="col">Notes</th> : null}
221          </tr>
222        </thead>
223        <tbody>
224          {record.equipment.map((e) => (
225            <tr key={e.name}>
226              <th scope="row">{e.item?.status === "published" ? <a href={itemPath("equipment", e.item.id)}>{e.name}</a> : e.name}</th>
227              {hasMaker ? <td>{e.item ? (e.item.manufacturer ?? "Not recorded") : ""}</td> : null}
228              {hasRotor ? <td>{e.item?.rotor ?? (e.item?.rotorGap ? "Not recorded" : "")}</td> : null}
229              {hasNote ? <td>{e.noteHtml ? <span dangerouslySetInnerHTML={html(e.noteHtml)} /> : null}</td> : null}
230            </tr>
231          ))}
232        </tbody>
233      </table>
234    </div>
235  );
236}
237
238export function MaterialsTable({ record, count, factor, units = null }: { record: ProcedureRecord; count: number; factor: number; units?: UnitSystem | null }) {
239  // A recipe's ingredients say every step they are used in (R2), linked, computed from the steps' marks.
240  const usedIn = record.profile === "recipe" ? ingredientSteps(record) : null;
241  const showTotal = record.profile === "protocol" && record.scale !== null && record.materials.some((m) => m.per === record.scale?.unit);
242  const hasStock = record.materials.some((m) => m.stock.length > 0);
243  const hasFinal = record.materials.some((m) => m.final);
244  const hasVersion = record.materials.some((m) => m.version);
245  // Where each reagent of the lab registry comes from, in one column, drawn from the registry's record.
246  const hasSource = record.materials.some((m) => m.reagent);
247  const hasKind = record.profile === "computational";
248  const unitWord = record.scale ? `${count} ${record.scale.unit}${count === 1 ? "" : "s"}` : "";
249  return (
250    <div className="table-scroll" data-run-swap="materials">
251      <table className="procedure-materials">
252        <thead>
253          <tr>
254            <th scope="col">{record.profile === "recipe" ? "Ingredient" : record.profile === "computational" ? "Item" : "Reagent"}</th>
255            {hasKind ? <th scope="col">Kind</th> : null}
256            {hasVersion ? <th scope="col">Version</th> : null}
257            {hasStock ? <th scope="col">Stock</th> : null}
258            {hasFinal ? <th scope="col">Final</th> : null}
259            <th scope="col">Amount</th>
260            {usedIn ? <th scope="col">Used in steps</th> : null}
261            {showTotal ? <th scope="col">For {unitWord}</th> : null}
262            {hasSource ? <th scope="col">Source</th> : null}
263            <th scope="col">Notes</th>
264          </tr>
265        </thead>
266        <tbody>
267          {record.materials.map((m) => (
268            <tr key={m.name} id={`material-${m.name.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`}>
269              <th scope="row">
270                {/* A published reagent of the lab registry links its page, which lists every protocol that uses it. */}
271                {m.reagent?.status === "published" ? <a href={itemPath("reagent", m.reagent.id)}>{m.display}</a> : m.display}
272                {m.group ? <span className="procedure-group"> ({m.group})</span> : null}
273              </th>
274              {hasKind ? <td>{m.kind}</td> : null}
275              {hasVersion ? <td>{m.version}</td> : null}
276              {hasStock ? <td>{m.stock.join(" or ")}</td> : null}
277              {hasFinal ? <td>{m.final}</td> : null}
278              <td>
279                {m.amount
280                  ? `${m.amount}${m.per ? ` per ${m.per}` : ""}`
281                  : m.quantity
282                    ? showQuantity(m.quantity, factor, units, m.gramsPerCup ?? null)
283                    : ""}
284              </td>
285              {usedIn ? (
286                <td>
287                  {(usedIn.get(m.name.toLowerCase()) ?? []).map((u, i) => (
288                    <span key={u.id}>
289                      {i > 0 ? ", " : null}
290                      <a href={`#${u.id}`}>{u.number}</a>
291                    </span>
292                  ))}
293                </td>
294              ) : null}
295              {showTotal ? <td>{total(m.amount, m.per, record, count) ?? ""}</td> : null}
296              {hasSource ? <td>{m.reagent ? <ReagentSource reagent={m.reagent} /> : null}</td> : null}
297              <td>
298                {m.noteHtml ? <span dangerouslySetInnerHTML={html(m.noteHtml)} /> : null}
299                {m.solution ? (
300                  <>
301                    {m.noteHtml ? " " : null}
302                    <a href={`#solution-${m.solution}`}>Recipe below.</a>
303                  </>
304                ) : null}
305              </td>
306            </tr>
307          ))}
308        </tbody>
309      </table>
310    </div>
311  );
312}
313
314export function Solutions({ record }: { record: ProcedureRecord }) {
315  if (record.solutions.length === 0) return null;
316  return (
317    <>
318      {record.solutions.map((s) => (
319        <div key={s.id} className="procedure-solution" id={`solution-${s.id}`}>
320          <h3>{s.name}</h3>
321          <ul>
322            {s.components.map((c) => (
323              <li key={c.name}>
324                {c.name}
325                {c.final ? `, ${c.final} final` : ""}
326                {c.amount ? `, ${c.amount}` : ""}
327              </li>
328            ))}
329          </ul>
330          {s.storage || s.shelfLife ? (
331            <p className="procedure-solution-keep">
332              {s.storage ? `Storage: ${s.storage}.` : null} {s.shelfLife ? `Shelf life: ${s.shelfLife}.` : null}
333            </p>
334          ) : null}
335        </div>
336      ))}
337    </>
338  );
339}