hecks 3.9.1 → 3.11.0

data/lib/hecks/projections/site/cms_editor/templates/src/ui/fields.ts.tmpl

@@ -0,0 +1,275 @@
+__BANNER__
+
+// The inputs of a form, derived from attributes. A value object is a group of its parts (one with a
+// single part is just that input, named for the attribute); a `list_of` attribute is a run of
+// repeatable rows (the rows it holds, then one blank row to fill, which the page's script lets the
+// person add to, remove and reorder); a lifecycle state is not an input at all. Each input is named
+// by its dotted path (`byline.name`, `body.blocks.0.text`), which input.ts reads back into the shape
+// the command takes. Inputs are plain `input` elements, so a form posts with no script at all. A
+// text a rule bounds above 200 characters is a writing box, a value object with a media key and a
+// description is a picture (its picker opens from the group), and a list whose members hold a body,
+// a picture or a list of their own is drawn as cards (see blocks.ts) so a new member is made from a
+// template, not copied from the page.
+import type { Aggregate, Attr } from "../schema.ts";
+import { SCHEMA } from "../schema.ts";
+import { esc, href } from "./html.ts";
+import { icon } from "./icons.ts";
+import { bodyToFields, bodyToHtml, emptyBody, fieldsToInputs } from "./body_model.js";
+import { heavy } from "./block_list.js";
+import { blockList } from "./blocks.ts";
+import type { Problem } from "./blocks.ts";
+import { isMoment, secondsOf } from "./moments.ts";
+import { datalists, pickerControl } from "./pickers.ts";
+import type { Choices } from "./pickers.ts";
+import { label, limitsNote, singular } from "./words.ts";
+
+type Value = unknown;
+
+/** The field a refusal named and what it said, so the form can mark it and the script can focus it. */
+export interface Invalid {
+  field: string;
+  message: string;
+}
+
+/** What a run of inputs needs to know beyond the attribute: whether to mark required, which field is invalid. */
+interface Context {
+  mark: boolean;
+  invalid?: Invalid | null;
+  top: boolean;
+  /** The row's own heading already names the input, so its label is for assistive technology only. */
+  quiet?: boolean;
+  /** What is on offer for each picker (see pickers.ts); a picker with nothing on offer is a text box. */
+  choices?: Choices;
+  /** The body attribute that is written as a draft: its editor saves by itself (see browser/autosave.js). */
+  draft?: string;
+  /** The blocks of a list of mixed blocks that a refusal named (see blocks.ts). */
+  problems?: Problem[];
+  /** A list is drawn as plain rows, whatever its members hold: it is inside a card's group, one level in. */
+  rows?: boolean;
+}
+
+const inputType = (attr: Attr): string => (attr.kind === "integer" || attr.kind === "number" ? "number" : "text");
+
+const member = (value: Value, key: string): Value => (value && typeof value === "object" ? (value as Record<string, Value>)[key] : undefined);
+
+const idOf = (name: string): string => `f-${name.replace(/[^A-Za-z0-9]+/g, "-")}`;
+
+function caption(attr: Attr, context: Context): string {
+  const text = esc(label(attr.name));
+  if (attr.optional) return `${text} <span class="ml-1 text-xs font-normal text-muted">optional</span>`;
+  return context.mark ? `${text} <span class="text-primary" title="Required" aria-hidden="true">*</span>` : text;
+}
+
+/**
+ * The words of the refusal that is about the field at `name`, or null: the one the command named for this
+ * attribute at the top of the form, or one that names this part of the value object it was about.
+ */
+function refusalAt(attr: Attr, name: string, context: Context): string | null {
+  if (context.top && context.invalid?.field === attr.name) return context.invalid.message;
+  const named = context.problems?.find((one) => one.slots.some((part) => name === `${one.name}.${part}` || name.startsWith(`${one.name}.${part}.`)));
+  return named ? named.message : null;
+}
+
+const flagged = (attr: Attr, name: string, context: Context): boolean => refusalAt(attr, name, context) !== null;
+
+/** The attributes of the control that is invalid: the state and the link to its message (and to its hint, when it has one). */
+function invalidAttrs(name: string, attr: Attr, context: Context, hint = false): string {
+  const ids = [...(hint ? [`${idOf(name)}-hint`] : []), ...(flagged(attr, name, context) ? [`${idOf(name)}-error`] : [])];
+  const described = ids.length > 0 ? ` aria-describedby="${esc(ids.join(" "))}"` : "";
+  return `${flagged(attr, name, context) ? ` aria-invalid="true"` : ""}${described}`;
+}
+
+function problem(name: string, attr: Attr, context: Context): string {
+  const text = refusalAt(attr, name, context);
+  return text !== null ? `<p class="text-xs font-semibold text-error" id="${esc(idOf(name))}-error">${esc(text)}</p>` : "";
+}
+
+/** A moment's input: the seconds in a number input; the script swaps it for a native date input in the viewer's zone. */
+function moment(attr: Attr, name: string, value: Value, context: Context): string {
+  const id = esc(idOf(name));
+  const seconds = secondsOf(value);
+  const classes = flagged(attr, name, context) ? "input input-error w-full max-w-xl" : "input w-full max-w-xl";
+  const required = context.mark && !attr.optional ? ` aria-required="true"` : "";
+  const input = `<input type="number" step="1" class="${classes}" id="${id}" name="${esc(name)}" value="${seconds ?? ""}" data-epoch-raw${required}${invalidAttrs(name, attr, context)}>`;
+  const note = `<p class="text-xs text-muted" data-epoch-note>Whole seconds since 1970, in UTC.</p>`;
+  return `<div class="my-4 grid gap-1" data-moment-field="${esc(attr.widget ?? "datetime")}"><label for="${id}" class="${context.quiet ? "sr-only" : "font-semibold"}">${caption(attr, context)}</label>${input}${note}${problem(name, attr, context)}</div>`;
+}
+
+/** The control a picker stands in for the text box, or null when the attribute has none. */
+function picked(attr: Attr, name: string, value: Value, context: Context): string | null {
+  if (!attr.picker) return null;
+  const held = member(value, "value") ?? value ?? "";
+  const required = context.mark && !attr.optional ? ` aria-required="true"` : "";
+  const control = { id: idOf(name), name, value: String(held), optional: attr.optional, invalid: flagged(attr, name, context), extra: `${required}${invalidAttrs(name, attr, context)}` };
+  return pickerControl(attr.picker, context.choices ?? {}, control);
+}
+
+/** A closed set's members as a native select, with the held value chosen; an optional one may be left unchosen. */
+function select(attr: Attr, name: string, value: Value, context: Context): string {
+  const held = String(member(value, "value") ?? value ?? "");
+  const id = esc(idOf(name));
+  const required = context.mark && !attr.optional ? ` aria-required="true"` : "";
+  const classes = flagged(attr, name, context) ? "select select-error w-full max-w-xl" : "select w-full max-w-xl";
+  const blank = attr.optional || held === "" ? `<option value=""${held === "" ? " selected" : ""}>${attr.optional ? "None" : "Choose"}</option>` : "";
+  const options = (attr.options ?? []).map((option) => `<option value="${esc(option)}"${option === held ? " selected" : ""}>${esc(label(option))}</option>`);
+  const input = `<select class="${classes}" id="${id}" name="${esc(name)}"${required}${invalidAttrs(name, attr, context)}>${blank}${options.join("")}</select>`;
+  return `<div class="my-4 grid gap-1"><label for="${id}" class="${context.quiet ? "sr-only" : "font-semibold"}">${caption(attr, context)}</label>${input}${problem(name, attr, context)}</div>`;
+}
+
+function scalar(attr: Attr, name: string, value: Value, context: Context): string {
+  if (isMoment(attr)) return moment(attr, name, value, context);
+  if (attr.options && !attr.list) return select(attr, name, value, context);
+  const text = esc(member(value, "value") ?? value ?? "");
+  const id = esc(idOf(name));
+  if (attr.kind === "boolean") {
+    return `<div class="my-4 flex items-center gap-2"><input type="checkbox" class="checkbox checkbox-sm" id="${id}" name="${esc(name)}"${value === true ? " checked" : ""}><label for="${id}" class="font-semibold">${caption(attr, context)}</label></div>`;
+  }
+  const step = attr.kind === "number" ? ` step="any"` : "";
+  const required = context.mark && !attr.optional ? ` aria-required="true"` : "";
+  const bad = flagged(attr, name, context);
+  const limit = attr.maxLength ? ` maxlength="${attr.maxLength}"` : "";
+  if (attr.multiline && !attr.list && attr.kind === "text") {
+    const classes = bad ? "textarea textarea-error w-full max-w-3xl" : "textarea w-full max-w-3xl";
+    const hint = `<p class="text-xs text-muted" id="${id}-hint">Up to ${attr.maxLength} characters.</p>`;
+    const box = `<textarea class="${classes}" rows="5" id="${id}" name="${esc(name)}"${limit}${required}${invalidAttrs(name, attr, context, true)}>\n${text}</textarea>`;
+    return `<div class="my-4 grid gap-1"><label for="${id}" class="${context.quiet ? "sr-only" : "font-semibold"}">${caption(attr, context)}</label>${box}${hint}${problem(name, attr, context)}</div>`;
+  }
+  const classes = bad ? "input input-error w-full max-w-xl" : "input w-full max-w-xl";
+  const chosen = picked(attr, name, value, context);
+  const input = chosen ?? `<input type="${inputType(attr)}"${step} class="${classes}" id="${id}" name="${esc(name)}" value="${text}"${limit}${required}${invalidAttrs(name, attr, context)}>`;
+  return `<div class="my-4 grid gap-1"><label for="${id}" class="${context.quiet ? "sr-only" : "font-semibold"}">${caption(attr, context)}</label>${input}${problem(name, attr, context)}</div>`;
+}
+
+/** A value object's one plain part as the attribute that holds it: it takes the attribute's name, picker and moment. */
+function plainOf(attr: Attr, part: Attr, name: string): Attr {
+  return { ...part, name, optional: attr.optional, widget: attr.widget ?? part.widget, picker: attr.picker ?? part.picker, options: attr.options ?? part.options };
+}
+
+function parts(agg: Aggregate, attr: Attr, name: string, value: Value, context: Context): string {
+  const members = agg.valueObjects[attr.type] ?? [];
+  const inside = { ...context, top: false, mark: context.mark && !attr.optional };
+  return members.map((part) => field(agg, part, member(value, part.name), `${name}.`, inside)).join("\n");
+}
+
+/** The words of the refusal about the value object at `name` as a whole, or about one of its parts by name. */
+function groupRefusal(attr: Attr, name: string, context: Context): string | null {
+  return refusalAt(attr, name, context) ?? context.problems?.find((one) => one.name === name)?.message ?? null;
+}
+
+/** The control a picture's media picker is opened from, or nothing when the editor has no pictures. */
+function pickButton(): string {
+  return SCHEMA.media ? `<button type="button" class="btn btn-sm w-fit" data-action="pick-picture" data-media="${esc(href("media"))}">${icon("image")}<span>Choose a picture</span></button>` : "";
+}
+
+/**
+ * A value object that is a picture: its file, its description (required wherever a picture is) and its
+ * caption as one group with a button that opens the picker, in whatever depth it sits; any other part
+ * it has is drawn after it as it is anywhere else.
+ */
+function pictureField(agg: Aggregate, attr: Attr, name: string, value: Value, context: Context): string {
+  const picture = attr.picture as NonNullable<Attr["picture"]>;
+  const members = agg.valueObjects[attr.type] ?? [];
+  const inside: Context = { ...context, top: false, mark: context.mark && !attr.optional };
+  const named = [picture.key, picture.alt, picture.caption].filter((part): part is string => part !== undefined);
+  const control = (part?: string): string => {
+    const found = members.find((one) => one.name === part);
+    return found ? field(agg, found, member(value, found.name), `${name}.`, inside) : "";
+  };
+  const others = members.filter((one) => !named.includes(one.name)).map((one) => field(agg, one, member(value, one.name), `${name}.`, inside));
+  const thumb = `<img class="size-20 shrink-0 border border-base-300 object-cover" alt="" width="80" height="80" data-picture-thumb hidden>`;
+  const said = groupRefusal(attr, name, context);
+  const bad = said !== null ? ` aria-invalid="true" aria-describedby="${esc(idOf(name))}-error"` : "";
+  const why = said !== null ? `<p class="text-xs font-semibold text-error" id="${esc(idOf(name))}-error">${esc(said)}</p>` : "";
+  return `<fieldset class="mt-6 [&>legend+*]:clear-both"${bad}><legend class="float-left mb-2 w-full border-t border-base-300 pt-4 text-lg font-semibold">${caption(attr, context)}</legend>
+<div class="my-4 grid gap-1 border border-base-300 p-3" data-picture data-key="${esc(`${name}.${picture.key}`)}" data-alt="${esc(`${name}.${picture.alt}`)}">
+<div class="flex flex-wrap items-start gap-3">${thumb}<div class="grid min-w-0 flex-1 gap-1 max-sm:basis-full">${control(picture.key)}${control(picture.alt)}${control(picture.caption)}${pickButton()}</div></div>
+<p class="text-xs text-muted">A picture needs a description for people who cannot see it.</p>
+</div>
+${others.join("\n")}${why}
+</fieldset>`;
+}
+
+function one(agg: Aggregate, attr: Attr, name: string, value: Value, context: Context): string {
+  if (attr.kind !== "object") return scalar(attr, name, value, context);
+  const members = agg.valueObjects[attr.type] ?? [];
+  const hit = groupRefusal(attr, name, context);
+  if (members.length === 1 && members[0].kind !== "object" && !members[0].list) {
+    const own: Context = hit !== null ? { ...context, top: true, invalid: { field: attr.name, message: hit } } : context;
+    return scalar(plainOf(attr, members[0], attr.name), `${name}.${members[0].name}`, member(value, members[0].name), own);
+  }
+  if (attr.picture) return pictureField(agg, attr, name, value, context);
+  const invalid = hit !== null ? ` aria-invalid="true" aria-describedby="${esc(idOf(name))}-error"` : "";
+  const why = hit !== null ? `<p class="text-xs font-semibold text-error" id="${esc(idOf(name))}-error">${esc(hit)}</p>` : "";
+  return `<fieldset class="mt-6 [&>legend+*]:clear-both"${invalid}><legend class="float-left mb-2 w-full border-t border-base-300 pt-4 text-lg font-semibold">${caption(attr, context)}</legend>\n${parts(agg, attr, name, value, context)}\n${why}</fieldset>`;
+}
+
+function listed(agg: Aggregate, attr: Attr, name: string, value: Value, context: Context): string {
+  const held = Array.isArray(value) ? value : [];
+  const inside = { ...context, mark: false, top: false };
+  const members = agg.valueObjects[attr.type] ?? [];
+  const only = attr.kind === "object" && members.length === 1 && members[0].kind !== "object" && !members[0].list ? members[0] : null;
+  const word = attr.name.replace(/([^aeiou])ies$/, "$1y").replace(/s$/, "");
+  const rows = [...held, undefined].map((item, index) => {
+    const body = only
+      ? scalar({ ...plainOf(attr, only, word), optional: only.optional }, `${name}.${index}.${only.name}`, member(item, only.name), { ...inside, quiet: true })
+      : attr.kind === "object"
+        ? parts(agg, attr, `${name}.${index}`, item, inside)
+        : scalar({ ...attr, name: word, list: false, optional: false }, `${name}.${index}`, item, { ...inside, quiet: true });
+    return `<fieldset class="relative my-3 border-l-2 border-base-300 pl-4 [&>legend+*]:clear-both" data-row data-index="${index}"><legend class="float-left w-full text-xs font-semibold text-muted">${esc(label(word))} ${index + 1}</legend>\n${body}\n</fieldset>`;
+  });
+  const noun = esc(singular(word));
+  const invalid = flagged(attr, name, context) ? ` aria-invalid="true" aria-describedby="${esc(idOf(name))}-error"` : "";
+  const max = attr.max ? ` data-max="${attr.max}"` : "";
+  const limits = limitsNote(attr.min, attr.max);
+  const note = limits ? `\n<p class="clear-both mb-2 text-xs text-muted">${esc(limits)}</p>` : "";
+  return `<fieldset class="mt-6 [&>legend+*]:clear-both" data-repeat data-path="${esc(name)}" data-noun="${noun}"${max}${invalid}><legend class="float-left mb-2 w-full border-t border-base-300 pt-4 text-lg font-semibold">${caption(attr, context)}</legend>${note}\n<div data-rows>\n${rows.join("\n")}\n</div>${problem(name, attr, context)}\n</fieldset>`;
+}
+
+// The rich-text editor. The server renders the body as its read-only text and as the hidden inputs
+// the form posts (the same dotted-path fields every value object and list uses), so a browser
+// without the script still posts the body unchanged; the editor replaces the text with a writing
+// surface and rewrites those inputs from the document as it is edited.
+function body(attr: Attr, name: string, value: Value, context: Context): string {
+  const tree = value && typeof value === "object" ? value : emptyBody();
+  const inputs = fieldsToInputs(bodyToFields(tree, name));
+  const media = SCHEMA.media ? ` data-media="${esc(href("media"))}"` : "";
+  const draft = context.draft === attr.name ? " data-draft" : "";
+  const said = groupRefusal(attr, name, context);
+  const bad = said !== null ? ` aria-invalid="true" aria-describedby="${esc(idOf(name))}-error"` : "";
+  const why = said !== null ? `\n<p class="mt-2 text-sm font-semibold text-error" id="${esc(idOf(name))}-error">${esc(said)}</p>` : "";
+  return `<fieldset class="mt-6 [&>legend+*]:clear-both"${bad}><legend class="float-left mb-2 w-full border-t border-base-300 pt-4 text-lg font-semibold">${caption(attr, context)}</legend>
+<div class="max-w-3xl" data-body-editor${draft} data-name="${esc(name)}" data-label="${esc(label(attr.name))}" data-body="${esc(JSON.stringify(tree))}"${media}>
+<div class="prose border border-base-300 bg-base-100 p-6" data-body-fallback>${bodyToHtml(tree, 2)}</div>
+<p class="mt-2 text-xs text-muted" data-needs-script>Editing this text needs scripts turned on in the browser.</p>
+<div data-fields>
+${inputs}
+</div>
+</div>${why}
+</fieldset>`;
+}
+
+/** A list of mixed blocks as cards; each slot is drawn by `field`, so a part is entered as it is anywhere else. */
+function blocks(agg: Aggregate, attr: Attr, name: string, value: Value, context: Context): string {
+  const slot = (part: Attr, prefix: string, held: Value, message?: string, required?: boolean, rows?: boolean): string => {
+    const own: Context = { ...context, top: message !== undefined, invalid: message ? { field: part.name, message } : null, mark: required === true, quiet: false, draft: undefined, rows };
+    return field(agg, required ? { ...part, optional: false } : part, held, prefix, own);
+  };
+  const message = groupRefusal(attr, name, context) ?? undefined;
+  const rendering = { slot, draft: context.draft === attr.name, problems: context.problems ?? [], caption: caption(attr, context), media: SCHEMA.media ? href("media") : undefined, message };
+  return blockList(agg, attr, name, value, rendering);
+}
+
+/** One attribute's inputs, `prefix` being the dotted path of the object that holds it. */
+export function field(agg: Aggregate, attr: Attr, value: Value, prefix = "", context: Context = { mark: true, top: true }): string {
+  const name = `${prefix}${attr.name}`;
+  if (attr.widget === "body") return body(attr, name, value, context);
+  if (attr.blockList && attr.list) return blocks(agg, attr, name, value, context);
+  if (attr.list && attr.kind === "object" && !context.rows && (attr.picture !== undefined || heavy(agg.valueObjects, attr.type))) return blocks(agg, attr, name, value, context);
+  return attr.list ? listed(agg, attr, name, value, context) : one(agg, attr, name, value, context);
+}
+
+/** The inputs for `attrs`, filled from `values` (an instance's state or a refused submission). */
+export function fields(agg: Aggregate, attrs: Attr[], values: Record<string, Value> = {}, invalid: Invalid | null = null, mark = true, choices: Choices = {}, draft?: string, problems: Problem[] = []): string {
+  const inputs = attrs.map((attr) => field(agg, attr, values[attr.name], "", { mark, invalid, top: true, choices, draft, problems }));
+  return [...inputs, datalists(agg, attrs, choices)].filter((text) => text !== "").join("\n");
+}

data/lib/hecks/projections/site/cms_editor/templates/src/ui/html.ts.tmpl

@@ -0,0 +1,61 @@
+__BANNER__
+
+// The small helpers every page shares. Pages are plain strings built on the server; every value that
+// came from the domain or the person is escaped on its way in, so no text becomes markup.
+//
+// Every class name below is written out whole. The stylesheet is built by Tailwind, which finds
+// classes by reading these files as text, so a class made by joining strings would not be found and
+// would have no style.
+import { EDITOR } from "../config.ts";
+import type { Aggregate } from "../schema.ts";
+import { icon } from "./icons.ts";
+import { label } from "./words.ts";
+
+/** Escapes text for an HTML body or a double-quoted attribute. */
+export function esc(value: unknown): string {
+  return String(value ?? "").replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
+}
+
+/** A path under the editor's base path; each segment is URL-encoded. */
+export function href(...segments: string[]): string {
+  return [EDITOR.basePath, ...segments.map(encodeURIComponent)].join("/");
+}
+
+/**
+ * The inline message a refused command shows above its form. The page's script moves focus to the
+ * first field marked invalid, or to this block when no field is named.
+ */
+export function refusal(message: string | null): string {
+  return message ? `<div class="alert alert-error alert-soft mb-4 items-start" tabindex="-1" data-refusal>${icon("alert")}<p class="font-medium">${esc(message)}</p></div>` : "";
+}
+
+/** A badge's classes and mark by tone. Colour is never the only cue: each tone has its own shape and the state's words. */
+const TONES: Record<string, [classes: string, mark: string]> = {
+  neutral: ["badge badge-soft gap-1 font-semibold", "dot"],
+  ok: ["badge badge-soft badge-success gap-1 font-semibold", "success"],
+  info: ["badge badge-soft badge-info gap-1 font-semibold", "info"],
+  warn: ["badge badge-soft badge-warning gap-1 font-semibold", "alert"],
+  danger: ["badge badge-soft badge-error gap-1 font-semibold", "alert"],
+};
+
+/** A status as a badge: its words, a shape and a colour. */
+export function badge(status: unknown, tone = "neutral"): string {
+  if (!status) return "";
+  const [classes, mark] = TONES[tone] ?? TONES.neutral;
+  return `<span class="${classes}">${icon(mark)}${esc(label(String(status)))}</span>`;
+}
+
+/** The badge of an aggregate's lifecycle state, in the tone the schema gives that state. */
+export function statusBadge(agg: Aggregate, status: unknown): string {
+  return badge(status, agg.lifecycle?.tones[String(status)] ?? "neutral");
+}
+
+/** A button that copies `value` to the clipboard (the page's script shows it and wires it; without a script it stays hidden). */
+export function copyButton(value: string, what: string): string {
+  return `<button type="button" class="btn btn-ghost btn-square btn-xs text-muted" data-copy="${esc(value)}" title="Copy ${esc(what)}" aria-label="Copy ${esc(what)}" hidden>${icon("copy")}</button>`;
+}
+
+/** A value with a button that copies it. */
+export function copyable(value: string, what: string): string {
+  return `<span class="inline-flex items-center gap-1"><span>${esc(value)}</span>${copyButton(value, what)}</span>`;
+}

data/lib/hecks/projections/site/cms_editor/templates/src/ui/icons.ts.tmpl

@@ -0,0 +1,15 @@
+__BANNER__
+
+// The editor's icons: one SVG sprite written into every page, and `icon(name)` to draw one. The
+// symbols are the project's single source of icons (the generator's own list), so the browser code
+// draws the same ones with `<use href="#i-name">` and nothing is fetched.
+
+/** The sprite, placed once at the top of every page. It takes no room and is hidden from readers. */
+export const SPRITE = `<svg class="absolute size-0 overflow-hidden" xmlns="http://www.w3.org/2000/svg" width="0" height="0" focusable="false" aria-hidden="true">
+__ICONS__
+</svg>`;
+
+/** An icon that decorates a label next to it. */
+export function icon(name: string): string {
+  return `<svg class="icon" aria-hidden="true" focusable="false"><use href="#i-${name}"/></svg>`;
+}

data/lib/hecks/projections/site/cms_editor/templates/src/ui/input.ts.tmpl

@@ -0,0 +1,92 @@
+__BANNER__
+
+// A submitted form turned back into what a command takes. The form's inputs are named by dotted
+// path (see fields.ts); this reads them against the same attributes, so a nested value object comes
+// back nested and a run of repeatable rows comes back as a list. A row left entirely blank is not a
+// row, and an optional part left blank is left out, as is an optional group with nothing in it; a
+// required text part left blank in a group that has something in it is sent as empty text so that
+// the domain's own rule refuses it in its own words. A rich-text body is read the
+// same way: the widget posts its tree as the same dotted-path fields (`body.blocks.0.spans.1.text`),
+// so there is no second encoding.
+import type { Aggregate, Attr } from "../schema.ts";
+
+export type Form = Map<string, string>;
+
+/**
+ * The fields of an `application/x-www-form-urlencoded` body, the last of a repeated name winning.
+ * A browser sends a line break in a field as CR LF; it is read back as the single LF the domain
+ * holds, or a line break in a body would grow by a character each time the body is saved and
+ * opened again.
+ */
+export function parseForm(body: string): Form {
+  const form: Form = new Map();
+  for (const [key, value] of new URLSearchParams(body)) form.set(key, value.replace(/\r\n?/g, "\n"));
+  return form;
+}
+
+const blank = (value: unknown): boolean =>
+  value === "" ||
+  value === undefined ||
+  value === null ||
+  (Array.isArray(value) && value.every(blank)) ||
+  (typeof value === "object" && !Array.isArray(value) && Object.values(value as object).every(blank));
+
+function indices(form: Form, path: string): number[] {
+  const found = new Set<number>();
+  for (const key of form.keys()) {
+    const match = key.startsWith(`${path}.`) ? /^(\d+)(\.|$)/.exec(key.slice(path.length + 1)) : null;
+    if (match) found.add(Number(match[1]));
+  }
+  return [...found].sort((a, b) => a - b);
+}
+
+function text(attr: Attr, form: Form, path: string, optional: boolean): unknown {
+  const raw = form.get(path);
+  if (attr.kind === "boolean") return form.has(path);
+  if (raw === undefined || (raw === "" && optional)) return undefined;
+  if ((attr.kind === "integer" || attr.kind === "number") && raw.trim() !== "" && !Number.isNaN(Number(raw))) return Number(raw);
+  return raw;
+}
+
+/**
+ * A value object from its fields. One that is optional, or sits in an optional one, and was left
+ * entirely blank is left out; one with anything in it is read again with its required parts counted
+ * as required, so a part left blank is sent empty and the domain's own rule refuses it in its own words.
+ */
+function object(agg: Aggregate, attr: Attr, form: Form, path: string, optional: boolean): unknown {
+  const read = (lenient: boolean): Record<string, unknown> => {
+    const built: Record<string, unknown> = {};
+    for (const part of agg.valueObjects[attr.type] ?? []) {
+      const value = build(agg, part, form, `${path}.`, lenient);
+      if (value !== undefined) built[part.name] = value;
+    }
+    return built;
+  };
+  const lenient = read(optional);
+  if (optional && blank(lenient)) return undefined;
+  const built = optional ? read(false) : lenient;
+  return Object.keys(built).length > 0 ? built : undefined;
+}
+
+function single(agg: Aggregate, attr: Attr, form: Form, path: string, optional: boolean): unknown {
+  return attr.kind === "object" ? object(agg, attr, form, path, optional) : text(attr, form, path, optional);
+}
+
+/** One attribute's value from the form, or undefined when it is to be left out. */
+export function build(agg: Aggregate, attr: Attr, form: Form, prefix: string, optionalAbove = false): unknown {
+  const path = `${prefix}${attr.name}`;
+  const optional = optionalAbove || attr.optional;
+  if (!attr.list) return single(agg, attr, form, path, optional);
+  const rows = indices(form, path).map((index) => single(agg, attr, form, `${path}.${index}`, optional));
+  return rows.filter((row) => !blank(row));
+}
+
+/** The arguments a command takes, from a submitted form; `empty` names the list arguments sent empty. */
+export function commandArguments(agg: Aggregate, attrs: Attr[], form: Form, empty: string[] = []): Record<string, unknown> {
+  const args: Record<string, unknown> = Object.fromEntries(empty.map((name) => [name, []]));
+  for (const attr of attrs) {
+    const value = build(agg, attr, form, "");
+    if (value !== undefined) args[attr.name] = value;
+  }
+  return args;
+}

data/lib/hecks/projections/site/cms_editor/templates/src/ui/links.ts.tmpl

@@ -0,0 +1,100 @@
+__BANNER__
+
+// How one record reaches another. A record is named to the rest of the domain by a plain key of the
+// form `<kind>:<slug>`, where the kind is its aggregate's snake-case name (`post:first-light`), so
+// this file makes that key, fills an input named by dotted path with it, and keeps the way back: a
+// page reached from a record's page carries `_back` (an address under the editor), and the form on it
+// posts `__back`, so a save returns to the record the person came from.
+import { EDITOR } from "../config.ts";
+import type { Aggregate, Attr } from "../schema.ts";
+import { esc } from "./html.ts";
+import { label } from "./words.ts";
+
+/** A record's names, as a key and its parts: `post:first-light` is kind `post`, slug `first-light`. */
+export interface Parts {
+  key: string;
+  kind: string;
+  slug: string;
+  id: string;
+}
+
+/** The snake-case name a kind is spelled: "MediaItem" is "media_item". */
+export const snake = (name: string): string => name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+
+/**
+ * A record's key and its parts. An identity that already reads `<kind>:<slug>` is that key; any
+ * other identity is the slug of a key whose kind is its aggregate's.
+ */
+export function partsOf(agg: Aggregate, id: string): Parts {
+  const given = /^([a-z][a-z0-9_]*):(.+)$/.exec(id);
+  if (given) return { key: id, kind: given[1], slug: given[2], id };
+  const kind = snake(agg.name);
+  return { key: `${kind}:${id}`, kind, slug: id, id };
+}
+
+/** The value object's one plain part that an attribute is entered as, or null when it has several. */
+function onlyPart(agg: Aggregate, attr: Attr): Attr | null {
+  const parts = attr.kind === "object" ? (agg.valueObjects[attr.type] ?? []) : [];
+  return parts.length === 1 && parts[0].kind !== "object" && !parts[0].list ? parts[0] : null;
+}
+
+/** The name of the input that holds an attribute of one plain value, as a form posts it. */
+export function plainName(agg: Aggregate, attr: Attr): string {
+  const part = onlyPart(agg, attr);
+  return part ? `${attr.name}.${part.name}` : attr.name;
+}
+
+/** `text` as a value of the attribute, wrapped in its value object when it has one. */
+export function plainValue(agg: Aggregate, attr: Attr, text: string): unknown {
+  const part = onlyPart(agg, attr);
+  return part ? { [part.name]: text } : text;
+}
+
+/** The text an attribute of one plain value holds. */
+export function plainText(value: unknown): string {
+  if (value && typeof value === "object") return plainText(Object.values(value as object).find((part) => part !== null && part !== undefined));
+  return value === null || value === undefined ? "" : String(value);
+}
+
+/** Where a page was reached from: the address to go back to, and the words for the link. */
+export interface Back {
+  path: string;
+  label: string;
+}
+
+/**
+ * The way back a request names, or null. Only an address under the editor's base path is one, so a
+ * link written by anyone cannot send a person off the editor; a control character or a backslash is
+ * refused as well.
+ */
+export function backOf(raw: string | null | undefined): Back | null {
+  if (!raw || raw.length > 400 || /[\u0000-\u001f\\]/.test(raw)) return null;
+  if (raw !== EDITOR.basePath && !raw.startsWith(`${EDITOR.basePath}/`)) return null;
+  const segments = raw.split(/[?#]/)[0].split("/").filter(Boolean);
+  const at = segments.indexOf("id");
+  const named = at >= 0 && segments[at + 1] ? segments[at + 1] : (segments.at(-1) ?? "");
+  return { path: raw, label: decoded(named) };
+}
+
+function decoded(text: string): string {
+  try {
+    return decodeURIComponent(text);
+  } catch {
+    return text;
+  }
+}
+
+/** `path` with the way back added to its query. */
+export const withBack = (path: string, back: string): string => `${path}${path.includes("?") ? "&" : "?"}_back=${encodeURIComponent(back)}`;
+
+/** The hidden input a form posts so that a save returns to `back`. */
+export const backInput = (back: Back | null): string => (back ? `<input type="hidden" name="__back" value="${esc(back.path)}">` : "");
+
+/** The link at the top of a page that leads back to the record it was reached from. */
+export function backLink(back: Back | null): string {
+  if (!back) return "";
+  return `<p class="mb-3"><a class="btn btn-ghost btn-sm" href="${esc(back.path)}">Back to ${esc(back.label)}</a></p>`;
+}
+
+/** What a record is called in a heading, such as "Search wording" or "Pictures", by the aggregate's own words. */
+export const titled = (agg: Aggregate): string => label(agg.name);

data/lib/hecks/projections/site/cms_editor/templates/src/ui/moments.ts.tmpl

@@ -0,0 +1,44 @@
+__BANNER__
+
+// Moments in time. An integer the bluebook names as a date or a time is whole seconds since 1970 UTC.
+// The server does not know the viewer's time zone, so it writes the moment in UTC inside a `time`
+// element that carries the seconds, and the page's script (browser/moments.js) rewrites it in the
+// viewer's own zone with how long ago or from now it is. A form carries the seconds in a plain
+// number input that works without a script; the script replaces it with a native date or
+// date-and-time input and keeps the seconds in step.
+import type { Attr } from "../schema.ts";
+import { esc } from "./html.ts";
+
+/** Whether the attribute is a moment. */
+export const isMoment = (attr: Attr): boolean => attr.widget === "date" || attr.widget === "datetime";
+
+/** The whole seconds a stored value holds: the number itself, or the single part of a value object. */
+export function secondsOf(value: unknown): number | null {
+  const held = value && typeof value === "object" && !Array.isArray(value) ? Object.values(value as object)[0] : value;
+  if (held === null || held === undefined || held === "" || typeof held === "boolean") return null;
+  const seconds = Number(held);
+  return Number.isFinite(seconds) && Math.abs(seconds) <= 8_640_000_000_000 ? Math.trunc(seconds) : null;
+}
+
+/** A moment in UTC, for a page read with no script: `YYYY-MM-DD`, or `YYYY-MM-DD HH:MM UTC` with a time. */
+export function utcText(seconds: number, mode: string): string {
+  const iso = new Date(seconds * 1000).toISOString();
+  return mode === "date" ? iso.slice(0, 10) : `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`;
+}
+
+/** A stored moment as a `time` element the script restates in the viewer's zone. */
+export function momentTime(seconds: number, mode: string): string {
+  const iso = new Date(seconds * 1000).toISOString();
+  return `<time class="whitespace-nowrap" datetime="${esc(iso)}" data-moment="${esc(mode)}" data-epoch="${seconds}">${esc(utcText(seconds, mode))}</time>`;
+}
+
+/** A stored value (or a list of them) of a moment attribute, shown read-only. */
+export function momentValue(attr: Attr, value: unknown): string {
+  const mode = attr.widget ?? "datetime";
+  const seconds = (item: unknown): string => {
+    const held = secondsOf(item);
+    return held === null ? `<span class="text-muted">Not set</span>` : momentTime(held, mode);
+  };
+  if (Array.isArray(value)) return value.length === 0 ? `<span class="text-muted">None</span>` : value.map(seconds).join(", ");
+  return seconds(value);
+}