app/lib/legal.ts

Functions

Imports

It imports app/lib/frontmatter.ts. Imported by app/components/editor/frontmatter-fields.tsx, app/lib/legal.server.ts, app/routes/legal.tsx.

Source

1// Legal pages: a privacy or terms page is an ordinary page on the site, with a few fields in its
2// frontmatter and shared sections in its body. A shared section is written once in Carrel and
3// reused by every site's page; a site's own facts are the fields. Each site still publishes its own
4// page, so the shared text reaches a site only when its page is published. Pure, so the server, the
5// editor and the tests read it the same way.
6
7import { joinSource, splitSource } from "@dustinedwards/site-api/frontmatter";
8import { readFields, setField } from "~/lib/frontmatter";
9
10export const LEGAL_TYPES = ["privacy", "terms"] as const;
11export type LegalType = (typeof LEGAL_TYPES)[number];
12
13/** The id a site gives each legal page; the page's address is registered on the site, never made here. */
14export const legalItemId = (type: LegalType) => `page.${type}`;
15
16/** The fields a shared section may name as `{{site_name}}`: the site's own facts. */
17const VARIABLES = ["site_name", "operator_name", "contact", "jurisdiction", "data_held"] as const;
18type Variable = (typeof VARIABLES)[number];
19
20export const SECTION_KEY = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
21
22/** Reads the frontmatter's `legal_type`, or null when the source is not a legal page. */
23export function legalTypeOf(source: string): LegalType | null {
24  const { front } = splitSource(source);
25  if (front === null) return null;
26  const match = /^legal_type:\s*["']?([a-z]+)["']?\s*$/m.exec(front);
27  return LEGAL_TYPES.find((t) => t === match?.[1]) ?? null;
28}
29
30/** The `path:` line of a source's frontmatter, or null. */
31export function pathOf(source: string): string | null {
32  const { front } = splitSource(source);
33  const match = front === null ? null : /^path:\s*["']?([^"'\r\n]*?)["']?\s*$/m.exec(front);
34  return match ? match[1]! : null;
35}
36
37export const marker = (key: string) => `<!-- shared:${key} -->`;
38
39// An opening marker, and the closing one when the section was already expanded.
40const BLOCK = /<!--\s*shared:([a-z0-9-]+)\s*-->(?:[\s\S]*?<!--\s*\/shared:\1\s*-->)?/g;
41const TOKEN = /\{\{\s*([a-z_]+)\s*\}\}/g;
42
43export type SharedSection = { key: string; title: string; body: string };
44
45export type Expansion = {
46  text: string;
47  /** Section keys the body names that Carrel does not have. They are left as written. */
48  unknownSections: string[];
49  /** Fields a used section needs and the page leaves empty. The token stays in the text. */
50  missingFields: string[];
51};
52
53/** The keys of the shared sections a body names, in order. */
54export function sectionsUsed(body: string): string[] {
55  return [...body.matchAll(BLOCK)].map((m) => m[1]!);
56}
57
58/**
59 * The body with each shared section's text written between its markers, the page's own fields
60 * filled in. Running it again on its own output changes nothing, so a page can be expanded on every
61 * write and compared with what is stored.
62 */
63export function expandShared(body: string, sections: readonly SharedSection[], values: Partial<Record<Variable, string>>): Expansion {
64  const unknownSections: string[] = [];
65  const missingFields: string[] = [];
66  const text = body.replace(BLOCK, (whole, key: string) => {
67    const section = sections.find((s) => s.key === key);
68    if (!section) {
69      unknownSections.push(key);
70      return whole;
71    }
72    const filled = section.body.replace(TOKEN, (token, name: string) => {
73      if (!(VARIABLES as readonly string[]).includes(name)) return token;
74      const value = values[name as Variable]?.trim();
75      if (value) return value;
76      if (!missingFields.includes(name)) missingFields.push(name);
77      return token;
78    });
79    return `${marker(key)}\n${filled.trim()}\n<!-- /shared:${key} -->`;
80  });
81  return { text, unknownSections, missingFields };
82}
83
84/** The page's own facts, from its frontmatter, for the sections that name them. */
85export function valuesOf(source: string): Partial<Record<Variable, string>> {
86  const fields = readFields(splitSource(source).front);
87  return Object.fromEntries(VARIABLES.map((v) => [v, fields[v]]));
88}
89
90export type LegalWrite = { ok: true; source: string } | { ok: false; message: string };
91
92/**
93 * What goes to the site for a write to a legal page: shared sections expanded, and `last_updated`
94 * stamped when the write makes a changed body public. Saving a draft only expands what it can: a
95 * missing field is no reason to lose work, but a page that would go public with `{{operator_name}}`
96 * still in it, or a section that does not exist, is refused with the field or key named.
97 *
98 * `public` is true for a publish, and for a save to a page that is already live.
99 */
100export function prepareLegalWrite(input: { source: string; stored: string | null; storedPublic: boolean; sections: readonly SharedSection[]; public: boolean; today: string }): LegalWrite {
101  const parts = splitSource(input.source);
102  if (parts.front === null) return { ok: false, message: "A legal page keeps its details in frontmatter, and this text has none." };
103  const expansion = expandShared(parts.body, input.sections, valuesOf(input.source));
104  if (input.public && expansion.unknownSections.length > 0) {
105    return { ok: false, message: `There is no shared section called ${expansion.unknownSections.map((k) => `"${k}"`).join(", ")}. Add it on the Legal tab or remove its marker.` };
106  }
107  if (input.public && expansion.missingFields.length > 0) {
108    return { ok: false, message: `The shared text needs ${expansion.missingFields.join(", ")} filled in on this page before it goes public.` };
109  }
110  let front = parts.front;
111  const storedBody = input.stored === null ? null : splitSource(input.stored).body;
112  if (input.public && (storedBody !== expansion.text || !input.storedPublic)) front = setField(front, "last_updated", input.today);
113  return { ok: true, source: joinSource({ ...parts, front, body: expansion.text }) };
114}