app/routes/admin.kb.tsx

Functions

Imports

It imports app/components/admin/tab-link.tsx, app/db/procedures.ts, app/db/registry.ts, app/kb/admin.mjs, app/kb/bases.mjs, app/lib/context.ts, app/lib/timing.ts. No module of this repo imports it.

Source

1import { Form, Link, data } from "react-router";
2
3import { Empty } from "capsomer/react/empty";
4import { Panel } from "capsomer/react/panel";
5import { Row, RowList, type RowLinkProps } from "capsomer/react/row-list";
6import { Status } from "capsomer/react/status";
7import { TabsNav } from "capsomer/react/tabs";
8
9import { PageHead } from "capsomer/react/page-head";
10import { TabLink } from "~/components/admin/tab-link";
11import { listProceduresForAdmin } from "~/db/procedures";
12import { listRegistry } from "~/db/registry";
13import { KB_ADMIN_PATH, NEEDS_INFO, baseEntries, entryEditHref, kbTabs, needsInfo, resolveTab, tabHref } from "~/kb/admin.mjs";
14import { BASES } from "~/kb/bases.mjs";
15import { getEnv } from "~/lib/context";
16import { timed, timedLoader } from "~/lib/timing";
17
18import type { Route } from "./+types/admin.kb";
19
20/*
21 * The Knowledge Base (docs/KNOWLEDGE-BASE.md, steps 2 and 3): a tab per base listing its entries, and Needs info, every
22 * recorded gap on one screen. This page has no action: a row opens its file in the editor (admin.kb.entry.tsx and
23 * admin.kb.item.tsx), which saves through the save the operator API uses. Owner-only like every admin page.
24 */
25
26export function meta() {
27  return [{ title: "Knowledge Base · Admin" }, { name: "robots", content: "noindex" }];
28}
29
30export async function loader({ request, context }: Route.LoaderArgs) {
31  return timedLoader(context, async (timings) => {
32    const env = getEnv(context);
33    const url = new URL(request.url);
34    const [entries, items] = await Promise.all([
35      timed(timings, "d1_list_procedures", () => listProceduresForAdmin(env)),
36      timed(timings, "d1_list_registry", () => listRegistry(env)),
37    ]);
38    const tab = resolveTab(url.searchParams.get("tab"));
39    const q = (url.searchParams.get("q") ?? "").trim();
40    const gaps = needsInfo(entries, items);
41    return data({
42      tab,
43      q,
44      tabs: kbTabs(entries, gaps),
45      rows: baseEntries(entries, tab, q),
46      gaps: tab === NEEDS_INFO ? gaps : [],
47    });
48  });
49}
50
51/** A row opens its file in the editor, inside the admin. */
52function AdminLink({ href, children, ...rest }: RowLinkProps) {
53  return (
54    <Link to={href} {...rest}>
55      {children}
56    </Link>
57  );
58}
59
60/** The public page, a document navigation since the public pages bring their own stylesheets; named for its row. */
61function ViewLink({ href, what }: { href: string; what: string }) {
62  return (
63    <Link to={href} reloadDocument className="cap-btn" data-variant="quiet" data-size="sm" aria-label={`View the page for ${what}`}>
64      View page
65    </Link>
66  );
67}
68
69function plural(count: number, one: string, many: string) {
70  return `${count} ${count === 1 ? one : many}`;
71}
72
73export default function AdminKnowledgeBase({ loaderData }: Route.ComponentProps) {
74  const { tab, q, tabs, rows, gaps } = loaderData;
75  const base = BASES.find((b) => b.id === tab);
76  const total = tabs.find((t) => t.id === tab)?.count ?? 0;
77
78  return (
79    <div className="app-page">
80      <PageHead
81        title="Knowledge Base"
82        lead={
83          tab === NEEDS_INFO
84            ? `${plural(gaps.length, "value", "values")} waiting on someone who has it, across every entry and registry item.`
85            : "Protocols, software how-tos and recipes. Each entry is a file in the repository; this page reads them."
86        }
87      />
88
89      <TabsNav aria-label="Knowledge bases" variant="line">
90        {tabs.map((t) => (
91          <TabLink
92            key={t.id}
93            to={tabHref(t.id, q)}
94            current={t.id === tab}
95            count={t.count}
96            aria-label={`${t.label}, ${plural(t.count, t.id === NEEDS_INFO ? "gap" : "entry", t.id === NEEDS_INFO ? "gaps" : "entries")}`}
97          >
98            {t.label}
99          </TabLink>
100        ))}
101      </TabsNav>
102
103      {base ? (
104        <>
105          <Form method="get" action={KB_ADMIN_PATH} role="search" className="app-filters">
106            <input type="hidden" name="tab" value={tab} />
107            <div className="cap-field">
108              <label className="cap-field-label" htmlFor="kb-q">
109                Search {base.name.toLowerCase()}
110              </label>
111              <input
112                id="kb-q"
113                className="cap-input"
114                type="search"
115                name="q"
116                defaultValue={q}
117                placeholder="Title, description or slug"
118              />
119            </div>
120          </Form>
121
122          {rows.length === 0 ? (
123            <Empty kind={total === 0 ? "nothing-yet" : "no-match"}>
124              {total === 0 ? `No ${base.name.toLowerCase()} yet.` : `Nothing in ${base.name.toLowerCase()} matches "${q}".`}
125            </Empty>
126          ) : (
127            <Panel title={base.name} count={rows.length} flush>
128              <RowList label={base.name}>
129                {rows.map((entry) => (
130                  <Row
131                    key={entry.slug}
132                    title={entry.title}
133                    href={entryEditHref(entry.slug)}
134                    renderLink={AdminLink}
135                    actions={<ViewLink href={entry.path} what={entry.title} />}
136                    status={<Status tone={entry.draft ? "nodata" : "ok"}>{entry.draft ? "draft" : "published"}</Status>}
137                    detail={entry.description}
138                    meta={
139                      <span>
140                        {[
141                          entry.path,
142                          entry.version ? `version ${entry.version}` : "no version yet",
143                          entry.updated ? `updated ${entry.updated}` : null,
144                          entry.gaps.length > 0 ? plural(entry.gaps.length, "gap", "gaps") : null,
145                        ]
146                          .filter(Boolean)
147                          .join(", ")}
148                      </span>
149                    }
150                  />
151                ))}
152              </RowList>
153            </Panel>
154          )}
155        </>
156      ) : gaps.length === 0 ? (
157        <Empty kind="all-clear">Nothing is waiting on information.</Empty>
158      ) : (
159        <Panel title="Needs info" count={gaps.length} flush>
160          <RowList label="Needs info">
161            {gaps.map((gap) => (
162              <Row
163                key={`${gap.href}#${gap.what}#${gap.field}`}
164                title={gap.what}
165                href={gap.editHref}
166                renderLink={AdminLink}
167                actions={<ViewLink href={gap.href} what={gap.what} />}
168                status={<Status tone="warn">{gap.kindLabel}</Status>}
169                // What is missing, in words, then why; the row opens the editor at the field it is filled in at.
170                detail={
171                  <>
172                    <strong>{gap.label}</strong>: {gap.reason}
173                  </>
174                }
175              />
176            ))}
177          </RowList>
178        </Panel>
179      )}
180    </div>
181  );
182}