hecks 3.10.0 → 3.11.0

data/lib/hecks/projections/site/cms_editor/templates/src/browser/pickers.js.tmpl

@@ -0,0 +1,152 @@
+__BANNER__
+
+// What a script does with pickers (see ui/pickers.ts). A text box that suggests keys is checked as it
+// is typed, so the form cannot be sent with a key that is not on offer. A `<kind>:<key>` value is
+// built from a kind and a record, two controls that write the one input the form posts. The server
+// checks every key again, whatever the script did.
+
+/** How many choices a native select holds before a text box with suggestions takes over (as in the page). */
+const SELECT_MAX = 30;
+
+/** The keys a text box's list offers. */
+const offered = (input) => [...(document.getElementById(input.getAttribute("list"))?.options ?? [])].map((option) => option.value);
+
+/** Whether `input` names something on offer, or nothing, or what it named when the page was made. */
+function valid(input) {
+  if (input.dataset.open !== undefined || input.value === "" || input.value === input.dataset.initial) return true;
+  return offered(input).includes(input.value);
+}
+
+/** Marks a strict box invalid, with the words the browser shows, until it names something on offer. */
+function check(input) {
+  input.setCustomValidity(valid(input) ? "" : `Nothing is called "${input.value}". Choose one of the suggestions.`);
+}
+
+const words = (option) => (option.label && option.label !== option.key ? `${option.label} (${option.key})` : option.key);
+
+let counter = 0;
+
+/** A text box for a record, with its list of suggestions when there are some. */
+function suggesting(options, strict, value) {
+  const input = document.createElement("input");
+  input.type = "text";
+  input.className = "input w-full";
+  input.setAttribute("aria-label", "Record");
+  input.autocomplete = "off";
+  input.value = value;
+  const holder = document.createElement("span");
+  holder.className = "flex min-w-0 flex-1";
+  holder.append(input);
+  if (options.length > 0) {
+    const list = document.createElement("datalist");
+    list.id = `kind-choices-${(counter += 1)}`;
+    for (const option of options) list.append(Object.assign(document.createElement("option"), { value: option.key, label: words(option) }));
+    input.setAttribute("list", list.id);
+    holder.append(list);
+  }
+  if (strict && options.length > 0) {
+    input.dataset.strict = "";
+    input.dataset.initial = value;
+    check(input);
+  }
+  return holder;
+}
+
+/** A native select of a kind's records. */
+function choosing(options, value) {
+  const select = document.createElement("select");
+  select.className = "select min-w-0 flex-1";
+  select.setAttribute("aria-label", "Record");
+  select.append(new Option("Choose...", ""));
+  for (const option of options) select.append(new Option(words(option), option.key, false, option.key === value));
+  if (value !== "" && !options.some((option) => option.key === value)) select.append(new Option(`${value} (not on offer)`, value, false, true));
+  return select;
+}
+
+/** The record's control for a kind: a select for a few records, a box that suggests for more, a plain box for none. */
+function control(kind, value) {
+  const options = kind?.options ?? [];
+  return kind?.strict && options.length > 0 && options.length <= SELECT_MAX ? choosing(options, value) : suggesting(options, Boolean(kind?.strict), value);
+}
+
+const fieldOf = (element) => (element.matches("input, select") ? element : element.querySelector("input"));
+
+/** The `<kind>:<key>` the pair of controls stand for, or empty when either is. */
+function sync(box) {
+  const kind = box.querySelector("[data-kind]");
+  const record = fieldOf(box.querySelector("[data-record]"));
+  box.querySelector("input[type=hidden]").value = kind.value !== "" && record.value !== "" ? `${kind.value}:${record.value}` : "";
+}
+
+/** Puts a record control for the chosen kind in place of the one there. */
+function place(box, value) {
+  box.querySelector("[data-record]")?.remove();
+  const kinds = JSON.parse(box.dataset.kinds);
+  const element = control(kinds.find((kind) => kind.kind === box.querySelector("[data-kind]").value), value);
+  element.dataset.record = "";
+  box.querySelector("[data-pair]").append(element);
+}
+
+/** Builds the kind and record controls of one `<kind>:<key>` input. */
+function mount(box) {
+  if (box.dataset.mounted) return;
+  const kinds = JSON.parse(box.dataset.kinds);
+  const input = box.querySelector("input");
+  const [first, ...rest] = input.value.split(":");
+  const known = kinds.some((kind) => kind.kind === first);
+  const kind = document.createElement("select");
+  kind.className = "select";
+  kind.id = input.id;
+  kind.dataset.kind = "";
+  kind.setAttribute("aria-label", "Kind");
+  kind.append(new Option("Kind...", ""));
+  for (const each of kinds) kind.append(new Option(each.kind, each.kind, false, known && each.kind === first));
+  const pair = document.createElement("div");
+  pair.className = "flex flex-wrap gap-2";
+  pair.dataset.pair = "";
+  pair.append(kind);
+  input.type = "hidden";
+  input.removeAttribute("id");
+  box.append(pair);
+  box.dataset.mounted = "true";
+  place(box, known ? rest.join(":") : "");
+  sync(box);
+}
+
+/** Mounts every `<kind>:<key>` input under `root` that has not been; a copied row is first undone so it can be. */
+export function mountPickers(root = document) {
+  for (const box of root.querySelectorAll("[data-key-picker]")) mount(box);
+}
+
+/** Undoes a copied `<kind>:<key>` row's controls, so the row can be mounted as a new one. */
+export function unmountPickers(root) {
+  for (const box of root.querySelectorAll("[data-key-picker][data-mounted]")) {
+    const hidden = box.querySelector("input[type=hidden]");
+    const id = box.querySelector("select[data-kind]")?.id;
+    box.querySelector("[data-pair]")?.remove();
+    hidden.type = "text";
+    hidden.value = "";
+    if (id) hidden.id = id;
+    delete box.dataset.mounted;
+  }
+}
+
+export function enhancePickers() {
+  for (const input of document.querySelectorAll("input[data-strict]")) {
+    input.dataset.initial = input.value;
+    check(input);
+  }
+  document.addEventListener("input", (event) => {
+    const target = event.target;
+    if (target.matches?.("input[data-strict]")) check(target);
+    const box = target.closest?.("[data-key-picker]");
+    if (box && !target.matches("[data-kind]")) sync(box);
+  });
+  document.addEventListener("change", (event) => {
+    const box = event.target.closest?.("[data-key-picker]");
+    if (!box) return;
+    if (event.target.matches("[data-kind]")) place(box, "");
+    sync(box);
+  });
+  mountPickers();
+}

data/lib/hecks/projections/site/cms_editor/templates/src/browser/preview.js.tmpl

@@ -0,0 +1,98 @@
+__BANNER__
+
+// The preview drawer (see ui/preview.ts): the site's own page for a record, framed beside the editor.
+// The button is a plain link to the address (it opens a new tab with no script); here it opens the
+// drawer instead and loads the frame, which is not loaded until then. The width buttons only change
+// the frame's width. A successful draft save (browser/autosave.js says so with `editor:saved`) reloads
+// the frame, and a drawer that was open when a form was sent is open again on the page that follows, so
+// a save or a publish is seen as the site shows it. Nothing is sent into the frame.
+
+const SIZES = { phone: "w-[375px]", tablet: "w-[768px]", desktop: "w-full" };
+const ALL = Object.values(SIZES);
+const KEY = "editor-preview";
+
+/** The path the drawer was open on, which survives one page change in this tab. */
+function remembered() {
+  try {
+    return sessionStorage.getItem(KEY);
+  } catch {
+    return null;
+  }
+}
+
+function remember(path) {
+  try {
+    if (path) sessionStorage.setItem(KEY, path);
+    else sessionStorage.removeItem(KEY);
+  } catch {
+    // Storage may be blocked; the drawer then simply starts closed on the next page.
+  }
+}
+
+/** Moves focus to `element`, trying again for a moment while the drawer is still becoming visible (a hidden element takes none). */
+function focusInto(element, tries = 20) {
+  element.focus();
+  if (tries > 0 && document.activeElement !== element) setTimeout(() => focusInto(element, tries - 1), 30);
+}
+
+const FOCUSABLE = "a[href], button:not([disabled]), input:not([disabled]), select, textarea, [tabindex]:not([tabindex='-1'])";
+
+export function enhancePreview() {
+  const root = document.querySelector("[data-preview]");
+  if (!root) return;
+  const toggle = root.querySelector(".drawer-toggle");
+  const frame = root.querySelector("[data-preview-frame]");
+  const opener = document.querySelector("[data-preview-open]");
+  const load = () => {
+    frame.src = frame.dataset.src;
+  };
+  const show = () => {
+    toggle.checked = true;
+    if (!frame.getAttribute("src")) load();
+    remember(location.pathname);
+    focusInto(root.querySelector("[data-preview-close]"));
+  };
+  const hide = () => {
+    toggle.checked = false;
+    remember(null);
+    opener?.focus();
+  };
+  opener?.addEventListener("click", (event) => {
+    event.preventDefault();
+    show();
+  });
+  toggle.addEventListener("change", () => remember(toggle.checked ? location.pathname : null));
+  const section = root.querySelector("[role='dialog']");
+  document.addEventListener("keydown", (event) => {
+    if (!toggle.checked) return;
+    if (event.key === "Escape") return hide();
+    if (event.key !== "Tab") return;
+    // The drawer is modal: Tab and Shift+Tab go round its own controls, not on to the page behind it.
+    const items = [...section.querySelectorAll(FOCUSABLE)].filter((item) => item.getClientRects().length > 0);
+    const first = items[0];
+    const last = items.at(-1);
+    if (!section.contains(document.activeElement)) {
+      event.preventDefault();
+      first?.focus();
+    } else if (event.shiftKey && document.activeElement === first) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && document.activeElement === last) {
+      event.preventDefault();
+      first.focus();
+    }
+  });
+  root.querySelector("[data-preview-close]").addEventListener("click", hide);
+  for (const button of root.querySelectorAll("[data-preview-width]")) {
+    button.addEventListener("click", () => {
+      frame.classList.remove(...ALL);
+      frame.classList.add(SIZES[button.dataset.previewWidth]);
+      for (const other of root.querySelectorAll("[data-preview-width]")) other.setAttribute("aria-pressed", String(other === button));
+    });
+  }
+  root.querySelector("[data-preview-refresh]").addEventListener("click", load);
+  document.addEventListener("editor:saved", () => {
+    if (toggle.checked) load();
+  });
+  if (remembered() === location.pathname) show();
+}

data/lib/hecks/projections/site/cms_editor/templates/src/browser/shell.js.tmpl

@@ -0,0 +1,140 @@
+__BANNER__
+
+// What the frame and the lists do with a script: the menu button, the theme toggle, the copy
+// buttons, and a list's filter and sort. Every page works without any of it.
+import { showToast } from "./toast.js";
+
+const icon = (name) => `<svg class="icon" aria-hidden="true" focusable="false"><use href="#i-${name}"/></svg>`;
+
+/** The drawer: a checkbox is the state, so the page needs no script to open it; this adds the button, Escape and focus. */
+function navigation() {
+  const toggle = document.getElementById("nav-toggle");
+  const button = document.querySelector("[data-nav-toggle]");
+  if (!toggle || !button) return;
+  const set = (open) => {
+    toggle.checked = open;
+    button.setAttribute("aria-expanded", String(open));
+    button.setAttribute("aria-label", open ? "Close the menu" : "Open the menu");
+    if (open) document.querySelector("#rail a")?.focus();
+  };
+  button.addEventListener("click", () => set(!toggle.checked));
+  document.addEventListener("keydown", (event) => {
+    if (event.key === "Escape" && toggle.checked) {
+      set(false);
+      button.focus();
+    }
+  });
+  document.querySelector(".drawer-overlay")?.addEventListener("click", () => set(false));
+}
+
+const dark = () => {
+  const named = document.documentElement.getAttribute("data-theme");
+  return named ? named === "editor-dark" : window.matchMedia("(prefers-color-scheme: dark)").matches;
+};
+
+/** The theme button: switches between light and dark, and remembers the choice where storage allows. */
+function theme() {
+  const button = document.querySelector("[data-theme-toggle]");
+  if (!button) return;
+  const show = () => {
+    button.innerHTML = icon(dark() ? "sun" : "moon");
+    button.setAttribute("aria-label", dark() ? "Switch to the light theme" : "Switch to the dark theme");
+    button.title = button.getAttribute("aria-label");
+  };
+  button.addEventListener("click", () => {
+    const next = dark() ? "light" : "dark";
+    document.documentElement.setAttribute("data-theme", `editor-${next}`);
+    try {
+      window.localStorage.setItem("editor-theme", next);
+    } catch (error) {
+      /* storage is blocked: the choice lasts for this page only */
+    }
+    show();
+  });
+  window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", show);
+  show();
+}
+
+/** Copy buttons: shown only when a script can make them work. */
+function copying() {
+  for (const button of document.querySelectorAll("[data-copy]")) {
+    button.hidden = false;
+    button.addEventListener("click", async () => {
+      try {
+        await navigator.clipboard.writeText(button.dataset.copy);
+        showToast("success", "Copied.", 2500);
+      } catch (error) {
+        showToast("error", "The browser did not allow copying. Select the text and copy it.");
+      }
+    });
+  }
+}
+
+const cellOf = (row, at) => row.cells[at];
+const valueOf = (cell) => cell?.dataset.value ?? cell?.textContent ?? "";
+
+/** A list's sort: each heading becomes a button that orders the rows by its column, and says which way. */
+function sorting(table) {
+  const body = table.tBodies[0];
+  const heads = [...table.tHead.rows[0].cells];
+  heads.forEach((head, at) => {
+    const label = head.textContent;
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "inline-flex items-center gap-1 font-semibold";
+    button.innerHTML = `<span>${label}</span><span class="opacity-60">${icon("sort")}</span>`;
+    head.replaceChildren(button);
+    button.addEventListener("click", () => {
+      const ascending = head.getAttribute("aria-sort") !== "ascending";
+      const numbers = head.dataset.sort === "number";
+      const rows = [...body.rows].sort((a, b) => {
+        const left = valueOf(cellOf(a, at));
+        const right = valueOf(cellOf(b, at));
+        const order = numbers ? Number(left) - Number(right) : left.localeCompare(right, undefined, { numeric: true, sensitivity: "base" });
+        return ascending ? order : -order;
+      });
+      body.append(...rows);
+      heads.forEach((other) => other.removeAttribute("aria-sort"));
+      head.setAttribute("aria-sort", ascending ? "ascending" : "descending");
+      button.lastChild.innerHTML = icon(ascending ? "chevron-up" : "chevron-down");
+    });
+  });
+}
+
+/**
+ * A list's search box, as it is typed: hides the rows of this page that do not hold the words, and
+ * says so in the count. Sending the form (Enter) searches the whole list on the server.
+ */
+function filtering(input) {
+  const table = document.querySelector("table[data-sortable]");
+  const count = document.querySelector("[data-count]");
+  if (!table || !count) return;
+  const rows = [...table.tBodies[0].rows];
+  input.addEventListener("input", () => {
+    const wanted = input.value.trim().toLowerCase();
+    let shown = 0;
+    for (const row of rows) {
+      const match = wanted === "" || row.textContent.toLowerCase().includes(wanted);
+      row.hidden = !match;
+      if (match) shown += 1;
+    }
+    count.textContent = wanted === "" ? count.dataset.text : `${shown} of ${rows.length} on this page`;
+  });
+}
+
+/** After a command ran, the part of the page it changed settles into view with a short highlight. */
+function highlight() {
+  if (!document.querySelector('[data-toast][role="status"]')) return;
+  for (const changed of document.querySelectorAll("aside .badge")) changed.parentElement?.classList.add("just-changed");
+}
+
+export function enhanceShell() {
+  navigation();
+  theme();
+  copying();
+  highlight();
+  const table = document.querySelector("table[data-sortable]");
+  if (table) sorting(table);
+  const filter = document.querySelector("[data-filter]");
+  if (filter) filtering(filter);
+}

data/lib/hecks/projections/site/cms_editor/templates/src/browser/toast.js.tmpl

@@ -0,0 +1,66 @@
+__BANNER__
+
+// Notices. The server renders the one a redirect carried ("Published.") into the page; this adds a
+// close button and lets it go after a few seconds, and shows others the page's own script raises
+// ("Copied."). A notice that reports an error stays until it is closed, and is announced at once
+// (`role="alert"`); the rest wait their turn (`role="status"`). The classes are written whole so the
+// stylesheet build finds them.
+const KINDS = {
+  success: ["alert alert-success alert-soft", "success", "status"],
+  error: ["alert alert-error alert-soft", "alert", "alert"],
+  info: ["alert alert-info alert-soft", "info", "status"],
+};
+
+const LIFETIME = 6000;
+
+const svg = (name) => `<svg class="icon" aria-hidden="true" focusable="false"><use href="#i-${name}"/></svg>`;
+
+function container() {
+  let found = document.querySelector("[data-toasts]");
+  if (!found) {
+    found = document.createElement("div");
+    found.className = "toast toast-top toast-center z-50 mt-14";
+    found.dataset.toasts = "";
+    document.body.append(found);
+  }
+  return found;
+}
+
+/** Closes a notice. */
+function dismiss(notice) {
+  notice.remove();
+}
+
+/** Gives a notice a close button and a lifetime. */
+function adopt(notice, lifetime) {
+  if (notice.querySelector("[data-close]")) return;
+  const close = document.createElement("button");
+  close.type = "button";
+  close.className = "btn btn-ghost btn-square btn-xs";
+  close.setAttribute("aria-label", "Dismiss");
+  close.dataset.close = "";
+  close.innerHTML = svg("close");
+  close.addEventListener("click", () => dismiss(notice));
+  notice.append(close);
+  if (lifetime > 0) setTimeout(() => dismiss(notice), lifetime);
+}
+
+/** Shows a notice: `kind` is `success`, `error` or `info`; `message` is shown as text, never as markup. */
+export function showToast(kind, message, lifetime) {
+  const [classes, mark, role] = KINDS[kind] ?? KINDS.info;
+  const notice = document.createElement("div");
+  notice.className = classes;
+  notice.setAttribute("role", role);
+  notice.dataset.toast = "";
+  notice.innerHTML = svg(mark);
+  const text = document.createElement("p");
+  text.textContent = message;
+  notice.append(text);
+  container().append(notice);
+  adopt(notice, lifetime ?? (kind === "error" ? 0 : LIFETIME));
+}
+
+/** Gives the notices the server rendered a close button and a lifetime. */
+export function adoptToasts() {
+  for (const notice of document.querySelectorAll("[data-toast]")) adopt(notice, notice.getAttribute("role") === "alert" ? 0 : LIFETIME);
+}

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

@@ -0,0 +1,99 @@
+__BANNER__
+
+// What a picker offers, and whether what was chosen is there. The offer is the target's own listing
+// query (or every instance when it declares none), read from the host as any other page is, and a
+// target the host cannot answer for is left without one, so its input stays a text box. A key is
+// checked against every instance the target holds, not only those on offer, so a retired record a
+// form already names is still a record that exists. Nothing here asks the domain to know about
+// pickers: the host answers the queries it already has.
+import { DomainRefusal, DomainUnavailable } from "@hecks/client";
+import type { HostClient } from "@hecks/client";
+
+import { leaf } from "./commands.ts";
+import { rowsAnswered } from "./host.ts";
+import type { State } from "./commands.ts";
+import type { Aggregate, Attr, Picker } from "./schema.ts";
+import { summaryText } from "./ui/outline.ts";
+import { OFFER_MAX, choiceText, targetKey, targetsOf } from "./ui/pickers.ts";
+import type { Choice, Choices, Target } from "./ui/pickers.ts";
+import { singular } from "./ui/words.ts";
+
+/** The words that name an instance: its label attribute when it has one that says more than the key. */
+function choiceOf(target: Target, row: State): Choice | null {
+  const key = leaf(row[target.key ?? ""]);
+  if (key === null) return null;
+  const words = target.label && target.label !== target.key ? summaryText(row[target.label]) : "";
+  return { key, label: words === "" ? key : words };
+}
+
+/** What `target` offers, or null when the host could not say. */
+async function offered(client: HostClient, target: Target): Promise<Choice[] | null> {
+  const name = targetKey(target);
+  try {
+    const rows = target.listing
+      ? rowsAnswered(await client.query(`${name}.${target.listing}`, {}), `${name}.${target.listing}`)
+      : client.instancesOf(await client.read(), name).map(([, state]) => state);
+    const found = rows.flatMap((row) => choiceOf(target, row) ?? []);
+    return found.sort((a, b) => choiceText(a).localeCompare(choiceText(b), undefined, { sensitivity: "base", numeric: true })).slice(0, OFFER_MAX);
+  } catch (err) {
+    if (err instanceof DomainRefusal || err instanceof DomainUnavailable) return null;
+    throw err;
+  }
+}
+
+/** What each picker among `attrs` offers, by target; a target the host could not answer for is absent. */
+export async function choicesFor(client: HostClient, agg: Aggregate, attrs: Attr[]): Promise<Choices> {
+  const targets = targetsOf(agg, attrs);
+  const found = await Promise.all(targets.map(async (target) => [targetKey(target), await offered(client, target)] as const));
+  return Object.fromEntries(found.filter((entry): entry is readonly [string, Choice[]] => entry[1] !== null));
+}
+
+/** A key that is not there, and the attribute of the form to mark. */
+export interface Unknown {
+  field: string;
+  message: string;
+}
+
+/** What `picker` makes of `key`: the target it must be an instance of, or a problem to say. */
+function resolve(picker: Picker, key: string): { target: Target; key: string } | string | null {
+  if (!picker.kinds) return picker.strict ? { target: picker, key } : null;
+  const colon = key.indexOf(":");
+  const kinds = picker.kinds.map((kind) => kind.kind);
+  const kind = picker.kinds.find((candidate) => candidate.kind === key.slice(0, Math.max(colon, 0)));
+  if (!kind) return `Start with one of ${kinds.join(", ")} and a colon, as in ${kinds[0]}:key.`;
+  return kind.target && kind.strict ? { target: kind, key: key.slice(colon + 1) } : null;
+}
+
+/** The keys the host holds for `target`, read once. */
+function holder(client: HostClient): (target: Target) => Promise<Set<string>> {
+  const answer = client.read();
+  return async (target) => new Set(client.instancesOf(await answer, targetKey(target)).map(([id]) => id));
+}
+
+/** Every key a form names that a strict picker's target does not hold, the first one found; null when all are there. */
+export async function unknownKey(client: HostClient, agg: Aggregate, attrs: Attr[], args: State): Promise<Unknown | null> {
+  const wanted: { field: string; target: Target; key: string }[] = [];
+  const problems: Unknown[] = [];
+  const walk = (list: Attr[], values: State, top?: string): void => {
+    for (const attr of list) {
+      const field = top ?? attr.name;
+      for (const item of [values[attr.name]].flat()) {
+        const key = leaf(item);
+        if (attr.options && key !== null && key !== "") {
+          if (!attr.options.includes(key)) problems.push({ field, message: `Choose one of ${attr.options.join(", ")}.` });
+        } else if (attr.picker && key !== null && key !== "") {
+          const next = resolve(attr.picker, key);
+          if (typeof next === "string") problems.push({ field, message: next });
+          else if (next) wanted.push({ field, ...next });
+        } else if (attr.kind === "object" && item && typeof item === "object") walk(agg.valueObjects[attr.type] ?? [], item as State, field);
+      }
+    }
+  };
+  walk(attrs, args);
+  if (problems.length > 0) return problems[0];
+  const held = wanted.length > 0 ? holder(client) : null;
+  for (const { field, target, key } of wanted) {
+    if (!(await held?.(target))?.has(key)) return { field, message: `No ${singular(target.target ?? "record")} has the key "${key}".` };
+  }
+  return null;
+}