tablewalk 0.0.1

package/dist/client/template.js

@@ -0,0 +1,539 @@
+/**
+ * Record templates on the client: storage, and the builder.
+ *
+ * A template says how a record of one table is laid out — which of its own
+ * fields show and in what blocks, which references get pulled in beside them,
+ * and which child tables appear underneath. It is bound to the *table*, so
+ * configuring `work_order` once lays out every work order.
+ *
+ * The default is derived rather than blank. A blank record page is a worse
+ * starting point than the layout the record view already produces, and the
+ * fastest way to explain what a template is is to show someone one made of
+ * their own data — the builder opens on a working layout they can subtract
+ * from, rather than an empty canvas they have to fill.
+ *
+ * The shared model lives in src/shared/recordview.ts and is TypeScript, which
+ * the browser cannot load, so the derivation is mirrored here. It is a mirror
+ * with a test on the other side rather than a second source of truth: the
+ * grouping rules and thresholds are asserted there.
+ */
+import {
+  api, el, findTable, labelColumn, loadJson, looksLikeDateColumn, primaryKey,
+  refsFrom, refsTo, render, saveJson, state, tableAtPrefix, toast,
+} from './core.js';
+import { promptFor } from './prompt.js';
+import { fieldArranger } from './arrange.js';
+
+const STORE = 'tablewalk.templates.v1';
+
+const connectionKey = () => state.activeConnection ?? 'default';
+
+/* ---------- storage ----------
+
+   Layouts live on the server, in a file the user can read and copy between
+   machines, and are mirrored into localStorage on the way past.
+
+   The mirror is not a cache for speed — it is what makes rendering
+   synchronous. A record is drawn from its layout, and a layout that had to be
+   awaited would make every record either flash the derived layout first or
+   wait on a round trip to show fields the browser already had. So the server
+   copy is loaded once per connection and the mirror answers every read after
+   that.
+
+   It is also the fallback. If the server cannot write the file — a read-only
+   home directory, a permissions problem — the layout is still kept here and
+   the toast says which of the two happened, rather than reporting a success
+   that only half occurred. */
+
+function allTemplates() {
+  return loadJson(STORE, {})[connectionKey()] ?? {};
+}
+
+function mirror(templates) {
+  const all = loadJson(STORE, {});
+  all[connectionKey()] = templates;
+  saveJson(STORE, all);
+}
+
+/**
+ * Pull this connection's layouts from the server into the mirror.
+ *
+ * Called when a connection is opened. A failure is silent: the mirror already
+ * holds whatever this browser saved, and a tool that refuses to draw a record
+ * because a preferences request failed would be worse than one that draws it
+ * from the copy it has.
+ */
+export async function loadTemplates() {
+  try {
+    const { layouts } = await api('/api/layouts');
+    if (layouts && typeof layouts === 'object') mirror(layouts);
+  } catch {
+    /* Server-side layouts unavailable; the mirror stands. */
+  }
+}
+
+function writeTemplate(tableId, template) {
+  const all = loadJson(STORE, {});
+  all[connectionKey()] = { ...(all[connectionKey()] ?? {}) };
+  if (template) all[connectionKey()][tableId] = template;
+  else delete all[connectionKey()][tableId];
+  const local = saveJson(STORE, all);
+
+  /* Sent after the local write, not before. The browser copy is what the next
+     render reads, so it has to be in place before the page redraws; the file
+     is what makes the layout outlive this browser. */
+  void api('/api/layouts', { table: tableId, layout: template ?? null })
+    .catch((err) => toast(err.message, 'error'));
+
+  if (!local) {
+    toast('Could not save the layout — this browser is not allowing local storage.', 'error');
+    return false;
+  }
+  return true;
+}
+
+/** True when this table's layout has been configured rather than derived. */
+export const hasSavedTemplate = (tableId) => Boolean(allTemplates()[tableId]);
+
+/**
+ * The template to render a record with: the saved one, or a derived one.
+ *
+ * Never null. Every table has a layout; the only question is whether anyone
+ * has changed it.
+ */
+export function templateFor(tableId) {
+  return allTemplates()[tableId] ?? deriveTemplate(tableId);
+}
+
+/* ---------- derivation (mirrors shared/recordview.ts) ---------- */
+
+const GROUP_THRESHOLD = 12;
+const AUDIT_NAME = /^(sys_|created|updated|modified|deleted|inserted)|_(at|by)$|^(version|etag|revision)$/i;
+/* Mirrors DEFAULT_LIST_LIMIT in shared/recordview.ts, which is the source of
+   truth and says ten. This copy said eight — the two drifted, and the drift
+   was invisible because each side looked right on its own. */
+const DEFAULT_LIST_LIMIT = 10;
+
+/* The date test comes from core.js rather than being written out again here.
+   The copy that used to live at this spot had a narrower name pattern than
+   shared/schema.ts — no `datetime` or `timestamp` — so `event_timestamp TEXT`
+   landed in Details on a wide record while the server's grouping put it under
+   Dates, and the same record was laid out two different ways depending on
+   which side derived it. */
+export function groupOwnColumns(table) {
+  const columns = table.columns;
+  if (columns.length < GROUP_THRESHOLD) return [[null, columns]];
+
+  const label = labelColumn(table);
+  const groups = new Map([
+    ['Identity', []], ['Bookkeeping', []], ['References', []], ['Details', []], ['Dates', []],
+  ]);
+  for (const col of columns) {
+    if (col.primaryKey || col.name === label) groups.get('Identity').push(col);
+    else if (col.references) groups.get('References').push(col);
+    else if (AUDIT_NAME.test(col.name)) groups.get('Bookkeeping').push(col);
+    else if (looksLikeDateColumn(col)) groups.get('Dates').push(col);
+    else groups.get('Details').push(col);
+  }
+  return [...groups].filter(([, cols]) => cols.length);
+}
+
+/** A few columns that say what a row is, skipping keys and the join column. */
+/** Mirrors listColumns in shared/recordview.ts. */
+export function listColumns(table, exclude = []) {
+  const skip = new Set(exclude);
+  const chosen = table.columns.filter((c) => !skip.has(c.name)).map((c) => c.name);
+  return chosen.length ? chosen : primaryKey(table).slice(0, 1);
+}
+
+export function summaryColumns(table, exclude = [], max = 5) {
+  const skip = new Set(exclude);
+  const chosen = [];
+  for (const column of table.columns) {
+    if (skip.has(column.name)) continue;
+    if (column.primaryKey && table.columns.some((c) => !c.primaryKey && !skip.has(c.name))) continue;
+    chosen.push(column.name);
+    if (chosen.length >= max) break;
+  }
+  return chosen.length ? chosen : primaryKey(table).slice(0, 1);
+}
+
+export function deriveTemplate(tableId) {
+  const table = findTable(tableId);
+  if (!table) return { id: `derived:${tableId}`, name: tableId, base: tableId, sections: [] };
+
+  const sections = groupOwnColumns(table).map(([title, columns]) => ({
+    kind: 'fields',
+    title: title ?? undefined,
+    paths: columns.map((c) => c.name),
+  }));
+
+  /* Reference blocks are derived but start switched off. Pulling every
+     related row's columns into every record by default would double the
+     length of a page nobody asked to change — the point is that they are one
+     click away and visibly available, not that they are all already there. */
+  for (const fk of refsFrom(tableId)) {
+    if (fk.to.table === tableId) continue;
+    const target = findTable(fk.to.table);
+    if (!target) continue;
+    const via = fk.from.columns.join('+');
+    sections.push({
+      kind: 'fields',
+      title: `${target.name} · via ${fk.from.columns.join(', ')}`,
+      paths: summaryColumns(target).map((c) => `${via}.${c}`),
+      off: true,
+    });
+  }
+
+  for (const fk of refsTo(tableId)) {
+    const child = findTable(fk.from.table);
+    if (!child) continue;
+    sections.push({
+      kind: 'list',
+      title: child.name,
+      via: fk.name,
+      // Every column except the ones being joined on. See listColumns in
+      // shared/recordview.ts for why a child table is not summarised.
+      columns: listColumns(child, fk.from.columns),
+      limit: DEFAULT_LIST_LIMIT,
+    });
+  }
+
+  return { id: `derived:${tableId}`, name: table.name, base: tableId, sections };
+}
+
+/** Paths the base row must supply, across every enabled field section. */
+export function fieldPathsOf(template) {
+  const seen = new Set();
+  for (const section of template.sections) {
+    if (section.kind !== 'fields' || section.off) continue;
+    for (const path of section.paths) seen.add(path);
+  }
+  return [...seen];
+}
+
+/** Enabled list sections, in order. */
+export const listSectionsOf = (template) =>
+  template.sections.filter((s) => s.kind === 'list' && !s.off);
+
+/* ---------- the builder ---------- */
+
+let editing = null;
+let editingTable = null;
+
+/**
+ * The layout being edited, if the builder is open for this table.
+ *
+ * The record renders from this rather than from storage while the builder is
+ * open, which is what makes the preview live: a toggle changes the draft, the
+ * record re-renders, and you see the result before deciding to keep it. A
+ * builder that only shows its effect after saving asks you to commit to a
+ * change you have not seen.
+ */
+export const activeDraft = (tableId) => (editingTable === tableId ? editing : null);
+
+export function openTemplateBuilder(tableId) {
+  const table = findTable(tableId);
+  if (!table) return;
+  // Edited on a copy, so Cancel is a real cancel rather than an undo the user
+  // has to perform themselves.
+  editing = structuredClone(templateFor(tableId));
+  editingTable = tableId;
+  document.body.classList.add('editing-layout');
+  // Escape closes it, the way every other dismissable surface here does. The
+  // listener is added on open and removed on close so a session that opens
+  // the builder twenty times does not accumulate twenty handlers.
+  document.addEventListener('keydown', onBuilderKey, true);
+  paintBuilder(tableId, table);
+  render();
+}
+
+function onBuilderKey(e) {
+  if (e.key !== 'Escape') return;
+  /* Not while a text field is being edited — Escape there means "undo this
+     entry", and closing the whole builder would throw away the rest of the
+     work to cancel one word. */
+  const tag = document.activeElement?.tagName;
+  if (tag === 'INPUT' || tag === 'TEXTAREA') {
+    document.activeElement.blur();
+    return;
+  }
+  e.preventDefault();
+  close();
+}
+
+/** Redraw the builder and the record it is previewing, in that order. */
+function applied(tableId, table) {
+  paintBuilder(tableId, table);
+  render();
+}
+
+/**
+ * The preview alone, at most once a frame's worth of gesture.
+ *
+ * The arranger commits on every step of a drag — that is what makes the list
+ * follow the pointer — and a record render re-runs the query behind it. Left
+ * undebounced, dragging one field down a block of twenty fired twenty
+ * fetches, and the preview lagged the thing it was previewing. */
+let previewing = null;
+function preview() {
+  clearTimeout(previewing);
+  previewing = setTimeout(() => { previewing = null; render(); }, 120);
+}
+
+function paintBuilder(tableId, table) {
+  document.querySelector('.tpl')?.remove();
+
+  const body = el('div', { class: 'tpl-body' },
+    editing.sections.map((section, index) => sectionCard(section, index, tableId, table)));
+
+  /* The layout has a name, and the name is editable here.
+
+     It was always called after the table, which was fine while a table had
+     exactly one layout and useless the moment you want two — "the one with
+     the finance fields" and "the one for the service desk" are different
+     things and calling them both `work_order` says so of neither. Naming it
+     is also the smallest step towards a table having more than one, which is
+     where this is going. */
+  const name = el('input', {
+    type: 'text',
+    class: 'tpl-name',
+    /* A layout nobody has named is the default layout, and says so. It was
+       seeded with the table's name, which named nothing — the eyebrow and
+       the "for …" beside it already say the table twice. */
+    value: editing.name ?? 'Default layout',
+    'aria-label': 'Layout name',
+    placeholder: 'Default layout',
+    spellcheck: 'false',
+  });
+  // Written straight onto the draft: a name typed and then not saved should
+  // be discarded with everything else Cancel discards.
+  name.addEventListener('input', () => { editing.name = name.value; });
+
+  const panel = el('div', { class: 'tpl' }, [
+    el('div', { class: 'tpl-head' }, [
+      el('div', { class: 'tpl-title' }, [
+        el('span', { class: 'tpl-eyebrow', text: 'Record layout' }),
+        name,
+        el('span', { class: 'tpl-for', text: `for ${table.name}` }),
+      ]),
+      el('p', {
+        class: 'tpl-lede',
+        text: 'Applies to every record of this table. The record beside this updates as you change it.',
+      }),
+      el('div', { class: 'tpl-head-actions' }, [
+        el('button', {
+          type: 'button', class: 'ghost', text: 'Reset to default',
+          onclick: () => {
+            editing = deriveTemplate(tableId);
+            applied(tableId, table);
+          },
+        }),
+        el('button', { type: 'button', class: 'ghost', text: 'Cancel', onclick: close }),
+        el('button', {
+          type: 'button', text: 'Save layout',
+          onclick: () => {
+            // A blank name is the default layout, not an empty heading.
+            editing.name = (editing.name ?? '').trim() || 'Default layout';
+            if (writeTemplate(tableId, editing)) {
+              toast(`Saved “${editing.name}” for ${table.name}.`, 'ok');
+              close();
+              render();
+            }
+          },
+        }),
+      ]),
+    ]),
+    body,
+  ]);
+
+  document.body.append(panel);
+}
+
+function close() {
+  clearTimeout(previewing);
+  previewing = null;
+  document.querySelector('.tpl')?.remove();
+  editing = null;
+  editingTable = null;
+  document.body.classList.remove('editing-layout');
+  document.removeEventListener('keydown', onBuilderKey, true);
+  render();
+}
+
+function move(index, delta, tableId, table) {
+  const next = index + delta;
+  if (next < 0 || next >= editing.sections.length) return;
+  const [section] = editing.sections.splice(index, 1);
+  editing.sections.splice(next, 0, section);
+  applied(tableId, table);
+}
+
+function sectionCard(section, index, tableId, table) {
+  const isList = section.kind === 'list';
+  const child = isList ? childOf(section) : null;
+
+  return el('section', { class: `tpl-section${section.off ? ' off' : ''}` }, [
+    el('div', { class: 'tpl-section-head' }, [
+      el('label', { class: 'tpl-toggle' }, [
+        el('input', {
+          type: 'checkbox',
+          checked: !section.off,
+          onchange: (e) => {
+            section.off = !e.currentTarget.checked;
+            applied(tableId, table);
+          },
+        }),
+        el('span', { class: 'tpl-section-name', text: section.title ?? 'Fields' }),
+      ]),
+      el('span', {
+        class: 'tpl-section-kind',
+        text: isList ? `table · ${child ? child.name : section.via}` : 'fields',
+      }),
+      el('div', { class: 'tpl-section-actions' }, [
+        el('button', {
+          type: 'button', class: 'tpl-move', title: 'Move up', 'aria-label': 'Move up',
+          text: '↑', disabled: index === 0, onclick: () => move(index, -1, tableId, table),
+        }),
+        el('button', {
+          type: 'button', class: 'tpl-move', title: 'Move down', 'aria-label': 'Move down',
+          text: '↓', disabled: index === editing.sections.length - 1,
+          onclick: () => move(index, 1, tableId, table),
+        }),
+        el('button', {
+          type: 'button', class: 'tpl-move', title: 'Rename', 'aria-label': 'Rename section',
+          text: '✎',
+          onclick: async () => {
+            const name = await promptFor({
+              title: 'Rename section',
+              label: 'Heading',
+              value: section.title ?? '',
+              confirmLabel: 'Rename',
+            });
+            if (name === null) return;
+            section.title = name.trim() || undefined;
+            applied(tableId, table);
+          },
+        }),
+      ]),
+    ]),
+    section.off ? null : isList
+      ? listChoices(section, child, tableId, table)
+      : fieldChoices(section, tableId, table),
+  ].filter(Boolean));
+}
+
+function childOf(section) {
+  const fk = state.schema.foreignKeys.find((f) => f.name === section.via);
+  return fk ? findTable(fk.from.table) : null;
+}
+
+/**
+ * Which of the section's fields are shown, and in what order.
+ *
+ * The arranger is `arrange.js`, shared with the page builder. It used to be a
+ * grid of checkboxes here, which could say which fields but not where they
+ * go — and a record draws its fields in the order the layout lists them, so
+ * the order was a decision the builder had no way to make. Everything below
+ * is the translation between a record section and what the arranger asks for.
+ */
+function fieldChoices(section, tableId, table) {
+  /* The candidates are the columns of whichever table the section's paths
+     address — the base for a plain block, the referenced table for a pulled-in
+     one — so a reference block offers every column of the customer rather than
+     only the few the derivation picked. */
+  const prefix = section.paths[0]?.includes('.')
+    ? section.paths[0].slice(0, section.paths[0].lastIndexOf('.'))
+    : '';
+  const source = prefix ? tableAtPrefix(tableId, prefix) : table;
+  if (!source) return el('p', { class: 'note', text: 'That reference is no longer in the schema.' });
+
+  const qualify = (name) => (prefix ? `${prefix}.${name}` : name);
+  const all = source.columns.map((c) => qualify(c.name));
+  const types = new Map(source.columns.map((c) => [qualify(c.name), c.type.toLowerCase()]));
+
+  return fieldArranger({
+    all,
+    chosen: section.paths,
+    /* No label of its own: the card this sits in is headed with the block's
+       name, and "Fields fields · Fields 7 of 7" is one word three times. */
+    heading: null,
+    label: (path) => (prefix && path.startsWith(`${prefix}.`) ? path.slice(prefix.length + 1) : path),
+    typeOf: (path) => types.get(path) ?? '',
+    owner: section,
+    /* The record beside the builder, and nothing else.
+
+       `applied` repaints the builder too, which would replace the row being
+       dragged with a new one halfway through the gesture and end the drag.
+       The arranger repaints itself; what it cannot do is repaint the preview,
+       which is the whole point of editing a layout with the record open. */
+    onChange: (next) => { section.paths = next; preview(); },
+    others: otherFieldSections(section).map(({ s, i }) => ({
+      title: s.title || `block ${i + 1}`,
+      receive: (name) => { if (!s.paths.includes(name)) s.paths = [...s.paths, name]; },
+    })),
+    onSend: () => applied(tableId, table),
+  });
+}
+
+/** Every other block of fields in the draft, for sending a field to one. */
+function otherFieldSections(section) {
+  return editing.sections
+    .map((s, i) => ({ s, i }))
+    .filter(({ s }) => s.kind === 'fields' && s !== section && !s.off);
+}
+
+function listChoices(section, child, tableId, table) {
+  if (!child) return el('p', { class: 'note', text: 'That relationship is no longer in the schema.' });
+  const types = new Map(child.columns.map((c) => [c.name, c.type.toLowerCase()]));
+
+  return el('div', {}, [
+    /* The same arranger as a field block, because a list's columns are the
+       same kind of decision: which ones, and in what order they read left to
+       right. Nowhere to send a column, though — the other blocks on this
+       layout are about a different table. */
+    fieldArranger({
+      heading: 'Columns',
+      all: child.columns.map((c) => c.name),
+      chosen: section.columns,
+      typeOf: (name) => types.get(name) ?? '',
+      owner: section,
+      onChange: (next) => { section.columns = next; preview(); },
+    }),
+    el('label', { class: 'tpl-rows' }, [
+      el('span', { text: 'Rows on the page' }),
+      el('input', {
+        type: 'number', min: '1', max: '50',
+        value: String(section.limit ?? DEFAULT_LIST_LIMIT),
+        onchange: (e) => {
+          section.limit = Math.max(1, Math.min(50, Number(e.currentTarget.value) || 8));
+          applied(tableId, table);
+        },
+      }),
+    ]),
+  ]);
+}
+
+/** The control that opens the builder, for the record page to place. */
+export function editLayoutButton(tableId) {
+  const saved = allTemplates()[tableId];
+  const table = findTable(tableId);
+  /* The name shows on the button when it says something the table name does
+     not. A layout still called `work_order` adds nothing to a page already
+     headed `work_order`; one called "Service desk" is the answer to "why does
+     this record look like this". */
+  const named = saved?.name && saved.name !== table?.name ? saved.name : null;
+
+  return el('button', {
+    type: 'button',
+    class: `ghost record-layout${saved ? ' is-custom' : ''}`,
+    title: named
+      ? `Editing “${named}” — the layout for every ${table?.name ?? tableId} record`
+      : 'Choose what this record shows',
+    onclick: () => openTemplateBuilder(tableId),
+  }, [
+    el('span', { text: 'Layout' }),
+    named ? el('span', { class: 'record-layout-name', text: named }) : null,
+    !named && saved ? el('span', { 'aria-hidden': 'true', text: '\u2713' }) : null,
+  ].filter(Boolean));
+}

package/dist/client/theme.js

@@ -0,0 +1,74 @@
+/**
+ * Light, dark, or whatever the machine is set to.
+ *
+ * The palette for all three has been in style.css from early on: a full token
+ * override under `@media (prefers-color-scheme: dark)`, guarded as
+ * `:root:not([data-theme="light"])`, and a second copy under
+ * `:root[data-theme="dark"]`. That guard only means anything if something can
+ * stamp `data-theme`, and nothing ever did — so the dark palette was reachable
+ * by changing your operating system and by no other route, and the light one
+ * was unreachable from a dark machine at all.
+ *
+ * This is that missing piece and nothing more. It writes one attribute.
+ *
+ * Three states rather than two, because "system" is a real answer and not the
+ * absence of one: a reader who has told their machine to go dark at sunset
+ * means it here too, and a toggle that only remembers light-or-dark quietly
+ * opts them out of that. Absent attribute *is* the system state, which is why
+ * the CSS was written to key off its absence.
+ */
+const KEY = 'tablewalk.theme';
+const ORDER = ['system', 'light', 'dark'];
+
+const LABEL = {
+  system: 'match the system',
+  light: 'always light',
+  dark: 'always dark',
+};
+
+let current = 'system';
+
+function stored() {
+  try {
+    const raw = window.localStorage?.getItem(KEY);
+    /* Validated, not trusted: this comes back from storage a stale build or a
+       hand edit may have written, and an unknown value would stamp
+       `data-theme="banana"` — which matches no rule, so the page would render
+       in the light palette while claiming to be in another one. */
+    return ORDER.includes(raw) ? raw : 'system';
+  } catch {
+    return 'system';
+  }
+}
+
+function apply(name) {
+  current = ORDER.includes(name) ? name : 'system';
+  const root = document.documentElement;
+  if (current === 'system') root.removeAttribute('data-theme');
+  else root.setAttribute('data-theme', current);
+  /* Tells the browser which way to paint the things the page does not: form
+     controls, scrollbars, the canvas behind an overscroll. Without it a dark
+     page keeps light scrollbars. */
+  root.style.colorScheme = current === 'system' ? '' : current;
+}
+
+/** Read the stored choice and put it on the page. Called once, at boot. */
+export function initTheme() {
+  apply(stored());
+}
+
+/** What is in force, for a menu item that has to say so. */
+export const themeChoice = () => current;
+export const themeLabel = () => LABEL[current];
+
+/** system → light → dark → system. */
+export function cycleTheme() {
+  const next = ORDER[(ORDER.indexOf(current) + 1) % ORDER.length];
+  apply(next);
+  try {
+    window.localStorage?.setItem(KEY, next);
+  } catch {
+    /* A theme that cannot be remembered is still a theme for this tab. */
+  }
+  return next;
+}