atom-html.ts · Source

atom-html.tspackages/editor/src/atom-html.tsraw ← src3,066 B← Back to the app
1/**
2 * Atom ↔ HTML bridge (T-148 web wiring).
3 *
4 * The canonical stored form of an atom-bearing text block is `{ text }` with
5 * the inline-atom tokens (`@date(…)` / `@status(…)` / `@label(…)`). The web
6 * editor renders atoms as Tiptap atom nodes (see `nodes/inline-atom.ts`),
7 * whose HTML is `<span class="factory-atom" data-atom-kind data-atom-value>…</span>`.
8 *
9 * These two pure functions convert between the two forms:
10 *   - `atomTextToHtml(text)`: `{text}` from the API → HTML for the Tiptap
11 *     editor (text segments ESCAPED — stored text is untrusted data).
12 *   - `atomHtmlToText(html)`: editor HTML → `{text}` token form for the API
13 *     (atoms become tokens; formatting tags are stripped — the stored form
14 *     is plain text by contract).
15 *
16 * Neither function emits executable markup: every dynamic value goes through
17 * `escapeHtml`, and the label value in particular may contain anything
18 * (XSS vector) — it is rendered as text, never as HTML.
19 */
20 
21import { parseInlineAtoms, formatDateAtom, STATUS_VALUES } from "./inline-atoms.js";
22 
23function escapeHtml(s: string): string {
24  return s
25    .replace(/&/g, "&amp;")
26    .replace(/</g, "&lt;")
27    .replace(/>/g, "&gt;")
28    .replace(/"/g, "&quot;");
29}
30 
31function unescapeHtml(s: string): string {
32  return s
33    .replace(/&quot;/g, '"')
34    .replace(/&lt;/g, "<")
35    .replace(/&gt;/g, ">")
36    .replace(/&amp;/g, "&");
37}
38 
39function atomSpan(kind: string, value: string): string {
40  return `<span class="factory-atom" data-atom-kind="${escapeHtml(kind)}" data-atom-value="${escapeHtml(value)}">${escapeHtml(
41    kind === "date" ? formatDateAtom(value) : kind === "status" ? value : value
42  )}</span>`;
43}
44 
45/** Stored plain text (may contain atom tokens) → HTML for the Tiptap editor. */
46export function atomTextToHtml(text: string): string {
47  return parseInlineAtoms(text)
48    .map((seg) =>
49      seg.type === "text" ? escapeHtml(seg.text) : atomSpan(seg.kind, seg.value)
50    )
51    .join("");
52}
53 
54/**
55 * Editor HTML → stored plain text. Atoms become tokens; other markup is
56 * stripped (the stored form is plain text). Returns `null` when the HTML has
57 * no atoms — the caller should then keep the original content untouched
58 * (preserving the block's existing formatting/HTML for atom-less blocks).
59 */
60export function atomHtmlToText(html: string): string | null {
61  if (!html.includes('class="factory-atom"')) return null;
62  const out = html
63    .replace(
64      /<span class="factory-atom" data-atom-kind="([^"]*)" data-atom-value="([^"]*)">[\s\S]*?<\/span>/g,
65      (_m, kind: string, rawValue: string) => {
66        const value = unescapeHtml(rawValue);
67        if (kind === "status" && !STATUS_VALUES.includes(value as (typeof STATUS_VALUES)[number])) {
68          return value; // unknown status → keep as plain text, don't forge a token
69        }
70        return `@${kind}(${value})`;
71      }
72    )
73    .replace(/<br\s*\/?>/gi, "\n")
74    .replace(/<\/(p|div)>/gi, "\n")
75    .replace(/<[^>]+>/g, "")
76    .replace(/\n{3,}/g, "\n\n")
77    .trim();
78  return out;
79}
80