tablewalk 0.0.1

package/dist/client/summary.js

@@ -0,0 +1,259 @@
+/**
+ * The schema, in a paragraph you can click.
+ *
+ * The diagram beneath this shows every table at once, which answers "what is in
+ * here" only for someone who already knows. This says it: where the domain
+ * centres, which tables are the ones you will actually query, how deep the
+ * references go, and what is sitting over there connected to nothing.
+ *
+ * Everything is a link, because a summary you cannot act on is a paragraph to
+ * read and then leave. Naming `customer` and not letting someone open it is the
+ * landing page describing the database instead of opening it.
+ *
+ * The analysis is in shape.js and is pure; this file only decides how to say
+ * it. Keeping those apart is what lets the hard part be tested without a
+ * browser.
+ */
+import { el, go, loadJson, saveJson, state, tableView } from './core.js';
+import { describeSchema } from './shape.js';
+import { openHelp } from './help.js';
+
+/* Collapsed or not, remembered.
+
+   The summary earns its space on a first visit and stops earning it on the
+   twentieth, and which visit this is is not something the page can work out.
+   So it asks once and remembers the answer — per database, because arriving
+   at an unfamiliar one is the case the summary exists for. */
+const OPEN_KEY = 'tablewalk.summary.open';
+const isOpen = (id) => loadJson(OPEN_KEY, {})[id] !== false;
+const setOpen = (id, open) => saveJson(OPEN_KEY, { ...loadJson(OPEN_KEY, {}), [id]: open });
+
+/** Names shown before a list becomes "and n more". */
+const NAMED = 5;
+
+const link = (table) =>
+  el('button', {
+    type: 'button',
+    class: 'shape-link',
+    title: `${table.columns.length} column${table.columns.length === 1 ? '' : 's'}`,
+    text: table.name,
+    onclick: () => go(tableView(table.id), 'reset'),
+  });
+
+/**
+ * A list of tables, capped.
+ *
+ * Twenty-three leaf tables listed in full is a wall that says less than five
+ * and a count — the reader is looking for the shape, and past a handful the
+ * names stop carrying it.
+ */
+function tableList(tables) {
+  const shown = tables.slice(0, NAMED);
+  const rest = tables.length - shown.length;
+  const out = [];
+  shown.forEach((t, i) => {
+    if (i) out.push(document.createTextNode(i === shown.length - 1 && !rest ? ' and ' : ', '));
+    out.push(link(t));
+  });
+  if (rest) out.push(document.createTextNode(`, and ${rest} more`));
+  return out;
+}
+
+function line(label, ...content) {
+  return el('li', { class: 'shape-line' }, [
+    el('span', { class: 'shape-label', text: label }),
+    el('span', { class: 'shape-says' }, content.flat()),
+  ]);
+}
+
+/**
+ * Where to start, in this database rather than in general.
+ *
+ * What stood here was three synthetic queries — `work_order is_urgent =
+ * false` and two more — teaching the syntax to someone who does not yet know
+ * what is in the database. That is the wrong first question. The paragraph
+ * directly above already answers the right one, and these are the same
+ * tables it names, with their sizes, as places to go.
+ *
+ * The language is still taught, just later and by example: clicking one puts
+ * `work_order` in the query bar and runs it, so the first thing anybody sees
+ * is that the bar takes a table name — which is the whole first lesson.
+ */
+function startingPoints(shape) {
+  const seen = new Set();
+  const picks = [];
+  const add = (table, why) => {
+    /* Four, not six. The card is capped at a share of the window, and a
+       fifth chip buys a row that gets clipped rather than read — the sixth
+       most-connected table in a schema is not where anyone starts. */
+    if (!table || seen.has(table.id) || picks.length >= 4) return;
+    seen.add(table.id);
+    picks.push({ table, why });
+  };
+
+  /* Hubs first — what the domain is built around — then the tables that
+     record what happened, which is usually what someone came to look at. */
+  for (const hub of shape.hubs) {
+    add(hub.table, `${hub.incoming} tables point at it`);
+  }
+  for (const leaf of shape.leaves) add(leaf, 'records events');
+  /* Then simply the biggest, for a schema with no clear shape: on a database
+     of forty flat tables, size is the only honest hint. */
+  for (const table of [...(state.schema?.tables ?? [])]
+    .filter((t) => !t.isView && typeof t.approxRows === 'number')
+    .sort((a, b) => (b.approxRows ?? 0) - (a.approxRows ?? 0))) {
+    add(table, 'the largest table here');
+  }
+  if (!picks.length) return null;
+
+  return el('section', { class: 'landing-starts' }, [
+    el('div', { class: 'landing-starts-head' }, [
+      el('h3', { class: 'shape-label', text: 'Start here' }),
+      el('button', {
+        type: 'button',
+        class: 'ghost help-more',
+        text: 'Query language (?)',
+        onclick: openHelp,
+      }),
+    ]),
+    el('div', { class: 'landing-chips' }, picks.map(({ table, why }) => el('button', {
+      type: 'button',
+      class: 'landing-chip start-chip',
+      title: `Open ${table.id}`,
+      onclick: () => go(tableView(table.id), 'reset'),
+    }, [
+      el('span', { class: 'landing-chip-name', text: table.name }),
+      el('span', { class: 'landing-chip-table' }, [
+        typeof table.approxRows === 'number'
+          ? el('span', { class: 'start-rows', text: `${table.approxRows.toLocaleString()} rows` })
+          : null,
+        el('span', { text: why }),
+      ].filter(Boolean)),
+    ]))),
+  ]);
+}
+
+export function schemaSummary() {
+  if (!state.schema) return null;
+  const shape = describeSchema(state.schema);
+  const { counts } = shape;
+  if (!counts.tables) return null;
+
+  const lines = [];
+
+  if (shape.hubs.length) {
+    /* First, because it is the answer to "what is this database about". A
+       table that nine others point at is the thing the domain is built
+       around, whatever it happens to be called. */
+    const [first] = shape.hubs;
+    lines.push(line(
+      'Centres on',
+      link(first.table),
+      document.createTextNode(`, referenced by ${first.incoming} other tables`),
+      shape.hubs.length > 1
+        ? [document.createTextNode('. Then '), ...tableList(shape.hubs.slice(1).map((h) => h.table))]
+        : [],
+    ));
+  }
+
+  if (shape.leaves.length) {
+    /* Leaves point outwards and are pointed at by nothing — the transaction
+       and event tables, which is usually what someone came to query and is
+       what a diagram buries at its edges. */
+    lines.push(line('Records events in', tableList(shape.leaves)));
+  }
+
+  if (shape.joins.length) {
+    lines.push(line(
+      'Connected through',
+      tableList(shape.joins.map((j) => j.table)),
+      document.createTextNode(shape.joins.length === 1 ? ', a join table' : ', which are join tables'),
+    ));
+  }
+
+  if (shape.chain.length > 2) {
+    // The domain written out. "Five levels deep" says less than the path.
+    const path = [];
+    shape.chain.forEach((t, i) => {
+      if (i) path.push(el('span', { class: 'shape-arrow', text: ' → ' }));
+      path.push(link(t));
+    });
+    lines.push(line('Deepest walk', path));
+  }
+
+  if (shape.islands.length) {
+    /* Worth saying out loud. A table connected to nothing is either
+       configuration or something whose relationships were never declared, and
+       both are things to know before trusting the diagram. */
+    lines.push(line(
+      'Standing alone',
+      tableList(shape.islands),
+      document.createTextNode(shape.islands.length === 1 ? ' — no foreign keys' : ' — no foreign keys at all'),
+    ));
+  }
+
+  if (!lines.length) return null;
+
+  const id = state.schema.connection ?? state.schema.label ?? '';
+  let open = isOpen(id);
+
+  /* The examples live inside this card rather than in a section of their own.
+     They are the same kind of thing — "here is what this database is, here is
+     what to type at it" — and two headed sections stacked above the diagram
+     spent more of the page on framing than on the schema. */
+  const body = el('div', { class: 'shape-body' }, [
+    el('ul', { class: 'shape-lines' }, lines),
+    startingPoints(shape),
+  ].filter(Boolean));
+
+  /* The one line that survives collapsing. Whatever else the summary said,
+     the table the domain is built around is the part worth keeping visible,
+     so folding the card away costs a reminder rather than the answer. */
+  const gist = shape.hubs.length
+    ? el('span', { class: 'shape-gist', text: `centres on ${shape.hubs[0].table.name}` })
+    : null;
+
+  const toggle = el('button', {
+    type: 'button',
+    class: 'shape-toggle',
+    'aria-expanded': String(open),
+    title: 'Show or hide the summary',
+    text: state.schema.label,
+  });
+
+  const section = el('section', { class: `shape${open ? '' : ' shape-closed'}` }, [
+    el('div', { class: 'shape-head' }, [
+      toggle,
+      el('span', {
+        class: 'shape-counts',
+        /* How many tables is a size, and a view is a different kind of
+           thing, so both are worth a word. A count of foreign keys is
+           neither: nobody decides anything from "20", and the lines
+           underneath say what the keys actually do — which is the only part
+           of the graph that was ever worth reading. */
+        text: `${counts.tables} table${counts.tables === 1 ? '' : 's'}`
+          + (counts.views ? `, ${counts.views} view${counts.views === 1 ? '' : 's'}` : ''),
+      }),
+      gist,
+      shape.start
+        ? el('button', {
+            type: 'button',
+            class: 'ghost shape-start',
+            title: 'The table that connects to the most, with names you can recognise rows by',
+            text: `Start at ${shape.start.name} →`,
+            onclick: () => go(tableView(shape.start.id), 'reset'),
+          })
+        : null,
+    ].filter(Boolean)),
+    body,
+  ]);
+
+  toggle.addEventListener('click', () => {
+    open = !open;
+    section.classList.toggle('shape-closed', !open);
+    toggle.setAttribute('aria-expanded', String(open));
+    setOpen(id, open);
+  });
+
+  return section;
+}