tablewalk 0.0.1

package/dist/client/table.js

@@ -0,0 +1,1035 @@
+/**
+ * The table view: tabs, results, sorting and paging.
+ *
+ * Sorting works by editing the query text rather than holding UI state, so
+ * the sort is visible in the language and survives being walked back to.
+ */
+import {
+  $, PAGE_SIZES, pageSize, setPageSize, api, currentEntry, el, findTable, go, keyOf,
+  looksLikeDateColumn, pageView, primaryKey, quote, render, rowLabel, rowView, setExplain,
+  showErrors, state, tableView, whenRemoved,
+} from './core.js';
+import { addSort, explicitLimit, nextSort, sortCount, sortDirection } from './clauses.js';
+import { SORT_SCAN_BELOW, planColumn, sortableFromHeader } from './columns.js';
+import { composeFilter } from './compose.js';
+import { promptFor, promptForRange } from './prompt.js';
+import { dropdown } from './dropdown.js';
+import { VIRTUAL_THRESHOLD, virtualise } from './virtual.js';
+import { diagram } from './diagram.js';
+import { exportControl } from './export.js';
+import { newRowButton } from './insert.js';
+import { recordQuery } from './history.js';
+import { applyPins, pinnedFor, togglePin } from './pins.js';
+import { initGrid } from './grid.js';
+import { peekable } from './peek.js';
+import { pagesFor } from './page.js';
+import { expandAllControl, expander, hasChildren, resetNested } from './nested.js';
+import { gridSkeleton, placeholder } from './skeleton.js';
+
+function tabs(entry) {
+  const bar = el('div', { class: 'tabs', role: 'tablist' });
+  for (const [id, label] of [['rows', 'Rows'], ['ddl', 'Definition'], ['diagram', 'Diagram']]) {
+    bar.append(el('button', {
+      type: 'button',
+      role: 'tab',
+      class: 'tab',
+      'aria-selected': String((entry.tab ?? 'rows') === id),
+      text: label,
+      onclick: () => go({ ...entry, tab: id }, 'replace'),
+    }));
+  }
+
+  /* The way into a page from a table.
+  
+     Not a tab of this table — a page is its own kind of entry, with its own
+     root — but this is where someone looks for it, and a feature reachable
+     only by editing a config file is a feature most people never meet. Every
+     table has a page: the one someone wrote, or the one built from its
+     schema. */
+  bar.append(el('button', {
+    type: 'button',
+    class: 'tab tab-page',
+    title: 'A page about one record of this table',
+    text: 'Page \u2192',
+    onclick: () => void openPageFor(entry.table),
+  }));
+  return bar;
+}
+
+/** Open this table's page: the configured one if there is one, else the suggested. */
+async function openPageFor(tableId) {
+  let pageId = `suggested:${tableId}`;
+  try {
+    const [configured] = await pagesFor(tableId);
+    if (configured && !configured.error) pageId = configured.id;
+  } catch {
+    // No config pages to read is not a reason to refuse the suggested one.
+  }
+  go(pageView(pageId, tableId), 'push');
+}
+
+/** The active virtualiser, torn down before another view replaces it. */
+let teardownVirtual = null;
+
+/** Bumped per run, so a reply that outlived its request paints nothing. */
+let runToken = 0;
+
+export async function renderTable(entry, content) {
+  // Any previous grid is gone the moment a new view renders; its scroll
+  // listener must go with it rather than outliving the DOM it watched.
+  teardownVirtual?.();
+  teardownVirtual = null;
+  $('query').value = entry.query;
+  const body = el('div');
+  content.append(tabs(entry), body);
+
+  if (entry.tab === 'diagram') {
+    body.replaceChildren(el('div', { class: 'panel-pad' }, diagram(entry.table)));
+    return;
+  }
+  if (entry.tab === 'ddl') {
+    const reading = placeholder(body, () => gridSkeleton(2, 6));
+    try {
+      const { sql, exact } = await api(`/api/ddl?table=${encodeURIComponent(entry.table)}`);
+      reading();
+      body.replaceChildren(
+        el('p', { class: 'ddl-note' }, [
+          el('strong', { text: exact ? 'Stored definition. ' : 'Reconstructed. ' }),
+          document.createTextNode(
+            exact
+              ? 'This is the statement the database itself keeps, verbatim.'
+              : 'Rebuilt from the catalog. Indexes, checks and triggers are not shown.',
+          ),
+        ]),
+        el('pre', { class: 'ddl', text: sql }),
+      );
+    } catch (err) {
+      reading();
+      body.replaceChildren(el('p', { class: 'note', text: err.message }));
+    }
+    return;
+  }
+
+  /* Shaped like the grid that is about to replace it, and only if the query
+     takes long enough to be worth acknowledging. */
+  const table = findTable(entry.table);
+  /* Claimed before the request goes out, checked when it comes back.
+  
+     Without this the *last response* won rather than the last request. Skim
+     the sidebar with the arrow keys and runs for two tables overlap; if the
+     slower one lands second it repaints the rows — but it also resets the
+     nested cache, replaces the error banner, rewrites the SQL pane and adds a
+     history entry, all belonging to a table you are no longer on. The grid
+     showed B's data under A's SQL and A's errors.
+  
+     Same shape as `runToken` in composer.js, which solved this for the
+     preview first. */
+  const mine = ++runToken;
+  const done = placeholder(body, () =>
+    gridSkeleton(table?.columns.length ?? 5, explicitLimit(entry.query) ?? pageSize()));
+
+  let data;
+  try {
+    /* An explicit `limit` in the query is a deliberate statement and beats
+       the page size. Without this the client's default silently overrode it,
+       so `limit 40000` returned twenty rows and the language quietly lied. */
+    const asked = explicitLimit(entry.query);
+    data = await api('/api/run', {
+      q: entry.query,
+      limit: asked ?? pageSize(),
+      offset: asked ? 0 : state.page * pageSize(),
+      // Set only by "count them", so the expensive path is asked for rather
+      // than arrived at.
+      exactCount: entry.exactCount === true,
+    });
+  } catch (err) {
+    if (mine !== runToken) return;
+    done();
+    body.replaceChildren(el('p', { class: 'note', text: err.message }));
+    return;
+  }
+  /* Nothing below this line touches only the body — `resetNested`,
+     `showErrors`, `setExplain` and `recordQuery` are all global — so a stale
+     reply has to stop here, before any of them. */
+  if (mine !== runToken) return;
+  done();
+  /* A new result means new rows; answers cached against the old ones are
+     answers to a question nobody is asking any more. */
+  resetNested();
+  showErrors(data.errors ?? []);
+  setExplain(data.explain);
+  if (!data.columns) {
+    body.replaceChildren(el('p', { class: 'note', text: 'Fix the query above to see results.' }));
+    return;
+  }
+
+  /* Recorded here rather than at submit: this is the point where the query is
+     known to have compiled and run, and a history full of typos you never got
+     an answer from is a history nobody opens. */
+  recordQuery(entry.query);
+
+  const shown = state.page * pageSize() + data.rows.length;
+  const head = el('div', { class: 'result-head' }, [
+    el('h2', { text: data.table }),
+    /* An estimate says so, and offers the real number.
+
+       `COUNT(*)` is a scan, so on a large table the header stat — which nobody
+       asked for — was the most expensive thing on the page. Above a threshold
+       it now comes from the catalog's own statistics instead, and the
+       interface has to be honest about which it is showing: "2,400,113" when
+       the truth is 2,411,908 is worse than "~2.4M", because one of them is
+       wrong and the other is not pretending. */
+    data.exactTotal === false
+      ? el('button', {
+          type: 'button',
+          class: 'stat stat-estimate',
+          title: 'Roughly, from the database’s own statistics — no rows were counted. Click to count them.',
+          onclick: () => void countExactly(entry, body),
+          text: data.total > shown
+            ? `${shown.toLocaleString()} of ~${approx(data.total)} rows`
+            : `~${approx(data.total)} rows`,
+        })
+      : el('span', {
+          class: 'stat',
+          text: data.total > shown
+            ? `${shown.toLocaleString()} of ${data.total.toLocaleString()} rows`
+            : `${data.total.toLocaleString()} row${data.total === 1 ? '' : 's'}`,
+        }),
+    el('span', { class: 'stat', text: `${data.ms} ms` }),
+    /* Named in the header as well as marked in the grid, because the column
+       it sorted by may not be one of the columns on screen — a `show name`
+       projection still gets ordered by the key. Clicking writes it into the
+       query, which turns a default into a decision. */
+    data.order?.implicit && data.order.order.length
+      ? el('button', {
+          type: 'button',
+          class: 'stat stat-order',
+          title: 'Rows have to come back in some order. Click to make this one explicit.',
+          onclick: () => sortBy(data.order.order[0].column, data.order.order[0].direction),
+          text: `sorted by ${data.order.order[0].column}${data.order.order[0].direction === 'desc' ? ' ↓' : ' ↑'}`,
+        })
+      : null,
+    /* Beside Export rather than among the stats: both are actions on the
+       table itself, and the gate (writable, write mode) already decided
+       whether the button exists at all. */
+    newRowButton(findTable(data.table)),
+    exportControl(entry, data),
+  ]);
+
+  body.replaceChildren(head, resultTable(findTable(data.table), data), pager(entry, data, shown));
+}
+
+/**
+ * A rounded figure, because an estimate written out in full reads as a count.
+ *
+ * "2,411,908" claims a precision the number does not have. "2.4M" says about
+ * as much as is known, which is the point.
+ */
+function approx(n) {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(n < 10_000_000 ? 1 : 0)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(n < 10_000 ? 1 : 0)}k`;
+  return String(n);
+}
+
+/** Re-run the query asking for the true count this time. */
+async function countExactly(entry, body) {
+  const stat = body.querySelector('.stat-estimate');
+  if (stat) stat.textContent = 'counting…';
+  /* The whole query again rather than a count on its own: the rows are already
+     cached by the browser and this keeps one code path, where a second one
+     would be a second place for the count and the page to disagree. */
+  go({ ...entry, exactCount: true }, 'replace');
+}
+
+/**
+ * A result grid, for anything that has rows and columns.
+ *
+ * Exported so the record page's embedded tables render exactly like the main
+ * grid — same type-aware cells, same alignment, same null and boolean
+ * treatment. Two renderers would drift, and a work order's parts showing
+ * `1`/`0` where the table above shows ✓/✗ is the kind of small inconsistency
+ * that makes a tool feel assembled rather than built.
+ */
+export function renderGrid(table, data, { onRowClick, compact = false, emptyText } = {}) {
+  const wrap = resultTable(table, data, { onRowClick, virtual: false, emptyText });
+  if (compact) wrap.classList.add('grid-compact');
+  return wrap;
+}
+
+function resultTable(table, data, options = {}) {
+  const wrap = el('div', { class: 'table-wrap' });
+  /* A caller that knows what it was asking for gets the shape of the answer
+     even when the answer is nothing: the headers say which columns had
+     nothing in them, which is the same argument the empty query result has
+     always made, and an empty related list is where it matters most — the
+     sentence alone leaves you unable to tell an empty list from a broken
+     one. */
+  if (!data.rows.length && !(options.emptyText && data.columns?.length)) {
+    /* "No rows match" claims a filter did it. On `customer` with no
+       conditions, nothing was excluded — the table is empty, which is a fact
+       about the database and a different thing to be told. Saying the first
+       when the second is true sends someone looking for a filter that is not
+       there. */
+    const entry = currentEntry();
+    const filtered = !entry || entry.kind !== 'table'
+      || entry.query.trim() !== entry.table
+      || Boolean(data.errors?.length);
+    wrap.append(el('p', {
+      class: 'note',
+      text: filtered ? 'No rows match.' : 'This table is empty.',
+    }));
+    return wrap;
+  }
+  const byName = new Map((table?.columns ?? []).map((c) => [c.name, c]));
+  const plans = new Map(data.columns.map((name) => [name, planColumn(byName.get(name), name, data.rows)]));
+  const empty = !data.rows.length;
+
+  const interactive = options.virtual !== false;
+  /* Only where the header controls apply: an embedded child table is a handful
+     of columns in a panel, and freezing one of them buys nothing. */
+  const pinned = interactive ? pinnedFor(table, data.columns) : [];
+
+  /* Expanders are offered only on a page the virtualiser is not managing.
+  
+     An opened detail row is many times the height of an ordinary one, and the
+     virtualiser's whole model is that every row is the same height — it
+     computes each offset as `index * rowHeight`. Mixing the two would make the
+     scrollbar disagree with the content by a screenful. The default page is
+     twenty rows and is never virtualised, so the affordance is there when it is
+     wanted and absent on the forty-thousand-row result where it could not
+     work. */
+  // Built before the header, which holds a control that watches it.
+  const tbody = el('tbody');
+
+  /* Decided here rather than beside the loop that uses it, because the header
+     has to know: expanding every row is meaningless on a table whose rows are
+     a moving window over the result. */
+  const virtual = options.virtual !== false && data.rows.length > VIRTUAL_THRESHOLD;
+  const expandable = interactive
+    && data.rows.length <= VIRTUAL_THRESHOLD
+    && hasChildren(table);
+
+  /**
+   * Whether the header's controls have anything to act on.
+   *
+   * Sorting and filtering here work by rewriting the query text — that is the
+   * design, and it is why a filter built by clicking can be edited by typing.
+   * It also means both are meaningless for a result that did not come from a
+   * tablewalk query: a view fall-through, or a SQL statement. `table` being
+   * undefined is exactly that case.
+   *
+   * Left alone, the degradation was silent and wrong in three ways at once.
+   * `!table?.indexed` is `true` when there is no table, so *every* column
+   * became sortable and the unindexed-sort guard disappeared; clicking one
+   * rewrote text that was not a query; and the filter menu fabricated
+   * `${table} show ${column}` and re-ran it, which for a SQL result would
+   * destroy the statement.
+   */
+  const language = interactive && Boolean(table);
+
+  /* Whether a row click can go anywhere. A uniform property of the result, not
+     of each row: either the key columns are present or they are not. */
+  const navigable = Boolean(options.onRowClick)
+    || Boolean(table && primaryKey(table).length
+      && primaryKey(table).every((c) => data.columns.includes(c)));
+  const headRow = el('tr');
+  // An empty header over the expander column, so the cells below line up.
+  /* The one control that belongs above the expander column, and costs no row
+     of its own. Not offered on a virtualised table: half those rows do not
+     exist, and the ones that do are replaced as you scroll. */
+  if (expandable) {
+    headRow.append(el('th', { class: 'expander-cell' },
+      virtual ? null : expandAllControl(tbody)));
+  }
+  for (const name of data.columns) {
+    const meta = byName.get(name);
+    const plan = plans.get(name);
+    // An embedded table has no query behind it to sort or filter, so its
+    // header is a label rather than a set of controls that would do nothing.
+    /* Three states, and the difference between the last two matters:
+       sorted because the query says so, sorted because nothing did and the
+       rows had to come back in *some* order, and not sorted at all. The
+       implicit one is drawn faintly and says so on hover — it is a fact about
+       the result, not a choice the reader made. */
+    /* Sorting from the header is offered only on columns the database can
+       sort cheaply.
+
+       A header click is a one-click action with no visible cost, and on an
+       unindexed column of a large table it is a full scan and a sort of
+       everything to show twenty rows. The language still allows it — typing
+       `sort status` is an explicit request, made by someone who has said what
+       they want — but the interface does not hand it to you as though it were
+       free. */
+    /* Indexed, or small enough that it does not matter. `approxRows` unknown
+       is not treated as small: a table nobody could count is not one to
+       assume is cheap. */
+    const sortable = table
+      ? !table.indexed || table.indexed.includes(name) || sortableFromHeader(table)
+      : false;
+    const explicit = language ? sortStateFor(name) : null;
+    const implied = !explicit && data.order?.implicit
+      ? data.order.order.find((o) => o.column === name)?.direction ?? null
+      : null;
+    const sorted = explicit ?? implied;
+    headRow.append(
+      el(
+        'th',
+        {
+          // Headers take the column's alignment, so the label sits over its
+          // own values instead of drifting away from a right-aligned number.
+          class: `align-${plan.align}${explicit ? ' sorted' : ''}${implied ? ' sorted-default' : ''}`,
+          title: implied
+            ? `${meta ? `${meta.type} · ` : ''}default order — rows have to come back in some order, and this is the one tablewalk chose`
+            /* A view's computed column has no declared type, and now says so
+               rather than claiming BLOB — so there may be nothing to put here,
+               and an empty tooltip is worse than the column's own name. */
+            : meta?.type ? `${meta.type}${meta.nullable ? '' : ' NOT NULL'}` : name,
+        },
+        [
+          el('button', {
+            class: `th-sort${language && !sortable ? ' not-sortable' : ''}`,
+            type: 'button',
+            /* `aria-disabled`, not `disabled`.
+            
+               A disabled button is not focusable, so the sentence explaining
+               *why* a column cannot be sorted — the most useful thing on this
+               header — was reachable by hovering and by nothing else. Keyboard
+               and screen-reader users got a control that was simply absent,
+               with no reason given. Marked unavailable instead, and the click
+               does nothing. */
+            'aria-disabled': String(!language || !sortable),
+            title: !language
+              ? `${name} — sorting a result like this one means editing the statement that produced it`
+              : sortable
+                ? `Sort by ${name}`
+                : `${name} is not indexed — sorting it would scan the whole table. Type "sort ${name}" in the query bar if you mean it.`,
+            // Sorting edits the query text, so the sort is visible in the
+            // language rather than hidden in UI state.
+            /* Shift-click adds a level rather than replacing the clause, so
+               a two-column sort can be built by clicking. Without a modifier
+               it still replaces: reversing one column of `sort a, b` is not
+               something a plain click can express. */
+            onclick: (e) => {
+              if (!language || !sortable) return;
+              if (e.shiftKey) sortBy(name, sortDirection(entry.query, name) === 'asc' ? 'desc' : 'asc', true);
+              else sortBy(name);
+            },
+          }, [
+            document.createTextNode(name),
+            meta?.primaryKey ? el('span', { class: 'pk', text: ' key' }) : null,
+            meta?.references ? el('span', { class: 'fk', text: ' →' }) : null,
+            sorted ? el('span', { class: 'th-arrow', text: sorted === 'desc' ? ' ↓' : ' ↑' }) : null,
+          ]),
+          language ? el('button', {
+            class: 'th-filter',
+            type: 'button',
+            title: `Filter on ${name}`,
+            'aria-label': `Filter on ${name}`,
+            text: '⌄',
+            onclick: (e) => { e.stopPropagation(); openFilterMenu(e.currentTarget, meta, name, data.rows, plan); },
+          }) : null,
+        ].filter(Boolean),
+      ),
+    );
+  }
+
+  const openRow = options.onRowClick
+    ?? ((row) => {
+      const key = table && keyOf(table, row);
+      // A projection that leaves out the key produces rows with nothing to
+      // navigate by. Better to do nothing than to open a row that is not there.
+      if (!key) return;
+      go(rowView(table.id, key, rowLabel(table, row)));
+    });
+  const buildRow = (row, index) => {
+    /* No handler at all when there is nowhere to go, so the row is inert in the
+       DOM as well as in effect. It used to keep its `onclick` and its pointer
+       cursor and simply do nothing, which is the worst of both: it advertises
+       an action it does not have. */
+    const tr = navigable
+      ? el('tr', { class: 'clickable', onclick: () => openRow(row) })
+      : el('tr');
+    /* The row's place in the result, not in the DOM. Above the threshold the
+       rows in `tbody` are a moving window over `data.rows`, so `tr` position
+       and row number are different numbers; the keyboard cursor navigates by
+       this one. */
+    if (index !== undefined) tr.dataset.row = String(index);
+    if (expandable) tr.append(expander(table, row, tr) ?? el('td', { class: 'expander-cell' }));
+    for (const name of data.columns) tr.append(cell(byName.get(name), plans.get(name), row[name]));
+    return tr;
+  };
+
+  /* Beyond a few hundred rows the DOM, not the database, is the bottleneck:
+     forty-two thousand rows arrive in about 100ms and take seconds to put on
+     the page, after which every scroll and hover is slow. Below the threshold
+     windowing costs more than it saves. */
+  if (!virtual) {
+    data.rows.forEach((row, i) => tbody.append(buildRow(row, i)));
+  }
+  wrap.append(el('table', {}, [el('thead', {}, headRow), tbody]));
+
+  if (virtual) {
+    /* Started after the table is in the document, because the window is
+       measured from a real rendered row and from the scroller's actual
+       height — neither of which exists until it is attached. */
+    queueMicrotask(() => {
+      const scroller = wrap.closest('.content') ?? document.scrollingElement;
+      if (!wrap.isConnected) return;
+      teardownVirtual?.();
+      teardownVirtual = virtualise({
+        scroller,
+        tbody,
+        rows: data.rows,
+        renderRow: buildRow,
+        columns: data.columns.length,
+      });
+    });
+    wrap.append(el('p', {
+      class: 'note virtual-note',
+      text: `${data.rows.length.toLocaleString()} rows, drawn as you scroll.`,
+    }));
+  }
+
+  if (pinned.length) {
+    /* After layout, because the offsets are the widths of the columns to the
+       left and those are not known until the browser has measured them. The
+       observer re-measures on resize *and* after a virtualised repaint swaps
+       the rows out from under the ones already frozen. */
+    const freeze = () => applyPins(wrap, data.columns, pinned);
+    requestAnimationFrame(freeze);
+    const size = new ResizeObserver(freeze);
+    size.observe(wrap);
+    const rows = new MutationObserver(freeze);
+    rows.observe(tbody, { childList: true });
+
+    /* Stopped when the table they watch leaves the document. Without this,
+       two observers were created on every render and never stopped — each one
+       re-measuring pinned columns on a table nobody can see. */
+    whenRemoved(wrap, () => {
+      size.disconnect();
+      rows.disconnect();
+    });
+  }
+
+  /* After the table exists and after virtualisation is set up, so the cursor
+     is measuring rows that are really there. */
+  initGrid(wrap, {
+    tbody,
+    rowCount: data.rows.length,
+    columnCount: data.columns.length,
+    offset: expandable ? 1 : 0,
+    onOpen: navigable ? (index) => openRow(data.rows[index]) : undefined,
+    /* So a screen reader hears "of 63,010" rather than "of 20". An estimate is
+       not passed: announcing a guess as the count is worse than announcing
+       nothing, because nothing at least sounds like nothing. */
+    totalRows: data.exactTotal === false ? undefined : data.total,
+    firstRow: explicitLimit(currentEntry()?.query ?? '') ? 0 : state.page * pageSize(),
+  });
+
+  /* The reason there are no rows, under the headers that say what would have
+     been in them. */
+  if (empty) wrap.append(el('p', { class: 'note grid-empty', text: options.emptyText }));
+
+  return wrap;
+}
+
+/**
+ * One cell, rendered by what it holds.
+ *
+ * A reference is marked on the way out rather than in each branch: a foreign
+ * key can be a number, a string or a code, so the branch that draws it is
+ * decided by its *type* while whether it points somewhere is decided by the
+ * schema. Marking it in one place is what stopped numeric keys — the most
+ * common kind there is — from being the one sort that could not be peeked at.
+ */
+function cell(meta, plan, value) {
+  return peekable(paint(meta, plan, value), meta?.references, value);
+}
+
+/**
+ * Thousands separators on a numeric string too big to be a JS number.
+ *
+ * `toLocaleString` is the usual way to group digits and it cannot be used
+ * here: it takes a number, and turning this back into one is the rounding
+ * being avoided. So the grouping is done on the digits directly, which is all
+ * `useGrouping` was ever doing to the integer part anyway.
+ */
+function groupDigits(text) {
+  const neg = text.startsWith('-');
+  const digits = neg ? text.slice(1) : text;
+  const grouped = digits.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+  return neg ? `-${grouped}` : grouped;
+}
+
+function paint(meta, plan, value) {
+  if (value === null || value === undefined) {
+    return el('td', { class: `null align-${plan.align}`, text: 'null' });
+  }
+  const raw = String(value);
+  const classes = [`align-${plan.align}`];
+  if (plan.mono || plan.kind === 'number') classes.push('mono');
+
+  if (plan.kind === 'boolean') {
+    const on = value === true || value === 1 || value === '1' || value === 't';
+    return el('td', { class: `${classes.join(' ')} bool`, title: raw },
+      el('span', { class: on ? 'yes' : 'no', text: on ? '✓' : '✗' }));
+  }
+
+  if (plan.kind === 'number') {
+    const n = Number(value);
+    /* A value the server sent as a string because it is past 2^53 must not be
+       run back through Number() here — that is the exact rounding the server
+       fix avoided, undone one layer later. `9223372036854775807` came over the
+       wire intact and `Number(...).toLocaleString()` renders it
+       `9223372036854776000`: a different number, off by 193, that looks
+       perfectly valid. So a raw string that is not a safe integer is shown as
+       it arrived, grouped by hand rather than by a lossy round trip. */
+    const overflow = typeof value === 'string' && /^-?\d+$/.test(value)
+      && !Number.isSafeInteger(n);
+    const shown = overflow
+      ? groupDigits(value)
+      : Number.isFinite(n)
+        ? n.toLocaleString(undefined, {
+            minimumFractionDigits: plan.decimals,
+            maximumFractionDigits: plan.decimals,
+            useGrouping: plan.group,
+          })
+        : raw;
+    const td = el('td', { class: `${classes.join(' ')} num`, text: shown, title: shown === raw ? undefined : raw });
+    // A numeric foreign key is still a link into another table.
+    if (meta?.references) td.classList.add('reflink');
+    return td;
+  }
+
+  if (plan.kind === 'date') {
+    const shown = plan.showTime ? raw.replace('T', ' ') : raw.slice(0, 10);
+    return el('td', { class: classes.join(' '), text: shown, title: shown === raw ? undefined : raw });
+  }
+
+  if (meta?.references) {
+    return el('td', { class: classes.join(' ') },
+      el('span', { class: 'ref', text: raw, title: `→ ${meta.references.table}` }));
+  }
+  /* A grid cell shows one line, clipped at 30rem with an ellipsis, so nothing
+     past a couple of hundred characters is ever visible in it — and a `TEXT`
+     column can hold a whole document. Putting the raw value into the DOM and
+     into the `title` regardless meant a page of a hundred rows carried
+     megabytes nobody could read, and a native tooltip that spanned the
+     screen. The cell shows a bounded prefix and says how much more there is;
+     the record page, which is where a long value is actually read, still gets
+     it whole. */
+  const cell = clampCell(raw);
+  return el('td', { class: classes.join(' '), title: cell.title, text: cell.text });
+}
+
+/** The most a single grid cell will put in the DOM. Well past what 30rem shows. */
+const CELL_MAX = 300;
+
+function clampCell(raw) {
+  if (raw.length <= CELL_MAX) {
+    return { text: raw, title: raw.length > 40 ? raw : undefined };
+  }
+  /* A count rather than a bare ellipsis, because "there is more" and "there
+     are forty thousand more characters" are different facts about a row, and
+     the second is the one worth knowing before you open it. */
+  const more = raw.length - CELL_MAX;
+  return {
+    text: `${raw.slice(0, CELL_MAX)}…`,
+    title: `${more.toLocaleString()} more character${more === 1 ? '' : 's'} — open the row to read it`,
+  };
+}
+
+/** 'asc' | 'desc' when the current query sorts by this column, else null. */
+function sortStateFor(column) {
+  const entry = currentEntry();
+  if (!entry || entry.kind !== 'table') return null;
+  return sortDirection(entry.query, column);
+}
+
+/**
+ * The per-column filter menu.
+ *
+ * Every option writes a condition into the query bar rather than holding
+ * hidden state. That keeps one source of truth — the text — so a filter built
+ * by clicking can be edited by typing, saved as a view, shared as a link and
+ * read back later. A filter you cannot see is a filter you cannot debug.
+ */
+async function openFilterMenu(anchor, meta, name, rows, plan) {
+  document.querySelector('.th-menu')?.remove();
+
+  /* Values are sampled from the *unfiltered* table, not the visible page.
+     Once you have filtered to status = scheduled the page contains only
+     scheduled rows, so a menu built from it offers exactly the filter you
+     already applied — useless precisely when you want to widen. */
+  const entryNow = currentEntry();
+  let sample = rows;
+  if (entryNow && entryNow.kind === 'table' && entryNow.query.trim() !== entryNow.table) {
+    try {
+      const unfiltered = await api('/api/run', {
+        q: `${entryNow.table} show ${name}`,
+        limit: 400,
+      });
+      if (unfiltered.rows?.length) sample = unfiltered.rows;
+    } catch {
+      // Sampling is a nicety; the rest of the menu still works without it.
+    }
+  }
+  rows = sample;
+
+  /* The header this menu belongs to may be gone.
+  
+     The sample takes a round trip, and navigating during it leaves the
+     anchor detached — `getBoundingClientRect` on a node that is no longer in
+     the document is all zeroes, so the menu opened in the top-left corner of
+     the window, attached to nothing, listing values from the table you just
+     left. */
+  if (!anchor.isConnected) return;
+
+  const add = (condition) => {
+    const entry = currentEntry();
+    if (!entry || entry.kind !== 'table') return;
+    go(tableView(entry.table, composeFilter(entry.query, entry.table, name, condition)), 'replace');
+    menu.remove();
+  };
+
+  const options = [];
+  const kind = plan.kind;
+
+  if (kind === 'boolean') {
+    options.push(['is true', `${name} = true`], ['is false', `${name} = false`]);
+  } else if (kind === 'date' || dateish(meta, name)) {
+    /* Dates get ranges, not equality. `= 2026-08-22` on a timestamp matches
+       an exact instant and almost never what was meant. */
+    for (const phrase of ['today', 'last 7 days', 'last 30 days', 'this month', 'last month', 'this year']) {
+      options.push([phrase, `${name} = ${phrase}`]);
+    }
+  } else if (kind === 'number') {
+    const values = rows.map((r) => Number(r[name])).filter((n) => Number.isFinite(n));
+    if (values.length) {
+      const max = Math.max(...values);
+      const min = Math.min(...values);
+      const mid = Math.round((min + max) / 2);
+      options.push([`greater than ${mid.toLocaleString()}`, `${name} > ${mid}`]);
+      options.push([`less than ${mid.toLocaleString()}`, `${name} < ${mid}`]);
+    }
+  }
+
+  /* Values present on this page, most frequent first. Only offered when the
+     column repeats — a column where every value is distinct is a key, and a
+     list of forty unique values is a worse way to pick one than typing it. */
+  const counts = new Map();
+  for (const row of rows) {
+    const value = row[name];
+    if (value === null || value === undefined) continue;
+    counts.set(value, (counts.get(value) ?? 0) + 1);
+  }
+  const distinct = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+  if (distinct.length && distinct.length <= Math.max(3, rows.length / 2)) {
+    for (const [value, count] of distinct.slice(0, 8)) {
+      const text = String(value);
+      const quoted = /^[\w.-]+$/.test(text) ? text : `"${text.replace(/"/g, '')}"`;
+      options.push([`${text}  ·  ${count}`, `${name} = ${quoted}`]);
+    }
+  }
+
+  options.push(['is empty', `${name} is empty`], ['is not empty', `${name} is not empty`]);
+
+  /* Typed conditions, always offered.
+
+     Sampled values only help on a column that repeats. On a key or a
+     high-cardinality reference — invoice_id across forty thousand rows — the
+     sample is a list of arbitrary values that happen to be near the top, and
+     the thing you actually want is to name the one you are looking for. */
+  /* Typed because the checker otherwise reads the tuples as a union and
+     decides `build` might be a string. Each entry is a label, the function
+     that turns a typed value into a condition, and the placeholder. */
+  /* A timestamp gets a time in its picker and a date does not. Read off the
+     declared type rather than the values: the answer has to be the same
+     before and after the table has any rows in it. */
+  const hasTime = /time|timestamp/i.test(meta?.type ?? '');
+  const dateInput = hasTime ? 'datetime-local' : 'date';
+  /* `2026-01-01T09:30` is what the control hands back and not what any of
+     these databases write. The separator is the only difference. */
+  const asStamp = (v) => String(v).replace('T', ' ');
+
+  /** @type {Array<[string, (value: string) => string, string, string]>} */
+  const typed = [];
+  if (kind === 'number') {
+    typed.push(
+      ['equals a value…', (v) => `${name} = ${v}`, 'Value', 'text'],
+      ['greater than…', (v) => `${name} > ${v}`, 'Minimum', 'text'],
+      ['less than…', (v) => `${name} < ${v}`, 'Maximum', 'text'],
+    );
+  } else if (kind === 'date') {
+    typed.push(
+      ['on or after…', (v) => `${name} >= ${quoteValue(asStamp(v))}`, 'Date', dateInput],
+      ['before…', (v) => `${name} < ${quoteValue(asStamp(v))}`, 'Date', dateInput],
+    );
+  } else {
+    typed.push(
+      ['equals a value…', (v) => `${name} = ${quoteValue(v)}`, 'Value', 'text'],
+      ['contains…', (v) => `${name} contains ${quoteValue(v)}`, 'Text to look for', 'text'],
+      ['starts with…', (v) => `${name} startswith ${quoteValue(v)}`, 'Prefix', 'text'],
+      /* The escape hatch from the three above, which all escape `%` so that
+         searching for `50%` finds a percent sign. Here the wildcards are the
+         question. */
+      ['matches a pattern…', (v) => `${name} like ${quoteValue(v)}`, 'Pattern, e.g. Wh% or _a%', 'text'],
+    );
+  }
+
+  /* `between` exists in the language and was reachable only by typing it.
+     Offered on the two kinds of column a range means anything on, and asked
+     as one question with two fields rather than as two prompts — a range with
+     one end filled in is a different filter from the one intended. */
+  /** @type {Array<[string, string, string]>} */
+  const ranges = [];
+  if (kind === 'date') ranges.push(['between…', dateInput, 'Date']);
+  else if (kind === 'number') ranges.push(['between…', 'text', 'Value']);
+
+  const table = findTable(currentEntry()?.table ?? '');
+  const columns = [...document.querySelectorAll('.table-wrap thead th')].map(
+    (th) => th.querySelector('.th-sort')?.firstChild?.textContent ?? '',
+  );
+  const pinned = pinnedFor(table, columns);
+
+  /* Sorting, always offered.
+
+     It was reachable only by clicking the header, and only on columns an index
+     leads on — so on an unindexed column there was no way to sort from the
+     interface at all, and nothing said why. The menu is where someone looks
+     for what they can do to a column, so both directions live here whatever
+     the index says, and the cost is stated rather than the action withheld:
+     a scan on a large table is a real cost, and it is the reader's to spend. */
+  const indexLeads = !table?.indexed || table.indexed.includes(name);
+  const bigTable = table?.approxRows != null && table.approxRows >= SORT_SCAN_BELOW;
+  const sortItem = (label, direction, add = false) => (entryNow && entryNow.kind === 'table'
+    ? el('button', {
+        type: 'button', class: 'th-menu-item', role: 'menuitem',
+        onclick: () => {
+          const rewrite = add ? addSort : nextSort;
+          go(tableView(entryNow.table, rewrite(entryNow.query, name, direction)), 'replace');
+          menu.remove();
+        },
+      }, [
+        el('span', { class: 'th-menu-label', text: label }),
+        el('span', {
+          class: 'th-menu-cond',
+          text: indexLeads || !bigTable ? `sort ${name}` : 'no index — a full scan',
+        }),
+      ])
+    : null);
+
+  /* "Then by" appears only once there is something to be *after*. Offering it
+     on an unsorted table would be offering a second step before the first. */
+  const sortsAlready = entryNow && entryNow.kind === 'table'
+    && sortCount(entryNow.query) > 0
+    && sortDirection(entryNow.query, name) === null;
+
+  const menu = el('div', { class: 'th-menu', role: 'menu' }, [
+    /* First, because it is the one item here that is about *reading* the table
+       rather than narrowing it — and on the wide tables where the menu is most
+       used it is the thing most often wanted. */
+    table
+      ? el('button', {
+          type: 'button', class: 'th-menu-item', role: 'menuitem',
+          onclick: () => { togglePin(table, columns, name); menu.remove(); render(); },
+        }, [
+          el('span', { class: 'th-menu-label', text: pinned.includes(name) ? 'Unpin this column' : 'Pin this column' }),
+          el('span', { class: 'th-menu-cond', text: pinned.includes(name) ? 'let it scroll away' : 'keep it in view' }),
+        ])
+      : null,
+    sortItem('Sort ascending', 'asc'),
+    sortItem('Sort descending', 'desc'),
+    sortsAlready ? sortItem('Then by, ascending', 'asc', true) : null,
+    sortsAlready ? sortItem('Then by, descending', 'desc', true) : null,
+    table ? el('div', { class: 'th-menu-sep', role: 'separator' }) : null,
+    ...typed.map(([label, build, placeholder, inputType]) =>
+      el('button', {
+        type: 'button', class: 'th-menu-item th-menu-typed', role: 'menuitem',
+        onclick: async () => {
+          menu.remove();
+          const value = await promptFor({
+            title: `Filter ${name}`,
+            label,
+            placeholder,
+            type: inputType,
+            confirmLabel: 'Apply',
+            hint: 'Adds a condition to the query, which you can edit afterwards.',
+          });
+          if (value) add(build(value));
+        },
+      }, [el('span', { class: 'th-menu-label', text: label })])),
+    ...ranges.map(([label, inputType, fieldLabel]) =>
+      el('button', {
+        type: 'button', class: 'th-menu-item th-menu-typed', role: 'menuitem',
+        onclick: async () => {
+          menu.remove();
+          const range = await promptForRange({
+            title: `Filter ${name}`,
+            fromLabel: `${fieldLabel} from`,
+            toLabel: `${fieldLabel} to`,
+            type: inputType,
+            hint: 'Both ends are included. Adds a condition you can edit afterwards.',
+          });
+          if (range) {
+            add(`${name} between ${quoteValue(asStamp(range.from))} and ${quoteValue(asStamp(range.to))}`);
+          }
+        },
+      }, [el('span', { class: 'th-menu-label', text: label })])),
+    typed.length ? el('div', { class: 'th-menu-sep', role: 'separator' }) : null,
+    ...options.map(([label, condition]) =>
+      el('button', { type: 'button', class: 'th-menu-item', role: 'menuitem', onclick: () => add(condition) }, [
+        el('span', { class: 'th-menu-label', text: label }),
+        el('span', { class: 'th-menu-cond', text: condition }),
+      ])),
+  ].filter(Boolean));
+
+  document.body.append(menu);
+  const box = anchor.getBoundingClientRect();
+  // Flipped to the left when it would run off the right edge, which happens
+  // constantly on a wide table scrolled to the end.
+  const width = menu.offsetWidth;
+  menu.style.top = `${box.bottom + 4}px`;
+  menu.style.left = `${Math.min(box.left, window.innerWidth - width - 12)}px`;
+
+  const dismiss = (e) => {
+    if (menu.contains(e.target)) return;
+    menu.remove();
+    document.removeEventListener('pointerdown', dismiss, true);
+    document.removeEventListener('keydown', onEsc, true);
+  };
+  const onEsc = (e) => { if (e.key === 'Escape') dismiss(e); };
+  document.addEventListener('pointerdown', dismiss, true);
+  document.addEventListener('keydown', onEsc, true);
+}
+
+/** Quote a typed value only when the grammar needs it. */
+/* Trims, then hands the value to the one quoter — this used to *delete* an
+   embedded quote, so `Harbour "HQ"` silently became `Harbour HQ` and the
+   filter matched a different row, or none. */
+function quoteValue(text) {
+  return quote(String(text).trim());
+}
+
+/**
+ * The date test from core.js, applied to the name the *result set* used.
+ *
+ * A joined column arrives under its path — `customer_id.opened_on` — and the
+ * column meta beside it still calls itself `opened_on`, so the name has to be
+ * passed in rather than read off the meta.
+ *
+ * The copy that used to be written out here had lost `timestamp`, `datetime`
+ * and `deleted` from the name pattern, so the filter menu offered `=` on an
+ * `event_timestamp TEXT` column and hid the relative-date phrases that are
+ * the only sensible thing to say about a date.
+ */
+const dateish = (meta, name) => Boolean(meta) && looksLikeDateColumn({ type: meta.type, name });
+
+/**
+ * `append` adds a level to the sort instead of replacing it — shift-click,
+ * which is the gesture every grid uses for exactly this.
+ */
+function sortBy(column, direction, append = false) {
+  const entry = state.stack[state.stack.length - 1];
+  if (!entry || entry.kind !== 'table') return;
+  /* `nextSort` must keep receiving `undefined` when no direction was named:
+     an explicit direction means "write down what is already happening" and
+     deliberately skips the ascending → descending cycle. Defaulting it here
+     cost the header its second click. `addSort` has no cycle to skip, so it
+     takes a direction. */
+  go(tableView(entry.table, append
+    ? addSort(entry.query, column, direction ?? 'asc')
+    : nextSort(entry.query, column, direction)), 'replace');
+}
+
+/**
+ * Paging, for a table somebody might actually reach the end of.
+ *
+ * This was one `Next →` at twenty rows a page. On the demo's invoice lines —
+ * sixty-three thousand of them — that is three thousand clicks to the last
+ * page, which means the table was browsable at the front and nowhere else.
+ * Every part below exists because that number is absurd.
+ *
+ * The size control sits on the left whether or not there is a second page: it
+ * is a property of how you are reading the table, not of how much is left.
+ * "Last" and the page box appear only when the total is a real count — an
+ * estimate cannot say which page is last, and a control that jumps to a page
+ * that may not exist is worse than no control.
+ */
+function pager(entry, data, shown) {
+  const bar = el('div', { class: 'pager' });
+  // A query that names its own limit defines the whole result; paging through
+  // it would contradict what the user asked for.
+  if (explicitLimit(entry.query)) return bar;
+
+  const size = pageSize();
+  /* An estimated total cannot decide whether there is a next page.
+
+     `total` is a guess above ESTIMATE_ABOVE rows — read from the catalog
+     rather than counted — and a guess that comes in low hid `Next` on a table
+     that had more, with nothing on screen to say browsing had been cut short.
+     A full page returned is the honest signal: it means the database had at
+     least that many, whatever the estimate thinks. */
+  const full = (data.rows?.length ?? 0) >= size;
+  const counted = data.exactTotal !== false && typeof data.total === 'number';
+  const more = counted ? data.total > shown : full;
+  const lastPage = counted ? Math.max(0, Math.ceil(data.total / size) - 1) : null;
+
+  const goTo = (page) => {
+    const wanted = Math.max(0, lastPage === null ? page : Math.min(page, lastPage));
+    if (wanted === state.page) return;
+    state.page = wanted;
+    render();
+  };
+
+  /* The app's own dropdown, not a native `<select>`. Everywhere else that
+     picks between a handful of values — the connection picker most visibly —
+     uses this control, and a system popup opening in the middle of a page
+     that has its own look reads as something the page did not draw. */
+  bar.append(el('div', { class: 'pager-size' }, [
+    el('span', { text: 'Rows' }),
+    dropdown({
+      ariaLabel: 'Rows per page',
+      value: size,
+      items: PAGE_SIZES.map((n) => ({ value: n, label: String(n) })),
+      onChange: (n) => { setPageSize(n); render(); },
+    }),
+  ]));
+
+  const step = (text, label, to, enabled) => el('button', {
+    class: 'ghost', type: 'button', text, 'aria-label': label,
+    disabled: enabled ? undefined : true,
+    onclick: () => goTo(to),
+  });
+
+  bar.append(el('div', { class: 'pager-steps' }, [
+    step('« First', 'First page', 0, state.page > 0),
+    step('← Previous', 'Previous page', state.page - 1, state.page > 0),
+    /* The page number is an input, not a label. Reaching page 400 by clicking
+       Next four hundred times is the thing this whole function is fixing. */
+    counted
+      ? el('span', { class: 'page-label' }, [
+          el('span', { text: 'Page' }),
+          el('input', {
+            class: 'page-input',
+            type: 'number',
+            min: '1',
+            max: String(lastPage + 1),
+            value: String(state.page + 1),
+            'aria-label': 'Page number',
+            onchange: (e) => {
+              const asked = Number(e.target.value);
+              if (!Number.isFinite(asked)) { e.target.value = String(state.page + 1); return; }
+              goTo(Math.round(asked) - 1);
+            },
+          }),
+          el('span', { text: `of ${(lastPage + 1).toLocaleString()}` }),
+        ])
+      : el('span', { class: 'page-label', text: `Page ${state.page + 1}` }),
+    step('Next →', 'Next page', state.page + 1, more),
+    /* Absent on an estimate: the last page of a guess is a guess. */
+    counted ? step('Last »', 'Last page', lastPage, state.page < lastPage) : null,
+  ].filter(Boolean)));
+
+  return bar;
+}