app/routes/mentions.tsx

Functions

Imports

It imports app/components/project-tabs.tsx, app/lib/context.ts, app/lib/mentions.server.ts, app/lib/projects.server.ts, app/lib/sites.server.ts. No module of this repo imports it.

Source

1// The webmention queue for a site: what other sites sent about its posts, in one table, filtered by
2// status. The Owner approves, rejects or deletes the chosen mentions and sweeps the expired ones; each
3// write goes to the site, which saves it and clears the post's cache as one step. Everything a
4// stranger sent is drawn as text: the source address is never a link.
5
6import { useEffect, useRef, useState } from "react";
7import { Form, Link, useRevalidator } from "react-router";
8import { Alert, Banner } from "capsomer/react/banner";
9import { BulkBar } from "capsomer/react/bulk-bar";
10import { Button } from "capsomer/react/button";
11import { ConfirmDialog } from "capsomer/react/confirm-dialog";
12import { Empty } from "capsomer/react/empty";
13import { Field } from "capsomer/react/field";
14import { Panel } from "capsomer/react/panel";
15import { Select } from "capsomer/react/select";
16import { Pill, Status } from "capsomer/react/status";
17import { Time } from "capsomer/react/time";
18import { PageHead } from "capsomer/react/page-head";
19
20import { ProjectTabs } from "~/components/project-tabs";
21
22import { getEnv, getViewer } from "~/lib/context";
23import { isMentionFilter, listMentions, mentionsOffered, type MentionFilter } from "~/lib/mentions.server";
24import { requireSiteProject } from "~/lib/projects.server";
25import { siteEntry } from "~/lib/sites.server";
26
27import type { Route } from "./+types/mentions";
28
29export function meta({ loaderData: data }: Route.MetaArgs) {
30  return [{ title: data ? `Mentions · ${data.project.name} · Carrel` : "Carrel" }];
31}
32
33const FILTER_LABEL: Record<MentionFilter, string> = {
34  pending: "Pending",
35  failed: "Failed",
36  approved: "Approved",
37  rejected: "Rejected",
38  unverified: "Unverified",
39  all: "All",
40};
41
42const EMPTY_LINE: Record<MentionFilter, string> = {
43  pending: "No pending mentions.",
44  failed: "No failed mentions.",
45  approved: "No approved mentions.",
46  rejected: "No rejected mentions.",
47  unverified: "No unverified mentions.",
48  all: "No mentions yet.",
49};
50
51export async function loader({ params, request, context }: Route.LoaderArgs) {
52  const env = getEnv(context);
53  // The Owner's alone, as Dustin ruled for the inbox (2026-09-26): anyone else is refused before the site is asked.
54  const project = await requireSiteProject(env.DB, getViewer(context), params.project, "read_mentions");
55  const head = { slug: project.slug, name: project.name, site: siteEntry(project.site).name, mentions: true };
56  const support = await mentionsOffered(env, project);
57  if (!support.offered) return { project: head, offered: false as const, reason: support.reason };
58  const url = new URL(request.url);
59  const requested = url.searchParams.get("status");
60  try {
61    const { filter, list } = await listMentions(env, project, {
62      filter: isMentionFilter(requested) ? requested : null,
63      cursor: url.searchParams.get("cursor") || undefined,
64    });
65    return { project: head, offered: true as const, filter, list, paged: url.searchParams.has("cursor") };
66  } catch (error) {
67    console.error(JSON.stringify({ mentions: "list-failed", error: String(error) }));
68    return { project: head, offered: false as const, reason: "The site did not answer, so its mentions cannot be listed. Try again in a moment." };
69  }
70}
71
72type Outcome = { id: string; ok: boolean; message: string };
73type Op = "approve" | "reject" | "delete";
74
75const DONE = "Done. The result for each mention is listed below the table.";
76
77export default function Mentions({ loaderData }: Route.ComponentProps) {
78  const { project } = loaderData;
79  const revalidator = useRevalidator();
80  const [selected, setSelected] = useState<string[]>([]);
81  const [result, setResult] = useState<{ what: string; outcomes: Outcome[] } | null>(null);
82  const [sweepNote, setSweepNote] = useState<{ ok: boolean; message: string } | null>(null);
83  const [sweepOpen, setSweepOpen] = useState(false);
84  const sweepOpener = useRef<HTMLElement | null>(null);
85  const resultRef = useRef<HTMLElement>(null);
86  useEffect(() => {
87    if (!result) return;
88    const el = resultRef.current;
89    if (el) {
90      el.tabIndex = -1;
91      el.focus();
92    }
93  }, [result]);
94
95  if (!loaderData.offered) {
96    return (
97      <div className="app-page">
98        <PageHead title={project.name} lead={`Webmentions about posts on ${project.site}.`} />
99        <ProjectTabs slug={project.slug} current="mentions" mentions />
100        <Banner tone="warn" title="Mentions are not available for this site yet">
101          {loaderData.reason}
102        </Banner>
103      </div>
104    );
105  }
106
107  const { filter, list, paged } = loaderData;
108  const items = list.items;
109  const names = new Map(items.map((m) => [m.id, m.authorName ?? "An unnamed sender"]));
110  const chosen = items.filter((m) => selected.includes(m.id));
111  const expired = list.expiring.failed + list.expiring.rejected;
112  const total = Object.values(list.counts).reduce((a, b) => a + b, 0);
113  const base = `/p/${encodeURIComponent(project.slug)}/mentions/api`;
114
115  const post = async (form: FormData) => {
116    const response = await fetch(base, { method: "POST", body: form, headers: { accept: "application/json" } });
117    const body = (await response.json().catch(() => null)) as { results?: Outcome[]; sweep?: { ok: boolean; message: string }; error?: string } | null;
118    if (!response.ok || !body) throw new Error(body?.error ?? `The server answered ${response.status}.`);
119    return body;
120  };
121
122  const run = (op: Op, what: string) => async (picked: readonly { id: string; label: string }[]) => {
123    const form = new FormData();
124    form.set("op", op);
125    const sent = items.filter((m) => picked.some((p) => p.id === m.id)).map((m) => ({ id: m.id, version: m.version, status: m.status }));
126    form.set("items", JSON.stringify(sent));
127    const body = await post(form);
128    if (!body.results) throw new Error(body.error ?? "The server gave no result.");
129    setResult({ what, outcomes: body.results });
130    // A mention that was acted on has moved or gone, so it leaves the selection.
131    setSelected((now) => now.filter((id) => !body.results!.some((o) => o.id === id && o.ok)));
132    void revalidator.revalidate();
133  };
134
135  const sweep = async () => {
136    const form = new FormData();
137    form.set("op", "sweep");
138    const body = await post(form);
139    if (!body.sweep) throw new Error(body.error ?? "The server gave no result.");
140    setSweepNote(body.sweep);
141    void revalidator.revalidate();
142    if (!body.sweep.ok) throw new Error(body.sweep.message);
143  };
144
145  const filtered = filter !== "all";
146  const countIn = (f: MentionFilter) => (f === "all" ? total : list.counts[f]);
147
148  return (
149    <div className="app-page">
150      <PageHead
151        title={project.name}
152        lead={
153          filter === "pending" && items.length > 0
154            ? `Webmentions about posts on ${project.site}. Approving one shows it on the post within seconds.`
155            : `Webmentions about posts on ${project.site}.`
156        }
157      />
158
159      <ProjectTabs slug={project.slug} current="mentions" mentions />
160
161      {/* The status region is always in the DOM, so a result is announced. */}
162      <div role="status">{sweepNote?.ok ? <Banner tone="ok">{sweepNote.message}</Banner> : null}</div>
163      {sweepNote && !sweepNote.ok ? <Alert tone="crit">{sweepNote.message}</Alert> : null}
164
165      {result ? (
166        <Panel
167          title="Result"
168          id="mention-result"
169          ref={resultRef}
170          src={`${result.what}: ${result.outcomes.filter((o) => o.ok).length} of ${result.outcomes.length} done`}
171          actions={
172            <Button size="sm" onClick={() => setResult(null)}>
173              Clear this result
174            </Button>
175          }
176        >
177          <ul className="app-flags" aria-label="Result for each mention">
178            {result.outcomes.map((o) => (
179              <li key={o.id}>
180                {o.ok ? <Status tone="ok">Done</Status> : <Status tone="crit">Left as it was</Status>}
181                <span>
182                  <strong>{names.get(o.id) ?? `Mention ${o.id}`}</strong> <span className="cap-mono cap-muted">{o.id}</span>
183                  <br />
184                  {o.message}
185                </span>
186              </li>
187            ))}
188          </ul>
189        </Panel>
190      ) : null}
191
192      <Panel title="Mentions" count={items.length} src={`${FILTER_LABEL[filter]} on ${project.site}`} flush>
193        <div className="cap-panel-pad">
194          <Form method="get" className="app-filters" role="search" aria-label="Filter mentions">
195            <Field label="Status">
196              <Select
197                name="status"
198                defaultValue={filter}
199                options={(["pending", "failed", "approved", "rejected", "unverified", "all"] as const).map((f) => ({ value: f, label: `${FILTER_LABEL[f]} (${countIn(f)})` }))}
200              />
201            </Field>
202            <div className="app-actions">
203              <Button type="submit" variant="primary">
204                Filter
205              </Button>
206            </div>
207          </Form>
208        </div>
209
210        {items.length === 0 ? (
211          <Empty kind={filtered ? "all-clear" : "nothing-yet"} flush title={EMPTY_LINE[filter]}>
212            {total === 0 ? "Nothing has been sent to this site yet." : `${total} mention${total === 1 ? "" : "s"} in other views.`}
213          </Empty>
214        ) : (
215          <div className="cap-table-wrap" role="region" aria-labelledby="mentions-caption" tabIndex={0}>
216            <table className="cap-table">
217              <caption id="mentions-caption" className="cap-sr-only">
218                {FILTER_LABEL[filter]} mentions of posts on {project.site}
219              </caption>
220              <thead>
221                <tr>
222                  <th scope="col">
223                    <span className="cap-sr-only">Select</span>
224                  </th>
225                  <th scope="col">From</th>
226                  <th scope="col">What it says</th>
227                  <th scope="col">Post</th>
228                  <th scope="col">Status</th>
229                  <th scope="col">Received</th>
230                </tr>
231              </thead>
232              <tbody>
233                {items.map((m) => {
234                  const from = m.authorName ?? "an unnamed sender";
235                  return (
236                    <tr key={m.id} data-state={selected.includes(m.id) ? "selected" : undefined}>
237                      <td>
238                        <label className="cap-check">
239                          <input
240                            type="checkbox"
241                            checked={selected.includes(m.id)}
242                            onChange={(event) => setSelected((now) => (event.target.checked ? [...now, m.id] : now.filter((id) => id !== m.id)))}
243                          />
244                          <span className="cap-sr-only">Select the mention from {from}</span>
245                        </label>
246                      </td>
247                      <th scope="row" data-wrap>
248                        {m.authorName ?? "An unnamed sender"}
249                        {/* Text, not a link: the sender chose this string. */}
250                        <span className="cap-table-aside" data-mention-source="">
251                          {m.sourceUrl}
252                        </span>
253                      </th>
254                      <td data-wrap>
255                        {m.excerpt ?? <span className="cap-muted">No excerpt</span>}
256                        {m.failureReason ? <span className="cap-table-aside">Reason: {m.failureReason}</span> : null}
257                      </td>
258                      <td>
259                        <Link to={`/p/${encodeURIComponent(project.slug)}/e/${encodeURIComponent(m.targetId)}`}>{m.targetId}</Link>
260                      </td>
261                      <td>
262                        {m.status === "approved" ? (
263                          <Pill tone="ok">Approved</Pill>
264                        ) : m.status === "pending" ? (
265                          <Pill tone="info">Pending</Pill>
266                        ) : m.status === "failed" ? (
267                          <Pill tone="crit">Failed</Pill>
268                        ) : (
269                          <Pill variant="secondary">{m.status === "rejected" ? "Rejected" : "Unverified"}</Pill>
270                        )}
271                        {m.decidedAt ? (
272                          <span className="cap-table-aside">
273                            Decided <Time at={m.decidedAt} />
274                          </span>
275                        ) : null}
276                      </td>
277                      <td>
278                        <Time at={m.receivedAt} />
279                      </td>
280                    </tr>
281                  );
282                })}
283              </tbody>
284            </table>
285          </div>
286        )}
287
288        {list.nextCursor || paged ? (
289          <div className="cap-panel-pad app-actions">
290            {paged ? (
291              <Link to={`?status=${filter}`} className="cap-btn">
292                First page
293              </Link>
294            ) : null}
295            {list.nextCursor ? (
296              <Link to={`?status=${filter}&cursor=${encodeURIComponent(list.nextCursor)}`} className="cap-btn">
297                Next page
298              </Link>
299            ) : null}
300          </div>
301        ) : null}
302      </Panel>
303
304      <Panel title="Retention">
305        <p>The site removes failed and rejected mentions once they pass its retention window. Pending and approved ones are never removed.</p>
306        <p>
307          {expired === 0
308            ? "None are past the window now."
309            : `${expired} past the window now: ${list.expiring.failed} failed, ${list.expiring.rejected} rejected.`}
310        </p>
311        <div className="app-actions">
312          <Button
313            disabledReason={expired === 0 ? "Nothing is past the retention window." : undefined}
314            onClick={(event) => {
315              sweepOpener.current = event.currentTarget;
316              setSweepOpen(true);
317            }}
318          >
319            Remove {expired} expired
320          </Button>
321        </div>
322      </Panel>
323
324      <BulkBar
325        items={chosen.map((m) => ({ id: m.id, label: `${m.authorName ?? "An unnamed sender"} on ${m.targetId} (${m.status})` }))}
326        total={items.length}
327        onSelectAll={() => setSelected(items.map((m) => m.id))}
328        onClear={() => setSelected([])}
329        actions={[
330          { id: "approve", label: "Approve", said: DONE, run: run("approve", "Approve") },
331          { id: "reject", label: "Reject", said: DONE, run: run("reject", "Reject") },
332          {
333            id: "delete",
334            label: "Delete",
335            destructive: true,
336            confirmTitle: "Delete {n} mention{s} permanently?",
337            confirmLead: `Each mention below is removed from ${project.site}. This removes the only copy of what the sender sent; nothing else has one. Reject it instead if you may want it back.`,
338            confirmAction: "Delete {n} mention{s}",
339            said: DONE,
340            run: run("delete", "Delete"),
341          },
342        ]}
343      />
344
345      <ConfirmDialog
346        open={sweepOpen}
347        title={`Remove ${expired} expired mention${expired === 1 ? "" : "s"}?`}
348        lead="The site removes these permanently. Nothing else has a copy of them."
349        body={[`${list.expiring.failed} failed`, `${list.expiring.rejected} rejected`]}
350        action={`Remove ${expired}`}
351        returnTo={sweepOpener.current}
352        perform={sweep}
353        onClose={() => setSweepOpen(false)}
354      />
355    </div>
356  );
357}