hecks 3.9.1 → 3.11.0

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

@@ -0,0 +1,36 @@
+__BANNER__
+
+// How an aggregate is named in the three places it has a name: its address in the editor, the name
+// the host knows it by, and the key the navigation and the counts hold it under. An editor of one
+// chapter names an aggregate by its own name in all three. An editor of several chapters names it by
+// its chapter as well, so two aggregates of one name in different chapters stay two.
+import { SCHEMA } from "./schema.ts";
+import type { Aggregate } from "./schema.ts";
+
+/** The path segments that address an aggregate under the editor's base path. */
+export const at = (agg: Aggregate): string[] => (agg.chapter ? [agg.chapter, agg.name] : [agg.name]);
+
+/** The name the host knows an aggregate by: `Chapter::Aggregate` when the editor spans chapters. */
+export const qualified = (agg: Aggregate): string => (agg.chapter ? `${agg.chapter}::${agg.name}` : agg.name);
+
+/** What the navigation and the counts hold an aggregate under. */
+export const keyOf = (agg: Aggregate): string => (agg.chapter ? `${agg.chapter}.${agg.name}` : agg.name);
+
+/** The host's name for an aggregate of `chapter` (this editor's first chapter when none is named). */
+export const hostName = (name: string, chapter?: string): string => `${chapter ?? SCHEMA.domain}::${name}`;
+
+/**
+ * The aggregate a path names, and the segments after it. With several chapters the path is
+ * `<Chapter>/<Aggregate>/...`, and with one it is `<Aggregate>/...`.
+ */
+export function locate(segments: string[]): { agg: Aggregate | undefined; rest: string[] } {
+  if (SCHEMA.chapters) {
+    const [chapter, name, ...rest] = segments;
+    return { agg: SCHEMA.aggregates.find((candidate) => candidate.chapter === chapter && candidate.name === name), rest };
+  }
+  const [name, ...rest] = segments;
+  return { agg: SCHEMA.aggregates.find((candidate) => candidate.name === name), rest };
+}
+
+/** Whether a person in `role` may edit `agg`: every role may, unless its chapter limits them. */
+export const mayEdit = (agg: Aggregate, role: string | null): boolean => !agg.roles || (role !== null && agg.roles.includes(role));

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

@@ -0,0 +1,214 @@
+__BANNER__
+
+// The domain's shape, read from its bluebook: every aggregate with its attributes, value objects,
+// lifecycle, commands and queries. The pages, the forms and the input parser all read this one
+// constant, so the editor can edit any aggregate; none of it is written by hand.
+
+/** How an attribute's value is entered: `object` is a value object, the rest are single values. */
+export type Kind = "text" | "integer" | "number" | "boolean" | "object" | "reference";
+
+/**
+ * What an attribute names: an instance of another aggregate, offered as a choice. `strict` pickers
+ * accept only a key that exists; the others suggest and accept any text. `listing` is the query of
+ * the target that lists what is on offer, or none to offer every instance. With `kinds`, the value is
+ * `<kind>:<key>`: the kind is chosen first, then the record of the aggregate that kind names.
+ */
+export interface Picker {
+  target?: string;
+  /** The target's chapter, when the editor spans several or the target is in another. */
+  chapter?: string;
+  /** The target's identity attribute. */
+  key?: string;
+  /** The attribute that names an instance to a person (its title, name or label, else its identity). */
+  label?: string;
+  listing?: string;
+  strict?: boolean;
+  kinds?: PickerKind[];
+}
+
+/** One kind of a `<kind>:<key>` value, and the aggregate it names when it names one. */
+export type PickerKind = Omit<Picker, "kinds"> & { kind: string };
+
+/**
+ * A list of mixed blocks: a list of one value object whose `discriminator` part is one of `kinds`. With
+ * `rules`, each kind's `requires` (parts it must have) and `uses` (parts it may have) come from a
+ * declared table; a part no row names belongs to every kind. With none, every part is shown and
+ * `mentions` says which parts a kind's rules read. `limits` are the most each list part of the block
+ * may hold; `pictures` says, for a value object, which of its parts are a picture's key, alt text and caption.
+ */
+export interface BlockList {
+  discriminator: string;
+  kinds: string[];
+  rules?: Record<string, { requires: string[]; uses: string[] }>;
+  mentions?: Record<string, string[]>;
+  limits?: Record<string, number>;
+  pictures?: Record<string, { key: string; alt: string; caption?: string }>;
+}
+
+export interface Attr {
+  name: string;
+  /** The type as the bluebook spells it ("String", "Byline"). */
+  type: string;
+  kind: Kind;
+  optional: boolean;
+  /** True for `list_of`: the attribute holds a list of `type`. */
+  list: boolean;
+  /**
+   * `body` for an attribute whose value object has the shape of a structured document (blocks of
+   * spans); `date` or `datetime` for whole seconds since 1970 that the names say are a moment.
+   */
+  widget?: "body" | "date" | "datetime";
+  /** Set when the attribute names an instance of another aggregate of the editor. */
+  picker?: Picker;
+  /** The members of the closed set the attribute is one of, when its value object declares one. */
+  options?: string[];
+  /** The aggregate a `reference` points at. */
+  target?: string;
+  /** Set when the attribute is a list of mixed blocks (see `BlockList`). */
+  blockList?: BlockList;
+  /** The most rows the list may hold, when a rule of its holder (an invariant or a command's `given`) says. */
+  max?: number;
+  /** The fewest rows the list may hold, when a rule of its holder says. */
+  min?: number;
+  /** The most characters a text may hold, when a rule of its holder says. */
+  maxLength?: number;
+  /** True when `maxLength` is long enough for the text to be written in a box of several lines. */
+  multiline?: boolean;
+  /** Set when the value object is a picture: the names of its parts that hold the file, its description and its caption. */
+  picture?: { key: string; alt: string; caption?: string };
+}
+
+export interface Transition {
+  verb: string;
+  from: string[];
+  to: string;
+}
+
+export interface Lifecycle {
+  field: string;
+  default: string;
+  transitions: Transition[];
+  /** Each state's badge tone: `neutral`, `ok`, `info`, `warn` or `danger`. */
+  tones: Record<string, string>;
+}
+
+export interface Command {
+  name: string;
+  goal: string | null;
+  role: string | null;
+  /** True when the command makes a new instance; false when it acts on one (`reference_to`). */
+  creates: boolean;
+  /** The aggregate the command acts on, when it is not a creating command. */
+  on: string | null;
+  /** True when the editor asks for confirmation before running it (see the generator's `Destructive`). */
+  destructive: boolean;
+  attributes: Attr[];
+  /** The arguments that only clear a field and are not offered as inputs: sent as empty lists. */
+  empty?: string[];
+}
+
+export interface Query {
+  name: string;
+  description: string | null;
+  attributes: Attr[];
+}
+
+/**
+ * A record of another aggregate that goes with this one's records, because its identity is a
+ * `<kind>:<slug>` key of this aggregate. `shape` says how to show it; `create` and `edit` name the
+ * commands that make and change it, when it has them.
+ */
+export interface Related {
+  aggregate: string;
+  chapter?: string;
+  /** The related aggregate's identity attribute, which the key fills. */
+  field: string;
+  shape: "document" | "gallery" | "metadata";
+  create?: string;
+  edit?: string;
+}
+
+/** An aggregate that keeps a draft of its content beside the live one, and the commands that handle it. */
+export interface Drafts {
+  /** The draft attribute (`draft_body`, `draft_content`) and the live one it stands for (`body`, `content`). */
+  attribute: string;
+  live: string;
+  save: string;
+  publish?: string;
+  discard?: string;
+}
+
+export interface Aggregate {
+  name: string;
+  /** The chapter that declares the aggregate; set when the editor spans several. */
+  chapter?: string;
+  /** The roles that may edit it, when its chapter limits them; any admitted role otherwise. */
+  roles?: string[];
+  description: string | null;
+  identity: string;
+  lifecycle: Lifecycle | null;
+  attributes: Attr[];
+  valueObjects: Record<string, Attr[]>;
+  commands: Command[];
+  queries: Query[];
+  /** The aggregates keyed by this one's records, shown as panels on a record's page. */
+  related?: Related[];
+  /** The draft the aggregate keeps beside its live content, when it keeps one. */
+  drafts?: Drafts;
+}
+
+/** How one part of a picture's record is sent: `wrap` is the part of a value object that holds the value. */
+export interface MediaField {
+  name: string;
+  wrap: string | null;
+}
+
+/** The aggregate that registers pictures, when the chapter has one: found by shape, never by name. */
+export interface Media {
+  aggregate: string;
+  command: string;
+  fields: { key: MediaField; alt: MediaField; mime: MediaField; width?: MediaField; height?: MediaField };
+  /** The query that lists the pictures, or null when every instance is read. */
+  listing: string | null;
+  /** The chapter that holds the picture aggregate, when it is not this editor's own chapter. */
+  domain?: string;
+  /** That aggregate, which is then not among the editor's own; see `domain`. */
+  definition?: Aggregate;
+}
+
+/**
+ * The aggregate whose records are actions to run later, found by shape: the attribute that names the
+ * record an action is for, the closed set of actions, the due time, and the commands. The editor only
+ * makes and changes these records; something else runs them.
+ */
+export interface Scheduling {
+  aggregate: string;
+  chapter?: string;
+  subject: string;
+  action: string;
+  actions: string[];
+  due: string;
+  /** The first state of a record: an action not yet run. */
+  pending: string;
+  schedule: string;
+  reschedule?: string;
+  cancel?: string;
+  /** The query that lists the actions of one subject, when there is one. */
+  query?: string;
+  /** The optional text a record may carry to say why it ended as it did. */
+  reason?: string;
+  /** True when the editor makes the record's identity, since it is not the subject. */
+  generated?: boolean;
+}
+
+export interface Schema {
+  /** The first chapter, which names the domain the host is asked for. */
+  domain: string;
+  /** Every chapter, in the order the navigation groups them; set when the editor spans several. */
+  chapters?: string[];
+  aggregates: Aggregate[];
+  media?: Media;
+  scheduling?: Scheduling;
+}
+
+export const SCHEMA: Schema = __SCHEMA__;

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

@@ -0,0 +1,65 @@
+__BANNER__
+
+// The editor's HTTP server: node's own `http` module turning each request into a web `Request` for
+// the handler in app.ts and writing its `Response` back. No framework. Start it with `npm start`;
+// it listens on `PORT` (default 4400) on `HOST` (default 127.0.0.1), behind the site's edge, which
+// routes the editor's base path here.
+import { createServer } from "node:http";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { createApp } from "./app.ts";
+import { EDITOR } from "./config.ts";
+
+const MAX_BODY_BYTES = 1_000_000;
+
+/** The room a picture upload's form framing takes beyond the picture's own size cap. */
+const UPLOAD_OVERHEAD_BYTES = 65_536;
+
+/** How much of a request's body is read: a picture upload may be as large as the row's size cap. */
+function limitOf(req: IncomingMessage): number {
+  const path = (req.url ?? "").split("?")[0];
+  return req.method === "POST" && path === `${EDITOR.basePath}/media` ? EDITOR.mediaMaxBytes + UPLOAD_OVERHEAD_BYTES : MAX_BODY_BYTES;
+}
+
+async function bodyOf(req: IncomingMessage): Promise<Buffer | undefined> {
+  if (req.method === "GET" || req.method === "HEAD") return undefined;
+  const limit = limitOf(req);
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > limit) throw new RangeError("request body too large");
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
+async function requestOf(req: IncomingMessage): Promise<Request> {
+  const proto = String(req.headers["x-forwarded-proto"] ?? "http").split(",")[0].trim();
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(req.headers)) if (value !== undefined) headers.set(name, String(value));
+  return new Request(`${proto}://${req.headers.host ?? "localhost"}${req.url ?? "/"}`, { method: req.method, headers, body: (await bodyOf(req)) as BodyInit | undefined });
+}
+
+async function send(res: ServerResponse, response: Response): Promise<void> {
+  const headers: Record<string, string | string[]> = {};
+  response.headers.forEach((value, name) => {
+    if (name !== "set-cookie") headers[name] = value;
+  });
+  const cookies = response.headers.getSetCookie();
+  if (cookies.length > 0) headers["set-cookie"] = cookies;
+  res.writeHead(response.status, headers);
+  res.end(Buffer.from(await response.arrayBuffer()));
+}
+
+const app = createApp();
+
+createServer(async (req, res) => {
+  try {
+    await send(res, await app(await requestOf(req)));
+  } catch (err) {
+    console.error(err);
+    res.writeHead(err instanceof RangeError ? 413 : 500, { "Content-Type": "text/plain" });
+    res.end(err instanceof RangeError ? "Request too large." : "The editor failed.");
+  }
+}).listen(Number(process.env.PORT || 4400), process.env.HOST || "127.0.0.1");

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

@@ -0,0 +1,15 @@
+__BANNER__
+
+// Which commands apply to a record now, and which of them need a page of their own.
+import type { Aggregate, Command } from "../schema.ts";
+
+type State = Record<string, unknown>;
+
+/** Whether a command applies to an instance in its present state: a lifecycle move only from its states. */
+export function available(agg: Aggregate, command: Command, state: State): boolean {
+  const move = agg.lifecycle?.transitions.find((transition) => transition.verb === command.name);
+  return !move || !agg.lifecycle || move.from.includes(String(state[agg.lifecycle.field]));
+}
+
+/** What a command needs asked first: it takes input, or it is destructive. */
+export const needsPage = (command: Command): boolean => command.attributes.length > 0 || command.destructive;

data/lib/hecks/projections/site/cms_editor/templates/src/ui/block_list.js.tmpl

@@ -0,0 +1,213 @@
+__BANNER__
+
+// The rules of a block list that need no page: which slots a kind shows, the one line that stands
+// for a block, whether a block is complete, and which block a refusal is about. Plain JavaScript
+// over plain data, used by the server that renders the cards and by the script that edits them, so
+// both answer the same way. A "list" here is an attribute's `blockList` (see schema.ts), a "block" is
+// one value of the list's value object, and a "part" is one of that value object's attributes.
+
+/** The discriminator's value in `block`, whether it is held as the plain text or as a one-part value object. */
+export function kindOf(list, block) {
+  const held = block?.[list.discriminator];
+  if (held && typeof held === "object") return String(Object.values(held)[0] ?? "");
+  return held === undefined || held === null ? "" : String(held);
+}
+
+const present = (value) => {
+  if (value === undefined || value === null || value === "") return false;
+  if (Array.isArray(value)) return value.some(present);
+  if (typeof value === "object") return Object.values(value).some(present);
+  return true;
+};
+
+/** Whether a part holds anything: text, a picture's key, a body with a block, a list with a row. */
+export const filled = present;
+
+/**
+ * The parts a kind shows, each with whether the kind needs it: the parts it needs first, then those it
+ * uses, then those common to every kind, each in the value object's own order.
+ * With a declared table (`rules`) these are the parts a row names, the parts no row names (common to
+ * every kind) and a picture's alt text with its key; with none, every part is shown, and a part that
+ * an invariant of the kind reads is marked as needed.
+ */
+export function slotsOf(list, parts, kind) {
+  const rule = list.rules?.[kind];
+  const named = new Set(Object.values(list.rules ?? {}).flatMap((row) => [...row.requires, ...row.uses]));
+  const mentioned = new Set(list.mentions?.[kind] ?? []);
+  const uses = new Set(rule ? [...rule.requires, ...rule.uses] : []);
+  const has = (name) => parts.some((part) => part.name === name);
+  const picture = Object.values(list.pictures ?? {}).find((one) => has(one.key) && has(one.alt));
+  if (picture && uses.has(picture.key)) uses.add(picture.alt);
+  return parts
+    .filter((part) => part.name !== list.discriminator)
+    .filter((part) => !rule || uses.has(part.name) || !named.has(part.name))
+    .map((part) => ({ part, required: rule ? rule.requires.includes(part.name) : false, mentioned: !rule && mentioned.has(part.name) }))
+    .map((slot, at) => ({ slot, at, rank: slot.required ? 0 : uses.has(slot.part.name) || slot.mentioned ? 1 : 2 }))
+    .sort((a, b) => a.rank - b.rank || a.at - b.at)
+    .map((one) => one.slot);
+}
+
+/** "1 entry", "3 entries": a list part's name, as a count of its rows. */
+const countOf = (name, count) => {
+  const words = name.replace(/_/g, " ");
+  return `${count} ${count === 1 ? words.replace(/([^aeiou])ies$/, "$1y").replace(/s$/, "") : words}`;
+};
+
+const textOf = (value) => (value && typeof value === "object" ? String(Object.values(value)[0] ?? "") : String(value ?? ""));
+
+/**
+ * The one line that stands for a block on its card: its first required text, else its longest text.
+ * A card that is itself a picture (`pictureOf`) in a list of one shape says the picture's description.
+ */
+export function summaryOf(list, parts, block, pictureOf) {
+  const kind = kindOf(list, block);
+  const slots = slotsOf(list, parts, kind).filter((slot) => slot.part.kind !== "object" && !slot.part.list && !slot.part.options);
+  const texts = slots.map((slot) => ({ ...slot, text: textOf(block?.[slot.part.name]).trim() })).filter((slot) => slot.text !== "");
+  const said = list.kinds.length === 0 && pictureOf ? texts.find((slot) => slot.part.name === pictureOf.alt) : undefined;
+  const first = said ?? texts.find((slot) => slot.required) ?? texts.reduce((best, slot) => (!best || slot.text.length > best.text.length ? slot : best), null);
+  if (first) return first.text.length > 80 ? `${first.text.slice(0, 79)}…` : first.text;
+  const counts = parts.filter((part) => part.list && filled(block?.[part.name])).map((part) => countOf(part.name, block[part.name].length));
+  return counts.join(", ");
+}
+
+/**
+ * What a block still lacks, as `{ slot, message }` for each: a part its kind requires that is empty,
+ * and a picture's alt text when it has a key. This is what the form can know before the domain is
+ * asked; the domain's own rules still decide.
+ */
+export function lacking(list, parts, block, pictureOf) {
+  const kind = kindOf(list, block);
+  const needs = slotsOf(list, parts, kind).filter((slot) => slot.required && !filled(block?.[slot.part.name]));
+  const missing = needs.map((slot) => ({ slot: slot.part.name, message: `${slot.part.name.replace(/_/g, " ")} is needed` }));
+  const picture = pictureOf?.key;
+  const alt = pictureOf?.alt;
+  if (picture && alt && filled(block?.[picture]) && !filled(block?.[alt])) missing.push({ slot: alt, message: "Describe the picture for people who cannot see it" });
+  return missing;
+}
+
+const normal = (value) => {
+  if (Array.isArray(value)) {
+    const items = value.map(normal).filter((item) => item !== undefined);
+    return items.length > 0 ? items : undefined;
+  }
+  if (value && typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    if (keys.length === 1 && keys[0] === "value") return normal(value.value);
+    const made = Object.fromEntries(keys.map((key) => [key, normal(value[key])]).filter(([, held]) => held !== undefined));
+    return Object.keys(made).length > 0 ? made : undefined;
+  }
+  return value === null || value === "" || value === undefined ? undefined : value;
+};
+
+const sameShape = (a, b) => JSON.stringify(normal(a) ?? null) === JSON.stringify(normal(b) ?? null);
+
+/** The words of a refusal: the value object it names, the rule's wording and the value it was given, when it echoes one. */
+export function readRefusal(error) {
+  const found = /^(.+?) invariant violated — (.+?)(?: \(given (.*)\))?$/s.exec(String(error ?? ""));
+  if (!found) return null;
+  let given = null;
+  try {
+    given = found[3] ? JSON.parse(found[3]) : null;
+  } catch {
+    given = null;
+  }
+  return { type: found[1], rule: found[2], given };
+}
+
+const sentence = (rule) => `${rule.charAt(0).toUpperCase()}${rule.slice(1)}.`;
+
+/** Whether a value object of `type` is held, at any depth, by the value object named `from`. */
+function holds(valueObjects, from, type, depth = 0) {
+  if (depth > 6) return false;
+  return (valueObjects[from] ?? []).some((part) => part.type === type || holds(valueObjects, part.type, type, depth + 1));
+}
+
+/**
+ * Every place in `args` (the arguments of the attributes `attrs`) a value object of `type` sits, as
+ * `{ path, name, attr }`: its path in the arguments, the dotted name of its fields in the form, and the
+ * attribute that holds it. A body holds the value objects of its tree, so a refusal about a block of it
+ * is the body's.
+ */
+function locate(type, attrs, args, valueObjects, path = [], prefix = "", depth = 0) {
+  const found = [];
+  if (depth > 6) return found;
+  for (const attr of attrs.filter((candidate) => candidate.kind === "object")) {
+    const held = args?.[attr.name];
+    const items = attr.list ? (Array.isArray(held) ? held : []) : held === undefined || held === null ? [] : [held];
+    items.forEach((item, at) => {
+      const here = attr.list ? [...path, attr.name, at] : [...path, attr.name];
+      const name = `${prefix}${attr.name}${attr.list ? `.${at}` : ""}`;
+      const within = attr.widget === "body" && holds(valueObjects, attr.type, type);
+      if (attr.type === type || within) found.push({ path: here, name, attr });
+      if (attr.widget !== "body") found.push(...locate(type, valueObjects[attr.type] ?? [], item, valueObjects, here, `${name}.`, depth + 1));
+    });
+  }
+  return found;
+}
+
+const pick = (args, path) => path.reduce((value, step) => value?.[step], args);
+
+/**
+ * The value objects a refused command's error is about, as `{ path, name, slots, message }` (`name` is
+ * the dotted name of the value object's fields in the form). The error is matched to the submitted
+ * value it echoes; with no echo it is the only value object of its type, else the blocks of a list
+ * whose kind the rule's wording names. A refusal that matches none gives nothing, and the page shows
+ * it as a whole. `slots` are the parts the value object lacks that it requires, else the parts the
+ * rule names.
+ */
+export function problemsOf(error, attrs, args, valueObjects) {
+  const read = readRefusal(error);
+  if (!read) return [];
+  const where = locate(read.type, attrs, args, valueObjects);
+  const exact = read.given ? where.filter((place) => sameShape(pick(args, place.path), read.given)) : [];
+  const worded = where.filter((place) => {
+    const kind = place.attr.blockList ? String(kindOf(place.attr.blockList, pick(args, place.path))) : "";
+    return kind !== "" && read.rule.includes(kind.replace(/_/g, " "));
+  });
+  const alone = !read.given && where.length === 1 ? where : [];
+  const chosen = [exact, worded, alone].find((list) => list.length > 0) ?? [];
+  return chosen.map((place) => ({ path: place.path, name: place.name, slots: slotsNamed(read, place, args, valueObjects), message: sentence(read.rule) }));
+}
+
+/** The parts of `parts` that a value object must have and has not (and a picture's description when it has the file). */
+function unmet(parts, block, picture) {
+  const missing = parts.filter((part) => !part.optional && !filled(block?.[part.name])).map((part) => part.name);
+  if (picture && filled(block?.[picture.key]) && !filled(block?.[picture.alt]) && !missing.includes(picture.alt)) missing.push(picture.alt);
+  return missing;
+}
+
+function slotsNamed(read, place, args, valueObjects) {
+  const parts = valueObjects[place.attr.type] ?? [];
+  const block = pick(args, place.path);
+  const list = place.attr.blockList;
+  const empty = list ? lacking(list, parts, block, list.pictures?.[place.attr.type]).map((one) => one.slot) : unmet(parts, block, place.attr.picture);
+  if (empty.length > 0) return empty;
+  return parts.filter((part) => new RegExp(`\\b${part.name.replace(/_/g, " ")}\\b`).test(read.rule)).map((part) => part.name);
+}
+
+/**
+ * Whether a member of a list holds anything a script has to make live: a rich-text body or a picture,
+ * at any depth (a list of its own among them). Such a member cannot be copied as plain inputs, so it is
+ * drawn as a card made from a template; a member of plain inputs, with rows of its own or none, stays
+ * a row.
+ */
+export function heavy(valueObjects, type, depth = 0) {
+  if (depth > 6) return false;
+  return (valueObjects[type] ?? []).some(
+    (part) => part.widget === "body" || part.picture !== undefined || (part.kind === "object" && heavy(valueObjects, part.type, depth + 1)),
+  );
+}
+
+/** A name as an id spells it: each run of anything but letters and digits is one hyphen. */
+export const safe = (text) => text.replace(/[^A-Za-z0-9]+/g, "-");
+
+/**
+ * `text` with the index of the card at `path` changed from `was` to `at`, in the dotted spelling of a
+ * field's name (`list.3.heading`) and in the spelling of an id made from it (`f-list-3-heading`), and
+ * in what is nested in the card at any depth.
+ */
+export function retarget(text, path, was, at) {
+  const dotted = text.split(`${path}.${was}.`).join(`${path}.${at}.`);
+  const tail = new RegExp(`(?<![A-Za-z0-9])${safe(path)}-${was}(?![0-9])`, "g");
+  return dotted.replace(tail, `${safe(path)}-${at}`);
+}