tablewalk 0.0.1

package/dist/client/pagebuilder.js

@@ -0,0 +1,1222 @@
+/**
+ * Building a page without writing one.
+ *
+ * A page is a short JSON document and the format is not hard, but two things
+ * about it are: knowing which relationships exist, and spelling the path that
+ * reaches one. `invoice_id.customer_id` is obvious only once you already know
+ * it — which is the wrong way round for the field that decides whether a
+ * section shows the right rows.
+ *
+ * So the builder does not ask for a path. It asks the schema what points at
+ * the root, directly and one table further out, and offers the answers with
+ * their paths already written. Everything else is a name, a width and a
+ * limit, and those are choices rather than knowledge.
+ *
+ * What comes out is the same `PageDef` the config file holds, saved per
+ * connection in the browser — and copyable as JSON, because a page worth
+ * keeping is usually a page worth committing, and the format the builder
+ * writes has to be the format the file reads or the two will drift.
+ */
+import {
+  api, disclosure, el, findTable, go, loadJson, pageView, refsFrom, saveJson, state,
+  tableAtPrefix, toast,
+} from './core.js';
+import { promptFor } from './prompt.js';
+import { dropdown } from './dropdown.js';
+import { forgetPages } from './page.js';
+/* The arranger under both builders. Renamed on the way in: this module's own
+   `fieldArranger` is the page-shaped adapter around it. */
+import { carriedField, dropCarried, fieldArranger as fieldArrangerFor } from './arrange.js';
+
+const KEY = 'tablewalk.pages.saved';
+/* A mirror of `WIDTHS` in shared/page.ts, which the client cannot import —
+   and which the config parser validates against, so a width offered here that
+   the parser refuses is a page the builder can save and the file cannot hold.
+   Exported so mirrors.test.ts can compare the two. */
+export const WIDTHS = ['full', 'half', 'third'];
+
+/* The same, for the empty space a section can hold to either side. */
+export const OFFSETS = ['quarter', 'third', 'half', 'two-thirds'];
+
+/* The same, for how many columns a group of fields fills. Mirrored for the
+   same reason and asserted the same way. */
+export const FIELD_COLUMNS = [1, 2, 3];
+
+const storeKey = () => `${KEY}.${state.activeConnection ?? ''}`;
+
+/** Pages saved for the connection in hand, read from the local mirror. */
+export function savedPages(tableId) {
+  const all = loadJson(storeKey(), {});
+  const pages = Object.values(all);
+  return tableId ? pages.filter((p) => p.base === tableId) : pages;
+}
+
+/**
+ * Pull this connection's saved pages from the server into the mirror.
+ *
+ * The same arrangement record layouts have, for the same reason: the mirror
+ * is what makes reads synchronous, the file is what makes the work outlive
+ * this browser. A failure is silent — the mirror already holds whatever this
+ * browser saved.
+ */
+export async function loadSavedPages() {
+  try {
+    const { pages } = await api('/api/pages/saved');
+    if (pages && typeof pages === 'object') saveJson(storeKey(), pages);
+  } catch {
+    /* Server-side pages unavailable; the mirror stands. */
+  }
+}
+
+export function savePage(page) {
+  const all = loadJson(storeKey(), {});
+  all[page.id] = page;
+  const ok = saveJson(storeKey(), all);
+  /* Local first — the next render reads the mirror — then the file, which is
+     what makes the page outlive this browser. */
+  void api('/api/pages/save', { id: page.id, page })
+    .catch((err) => toast(err.message, 'error'));
+  /* Also tells the menu to rebuild: it was registered once at boot, so a page
+     built afterwards was reachable only from the link you were already on,
+     and a deleted one stayed listed as a command that opened nothing. */
+  forgetPages();
+  return ok;
+}
+
+export function deletePage(id) {
+  const all = loadJson(storeKey(), {});
+  delete all[id];
+  saveJson(storeKey(), all);
+  void api('/api/pages/save', { id, page: null })
+    .catch((err) => toast(err.message, 'error'));
+  forgetPages();
+}
+
+/* ---------- the panel ---------- */
+
+let panel = null;
+
+export function closeBuilder() {
+  panel?.remove();
+  panel = null;
+  document.removeEventListener('keydown', onKey, true);
+}
+
+function onKey(e) {
+  if (e.key !== 'Escape' || !panel) return;
+  /* Stopped as well as prevented: the composer and the palette both listen at
+     the document, and an Escape that closed three surfaces at once was a
+     complaint about this app's keyboard before. */
+  e.preventDefault();
+  e.stopPropagation();
+  closeBuilder();
+}
+
+/**
+ * Open the builder on a page.
+ *
+ * The draft is a copy, and nothing is written until Save. A builder that
+ * edited the live page would make "close without saving" impossible to offer
+ * honestly, and the first thing anyone does in a builder is try something.
+ */
+export async function openBuilder(page, { onSaved, onDeleted } = {}) {
+  closeBuilder();
+  const draft = structuredClone(page);
+  /* A page that came from the config file or from the schema is not this
+     browser's to change. Editing one starts a copy — which is what someone
+     means by opening the builder on it. */
+  /* One test, `source`, rather than the source *and* the id prefix it used
+     to also check: those two could disagree, and did — a suggested page said
+     `source: 'saved'`, so the builder here knew it was derived from the
+     prefix while the button that opens the builder read the source and
+     offered to edit it in place. */
+  const derived = page.source !== 'saved';
+  if (derived) {
+    draft.id = `saved:${page.base}:${Date.now()}`;
+    draft.name = `${page.name} (edited)`;
+    draft.source = 'saved';
+  }
+
+  let relations = [];
+  let references = [];
+  try {
+    const data = await api(`/api/pages/relations?table=${encodeURIComponent(page.base)}`);
+    relations = data.relations ?? [];
+    references = data.references ?? [];
+  } catch {
+    /* Without relations the builder can still reorder and rename what is
+       already there, which is worth more than refusing to open. */
+  }
+
+  const body = el('div', { class: 'pb-body' });
+  /* Which section has its panel open, if any. One at a time: two open panels
+     is a form taller than the window, and the second is nearly always the one
+     that was wanted. */
+  let open = -1;
+  const setOpen = (i) => { open = i; draw(); };
+  const draw = () => body.replaceChildren(...sections(draft, relations, references, draw, open, setOpen));
+
+  panel = el('div', { class: 'pb-backdrop', onclick: (e) => { if (e.target === panel) closeBuilder(); } }, [
+    el('div', { class: 'pb', role: 'dialog', 'aria-label': 'Edit page' }, [
+      el('div', { class: 'pb-head' }, [
+        el('h2', { class: 'pb-title', text: derived ? 'New page' : 'Edit page' }),
+        el('span', { class: 'pb-base', text: `about one ${page.base}` }),
+        el('button', {
+          type: 'button', class: 'ghost pb-close', text: '×',
+          'aria-label': 'Close', onclick: closeBuilder,
+        }),
+      ]),
+      el('div', { class: 'pb-name-row' }, [
+        el('label', { class: 'pb-label', text: 'Name' }),
+        el('input', {
+          /* The label beside it is a `<span>`-shaped `<label>` with no `for`,
+             so nothing connects the two — a screen reader reads an unlabelled
+             text box next to the word "Name" and cannot say they belong
+             together. */
+          'aria-label': 'Page name',
+          class: 'pb-input', value: draft.name,
+          oninput: (e) => { draft.name = e.target.value; },
+        }),
+        /* Tabs are the default, so this is the way *out* of them. Beside the
+           name rather than on any one section, because it is a fact about
+           the page: which lists are tabs of each other is decided by their
+           order, which is what the grips are for. */
+        el('label', { class: 'pb-tabs-toggle', title: 'Lists that sit next to each other become tabs' }, [
+          el('input', {
+            type: 'checkbox',
+            checked: draft.listTabs !== false,
+            onchange: (e) => {
+              draft.listTabs = e.target.checked ? undefined : false;
+              draw();
+            },
+          }),
+          el('span', { text: 'Lists as tabs' }),
+        ]),
+      ]),
+      body,
+      el('div', { class: 'pb-add' }, [
+        el('span', { class: 'pb-label', text: 'Add' }),
+        addFields(draft, draw),
+        addRelation('+ Count', 'metric', draft, relations, references, draw),
+        addRelation('+ List', 'list', draft, relations, references, draw),
+      ]),
+      el('div', { class: 'pb-foot' }, [
+        /* Only on a page this browser owns. A config page belongs to the file
+           and a suggested one to the schema; neither is this dialog's to
+           remove, and offering it would be offering something that cannot
+           work. */
+        derived ? null : el('button', {
+          type: 'button', class: 'ghost pb-delete', text: 'Delete',
+          title: `Remove "${page.name}" from this browser`,
+          onclick: async () => {
+            const sure = await promptFor({
+              title: `Delete "${page.name}"?`,
+              label: 'Type the page name to confirm',
+              placeholder: page.name,
+              hint: 'It is stored in this browser only, so this cannot be undone from here.',
+            });
+            if (sure?.trim() !== page.name) return;
+            deletePage(page.id);
+            closeBuilder();
+            toast(`Deleted "${page.name}".`, 'ok');
+            onDeleted?.(page);
+          },
+        }),
+        el('button', {
+          type: 'button', class: 'ghost pb-json', text: 'Copy as JSON',
+          title: 'Paste into tablewalk.json to share it with the team',
+          onclick: () => void copyJson(draft),
+        }),
+        el('span', { class: 'pb-spacer' }),
+        el('button', { type: 'button', class: 'ghost', text: 'Cancel', onclick: closeBuilder }),
+        el('button', {
+          type: 'button', class: 'primary', text: 'Save',
+          onclick: () => {
+            if (!draft.sections.length) {
+              toast('A page needs at least one section.', 'error');
+              return;
+            }
+            if (!savePage(draft)) {
+              toast('This browser would not store the page.', 'error');
+              return;
+            }
+            closeBuilder();
+            toast(`Saved "${draft.name}".`, 'ok');
+            onSaved?.(draft);
+          },
+        }),
+      ].filter(Boolean)),
+    ]),
+  ]);
+
+  draw();
+  document.body.append(panel);
+  document.addEventListener('keydown', onKey, true);
+  panel.querySelector('.pb-input')?.focus();
+}
+
+/**
+ * The Add buttons, each opening the list of real relationships.
+ *
+ * A menu of what the schema says exists, rather than a form asking for a
+ * table and a path. Grouped by distance because "points straight at this" and
+ * "two references away" are different kinds of answer, and the first is what
+ * someone wants nine times in ten.
+ */
+/**
+ * A group of fields: this record's own, or a referenced record's pulled in.
+ *
+ * The record view has always been able to show a to-one reference inline —
+ * the site a work order is at, laid out under the work order's own fields
+ * rather than one click away — and a page could express it too, because a
+ * field path may follow references. What was missing was the way to ask for
+ * it: `+ Fields` added the base table's columns and nothing else, so the one
+ * thing a page could do that a plain record view could not was the one thing
+ * the builder would not offer.
+ *
+ * Composite keys are spelled by constraint, single-column ones by their
+ * column — the same two spellings a path takes everywhere else, and the
+ * readable one wherever it is available.
+ */
+/**
+ * Keep an upward-opening menu inside the viewport.
+ *
+ * The menu anchors above its button and grew a set of reference groups, so
+ * on a page with few sections — where the Add row sits high — its top rows
+ * ran off the screen and could not be clicked. Where the button sits depends
+ * on the page, so the clamp is measured when the menu opens, not styled.
+ */
+function clampMenu(wrap, menu) {
+  wrap.addEventListener('toggle', () => {
+    if (!wrap.open) return;
+    const top = wrap.getBoundingClientRect().top;
+    menu.style.maxHeight = `${Math.min(352, Math.max(160, top - 16))}px`;
+  });
+}
+
+function addFields(draft, draw) {
+  const base = findTable(draft.base);
+  const outgoing = (base ? refsFrom(base.id) : [])
+    .filter((fk) => fk.to.table !== draft.base)
+    .map((fk) => ({ fk, target: findTable(fk.to.table) }))
+    .filter(({ target }) => target);
+
+  const push = (section) => { draft.sections.push(section); draw(); };
+
+  /* With nothing to reference there is no choice to make, and a menu with one
+     item is a button wearing a hat. */
+  if (!outgoing.length) {
+    return el('button', {
+      type: 'button', class: 'ghost', text: '+ Fields',
+      onclick: () => push({ kind: 'fields', width: 'full' }),
+    });
+  }
+
+  const menu = el('div', { class: 'pb-menu' });
+  const wrap = disclosure(el('details', { class: 'pb-picker' }, [
+    el('summary', { class: 'ghost pb-add-btn' }, '+ Fields'),
+    menu,
+  ]));
+  clampMenu(wrap, menu);
+
+  menu.append(el('div', { class: 'pb-group' }, [
+    el('h4', { class: 'pb-group-head', text: 'This record' }),
+    el('button', {
+      type: 'button', class: 'pb-menu-item',
+      onclick: () => { wrap.open = false; push({ kind: 'fields', width: 'full' }); },
+    }, [
+      el('span', { class: 'pb-menu-label', text: base?.name ?? draft.base }),
+      el('span', { class: 'pb-menu-detail', text: 'its own fields' }),
+    ]),
+  ]));
+
+  /* One item per referenced record, at either depth. The section a click
+     writes is the same shape both times: a prefix, and every column of the
+     table it lands on except the key the last hop used. */
+  const item = (prefix, viaText, target, lastFk) => el('button', {
+    type: 'button', class: 'pb-menu-item',
+    title: `${viaText} \u2192 ${target.name}`,
+    onclick: () => {
+      wrap.open = false;
+      push({
+        kind: 'fields',
+        title: `${target.name} \u00b7 via ${viaText}`,
+        /* Everything but the key it was reached by: the value is already
+           on the row above, and repeating it is a line of the form spent
+           saying what the heading said. */
+        paths: target.columns
+          .filter((c) => c.name !== lastFk.to.columns[0] || lastFk.to.columns.length > 1)
+          .map((c) => `${prefix}.${c.name}`),
+        width: 'full',
+        columns: 2,
+      });
+    },
+  }, [
+    el('span', { class: 'pb-menu-label', text: target.name }),
+    el('span', { class: 'pb-menu-detail', text: `via ${viaText}` }),
+  ]);
+
+  const hop = (fk) => (fk.from.columns.length === 1 ? fk.from.columns[0] : fk.name);
+
+  menu.append(el('div', { class: 'pb-group' }, [
+    el('h4', { class: 'pb-group-head', text: 'A record it points at' }),
+    ...outgoing.map(({ fk, target }) => item(hop(fk), fk.from.columns.join(', '), target, fk)),
+  ]));
+
+  /* And one reference further: the address of the site, the party of the
+     manager. The paths could always say it — `site_id.address_id.city` is
+     legal in a config — and the menu simply never offered it. Self-references
+     and round trips back to a table already one hop away are left out; the
+     one-hop entry is the shorter spelling of the same record. */
+  const oneAway = new Set(outgoing.map(({ target }) => target.id));
+  const further = outgoing.flatMap(({ fk, target }) =>
+    refsFrom(target.id)
+      .filter((second) => second.to.table !== draft.base && second.to.table !== target.id && !oneAway.has(second.to.table))
+      .map((second) => ({ fk, second, far: findTable(second.to.table) }))
+      .filter(({ far }) => far));
+  if (further.length) {
+    menu.append(el('div', { class: 'pb-group' }, [
+      el('h4', { class: 'pb-group-head', text: 'Two references along' }),
+      ...further.map(({ fk, second, far }) => item(
+        `${hop(fk)}.${hop(second)}`,
+        `${fk.from.columns.join(', ')} \u2192 ${second.from.columns.join(', ')}`,
+        far,
+        second,
+      )),
+    ]));
+  }
+
+  return wrap;
+}
+
+function addRelation(label, kind, draft, relations, references, draw) {
+  const menu = el('div', { class: 'pb-menu' });
+  const wrap = disclosure(el('details', { class: 'pb-picker' }, [
+    el('summary', { class: 'ghost pb-add-btn' }, label),
+    menu,
+  ]));
+  clampMenu(wrap, menu);
+
+  if (!relations.length && !references.length) {
+    menu.append(el('p', { class: 'note', text: 'Nothing points at this table.' }));
+    return wrap;
+  }
+
+  /* What is already on the page, of this kind, is not on offer.
+  
+     The menu listed every relationship whether or not the page already had a
+     list of it, so `+ List` on a page with three lists offered those same
+     three at the top — and a second identical section is almost never what
+     someone means by clicking Add.
+  
+     Per kind, not per relationship: counting a thing and also listing it is a
+     reasonable page, and is exactly what someone building one by hand does. */
+  const used = new Set(
+    draft.sections.filter((s) => s.kind === kind).map((s) => `${s.of ?? ''}|${s.from}|${s.path}`),
+  );
+  const available = relations.filter((r) => !used.has(`|${r.from}|${r.path}`));
+  /* The same offer, one reference out: what points at each record the root
+     points at. "Tickets at its site" is a real section and was previously a
+     hand-written config or nothing. */
+  const farther = references
+    .map((ref) => ({
+      ...ref,
+      relations: ref.relations.filter((r) => !used.has(`${ref.of}|${r.from}|${r.path}`)),
+    }))
+    .filter((ref) => ref.relations.length);
+
+  if (!available.length && !farther.length) {
+    menu.append(el('p', {
+      class: 'note',
+      text: kind === 'list'
+        ? 'Every relationship is already listed on this page.'
+        : 'Every relationship is already counted on this page.',
+    }));
+    return wrap;
+  }
+
+  /* Grouped by distance, and named for every distance that turns up. It said
+     "Two references away" over everything past the first hop, which on a wide
+     schema is also where the three-hop routes are — a hundred entries under a
+     heading that was wrong for most of them. */
+  const DISTANCE = ['Points straight at this', 'One reference away', 'Two references away', 'Three references away'];
+  const byHops = [...new Set(available.map((r) => r.hops))].sort((a, b) => a - b);
+  const groups = byHops.map((hops) => [
+    hops === 1 ? DISTANCE[0] : DISTANCE[hops] ?? `${hops} references away`,
+    available.filter((r) => r.hops === hops),
+  ]);
+
+  /* A hundred relationships is a scroll, and the one being looked for has a
+     name. Shown only where the list is long enough to need it — a search box
+     over six entries is furniture. */
+  const rows = [];
+  if (available.length + farther.reduce((n, ref) => n + ref.relations.length, 0) > 12) {
+    const search = el('input', {
+      type: 'search',
+      class: 'pb-input pb-menu-search',
+      placeholder: 'Filter\u2026',
+      'aria-label': 'Filter relationships',
+      autocomplete: 'off',
+      spellcheck: 'false',
+    });
+    search.addEventListener('input', () => {
+      const needle = search.value.trim().toLowerCase();
+      let shown = 0;
+      for (const { row, hay } of rows) {
+        const hit = !needle || hay.includes(needle);
+        row.hidden = !hit;
+        if (hit) shown += 1;
+      }
+      /* A heading with nothing under it reads as a category with no members
+         rather than as one that was filtered away. */
+      for (const group of menu.querySelectorAll('.pb-group')) {
+        group.hidden = ![...group.querySelectorAll('.pb-menu-item')].some((b) => !b.hidden);
+      }
+      empty.hidden = shown > 0;
+    });
+    /* Typed into rather than clicked through: the picker opens on a click on
+       its summary, and the caret should already be where the next keystroke
+       is going. */
+    wrap.addEventListener('toggle', () => { if (wrap.open) search.focus(); });
+    menu.append(search);
+  }
+  const empty = el('p', { class: 'note', text: 'Nothing matches.', hidden: true });
+
+  for (const [title, list] of groups) {
+    if (!list.length) continue;
+    menu.append(el('div', { class: 'pb-group' }, [
+      el('h4', { class: 'pb-group-head', text: title }),
+      ...list.map((relation) => el('button', {
+        type: 'button',
+        class: 'pb-menu-item',
+        // The route, so a choice between two `contract_line` entries is a
+        // choice between two things you can tell apart.
+        title: relation.via.join('  ←  '),
+        onclick: () => {
+          wrap.open = false;
+          draft.sections.push(kind === 'metric'
+            ? {
+                kind: 'metric', fn: 'count', from: relation.from, path: relation.path,
+                title: relation.label, width: 'third',
+              }
+            : {
+                kind: 'list', from: relation.from, path: relation.path,
+                title: relation.label, limit: 10, width: 'half',
+              });
+          draw();
+        },
+      }, [
+        el('span', { class: 'pb-menu-label', text: relation.label }),
+        el('span', { class: 'pb-menu-detail', text: relation.via.join('  \u2190  ') }),
+      ])),
+    ]));
+  }
+  /* Sections about a record the root points at, grouped per reference so
+     "of its site" reads as the destination it is rather than as one more
+     distance. Picking one writes `of` onto the section; everything else —
+     planning, filters, the empty state — is the machinery above. */
+  for (const ref of farther) {
+    menu.append(el('div', { class: 'pb-group' }, [
+      el('h4', { class: 'pb-group-head', text: `Points at its ${ref.targetName} (via ${ref.via})` }),
+      ...ref.relations.map((relation) => el('button', {
+        type: 'button',
+        class: 'pb-menu-item',
+        title: `${relation.via.join('  \u2190  ')}  \u2190  ${ref.targetName} of this record`,
+        onclick: () => {
+          wrap.open = false;
+          const title = `${relation.label} \u00b7 of its ${ref.targetName}`;
+          draft.sections.push(kind === 'metric'
+            ? {
+                kind: 'metric', fn: 'count', from: relation.from, path: relation.path,
+                of: ref.of, title, width: 'third',
+              }
+            : {
+                kind: 'list', from: relation.from, path: relation.path,
+                of: ref.of, title, limit: 10, width: 'half',
+              });
+          draw();
+        },
+      }, [
+        el('span', { class: 'pb-menu-label', text: relation.label }),
+        el('span', { class: 'pb-menu-detail', text: `of its ${ref.targetName}` }),
+      ])),
+    ]));
+  }
+  for (const button of menu.querySelectorAll('.pb-menu-item')) {
+    rows.push({ row: button, hay: button.textContent.toLowerCase() });
+  }
+  menu.append(empty);
+  return wrap;
+}
+
+/** The two lines a drop can be about to land on, cleared together. */
+function clearDropMarks(row) {
+  row.classList.remove('pb-drop-above', 'pb-drop-below');
+}
+
+/* ---------- one section ---------- */
+
+function sections(draft, relations, references, draw, open, setOpen) {
+  if (!draft.sections.length) {
+    return [el('p', { class: 'note', text: 'No sections yet. Add one below.' })];
+  }
+  return draft.sections.map((section, i) =>
+    sectionRow(draft, section, i, relations, references, draw, open, setOpen));
+}
+
+/**
+ * The relation a section came from, searched in the right pool.
+ *
+ * A section with `of` is about a record the root points at, so its relation
+ * lives under that reference — matching it against the root's own relations
+ * would either find nothing or, worse, find a same-named path that resolves
+ * somewhere else entirely.
+ */
+function relationBehind(section, relations, references) {
+  const pool = section.of
+    ? references.find((ref) => ref.of === section.of)?.relations ?? []
+    : relations;
+  return pool.find(
+    (r) => r.from === section.from && (r.path === section.path || r.aliases?.includes(section.path)),
+  );
+}
+
+function sectionRow(draft, section, index, relations, references, draw, open, setOpen) {
+  const move = (to) => {
+    if (to < 0 || to >= draft.sections.length) return;
+    const [moved] = draft.sections.splice(index, 1);
+    draft.sections.splice(to, 0, moved);
+    draw();
+  };
+
+  /* The order of these rows is the order of the page, so dragging one is the
+     most direct way to say where a section goes — the arrows are two clicks
+     each and four rows of travel. The grip rather than the whole row,
+     because the row is mostly inputs and dropdowns: a draggable row swallows
+     the click that puts a caret in the title. `draggable` is switched on
+     only while the pointer is on the grip, and off again the moment the drag
+     ends, so the inputs keep their own behaviour the rest of the time. */
+  const grip = el('span', {
+    class: 'pb-section-grip',
+    title: 'Drag to reorder',
+    'aria-hidden': 'true',
+    text: '\u2237',
+    onmousedown: () => { row.draggable = true; },
+    onmouseup: () => { row.draggable = false; },
+  });
+
+  const controls = [
+    el('input', {
+      class: 'pb-input pb-title-input',
+      value: section.title ?? '',
+      placeholder: section.kind === 'fields' ? 'Untitled' : section.from,
+      'aria-label': 'Section title',
+      oninput: (e) => { section.title = e.target.value || undefined; },
+    }),
+    /* Whose fields this group actually holds, said beside the title —
+       because the title is the author's and can say anything. A base-fields
+       group renamed "Country" showed every customer column under a heading
+       that promised the country's, and nothing on the row disagreed. */
+    section.kind === 'fields'
+      ? el('span', {
+          class: 'pb-holds',
+          text: `${(sharedPrefix(section.paths)
+            ? tableAtPrefix(draft.base, sharedPrefix(section.paths))?.name
+            : findTable(draft.base)?.name) ?? draft.base}'s fields`,
+        })
+      : null,
+  ].filter(Boolean);
+
+  /* One button for both kinds, built here so the panel below can relabel it
+     as boxes are ticked. Without that the count in the panel and the count on
+     the button disagreed until something else redrew the form. */
+  let relabel = null;
+
+  if (section.kind !== 'metric') {
+    const isFields = section.kind === 'fields';
+    // Matched on any spelling of the path, in the pool `of` says to search.
+    const relation = isFields ? null : relationBehind(section, relations, references);
+    /* For a group of fields that follows a reference, "all" is the *other*
+       table's columns — a site group reading "4 of 9" was counting against
+       the employee the page is about. Same rule the arranger uses, read off
+       the paths rather than stored twice. */
+    const fieldsPrefix = isFields ? sharedPrefix(section.paths) : '';
+    const fieldsTable = isFields
+      ? (fieldsPrefix ? tableAtPrefix(draft.base, fieldsPrefix) : findTable(draft.base))
+      : null;
+    const all = isFields
+      ? fieldsTable?.columns.map((c) => c.name) ?? []
+      : relation?.all ?? findTable(section.from)?.columns.map((c) => c.name) ?? [];
+
+    /* A record section says `all N`, because that is what no selection means
+       there. A list says `default`, because there it means the columns
+       tablewalk picks — not a fixed list, so saying "6 of 13" would claim a
+       choice nobody made. */
+    const label = () => {
+      const chosen = isFields ? section.paths : section.columns;
+      if (chosen?.length) return `${chosen.length} of ${all.length}`;
+      return isFields ? `all ${all.length}` : 'default';
+    };
+
+    const button = el('button', {
+      type: 'button',
+      class: `ghost pb-fields-btn${open === index ? ' open' : ''}`,
+      title: isFields
+        ? 'Choose which fields this section shows'
+        : 'Choose which columns this list shows',
+      'aria-expanded': String(open === index),
+      text: label(),
+      /* Opens in place rather than in a dialog of its own. A modal on top of
+         a modal buries the thing being edited — you lose sight of the section
+         you are configuring at the moment you are configuring it — and the
+         second has to be dismissed before the first can be touched again. */
+      onclick: () => { setOpen(open === index ? -1 : index); },
+    });
+    relabel = () => { button.textContent = label(); };
+    controls.push(button);
+  }
+
+  if (section.kind === 'list') {
+    const table = findTable(section.from);
+    const columns = table?.columns.map((c) => c.name) ?? [];
+    const current = section.orderBy?.[0];
+    controls.push(dropdown({
+      ariaLabel: 'Sort by',
+      value: current ? `${current.column}:${current.direction}` : '',
+      items: [
+        { value: '', label: 'default order', detail: 'whatever the table gives back' },
+        ...columns.flatMap((c) => [
+          { value: `${c}:asc`, label: `${c} ↑`, detail: 'lowest first' },
+          { value: `${c}:desc`, label: `${c} ↓`, detail: 'highest first' },
+        ]),
+      ],
+      onChange: (v) => {
+        if (!v) { section.orderBy = undefined; return; }
+        const [column, direction] = v.split(':');
+        section.orderBy = [{ column, direction }];
+      },
+    }));
+  }
+
+  if (section.kind === 'metric') {
+    // Matched on any spelling of the path, in the pool `of` says to search.
+    const relation = relationBehind(section, relations, references);
+    const numeric = relation?.columns ?? [];
+
+    controls.push(dropdown({
+      ariaLabel: 'Function',
+      value: section.fn,
+      items: ['count', 'sum', 'avg', 'min', 'max'].map((fn) => ({
+        value: fn,
+        label: fn,
+        /* Said where the choice is made rather than discovered on save: only
+           `count` reaches past one reference, and only `count` can be
+           narrowed by a filter. */
+        detail: fn === 'count'
+          ? 'rows, at any distance, and can be filtered'
+          : `${fn} of a column, one reference away`,
+        disabled: fn !== 'count' && numeric.length === 0,
+      })),
+      onChange: (fn) => {
+        section.fn = fn;
+        /* `count` takes no column, and leaving a stale one set would save a
+           page whose JSON says `count of total` — legal, ignored, and
+           confusing to whoever reads the file next. */
+        if (fn === 'count') section.column = undefined;
+        draw();
+      },
+    }));
+
+    if (section.fn !== 'count') {
+      controls.push(dropdown({
+        ariaLabel: 'Column',
+        value: section.column ?? '',
+        items: [
+          { value: '', label: numeric.length ? 'column…' : 'no number columns' },
+          ...numeric.map((c) => ({ value: c, label: c })),
+        ],
+        onChange: (c) => { section.column = c || undefined; },
+      }));
+    }
+  }
+
+  if (section.kind === 'list') {
+    controls.push(el('input', {
+      class: 'pb-input pb-limit',
+      type: 'number', min: '1', max: '100',
+      value: String(section.limit ?? 10),
+      'aria-label': 'Rows',
+      oninput: (e) => { section.limit = Number(e.target.value) || undefined; },
+    }));
+  }
+
+  if (section.kind === 'fields') {
+    /* How the fields inside this group are laid out, which is a different
+       question from how wide the group is: `half` is the group's share of the
+       page, `2` is the number of columns the fields fill inside it. */
+    controls.push(el('div', { class: 'pb-cols' }, dropdown({
+      ariaLabel: 'Field columns',
+      value: String(section.columns ?? ''),
+      items: [
+        { value: '', label: 'fit', detail: 'as many as the width allows' },
+        ...FIELD_COLUMNS.map((n) => ({
+          value: String(n),
+          label: `${n} col`,
+          detail: n === 1 ? 'one under another' : `${n} across, filled left to right`,
+        })),
+      ],
+      onChange: (v) => { section.columns = v ? Number(v) : undefined; draw(); },
+    })));
+  }
+
+  const WIDTH_MEANS = {
+    full: 'a row to itself',
+    half: 'two across',
+    third: 'three across',
+  };
+  const OFFSET_SHORT = { quarter: '\u00bc', third: '\u2153', half: '\u00bd', 'two-thirds': '\u2154' };
+  controls.push(el('div', { class: 'pb-width' }, dropdown({
+    ariaLabel: 'Width',
+    value: section.width ?? 'full',
+    items: WIDTHS.map((w) => ({ value: w, label: w, detail: WIDTH_MEANS[w] })),
+    onChange: (w) => { section.width = w; },
+  })));
+
+  /* Where the section sits, not just how wide it is: empty space to either
+     side, in the same fractions the widths come in. Two controls rather than
+     a matrix of combinations, because "half width, quarter each side" is
+     three independent choices and should read as three. */
+  const OFFSET_MEANS = {
+    quarter: 'a quarter of the row',
+    third: 'a third of the row',
+    half: 'half the row',
+    'two-thirds': 'two thirds of the row',
+  };
+  const offsetControl = (side, label, key) => el('div', { class: 'pb-width pb-offset' }, dropdown({
+    ariaLabel: `${side} offset`,
+    value: section[key] ?? '',
+    items: [
+      { value: '', label: `${label} 0`, detail: 'flush with the row' },
+      ...OFFSETS.map((o) => ({
+        value: o,
+        label: `${label} ${OFFSET_SHORT[o]}`,
+        detail: `${OFFSET_MEANS[o]} of empty space`,
+      })),
+    ],
+    onChange: (o) => { section[key] = o || undefined; },
+  }));
+  controls.push(offsetControl('Left', '\u21e5', 'offsetLeft'));
+  controls.push(offsetControl('Right', '\u21e4', 'offsetRight'));
+
+  const row = el('div', {
+    class: `pb-section pb-${section.kind}${open === index ? ' pb-open' : ''}${section.hidden ? ' pb-hidden' : ''}`,
+    /* A closed group of fields is a drop target for a field being dragged
+       out of an open one. The `\u2192` menu on each field row remains — it is
+       the keyboard's way of doing this — the drag is the direct version of
+       the same move. */
+    ondragstart: (e) => {
+      sectionDrag = index;
+      row.classList.add('pb-dragging');
+      e.dataTransfer.effectAllowed = 'move';
+      /* Firefox refuses to start a drag with nothing on the transfer, and
+         the payload is never read — the index above is the state. */
+      e.dataTransfer.setData('text/plain', String(index));
+      /* Stops the row from also being read as a field drop target while it
+         is the thing being dragged. */
+      e.stopPropagation();
+    },
+    ondragend: () => {
+      sectionDrag = null;
+      row.draggable = false;
+      row.classList.remove('pb-dragging');
+      clearDropMarks(row);
+    },
+    ondragover: (e) => {
+      /* A section being carried takes precedence: both drags land on the
+         same rows, and only one of them can be happening. */
+      if (sectionDrag !== null) {
+        if (sectionDrag === index) return;
+        e.preventDefault();
+        e.dataTransfer.dropEffect = 'move';
+        /* Above or below, decided by which half of the row the pointer is
+           in — so a drop lands where the line is drawn rather than where the
+           row happens to start. */
+        const box = row.getBoundingClientRect();
+        const below = e.clientY > box.top + box.height / 2;
+        row.classList.toggle('pb-drop-above', !below);
+        row.classList.toggle('pb-drop-below', below);
+        return;
+      }
+      const drag = carriedField();
+      if (section.kind !== 'fields' || !drag || drag.owner === section) return;
+      e.preventDefault();
+      e.dataTransfer.dropEffect = 'move';
+      row.classList.add('pb-drop');
+    },
+    ondragleave: () => {
+      row.classList.remove('pb-drop');
+      clearDropMarks(row);
+    },
+    ondrop: (e) => {
+      if (sectionDrag !== null) {
+        e.preventDefault();
+        clearDropMarks(row);
+        const box = row.getBoundingClientRect();
+        const below = e.clientY > box.top + box.height / 2;
+        const from = sectionDrag;
+        sectionDrag = null;
+        /* Insert-before semantics, corrected for the row that is about to
+           leave the list: dropping row 1 below row 3 means index 3, not 4. */
+        let to = below ? index + 1 : index;
+        if (from < to) to -= 1;
+        if (to === from) { draw(); return; }
+        const [moved] = draft.sections.splice(from, 1);
+        draft.sections.splice(to, 0, moved);
+        draw();
+        return;
+      }
+      if (section.kind !== 'fields') return;
+      e.preventDefault();
+      row.classList.remove('pb-drop');
+      dropFieldInto(draft, section, draw);
+    },
+  }, [
+    grip,
+    el('span', { class: 'pb-kind', text: section.kind }),
+    ...controls,
+    el('div', { class: 'pb-section-actions' }, [
+      /* Hidden, not removed. Removing throws away the columns, the order and
+         the filter that were chosen for this section; hiding keeps all of it
+         and stops drawing it, which is what "not on this page for now"
+         means. The row stays in the builder, dimmed, so the page can be got
+         back with one click rather than rebuilt. */
+      el('button', {
+        type: 'button',
+        class: 'ghost pb-hide',
+        text: section.hidden ? '\u25cc' : '\u25cf',
+        title: section.hidden ? 'Hidden — click to show' : 'Shown — click to hide',
+        'aria-label': section.hidden ? 'Show this section' : 'Hide this section',
+        'aria-pressed': String(Boolean(section.hidden)),
+        onclick: () => { section.hidden = section.hidden ? undefined : true; draw(); },
+      }),
+      el('button', {
+        type: 'button', class: 'ghost', text: '↑', title: 'Move up',
+        'aria-label': 'Move up', disabled: index === 0,
+        onclick: () => move(index - 1),
+      }),
+      el('button', {
+        type: 'button', class: 'ghost', text: '↓', title: 'Move down',
+        'aria-label': 'Move down', disabled: index === draft.sections.length - 1,
+        onclick: () => move(index + 1),
+      }),
+      el('button', {
+        type: 'button', class: 'ghost pb-remove', text: '×', title: 'Remove',
+        'aria-label': 'Remove section',
+        onclick: () => { draft.sections.splice(index, 1); draw(); },
+      }),
+    ]),
+  ]);
+
+  if (section.kind === 'metric' || open !== index) return row;
+  return el('div', { class: 'pb-group-row' }, [
+    row,
+    panelFor(draft, section, relations, draw, relabel),
+  ]);
+}
+
+/**
+ * Which columns a section shows, chosen in place.
+ *
+ * One picker for both kinds. A record section chooses among the page's own
+ * table; a list chooses among the table it lists — the same question about a
+ * different table, and two implementations of it would be two chances for
+ * them to disagree about what "all" means.
+ *
+ * A grid rather than a list: forty column names in one column is a scroll,
+ * and the names are short enough to read three or four across. Each row is a
+ * label, so the whole line toggles — a checkbox is a twelve-pixel target and
+ * the name beside it is not.
+ */
+function columnPicker({ title, all, chosen, isDefault, onChange, draw }) {
+  const picked = new Set(chosen);
+
+  const boxes = all.map((name) => el('label', { class: 'pb-field-row' }, [
+    el('input', {
+      type: 'checkbox',
+      checked: picked.has(name),
+      onchange: (e) => {
+        if (e.target.checked) picked.add(name);
+        else picked.delete(name);
+        commit();
+      },
+    }),
+    el('span', { class: 'pb-field-name', text: name }),
+  ]));
+
+  const count = el('span', { class: 'pb-field-count' });
+  const label = () => `${picked.size} of ${all.length}`;
+
+  function commit() {
+    onChange(all.filter((n) => picked.has(n)));
+    count.textContent = label();
+  }
+
+  const setAll = (on) => {
+    picked.clear();
+    if (on) for (const n of all) picked.add(n);
+    for (const box of boxes) box.querySelector('input').checked = on;
+    commit();
+    draw();
+  };
+
+  count.textContent = label();
+
+  return el('div', { class: 'pb-panel' }, [
+    el('div', { class: 'pb-panel-head' }, [
+      el('span', { class: 'pb-label', text: title }),
+      count,
+      el('span', { class: 'pb-spacer' }),
+      /* Only where there is one to go back to. A record section's "all" is
+         every column; a list's default is a chosen handful, and losing it by
+         clicking around would mean rebuilding it by hand. */
+      isDefault ? el('button', {
+        type: 'button', class: 'ghost', text: 'Default',
+        title: 'The columns tablewalk would pick',
+        onclick: () => { isDefault(); draw(); },
+      }) : null,
+      el('button', { type: 'button', class: 'ghost', text: 'All', onclick: () => setAll(true) }),
+      el('button', { type: 'button', class: 'ghost', text: 'None', onclick: () => setAll(false) }),
+    ].filter(Boolean)),
+    el('div', { class: 'pb-field-grid' }, boxes),
+  ]);
+}
+
+/**
+ * The hop every one of these paths starts with, if they all start with one.
+ *
+ * One segment, not the longest common run: a group two references deep is a
+ * thing someone can write in the file and the builder does not offer, and
+ * treating `a.b.c` and `a.b.d` as a group about `a.b` would have the arranger
+ * offer columns of a table the rest of the page cannot name.
+ */
+/**
+ * The hop every path in a group shares — `site_id`, or `site_id.address_id`
+ * two references along — or '' when the group is mixed.
+ *
+ * Read as everything up to the last segment, at any depth, so a config that
+ * writes `a.b.c` gets the same treatment as one that writes `a.b`: the
+ * arranger offers the right table's columns and the page drops the prefix
+ * from every label. This deliberately handled one hop for a while; the depth
+ * limit was in the reading, not in anything the paths could not say.
+ */
+export function sharedPrefix(paths) {
+  if (!paths?.length) return '';
+  const first = paths[0];
+  if (!first.includes('.')) return '';
+  const prefix = first.slice(0, first.lastIndexOf('.'));
+  return paths.every(
+    (p) => p.startsWith(`${prefix}.`) && !p.slice(prefix.length + 1).includes('.'),
+  ) ? prefix : '';
+}
+
+/* The section being carried, while it is being carried.
+   Module-level for the same reason the arranger's carried field is: the row
+   under the pointer and the row being dragged are two closures that never
+   meet, and the drag is one gesture across both. */
+let sectionDrag = null;
+
+/**
+ * A fields section's current paths, materialised.
+ *
+ * `undefined` means every column of the page's base in table order — the
+ * *target's* default. It was read as the source arranger's `all` for a
+ * while, which is one prefix away from being a different table's columns:
+ * sending `site_id.code` out of a site group into an untouched base group
+ * rewrote the base group as the site's fields.
+ */
+function fieldsOf(draft, target) {
+  return target.paths ?? (findTable(draft.base)?.columns.map((c) => c.name) ?? []);
+}
+
+/**
+ * Put a field into a group, once.
+ *
+ * A group still on its default holds every base column already, so blindly
+ * appending would list the field twice — once where it always was and once
+ * where it just landed.
+ */
+function receiveField(draft, target, name) {
+  const into = fieldsOf(draft, target);
+  target.paths = into.includes(name) ? into : [...into, name];
+}
+
+/** Move a dragged field into `target`, keeping both groups' invariants. */
+function dropFieldInto(draft, target, draw) {
+  dropCarried(target, (name) => receiveField(draft, target, name), draw);
+}
+
+/**
+ * The fields on this page section, in the order they are laid out.
+ *
+ * The interaction is `arrange.js`; this is only the translation between a
+ * page section and what the arranger asks for. Two things are page-specific
+ * and stay here: which table the group's fields come from, read off the
+ * shared prefix of its paths, and the storage rule — `undefined` means "every
+ * field in the table's own order", so a *reordered* "all" has to be written
+ * out or the arrangement is thrown away on save.
+ */
+function fieldArranger(draft, section, draw, relabel) {
+  const base = findTable(draft.base);
+  if (!base) return el('div');
+
+  /* Which table this group is about.
+
+     A group whose paths all start with the same hop is a *referenced* record
+     pulled inline — `site_id.code`, `site_id.name` — and the fields on offer
+     there are the site's, not the work order's. Read off the paths rather
+     than stored beside them, because the paths are the thing that has to stay
+     true: a group that says it is about `site` and holds a path that is not
+     would be two facts and one of them wrong. */
+  const prefix = sharedPrefix(section.paths);
+  const on = (prefix ? tableAtPrefix(draft.base, prefix) : base) ?? base;
+  const qualify = (name) => (prefix ? `${prefix}.${name}` : name);
+
+  const all = on.columns.map((c) => qualify(c.name));
+  const types = new Map(on.columns.map((c) => [qualify(c.name), c.type]));
+
+  return fieldArrangerFor({
+    all,
+    /* `undefined` means every field, in table order. The moment anything is
+       arranged that has to become an explicit list, or the arrangement has
+       nowhere to live. */
+    chosen: section.paths ?? all,
+    columns: section.columns ?? 1,
+    noun: 'page',
+    heading: 'Fields',
+    /* Shown without the hop that every one of them shares: the heading
+       already says which record this is, and repeating `site_id.` on every
+       line is the same eleven characters twelve times. */
+    label: (path) => (prefix && path.startsWith(`${prefix}.`) ? path.slice(prefix.length + 1) : path),
+    typeOf: (path) => types.get(path) ?? '',
+    owner: section,
+    onChange: (next) => {
+      /* Stored as no selection only when it is genuinely the default — every
+         field, in the table's own order. A reordered "all" is a choice, and
+         writing it back as `undefined` would throw the arrangement away on
+         save. */
+      const isDefault = next.length === all.length && next.every((n, i) => n === all[i]);
+      section.paths = isDefault ? undefined : next;
+      relabel?.();
+    },
+    /* Every other group of fields on this page, for sending a field to one. */
+    others: draft.sections
+      .map((s, i) => ({ s, i }))
+      .filter(({ s }) => s.kind === 'fields' && s !== section)
+      .map(({ s, i }) => ({
+        title: s.title || `group ${i + 1}`,
+        receive: (name) => receiveField(draft, s, name),
+      })),
+    onSend: draw,
+  });
+}
+
+/** The picker for whichever kind of section is open. */
+function panelFor(draft, section, relations, draw, relabel) {
+  if (section.kind === 'fields') return fieldArranger(draft, section, draw, relabel);
+
+  /* Matched on any spelling of the path: a hand-written config names a hop
+     by its column and this list names it by its constraint, and both resolve
+     to the same relationship. */
+  const relation = relations.find(
+    (r) => r.from === section.from && (r.path === section.path || r.aliases?.includes(section.path)),
+  );
+  const all = relation?.all ?? findTable(section.from)?.columns.map((c) => c.name) ?? [];
+  const defaults = relation?.defaults ?? [];
+  return columnPicker({
+    title: 'Columns',
+    all,
+    chosen: section.columns ?? defaults,
+    /* Undefined means "whatever tablewalk would pick", which is not the same
+       as the list those columns happen to be today — a page that said
+       `default` keeps working when the table gains a better one. */
+    isDefault: () => { section.columns = undefined; relabel?.(); },
+    onChange: (kept) => { section.columns = kept; relabel?.(); },
+    draw,
+  });
+}
+
+/* ---------- taking it out ---------- */
+
+/**
+ * The page as it would appear in tablewalk.json.
+ *
+ * The same shape the parser reads, not a description of it: a builder that
+ * emitted a near-miss would be a builder whose output someone has to correct
+ * before it works, which is worse than no button. `id` and `source` are left
+ * out because the file gives its own.
+ */
+export function asConfig(page) {
+  return JSON.stringify({
+    pages: [{
+      name: page.name,
+      base: page.base,
+      sections: page.sections.map((s) => {
+        const out = { kind: s.kind };
+        if (s.title) out.title = s.title;
+        if (s.kind === 'metric') {
+          out.fn = s.fn;
+          out.from = s.from;
+          out.path = s.path;
+          if (s.column) out.column = s.column;
+        }
+        if (s.kind === 'list') {
+          out.from = s.from;
+          out.path = s.path;
+          if (s.limit) out.limit = s.limit;
+          if (s.orderBy) out.orderBy = s.orderBy;
+        }
+        if (s.filter) out.filter = s.filter;
+        if (s.width && s.width !== 'full') out.width = s.width;
+        return out;
+      }),
+    }],
+  }, null, 2);
+}
+
+async function copyJson(page) {
+  const text = asConfig(page);
+  try {
+    await navigator.clipboard.writeText(text);
+    toast('Copied. Paste it into your tablewalk.json to share it.', 'ok');
+  } catch {
+    /* Clipboard access can be refused, and the text is the point — a prompt
+       someone can select from is a worse offer than the clipboard and a much
+       better one than nothing. */
+    await promptFor({
+      title: 'Copy this into tablewalk.json',
+      label: 'Page',
+      value: text,
+      multiline: true,
+    });
+  }
+}
+
+/** Start a page from scratch for a table. */
+export async function newPage(tableId, { onSaved } = {}) {
+  const table = findTable(tableId);
+  if (!table) return;
+  const name = await promptFor({
+    title: 'New page',
+    label: 'Name',
+    value: `${table.name}`,
+    placeholder: 'e.g. Customer 360',
+  });
+  if (!name) return;
+  await openBuilder({
+    id: `saved:${table.id}:${Date.now()}`,
+    name,
+    base: table.id,
+    sections: [{ kind: 'fields', width: 'full' }],
+    source: 'saved',
+  }, { onSaved: onSaved ?? ((page) => go(pageView(page.id, page.base), 'replace')) });
+}