app/kb/form-fields.mjs

Functions

Imports

It imports app/kb/procedures/taxonomy.mjs, app/kb/procedures/validate.mjs. Imported by app/kb/form.server.ts, app/kb/gap-labels.mjs.

Source

1// What the Knowledge Base form shows for each front-matter field (docs/KNOWLEDGE-BASE.md): its label, the input it is
2// edited with and, for a choice, the closed list it is chosen from. The lists are the ones the validator holds a file to
3// (taxonomy.mjs, validate.mjs), so the form cannot offer a value the save would refuse. A field not named here is still
4// edited, as YAML, so nothing in a file is out of the form's reach.
5
6import { BIOSAFETY_LEVELS, HOWTO_TYPES } from "./procedures/validate.mjs";
7import { COURSES, METHODS, NON_STRAIN_ORGANISMS, PROTOCOL_STATUSES } from "./procedures/taxonomy.mjs";
8
9/**
10 * @typedef {"text" | "textarea" | "lines" | "date" | "number" | "checkbox" | "select" | "multi" | "choice" | "materials" | "equipment" | "primers" | "strains" | "readonly" | "yaml"} FieldKind
11 * @typedef {{ key: string, label: string, kind: FieldKind, help?: string, options?: Array<{ value: string, label: string }> }} FieldSpec
12 */
13
14/** A key the form has no label for, in words: "published_doi" is "Published DOI". @param {string} key */
15export const keyWords = (key) =>
16  key
17    .replaceAll("_", " ")
18    .replace(/\b(doi|rrid|url|atcc|id|pmid)\b/gi, (m) => m.toUpperCase())
19    .replace(/^./, (c) => c.toUpperCase());
20
21/** @param {Record<string, string | { label: string }>} map */
22const options = (map) => Object.entries(map).map(([value, label]) => ({ value, label: typeof label === "string" ? label : label.label }));
23
24/** Every profile's fields first, in the order a person fills them in. @type {FieldSpec[]} */
25const COMMON = [
26  { key: "title", label: "Title", kind: "text" },
27  { key: "seo_title", label: "Search title", kind: "text", help: "The title search engines show; at most 60 characters." },
28  { key: "description", label: "Description", kind: "textarea", help: "One sentence, at most 155 characters." },
29  { key: "draft", label: "Draft (only you can see it)", kind: "checkbox" },
30  { key: "version", label: "Version", kind: "text", help: "Letters, digits, dots and hyphens, such as 2 or 1.1. A version, once published, is frozen." },
31  { key: "updated", label: "Updated", kind: "date" },
32];
33
34/** @type {FieldSpec[]} */
35const PROTOCOL = [
36  { key: "status", label: "Status", kind: "select", options: options(PROTOCOL_STATUSES) },
37  { key: "biosafety_level", label: "Biosafety level", kind: "choice", options: BIOSAFETY_LEVELS.map((v) => ({ value: v, label: v })) },
38  { key: "method", label: "Method", kind: "multi", options: options(METHODS) },
39  { key: "course", label: "Courses", kind: "multi", options: options(COURSES) },
40  { key: "organism", label: "Organisms", kind: "multi" },
41  { key: "target", label: "Targets", kind: "lines", help: "One per line: a gene, region or sample." },
42  { key: "first_used", label: "First used", kind: "text" },
43  { key: "last_run", label: "Last run", kind: "date" },
44  { key: "start_here", label: "Start-here position", kind: "number", help: "Its place in the library's Start here list; leave empty for none." },
45  { key: "host_strain", label: "Host strains", kind: "strains" },
46  { key: "primers", label: "Primers", kind: "primers" },
47  { key: "materials", label: "Reagents", kind: "materials" },
48  { key: "equipment", label: "Equipment", kind: "equipment" },
49  { key: "biosafety", label: "Biosafety agent", kind: "yaml", help: "The agent only: { organism, strain, atcc }, or not applicable." },
50  { key: "expected_results", label: "Expected results", kind: "textarea" },
51  { key: "limitations", label: "Limitations", kind: "textarea" },
52];
53
54/** @type {FieldSpec[]} */
55const RECIPE = [
56  { key: "servings", label: "Servings", kind: "number" },
57  { key: "prep_time", label: "Prep time", kind: "text" },
58  { key: "cook_time", label: "Cook time", kind: "text" },
59  { key: "cuisine", label: "Cuisine", kind: "text" },
60  { key: "category", label: "Category", kind: "text" },
61  { key: "diet", label: "Diet", kind: "lines" },
62  { key: "materials", label: "Ingredients", kind: "materials" },
63  { key: "equipment", label: "Equipment", kind: "equipment" },
64];
65
66/** @type {FieldSpec[]} */
67const COMPUTATIONAL = [
68  { key: "type", label: "Type", kind: "select", options: options(HOWTO_TYPES), help: "A tutorial teaches, step by step; a how-to gets one task done." },
69  { key: "questions", label: "Questions", kind: "lines", help: "One per line: what the reader will be able to answer." },
70  { key: "objectives", label: "Objectives", kind: "lines", help: "One per line: what the reader will be able to do. A tutorial needs them." },
71  { key: "key_points", label: "Key points", kind: "lines", help: "One per line, shown at the end." },
72  { key: "method", label: "Method", kind: "multi", options: options(METHODS) },
73  { key: "course", label: "Courses", kind: "multi", options: options(COURSES) },
74  { key: "environment", label: "Environment", kind: "textarea" },
75  { key: "prerequisites", label: "Prerequisites", kind: "lines" },
76  { key: "materials", label: "Software and data", kind: "materials" },
77  { key: "expected_results", label: "Expected results", kind: "textarea" },
78  { key: "limitations", label: "Limitations", kind: "textarea" },
79];
80
81/** Shown, never edited: a procedure's profile and address are its file's name and place (the validator ties them). */
82const FIXED = [
83  { key: "profile", label: "Profile", kind: /** @type {const} */ ("readonly") },
84  { key: "path", label: "Address", kind: /** @type {const} */ ("readonly") },
85  { key: "forked_from", label: "Copied from", kind: /** @type {const} */ ("readonly") },
86];
87
88/**
89 * The fields of an entry of `profile`, then every other field the file has, as YAML. The organism list is the registry's
90 * strains and the non-strain organisms, the list the validator holds `organism` to.
91 *
92 * @param {string} profile
93 * @param {Record<string, unknown>} data
94 * @param {Array<{ value: string, label: string }>} strains
95 * @returns {FieldSpec[]}
96 */
97export function entryFields(profile, data, strains) {
98  const own = profile === "recipe" ? RECIPE : profile === "computational" ? COMPUTATIONAL : PROTOCOL;
99  /** @type {FieldSpec[]} */
100  const specs = [...FIXED, ...COMMON, ...own].map((spec) =>
101    spec.key === "organism" ? { ...spec, options: [...strains, ...options(NON_STRAIN_ORGANISMS)] } : spec,
102  );
103  const named = new Set(specs.map((s) => s.key));
104  const rest = Object.keys(data)
105    .filter((key) => !named.has(key))
106    .map((key) => ({ key, label: keyWords(key), kind: /** @type {const} */ ("yaml") }));
107  return [...specs, ...rest];
108}
109
110/**
111 * A field's label as the form shows it, for any key a file of `profile` can have.
112 *
113 * @param {string} profile
114 * @param {string} key
115 */
116export function fieldLabel(profile, key) {
117  const own = profile === "recipe" ? RECIPE : profile === "computational" ? COMPUTATIONAL : PROTOCOL;
118  return [...FIXED, ...COMMON, ...own].find((s) => s.key === key)?.label ?? keyWords(key);
119}
120
121/**
122 * A registry item's fields: its name, whether it is a draft, then every field its kind declares. A field that holds true
123 * or false is a checkbox; every other is text, since a kind's fields are words (docs/REGISTRY.md).
124 *
125 * @param {string[]} declared
126 * @param {Record<string, unknown>} data
127 * @returns {FieldSpec[]}
128 */
129export function itemFields(declared, data) {
130  return [
131    { key: "name", label: "Name", kind: "text" },
132    { key: "draft", label: "Draft (only you can see it)", kind: "checkbox" },
133    ...declared.map((key) => ({
134      key,
135      label: keyWords(key),
136      kind: /** @type {FieldKind} */ (typeof data[key] === "boolean" || key.startsWith("prepared_") ? "checkbox" : "text"),
137    })),
138  ];
139}
140
141/** A recorded gap's reason, or null for a value. @param {unknown} value */
142export function gapReason(value) {
143  const match = typeof value === "string" ? /^MISSING:\s*([\s\S]+)$/.exec(value) : null;
144  return match ? /** @type {string} */ (match[1]) : null;
145}