app/components/admin/kb-form.tsx

Functions

Imports

It imports app/components/admin/kb-file-editor.tsx, app/components/admin/kb-form-fields.tsx, app/components/admin/kb-form-steps.tsx, app/components/admin/shell-parts.tsx, app/kb/editor.server.ts, app/kb/form.mjs, app/kb/form.server.ts. Imported by app/routes/admin.kb.entry.tsx, app/routes/admin.kb.item.tsx.

Source

1import { useEffect, useMemo, useRef, useState } from "react";
2import { Form, Link, useNavigation } from "react-router";
3
4import { Alert, Banner } from "capsomer/react/banner";
5import { Button } from "capsomer/react/button";
6import { Panel } from "capsomer/react/panel";
7
8import { PageHead } from "capsomer/react/page-head";
9import { crumbLink } from "~/components/admin/shell-parts";
10import { KbCheckSave, type KbEditorActionData } from "~/components/admin/kb-file-editor";
11import type { KbFile } from "~/kb/editor.server";
12import type { FormBody, FormModel } from "~/kb/form.mjs";
13import type { Choice, FormField, KbForm } from "~/kb/form.server";
14import { type EquipmentEntry, FieldInput, type Material, type Values } from "~/components/admin/kb-form-fields";
15import { BodyEditor, type Inserts, goTo } from "~/components/admin/kb-form-steps";
16
17/*
18 * The Knowledge Base's form editor (docs/KNOWLEDGE-BASE.md): every field its own input, the values nobody has yet at the
19 * top as Needs info, and the method as step cards in their sections, reordered by dragging or with Move up and Move down
20 * (Alt+Up and Alt+Down on a focused card), as WCAG 2.2's 2.5.7 asks of any drag. What it sends is the form's model; the
21 * server writes the file from it (form.mjs) and runs the same Check and Save the raw editor does. The raw file stays one
22 * link away, behind Advanced, which also works with no script.
23 */
24
25type PreviewResult = { html: string; styles: string[] } | { errors: string[] } | { error: string };
26
27const PREVIEW_DELAY_MS = 900;
28/** The width at which the preview sits beside the form; below it, the preview is a tab. Matches app/admin.css. */
29const SIDE_BY_SIDE = "(min-width: 72rem)";
30
31/**
32 * The entry the form describes, rendered as its public page by the server a beat after the form stops changing. A
33 * sequence number keeps a slow answer from landing over a newer one.
34 */
35function useEntryPreview(slug: string | null, original: string, model: string, active: boolean) {
36  const [result, setResult] = useState<PreviewResult | null>(null);
37  const [busy, setBusy] = useState(false);
38  const seq = useRef(0);
39  useEffect(() => {
40    if (!slug || !active) return;
41    const mine = (seq.current += 1);
42    setBusy(true);
43    const timer = window.setTimeout(async () => {
44      const body = new FormData();
45      body.set("original", original);
46      body.set("model", model);
47      try {
48        const response = await fetch(`/admin/kb/preview/${slug}`, { method: "POST", body });
49        const json = (await response.json().catch(() => null)) as PreviewResult | null;
50        if (mine !== seq.current) return;
51        setResult(json ?? { error: `The preview request failed with HTTP ${response.status}.` });
52      } catch (error) {
53        if (mine === seq.current) setResult({ error: error instanceof Error ? error.message : String(error) });
54      } finally {
55        if (mine === seq.current) setBusy(false);
56      }
57    }, PREVIEW_DELAY_MS);
58    return () => window.clearTimeout(timer);
59  }, [slug, original, model, active]);
60  return { result, busy };
61}
62
63/**
64 * The public page in a sandboxed frame: no script runs in it, and it links the public page's own stylesheets, so it
65 * looks as the page will. A frame, because the page's styles are the public site's and the admin's are its own.
66 */
67function PreviewPane({ result, busy, publicHref }: { result: PreviewResult | null; busy: boolean; publicHref: string | null }) {
68  const [doc, setDoc] = useState("");
69  useEffect(() => {
70    if (!result || !("html" in result)) return;
71    const styles = result.styles.map((href) => `<link rel="stylesheet" href="${new URL(href, window.location.href).href}">`).join("");
72    const theme = document.documentElement.getAttribute("data-theme");
73    setDoc(`<!doctype html><html lang="en"${theme ? ` data-theme="${theme}"` : ""}><head><meta charset="utf-8"><base target="_blank">${styles}</head><body>${result.html}</body></html>`);
74  }, [result]);
75  const failed = result && "errors" in result ? result.errors : result && "error" in result ? [result.error] : null;
76  return (
77    <Panel title="Preview" src={busy ? "Updating" : failed ? "Not drawn" : "As the page will look"} flush>
78      {failed ? (
79        <div className="kb-preview-note">
80          <Alert tone="warn" title="The page cannot be drawn until these are fixed">
81            <ul>
82              {failed.map((e) => (
83                <li key={e}>{e}</li>
84              ))}
85            </ul>
86          </Alert>
87        </div>
88      ) : null}
89      {doc ? (
90        <iframe className="kb-preview-frame" title={`Preview of the page${publicHref ? ` at ${publicHref}` : ""}`} sandbox="" srcDoc={doc} />
91      ) : (
92        <p className="kb-preview-note">{busy || !result ? "Drawing the page…" : null}</p>
93      )}
94    </Panel>
95  );
96}
97
98/** What the form posts: the model, with each YAML field sent as its text for the server to read. */
99function posted(model: FormModel, values: Values, yaml: Record<string, string>, fields: FormField[], body: FormBody | null) {
100  const data: Values = { ...values };
101  for (const f of fields) if (f.kind === "yaml" && f.key in yaml) data[f.key] = { $yaml: yaml[f.key] };
102  return JSON.stringify({ ...model, data, body });
103}
104
105export function KbFormEditor({
106  file,
107  form,
108  actionData,
109  saved,
110  created,
111}: {
112  file: KbFile;
113  form: KbForm;
114  actionData?: KbEditorActionData;
115  saved?: { commit: string; unchanged: boolean } | null;
116  created?: boolean;
117}) {
118  const navigation = useNavigation();
119  const busy = navigation.state === "submitting" ? String(navigation.formData?.get("intent") ?? "") : "";
120  // A Check or a refused Save hands the form back as it was sent, so nothing typed is lost.
121  const start = useMemo(() => {
122    const sent = actionData && "model" in actionData && actionData.model ? (JSON.parse(actionData.model) as FormModel) : null;
123    return sent ?? form.model;
124  }, [actionData, form.model]);
125  const [values, setValues] = useState<Values>(() => {
126    const v = { ...start.data };
127    for (const f of form.fields) if (f.kind === "yaml" && v[f.key] && typeof v[f.key] === "object" && "$yaml" in (v[f.key] as object)) delete v[f.key];
128    return v;
129  });
130  const [yaml, setYaml] = useState<Record<string, string>>(() => {
131    const out: Record<string, string> = {};
132    for (const f of form.fields) {
133      if (f.kind !== "yaml") continue;
134      const sent = start.data[f.key];
135      out[f.key] = sent && typeof sent === "object" && "$yaml" in (sent as object) ? String((sent as { $yaml: string }).$yaml) : (f.yaml ?? "");
136    }
137    return out;
138  });
139  const [body, setBody] = useState<FormBody | null>(start.body);
140  const [duplicating, setDuplicating] = useState(actionData?.intent === "duplicate");
141  // A Needs info link from the Knowledge Base list opens the editor at the gap's field.
142  useEffect(() => {
143    if (window.location.hash.length > 1) goTo(null, decodeURIComponent(window.location.hash.slice(1)));
144  }, []);
145
146  const checked = actionData?.intent === "check" ? actionData : null;
147  const errors = checked ? checked.errors : actionData?.intent === "save" ? (actionData.refused ?? []) : file.errors;
148  const gaps = checked ? checked.gaps : file.gaps;
149  const original = form.model.data;
150  const gapFields = form.fields.filter((f) => f.gap && f.kind !== "readonly");
151  const otherFields = form.fields.filter((f) => !f.gap);
152  // Gaps inside a field (a reagent's amount, a cycling step), which the field's own input holds.
153  const topKeys = new Set(form.fields.map((f) => f.key));
154  const nested = gaps.filter((g) => !topKeys.has(g.field));
155
156  const materials = (Array.isArray(values.materials) ? values.materials : []) as Material[];
157  const equipment = (Array.isArray(values.equipment) ? values.equipment : []) as EquipmentEntry[];
158  const nameOf = (list: Choice[], value: string) => list.find((o) => o.value === value)?.label.replace(/ \(draft\)$/, "") ?? value;
159  const inserts: Inserts = {
160    reagents: [
161      ...materials.filter((m) => m.name).map((m) => ({ value: `m:${m.name}`, label: String(m.name) })),
162      ...form.registry.reagent.filter((r) => !materials.some((m) => m.reagent === r.value)).map((r) => ({ value: `r:${r.value}`, label: `${r.label} (from the registry)` })),
163    ],
164    equipment: [
165      ...equipment.map((e) => (typeof e === "string" ? e : String(e.name ?? ""))).filter(Boolean).map((name) => ({ value: `m:${name}`, label: name })),
166      ...form.registry.equipment.filter((r) => !equipment.some((e) => typeof e === "object" && e.equipment === r.value)).map((r) => ({ value: `r:${r.value}`, label: `${r.label} (from the registry)` })),
167    ],
168    primers: form.registry.primer,
169    strains: form.registry.strain,
170    names: {
171      reagent: materials.map((m) => String(m.name ?? "")).filter(Boolean),
172      equipment: equipment.map((e) => (typeof e === "string" ? e : String(e.name ?? ""))).filter(Boolean),
173    },
174    references: form.references,
175  };
176
177  /** An insert from a step card: a material or equipment the protocol does not list yet is added to its list, so the mark resolves. */
178  const onInsert = (kind: "reagent" | "equipment" | "primer" | "strain", value: string, amount?: string): string | null => {
179    if (kind === "reagent") {
180      let name = value.slice(2);
181      if (value.startsWith("r:")) {
182        name = nameOf(form.registry.reagent, value.slice(2));
183        setValues((v) => ({ ...v, materials: [...((Array.isArray(v.materials) ? v.materials : []) as Material[]), { name, reagent: value.slice(2) }] }));
184      }
185      return `@${name}{${amount ?? ""}}`;
186    }
187    if (kind === "equipment") {
188      let name = value.slice(2);
189      if (value.startsWith("r:")) {
190        name = nameOf(form.registry.equipment, value.slice(2));
191        setValues((v) => ({ ...v, equipment: [...((Array.isArray(v.equipment) ? v.equipment : []) as EquipmentEntry[]), { name, equipment: value.slice(2) }] }));
192      }
193      return `#${name}{}`;
194    }
195    if (kind === "primer") {
196      setValues((v) => {
197        const list = (Array.isArray(v.primers) ? v.primers : []) as Array<{ primer: string }>;
198        return list.some((p) => p.primer === value) ? v : { ...v, primers: [...list, { primer: value }] };
199      });
200      return nameOf(form.registry.primer, value);
201    }
202    setValues((v) => {
203      const list = (Array.isArray(v.host_strain) ? v.host_strain : []) as Array<{ strain: string }>;
204      return list.some((s) => s.strain === value) ? v : { ...v, host_strain: [...list, { strain: value }] };
205    });
206    return nameOf(form.registry.strain, value);
207  };
208
209  const input = (f: FormField) => (
210    <FieldInput
211      key={f.key}
212      field={f}
213      value={values[f.key]}
214      original={original[f.key]}
215      yaml={yaml[f.key] ?? ""}
216      form={form}
217      onValue={(v) => setValues((cur) => ({ ...cur, [f.key]: v }))}
218      onYaml={(t) => setYaml((cur) => ({ ...cur, [f.key]: t }))}
219    />
220  );
221  const isEntry = file.target.type === "entry";
222  const modelJson = posted(form.model, values, yaml, form.fields, body);
223  // The preview is drawn while it can be seen: beside the form on a wide screen, or on the phone when its tab is open.
224  const [pane, setPane] = useState<"form" | "preview">("form");
225  const [wide, setWide] = useState(false);
226  useEffect(() => {
227    const query = window.matchMedia(SIDE_BY_SIDE);
228    const update = () => setWide(query.matches);
229    update();
230    query.addEventListener("change", update);
231    return () => query.removeEventListener("change", update);
232  }, []);
233  const preview = useEntryPreview(file.target.type === "entry" ? file.target.slug : null, file.raw, modelJson, wide || pane === "preview");
234
235  return (
236    <div className="app-page">
237      <PageHead
238        renderLink={crumbLink}
239        crumbs={[
240          { label: "Knowledge Base", href: "/admin/kb" },
241          { label: file.group, href: file.listHref },
242        ]}
243        title={file.title}
244        lead={
245          <>
246            <code>{file.file}</code>
247            {file.publicHref ? (
248              <>
249                {" "}
250                <Link to={file.publicHref} reloadDocument>
251                  View the page
252                </Link>
253              </>
254            ) : null}
255          </>
256        }
257        actions={
258          <>
259            {isEntry ? (
260              <Button type="button" onClick={() => setDuplicating(!duplicating)} aria-expanded={duplicating} aria-controls="kb-duplicate">
261                Duplicate
262              </Button>
263            ) : null}
264            <Link to="?view=file" className="cap-btn" data-variant="quiet">
265              Advanced: edit the file
266            </Link>
267          </>
268        }
269      />
270
271      {created ? <Banner tone="ok">A new draft, copied from the protocol named under Copied from. Nothing about it is public until you publish it.</Banner> : null}
272      {saved ? (
273        <Banner tone="ok">
274          {saved.unchanged ? "Nothing to commit: the file was already this. Its page was brought up to date." : `Saved as commit ${saved.commit}. The page shows it on the next visit.`}
275        </Banner>
276      ) : null}
277
278      {isEntry && duplicating ? (
279        <Panel title="Duplicate as a new draft" description="A copy with its own title and address, recording that it came from this one. Its version, history and Start-here place are left behind.">
280          <Form method="post" id="kb-duplicate" className="app-filters">
281            <input type="hidden" name="intent" value="duplicate" />
282            <div className="cap-field">
283              <label className="cap-field-label" htmlFor="kb-dup-title">
284                New title
285              </label>
286              <input id="kb-dup-title" name="title" className="cap-input" required defaultValue={`${file.title} (variant)`} />
287            </div>
288            <div className="cap-field">
289              <label className="cap-field-label" htmlFor="kb-dup-slug">
290                File name (optional)
291              </label>
292              <input id="kb-dup-slug" name="slug" className="cap-input" pattern="[a-z0-9]+(-[a-z0-9]+)*" placeholder="made from the title" />
293            </div>
294            <Button type="submit" variant="primary" pending={busy === "duplicate"}>
295              Make the copy
296            </Button>
297          </Form>
298          {actionData?.intent === "duplicate" ? (
299            <Alert tone="crit" title="Not copied">
300              <ul>
301                {actionData.refused.map((e) => (
302                  <li key={e}>{e}</li>
303                ))}
304              </ul>
305            </Alert>
306          ) : null}
307        </Panel>
308      ) : null}
309
310      {isEntry ? (
311        <div className="kb-pane-tabs" role="tablist" aria-label="Form or preview">
312          <button type="button" role="tab" id="kb-tab-form" aria-controls="kb-pane-form" aria-selected={pane === "form"} className="cap-btn" data-variant={pane === "form" ? "primary" : "quiet"} onClick={() => setPane("form")}>
313            Edit
314          </button>
315          <button type="button" role="tab" id="kb-tab-preview" aria-controls="kb-pane-preview" aria-selected={pane === "preview"} className="cap-btn" data-variant={pane === "preview" ? "primary" : "quiet"} onClick={() => setPane("preview")}>
316            Preview
317          </button>
318        </div>
319      ) : null}
320
321      <div className={isEntry ? "kb-layout" : undefined} data-pane={pane}>
322      <Form method="post" className="kb-editor-form kb-pane-form" id="kb-pane-form" role={isEntry && !wide ? "tabpanel" : undefined} aria-labelledby={isEntry && !wide ? "kb-tab-form" : undefined}>
323        <input type="hidden" name="sha" value={file.sha} />
324        <input type="hidden" name="original" value={file.raw} />
325        <input type="hidden" name="model" value={modelJson} />
326
327        {gapFields.length > 0 || nested.length > 0 ? (
328          <Panel title="Needs info" count={gapFields.length + nested.length} description="Values nobody has yet. Fill one in here and it is saved with the rest; leave it empty and it keeps its reason.">
329            <div className="kb-fields">{gapFields.map(input)}</div>
330            {nested.length > 0 ? (
331              <ul className="kb-nested-gaps">
332                {nested.map((g) => (
333                  <li key={`${g.field}#${g.reason}`}>
334                    <a href={`#${g.anchor}`} onClick={(e) => goTo(e, g.anchor)}>
335                      {g.label}
336                    </a>
337                    : {g.reason}
338                  </li>
339                ))}
340              </ul>
341            ) : null}
342          </Panel>
343        ) : null}
344
345        <Panel title="Details">
346          <div className="kb-fields">{otherFields.map(input)}</div>
347        </Panel>
348
349        {body ? <BodyEditor body={body} flags={form.flags} inserts={inserts} onChange={setBody} onInsert={onInsert} /> : null}
350
351        <div className="kb-savebar">
352          <KbCheckSave busy={busy} actionData={actionData} errors={errors} />
353        </div>
354      </Form>
355      {isEntry ? (
356        <aside className="kb-pane-preview" id="kb-pane-preview" role={wide ? undefined : "tabpanel"} aria-labelledby={wide ? undefined : "kb-tab-preview"} aria-label={wide ? "Preview" : undefined}>
357          <PreviewPane result={preview.result} busy={preview.busy} publicHref={file.publicHref} />
358        </aside>
359      ) : null}
360      </div>
361    </div>
362  );
363}