app/components/admin/kb-file-editor.tsx

Functions

Imports

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

Source

1import { 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 { MarkdownEditor } from "capsomer/react/markdown-editor";
7import { Panel } from "capsomer/react/panel";
8import { Row, RowList } from "capsomer/react/row-list";
9
10import { PageHead } from "capsomer/react/page-head";
11import { crumbLink } from "~/components/admin/shell-parts";
12import type { KbFile, KbGap } from "~/kb/editor.server";
13
14/** What the action hands back: a check's verdict, or a save that did not land, with the text the reader sent. */
15export type KbEditorActionData =
16  | { intent: "check"; raw: string; model?: string; ok: boolean; errors: string[]; gaps: KbGap[] }
17  | { intent: "save"; raw: string; model?: string; refused?: string[]; conflict?: string }
18  | { intent: "duplicate"; raw: string; refused: string[] };
19
20// Read off the document, not loader data, as the post editor does: the IDL property, since browsers hide the attribute.
21function documentCspNonce(): string {
22  if (typeof document === "undefined") return "";
23  return document.querySelector<HTMLScriptElement>("script[nonce]")?.nonce ?? "";
24}
25
26export function plural(count: number, one: string, many: string) {
27  return `${count} ${count === 1 ? one : many}`;
28}
29
30/**
31 * Check and Save, and what the last one said, for the file editor and the form editor alike. The answer sits beside the
32 * buttons that ask for it, so a Check's answer is in view. The status region is always in the DOM, so a result is
33 * announced; a refusal is an alert. `onFile` names the committed file when no Check has run yet.
34 */
35export function KbCheckSave({ busy, actionData, errors, onFile = false }: { busy: string; actionData?: KbEditorActionData; errors: string[]; onFile?: boolean }) {
36  const checked = actionData?.intent === "check" ? actionData : null;
37  return (
38    <>
39      <div className="app-actions">
40        <Button type="submit" name="intent" value="check" pending={busy === "check"}>
41          Check
42        </Button>
43        <Button type="submit" name="intent" value="save" variant="primary" pending={busy === "save"}>
44          Save
45        </Button>
46      </div>
47      <div role="status">{checked?.ok ? <Banner tone="ok">Passes every check. Nothing was saved.</Banner> : null}</div>
48      {actionData?.intent === "save" && actionData.conflict ? (
49        <Alert tone="crit" title="Not saved">
50          {actionData.conflict}
51        </Alert>
52      ) : null}
53      {errors.length > 0 ? (
54        <Alert tone="crit" title={`${plural(errors.length, "check fails", "checks fail")}${onFile && !checked ? " on this file" : ""}`}>
55          <ul>
56            {errors.map((error) => (
57              <li key={error}>{error}</li>
58            ))}
59          </ul>
60        </Alert>
61      ) : null}
62    </>
63  );
64}
65
66/**
67 * One Knowledge Base file (docs/KNOWLEDGE-BASE.md, step 3), an entry or a registry item, edited as the file it is. Check
68 * runs the save's own checks and commits nothing; Save commits through the save the operator API uses. Without script the
69 * editor is a plain textarea in the same form, so both buttons still work.
70 */
71export function KbFileEditor({
72  file,
73  actionData,
74  saved,
75}: {
76  file: KbFile;
77  actionData?: KbEditorActionData;
78  saved?: { commit: string; unchanged: boolean } | null;
79}) {
80  const navigation = useNavigation();
81  const busy = navigation.state === "submitting" ? String(navigation.formData?.get("intent") ?? "") : "";
82  const [raw, setRaw] = useState(actionData?.raw ?? file.raw);
83
84  // The latest word on the file: a check just run, else what the loader's check said of the committed file.
85  const checked = actionData?.intent === "check" ? actionData : null;
86  const errors = checked ? checked.errors : actionData?.intent === "save" && actionData.refused ? actionData.refused : file.errors;
87  const gaps = checked ? checked.gaps : file.gaps;
88
89  return (
90    <div className="app-page">
91      <PageHead
92        renderLink={crumbLink}
93        crumbs={[
94          { label: "Knowledge Base", href: "/admin/kb" },
95          { label: file.group, href: file.listHref },
96        ]}
97        title={file.title}
98        actions={
99          <Link to={{ search: "" }} className="cap-btn" data-variant="quiet">
100            Back to the form
101          </Link>
102        }
103        lead={
104          <>
105            <code>{file.file}</code>
106            {file.publicHref ? (
107              <>
108                {" "}
109                <Link to={file.publicHref} reloadDocument>
110                  View the page
111                </Link>
112              </>
113            ) : null}
114          </>
115        }
116      />
117
118      {saved ? (
119        <Banner tone="ok">
120          {saved.unchanged
121            ? "Nothing to commit: the file was already this. Its page was brought up to date."
122            : `Saved as commit ${saved.commit}. The page shows it on the next visit.`}
123        </Banner>
124      ) : null}
125
126      <Form method="post" className="kb-editor-form">
127        <input type="hidden" name="sha" value={file.sha} />
128        <MarkdownEditor
129          label="File"
130          ariaLabel="File, markdown with front matter"
131          id="kb-file"
132          name="raw"
133          value={raw}
134          onChange={setRaw}
135          nonce={documentCspNonce()}
136          lineNumbers
137          help={
138            file.target.type === "entry"
139              ? "The whole file: its fields between the --- lines, then the steps with their marks. Check runs every check a save runs and saves nothing."
140              : "The whole file: the item's fields between the --- lines, and nothing after them. Check runs every check a save runs and saves nothing."
141          }
142        />
143        <KbCheckSave busy={busy} actionData={actionData} errors={errors} onFile />
144      </Form>
145
146      {gaps.length > 0 ? (
147        <Panel title="Needs info" count={gaps.length} flush>
148          <RowList label="Needs info">
149            {gaps.map((gap) => (
150              <Row key={`${gap.field}#${gap.reason}`} title={<code>{gap.field}</code>} detail={gap.reason} />
151            ))}
152          </RowList>
153        </Panel>
154      ) : null}
155    </div>
156  );
157}