tablewalk 0.0.1

package/dist/client/breakdown.js

@@ -0,0 +1,317 @@
+/**
+ * Counting things by something, on screen.
+ *
+ * The language grew `by` — `invoice count by status`, `sum total by month
+ * invoice_date` — and the query bar had nowhere to send it. Typing one got
+ * `"billed" is not a column on invoice`, an error about a column nobody
+ * claimed was one, with no hint that the thing being asked for exists. The
+ * agent tools could answer the sentence and the person looking at the same
+ * database could not.
+ *
+ * A breakdown is not a table view with a GROUP BY on it, and this module is
+ * separate from table.js for the same reason `BreakdownDef` is a sibling of
+ * `ViewDef` rather than a field on it: **the rows are not records.** Nothing
+ * that makes the grid a walking surface applies here — a group cannot be
+ * opened, has no primary key, has nothing pointing at it, and cannot be
+ * expanded, peeked at, pinned or edited. Building this on `resultTable` would
+ * have meant switching every one of those off and hoping none came back.
+ *
+ * What it does keep is the two things that are true of every result here: the
+ * keyboard cursor (`initGrid`, with no `onOpen` — the cells are readable and
+ * copyable, they just do not go anywhere), and sorting expressed by editing
+ * the query text rather than held as UI state. The second falls out of the
+ * grammar: `sort` on a breakdown names an output column, so a header click is
+ * the same text edit it is everywhere else in this tool.
+ *
+ * The parsing all happens on the server, as it does for the query bar and the
+ * composer's filter box. The one rule that has to exist twice is *whether a
+ * line is a breakdown at all*, because that decision is made before any
+ * request goes out — see `looksLikeBreakdown`, and the parity test in
+ * mirrors.test.ts that runs both copies over the same lines.
+ */
+import {
+  $, pageSize, api, disclosure, el, findTable, go, render, setExplain, showErrors, state, toast,
+} from './core.js';
+import { EXPORT_MAX_ROWS, download, exportFilename, toCsv, toJson } from './export.js';
+import { explicitLimit, nextSort, sortDirection } from './clauses.js';
+import { planColumn } from './columns.js';
+import { valueNode } from './value.js';
+import { initGrid } from './grid.js';
+import { recordQuery } from './history.js';
+import { gridSkeleton, placeholder } from './skeleton.js';
+
+/**
+ * Is this line asking for a breakdown at all?
+ *
+ * The mirror of `looksLikeBreakdown` in shared/breakdowntext.ts, and one of
+ * the handful of rules this client has a second copy of — the browser cannot
+ * import the TypeScript the server runs on. It is here rather than on the
+ * server because it decides *which endpoint to call*, which is a decision that
+ * has to be made before there is anything to send.
+ *
+ * The `by` keyword standing alone and not the tail of `order by`. That is the
+ * whole tell: no other clause in the language uses it, which is why it was
+ * available to mean this.
+ */
+export function looksLikeBreakdown(text) {
+  return /(?<!\border\s)\bby\s+\S/i.test(String(text ?? ''));
+}
+
+/* Same shape as table.js's, and for the same reason: skim two breakdowns and
+   the slower reply must not repaint over the newer one, or rewrite the SQL
+   pane and the error banner belonging to a question nobody is asking. */
+let runToken = 0;
+
+export async function renderBreakdown(entry, content) {
+  $('query').value = entry.query;
+  const body = el('div');
+  content.append(body);
+
+  const mine = ++runToken;
+  const asked = explicitLimit(entry.query);
+  /* Shaped like the grid about to replace it. Two columns is the usual size of
+     a breakdown — one key and one measure — and a better guess than the base
+     table's column count, which is the shape of the thing being counted rather
+     than the shape of the answer. */
+  const done = placeholder(body, () => gridSkeleton(2, Math.min(asked ?? pageSize, pageSize())));
+
+  let data;
+  try {
+    data = await api('/api/breakdown', {
+      text: entry.query,
+      limit: asked ?? pageSize(),
+      offset: asked ? 0 : state.page * pageSize(),
+    });
+  } catch (err) {
+    if (mine !== runToken) return;
+    done();
+    body.replaceChildren(el('p', { class: 'note', text: err.message }));
+    return;
+  }
+  /* Everything below is global — the error banner, the SQL pane, the history —
+     so a stale reply stops here, before any of it. */
+  if (mine !== runToken) return;
+  done();
+
+  showErrors(data.errors ?? []);
+  setExplain(data.explain);
+
+  if (!data.columns) {
+    /* A half-typed breakdown is the normal state of an input box, so the
+       messages are the answer rather than a failure. They are already in the
+       banner; this is the space where the grid would have been. */
+    body.replaceChildren(el('p', { class: 'note', text: 'Fix the line above to see groups.' }));
+    return;
+  }
+
+  recordQuery(entry.query);
+
+  const shown = (asked ? 0 : state.page * pageSize()) + data.rows.length;
+  body.replaceChildren(
+    head(entry, data, shown),
+    grid(entry, data),
+    pager(entry, data, shown),
+  );
+}
+
+/**
+ * What the answer is, in numbers.
+ *
+ * "Groups" rather than "rows", because that is what they are and because the
+ * difference is the whole point: 12,006 invoices came back as 4 groups, and
+ * calling those 4 rows invites the reader to think the table is nearly empty.
+ */
+function head(entry, data, shown) {
+  const base = data.breakdown?.base ?? entry.table;
+  const total = data.total;
+  return el('div', { class: 'result-head' }, [
+    el('h2', { text: findTable(base)?.name ?? base }),
+    el('span', {
+      class: 'stat',
+      text: total === undefined
+        ? `${shown.toLocaleString()} group${shown === 1 ? '' : 's'}`
+        : total > shown
+          ? `${shown.toLocaleString()} of ${total.toLocaleString()} groups`
+          : `${total.toLocaleString()} group${total === 1 ? '' : 's'}`,
+    }),
+    el('span', { class: 'stat', text: `${data.ms} ms` }),
+    exportGroups(entry, data),
+  ]);
+}
+
+/**
+ * Export, for groups.
+ *
+ * Not `exportControl`. That one is built around a table: it remembers a
+ * column selection per table, re-runs through `/api/run` with a `show`
+ * clause, and names the file after the table. None of it transfers. A
+ * breakdown has no `show` — every column is a key or a measure, and dropping
+ * one does not narrow the answer, it makes it a different and wrong one — so
+ * there is no column chooser here, deliberately.
+ *
+ * What it keeps is the part worth sharing: the two scopes, each with its
+ * count spelled out, because a file named after a table gives no hint that
+ * the other forty groups were left behind.
+ */
+function exportGroups(entry, data) {
+  const rows = data.rows ?? [];
+  const columns = data.columns ?? [];
+  const total = data.total ?? rows.length;
+  const capped = Math.min(total, EXPORT_MAX_ROWS);
+  const base = data.breakdown?.base ?? entry.table;
+
+  const menu = el('div', { class: 'export-menu' });
+  const wrap = disclosure(el('details', { class: 'export' }, [
+    el('summary', { class: 'export-summary', title: 'Download these groups' }, 'Export'),
+    menu,
+  ]));
+
+  const write = (kind, all, groups) => {
+    const name = `${base}-by-${(data.breakdown?.by ?? []).map((k) => k.alias || k.path).join('-') || 'group'}`;
+    if (kind === 'csv') download(exportFilename(name, 'csv'), toCsv(columns, groups), 'text/csv');
+    else download(exportFilename(name, 'json'), toJson(columns, groups), 'application/json');
+    toast(`Exported ${groups.length.toLocaleString()} group${groups.length === 1 ? '' : 's'}.`);
+  };
+
+  const start = async (button, kind, all) => {
+    if (!all) {
+      wrap.open = false;
+      write(kind, all, rows);
+      return;
+    }
+    /* One bounded re-run rather than pages stitched together — the same
+       argument the table's export makes, and it applies harder here: a group
+       is an aggregate over rows that may have changed between two requests. */
+    const label = button.textContent;
+    button.disabled = true;
+    button.textContent = 'Fetching…';
+    try {
+      const fresh = await api('/api/breakdown', { text: entry.query, limit: capped, offset: 0 });
+      if (!fresh.columns) throw new Error(fresh.errors?.[0]?.message ?? 'That line no longer groups.');
+      wrap.open = false;
+      write(kind, all, fresh.rows ?? []);
+    } catch (err) {
+      toast(err.message, 'error');
+    } finally {
+      button.disabled = false;
+      button.textContent = label;
+    }
+  };
+
+  const pageLabel = `this page (${rows.length.toLocaleString()} group${rows.length === 1 ? '' : 's'})`;
+  const allLabel = `all groups (${capped.toLocaleString()})`;
+  for (const [kind, heading] of [['csv', 'CSV'], ['json', 'JSON']]) {
+    const group = el('div', { class: 'export-group' }, el('div', { class: 'export-heading', text: heading }));
+    for (const [label, all] of [[pageLabel, false], [allLabel, true]]) {
+      /* The second scope is offered only when it differs: "all groups (20)"
+         beside "this page (20 groups)" is two buttons for one file. */
+      if (all && capped <= rows.length) continue;
+      const button = el('button', { type: 'button', class: 'export-item', text: label });
+      button.addEventListener('click', () => void start(button, kind, all));
+      group.append(button);
+    }
+    menu.append(group);
+  }
+  return wrap;
+}
+
+/**
+ * The grid.
+ *
+ * Deliberately plain: a header that sorts, cells that render through the same
+ * `valueNode` every other surface uses, and the keyboard cursor. No row click,
+ * because there is no row to open — see the note at the top of this file.
+ */
+function grid(entry, data) {
+  const wrap = el('div', { class: 'table-wrap' });
+  if (!data.rows.length) {
+    /* The headers would say which columns had nothing in them, but a breakdown
+       with no groups means the filter matched no rows at all — there is no
+       shape to show, only that fact. */
+    wrap.append(el('p', { class: 'note', text: 'Nothing to group — no rows matched.' }));
+    return wrap;
+  }
+
+  /* `resolved` names each column and says whether it is a key or a measure,
+     which is the only classification a breakdown has. Its `type` is the
+     database's own, so a summed REAL right-aligns and a text key does not. */
+  const byName = new Map((data.resolved ?? []).map((c) => [c.name, c]));
+  const plans = new Map(
+    data.columns.map((name) => [name, planColumn(byName.get(name), name, data.rows)]),
+  );
+
+  const headRow = el('tr');
+  for (const name of data.columns) {
+    const meta = byName.get(name);
+    const plan = plans.get(name);
+    const direction = sortDirection(entry.query, name);
+    headRow.append(el('th', {
+      class: `align-${plan.align}${direction ? ' sorted' : ''}`,
+      /* Which half of the answer this column is. A reader who did not write
+         the line cannot otherwise tell `count` the measure from a column
+         somebody happened to group by and call `count`. */
+      title: meta?.kind === 'measure'
+        ? `${meta.fn}${meta.path ? `(${meta.path})` : ''} — a measure`
+        : meta?.path
+          ? `${meta.path} — grouped by${meta.type ? ` · ${meta.type}` : ''}`
+          : name,
+    }, el('button', {
+      type: 'button',
+      class: 'th-sort',
+      /* Sorting a breakdown names an output column, which is exactly what this
+         header is. So the click is the same text edit it is on a table — the
+         sort stays visible in the language and survives being walked back to. */
+      title: `Sort by ${name}`,
+      onclick: () => go({ ...entry, query: nextSort(entry.query, name) }, 'replace'),
+      text: `${name}${direction === 'desc' ? ' ↓' : direction === 'asc' ? ' ↑' : ''}`,
+    })));
+  }
+
+  const tbody = el('tbody');
+  data.rows.forEach((row, i) => {
+    const tr = el('tr', { 'data-row': String(i) });
+    for (const name of data.columns) {
+      const value = row[name];
+      const plan = plans.get(name);
+      tr.append(el('td', { class: `align-${plan.align}` },
+        value === null || value === undefined
+          ? el('span', { class: 'null-value', text: '—' })
+          : valueNode({ ...(byName.get(name) ?? {}), name }, value)));
+    }
+    tbody.append(tr);
+  });
+
+  wrap.append(el('table', {}, [el('thead', {}, headRow), tbody]));
+  /* The keyboard cursor, with nowhere to open: `onOpen` is deliberately absent
+     rather than a no-op, so Enter does nothing instead of appearing to. */
+  initGrid(wrap, {
+    tbody,
+    rowCount: data.rows.length,
+    columnCount: data.columns.length,
+    totalRows: data.total,
+    firstRow: explicitLimit(entry.query) ? 0 : state.page * pageSize(),
+  });
+  return wrap;
+}
+
+/** The same paging the table view has, over groups instead of rows. */
+function pager(entry, data, shown) {
+  const bar = el('div', { class: 'pager' });
+  // A line that names its own limit defines the whole answer — `sort billed
+  // desc limit 12` is a top-twelve, and a second page of it is a contradiction.
+  if (explicitLimit(entry.query)) return bar;
+  if (state.page > 0) {
+    bar.append(el('button', {
+      class: 'ghost', type: 'button', text: '← Previous',
+      onclick: () => { state.page--; render(); },
+    }));
+  }
+  if (data.total !== undefined ? data.total > shown : data.rows.length >= pageSize()) {
+    bar.append(el('button', {
+      class: 'ghost', type: 'button', text: 'Next →',
+      onclick: () => { state.page++; render(); },
+    }));
+  }
+  if (bar.childElementCount) bar.append(el('span', { class: 'page-label', text: `Page ${state.page + 1}` }));
+  return bar;
+}