tablewalk 0.0.1

package/dist/client/value.js

@@ -0,0 +1,223 @@
+/**
+ * One value, rendered by what it is — shared by every view that shows fields.
+ *
+ * The record view and the page view each grew their own idea of what a value
+ * looks like, and the page's was the worse one: `active` rendered as `1`,
+ * dates kept their midnights, and a foreign key was a bare integer. Two
+ * renderers for the same value will always disagree eventually; this is the
+ * one, and the grid's planner is its rule book.
+ */
+import { api, el, findTable, go, labelColumn, openRecord, primaryKey, rowLabel, state } from './core.js';
+import { planColumn } from './columns.js';
+import { peekable } from './peek.js';
+
+/**
+ * Render a value by what it is, matching how the result grid renders it.
+ *
+ * The record view drifted from the table view: the grid renders booleans as
+ * ticks, right-aligns numbers and trims midnight off dates, while the record
+ * showed everything as a bare string. Two views of the same value should not
+ * disagree about what it is.
+ */
+/** Thousands separators on a numeric string too big to survive Number(). */
+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;
+}
+
+export function valueNode(col, value) {
+  const type = (col?.type ?? '').toLowerCase();
+  const text = String(value);
+
+  /* Classified by the same planner the grid uses, on a row of one.
+
+     This file had its own rule, and it was the looser of the two: an
+     unanchored `^(active|enabled|urgent|billable)` with no check on the
+     value, so an integer column called `active_connections` was a boolean
+     here and a number in the grid — `active_connections = 3` rendered as
+     "✗ no" on the record page and as `3` two clicks away. The grid's rule
+     wants the name to match a flag *exactly* and every value to be 0 or 1,
+     which is the test that makes 0/1 mean true and false rather than being
+     two small numbers. */
+  const plan = planColumn(col, col?.name ?? '', [{ [col?.name ?? '']: value }]);
+
+  if (plan.kind === 'boolean') {
+    const on = value === true || value === 1 || value === '1' || value === 't';
+    return el('span', { class: `bool-value ${on ? 'yes' : 'no'}`, title: text },
+      on ? '✓ yes' : '✗ no');
+  }
+  if (plan.kind === 'number' && Number.isFinite(Number(value))) {
+    const n = Number(value);
+    /* A big id arrives as a string because it is past 2^53, and running it
+       back through Number() here rounds it — the same corruption the adapter
+       fix avoided, one layer later, on the page where the value is read most
+       carefully. Shown as it came, grouped by hand. `plan.identifier` already
+       passed the raw string through; this widens that to any overflow. */
+    const overflow = typeof value === 'string' && /^-?\d+$/.test(value)
+      && !Number.isSafeInteger(n);
+    const shown = plan.identifier || overflow
+      ? (overflow ? groupDigits(text) : text)
+      : n.toLocaleString(undefined, { maximumFractionDigits: 6 });
+    return el('span', { class: 'num-value', title: shown === text ? undefined : text, text: shown });
+  }
+  if (plan.kind === 'date' || /date|time/.test(type)) {
+    /* Postgres hands back an ISO wire format — 2025-03-14T09:30:00.000Z —
+       which is precise and unreadable. Shown as a date and a time, with the
+       original kept in the title because a timezone offset can matter and
+       should not be thrown away. */
+    const trimmed = text
+      .replace(/[ T]00:00:00(\.0+)?(Z|[+-]\d{2}:?\d{2})?$/, '')
+      .replace(/T/, ' ')
+      .replace(/:\d{2}\.\d+(Z|[+-]\d{2}:?\d{2})?$/, '')
+      .replace(/(\d{2}:\d{2}:\d{2})(Z|[+-]\d{2}:?\d{2})$/, '$1');
+    return el('span', { class: 'date-value', title: trimmed === text ? undefined : text, text: trimmed });
+  }
+  /* Long text gets its own block, and its field spans every column rather
+     than wrapping to five lines inside one. The threshold came down when the
+     record went multi-column: a column is now roughly half as wide, so text
+     that used to fit on one line no longer does. */
+  if (text.length > 90) return el('div', { class: 'long-value prose', text });
+
+  /* Monospace is right for data you compare character by character — ids,
+     codes, timestamps, amounts — and wrong for names, which it makes wider
+     and harder to read for no benefit. A space is a good enough tell: a value
+     with one is prose ("Southerly Logistics", "272 Cuba St"), a value without
+     is a token ("on_hold", "SKU-1314", an email). */
+  return el('span', { class: /\s/.test(text.trim()) ? 'prose' : '', text });
+}
+
+/** How deep the walk may unfold in place before it has to navigate. */
+const MAX_NEST = 3;
+
+/** Fields a nested card shows before deferring to its own page. */
+const NEST_FIELDS = 10;
+
+/** Referenced rows already unfolded once, keyed like the peek cache is. */
+const nestCache = new Map();
+
+async function referencedRow(target, column, value) {
+  const id = `${state.activeConnection ?? ''} ${target.id} ${column} ${value}`;
+  if (nestCache.has(id)) return nestCache.get(id);
+  const data = await api('/api/query', {
+    table: target.id,
+    filter: { groups: [[{ column, op: '=', value }]] },
+    limit: 1,
+    offset: 0,
+  });
+  const row = data.rows?.[0] ?? null;
+  nestCache.set(id, row);
+  return row;
+}
+
+/**
+ * A foreign key value as the walk it is: the value, the table it points at,
+ * a hover that shows the row, a click that goes there — and a caret that
+ * unfolds the row *here*.
+ *
+ * The hover answers "who is 4?" and vanishes; the caret is for when the
+ * answer should stay put while you keep reading, and for when the answer has
+ * its own references worth one more step. Each unfolded card renders its
+ * values through the same functions the record does — booleans as words,
+ * references as chips with carets of their own — so the walk continues in
+ * place, three levels deep at most. Past the cap the chip still navigates;
+ * depth is a courtesy, not a wall.
+ *
+ * Deliberately not in the URL. An expansion is a look, not a place: the
+ * deep link already names any row exactly, and a link that encoded every
+ * open caret would break the moment a layout moved — the argument that
+ * settled list pagers applies unchanged.
+ */
+export function refJump(references, value, depth = 0) {
+  const target = findTable(references.table);
+  const chip = peekable(el('button', {
+    class: 'ref-jump',
+    type: 'button',
+    title: `Open ${references.table} ${value}`,
+    onclick: () => {
+      if (!target) return;
+      /* In the view the walk is already in: a reference followed from a page
+         opens the referenced record as a page. */
+      void openRecord(target.id, { [references.column]: value }, `${references.table} ${value}`);
+    },
+  }, [
+    el('span', { class: 'ref-jump-value', text: String(value) }),
+    el('span', { class: 'ref-jump-table', text: references.table }),
+  ]), references, value);
+
+  if (!target || depth >= MAX_NEST) return chip;
+
+  const holder = el('span', { class: 'nest-holder' });
+  const caret = el('button', {
+    type: 'button',
+    class: 'nest-caret',
+    'aria-expanded': 'false',
+    title: `Show this ${target.name} here`,
+    'aria-label': `Show ${references.table} ${value} inline`,
+    text: '\u25b8',
+    onclick: async () => {
+      if (holder.childElementCount) {
+        holder.replaceChildren();
+        caret.textContent = '\u25b8';
+        caret.setAttribute('aria-expanded', 'false');
+        return;
+      }
+      caret.textContent = '\u25be';
+      caret.setAttribute('aria-expanded', 'true');
+      const row = await referencedRow(target, references.column, value);
+      /* The caret may have been closed while the row travelled. */
+      if (caret.getAttribute('aria-expanded') !== 'true') return;
+      holder.replaceChildren(row
+        ? nestCard(target, row, depth + 1)
+        : el('p', { class: 'nest-missing', text: 'That row is no longer there.' }));
+    },
+  });
+
+  return el('span', { class: 'nest-wrap' }, [chip, caret, holder]);
+}
+
+/**
+ * The referenced row, as a card: key and label first, then what fits, each
+ * value rendered by what it is — which is what makes the card walkable in
+ * turn rather than a dead end of strings.
+ */
+function nestCard(table, row, depth) {
+  const key = primaryKey(table);
+  const label = labelColumn(table);
+  const ordered = [
+    ...key,
+    ...(label && !key.includes(label) ? [label] : []),
+    ...table.columns.map((c) => c.name).filter((n) => !key.includes(n) && n !== label),
+  ].slice(0, NEST_FIELDS);
+  const byName = new Map(table.columns.map((c) => [c.name, c]));
+
+  return el('div', { class: 'nest-card' }, [
+    el('div', { class: 'nest-head' }, [
+      el('span', { class: 'nest-table', text: table.name }),
+      el('span', { class: 'nest-label', text: rowLabel(table, row) }),
+      el('button', {
+        type: 'button', class: 'ghost nest-open', text: 'open \u2192',
+        onclick: () => {
+          const keyValues = Object.fromEntries(key.map((c) => [c, row[c]]));
+          void openRecord(table.id, keyValues, rowLabel(table, row));
+        },
+      }),
+    ]),
+    ...ordered.map((name) => {
+      const column = byName.get(name);
+      const cell = row[name];
+      return el('div', { class: 'nest-line' }, [
+        el('span', { class: 'nest-name', text: name }),
+        cell === null || cell === undefined
+          ? el('span', { class: 'nest-value null', text: 'null' })
+          : column?.references
+            ? el('span', { class: 'nest-value' }, refJump(column.references, cell, depth))
+            : el('span', { class: 'nest-value' }, valueNode(column, cell)),
+      ]);
+    }),
+    table.columns.length > NEST_FIELDS
+      ? el('p', { class: 'nest-more', text: `+ ${table.columns.length - NEST_FIELDS} more on the record` })
+      : null,
+  ].filter(Boolean));
+}

package/dist/client/views.js

@@ -0,0 +1,215 @@
+/**
+ * Saved filters, as named tabs on a table.
+ *
+ * A filter you retype every morning is a filter that should have a name. The
+ * saved view stores the *query text*, not a compiled filter, for two reasons:
+ * it stays readable and editable in the bar, and it keeps working when the
+ * schema changes underneath it — a stored filter referencing a dropped column
+ * would be a silent empty result, while stored text is at worst a visible
+ * error you can fix.
+ *
+ * Scoped per connection as well as per table, because `orders` on staging and
+ * `orders` on production are not the same table and their useful filters are
+ * rarely the same either.
+ */
+import { el, go, loadJson, saveJson, state, tableView, toast } from './core.js';
+import { promptFor } from './prompt.js';
+import { activeClauses, withoutClause, withoutCondition } from './clauses.js';
+
+const KEY = 'tablewalk.views.v1';
+
+function allViews() {
+  return loadJson(KEY, {});
+}
+
+function viewsFor(connectionId, tableId) {
+  const all = allViews();
+  return all[connectionId]?.[tableId] ?? [];
+}
+
+function writeViews(connectionId, tableId, list) {
+  const all = allViews();
+  all[connectionId] = all[connectionId] ?? {};
+  all[connectionId][tableId] = list;
+  if (!saveJson(KEY, all)) {
+    toast('Could not save — this browser is not allowing local storage.', 'error');
+    return false;
+  }
+  return true;
+}
+
+const connectionKey = () => state.activeConnection ?? 'default';
+
+/**
+ * Every saved filter for this connection, flattened across tables.
+ *
+ * The landing page needs them together; the tab strip needs them per table.
+ * Both read the same store, so a filter saved on a table is immediately on
+ * the front page without anything having to be kept in step.
+ */
+export function allSavedFilters() {
+  const byTable = allViews()[connectionKey()] ?? {};
+  return Object.entries(byTable).flatMap(([table, list]) =>
+    (list ?? []).map((view) => ({ ...view, table })),
+  );
+}
+
+/**
+ * The tab strip for a table view. Returns null when there is nothing to show
+ * and nothing has been saved yet, so an unused feature costs no screen space.
+ */
+export function savedViewsBar(entry) {
+  const conn = connectionKey();
+  const views = viewsFor(conn, entry.table);
+  const bar = el('div', { class: 'views', role: 'tablist', 'aria-label': 'Saved filters' });
+
+  /* "All" is the unfiltered table, and is only meaningful once something else
+     exists to contrast it with. */
+  const isPlain = entry.query.trim() === entry.table;
+  if (views.length) {
+    bar.append(el('button', {
+      type: 'button',
+      class: 'view-tab',
+      role: 'tab',
+      'aria-selected': String(isPlain),
+      text: 'All',
+      onclick: () => go(tableView(entry.table), 'replace'),
+    }));
+  }
+
+  for (const view of views) {
+    const active = view.query.trim() === entry.query.trim();
+    const tab = el('span', { class: `view-tab-wrap${active ? ' active' : ''}` }, [
+      el('button', {
+        type: 'button',
+        class: 'view-tab',
+        role: 'tab',
+        'aria-selected': String(active),
+        title: view.query,
+        text: view.name,
+        onclick: () => go(tableView(entry.table, view.query), 'replace'),
+        ondblclick: () => void renameView(conn, entry, view),
+      }),
+      el('button', {
+        type: 'button',
+        class: 'view-remove',
+        title: `Remove "${view.name}"`,
+        'aria-label': `Remove ${view.name}`,
+        text: '×',
+        onclick: (e) => {
+          e.stopPropagation();
+          removeView(conn, entry, view);
+        },
+      }),
+    ]);
+    bar.append(tab);
+  }
+
+  /* Saving is offered only when there is a filter worth saving. Naming the
+     bare table is a saved view that does nothing. */
+  const alreadySaved = views.some((v) => v.query.trim() === entry.query.trim());
+  if (!isPlain && !alreadySaved) {
+    bar.append(el('button', {
+      type: 'button',
+      class: 'view-save',
+      text: '+ Save this filter',
+      onclick: () => void saveCurrent(conn, entry),
+    }));
+  }
+
+  /* What is currently narrowing the result, each with a way off.
+
+     The query bar can write these but could not un-write them: having sorted
+     by clicking a header, going back to unsorted meant finding `sort
+     contract_id` in a line of text and deleting exactly it. */
+  for (const clause of activeClauses(entry.query)) {
+    bar.append(el('span', { class: `clause clause-${clause.key}` }, [
+      el('span', { class: 'clause-label', text: clause.label }),
+      el('span', { class: 'clause-text', title: clause.text, text: clause.text }),
+      el('button', {
+        type: 'button',
+        class: 'clause-remove',
+        title: `Remove ${clause.label} ${clause.text}`,
+        'aria-label': `Remove ${clause.label} ${clause.text}`,
+        text: '×',
+        /* A filter chip removes its own condition; everything else removes
+           the whole clause, because a sort or a limit has only one of it. */
+        onclick: () => go(tableView(
+          entry.table,
+          clause.index === undefined
+            ? withoutClause(entry.query, clause.key)
+            : withoutCondition(entry.query, clause.index),
+        ), 'replace'),
+      }),
+    ]));
+  }
+
+  return bar.childElementCount ? bar : null;
+}
+
+async function saveCurrent(conn, entry) {
+  const trimmed = await promptFor({
+    title: 'Save this filter',
+    label: 'Name',
+    value: suggestName(entry, entry.table),
+    hint: entry.query,
+    placeholder: 'e.g. Open, high priority',
+  });
+  if (!trimmed) return;
+
+  const views = viewsFor(conn, entry.table);
+  // A repeated name replaces rather than duplicating: two tabs reading
+  // "Open" that do different things is worse than losing the older one.
+  const without = views.filter((v) => v.name !== trimmed);
+  without.push({ id: `${Date.now()}`, name: trimmed, query: entry.query });
+  if (writeViews(conn, entry.table, without)) {
+    toast(`Saved "${trimmed}".`, 'ok');
+    go({ ...entry }, 'replace');
+  }
+}
+
+async function renameView(conn, entry, view) {
+  const trimmed = await promptFor({
+    title: 'Rename filter',
+    label: 'Name',
+    value: view.name,
+    hint: view.query,
+    confirmLabel: 'Rename',
+  });
+  if (!trimmed) return;
+  const views = viewsFor(conn, entry.table).map((v) => (v.id === view.id ? { ...v, name: trimmed } : v));
+  if (writeViews(conn, entry.table, views)) go({ ...entry }, 'replace');
+}
+
+function removeView(conn, entry, view) {
+  const views = viewsFor(conn, entry.table).filter((v) => v.id !== view.id);
+  if (writeViews(conn, entry.table, views)) go({ ...entry }, 'replace');
+}
+
+/**
+ * A first guess at a name.
+ *
+ * `invoice total > 500 sort total desc` suggests "total > 500" — the part
+ * that distinguishes it. Stripping the table name and the trailing clauses
+ * leaves what the filter is actually about.
+ *
+ * When the filter was reached by walking, the trail says more than the filter
+ * does: `work_order supersedes_id = 5` means little on its own, while
+ * "WO-100005 · supersedes_id = 5" says which row it came from. The row you
+ * walked through is the context the filter is really about.
+ */
+function suggestName(entry, table) {
+  const query = entry.query;
+  const previousRow = [...state.stack]
+    .slice(0, state.stack.indexOf(entry))
+    .reverse()
+    .find((e) => e.kind === 'row');
+  const withoutTable = query.trim().slice(table.length).trim();
+  const withoutClauses = withoutTable
+    .replace(/\s+(?:sort|order\s+by|limit|show|select)\s+.*$/i, '')
+    .replace(/^(?:filter|where)\s+/i, '')
+    .trim();
+  const filterPart = withoutClauses || withoutTable;
+  const candidate = previousRow?.label ? `${previousRow.label} · ${filterPart}` : filterPart;
+  return candidate.length > 48 ? `${candidate.slice(0, 47)}…` : candidate;
+}

package/dist/client/virtual.js

@@ -0,0 +1,176 @@
+/**
+ * Row virtualisation for the result grid.
+ *
+ * The database is not the bottleneck. On the 87k demo, forty-two thousand
+ * rows are fetched in 35ms and arrive in the browser in about 100ms; putting
+ * them in the DOM is what takes seconds and then makes every subsequent
+ * scroll and hover slow. So the fix belongs in rendering, not in fetching,
+ * and the 2,000-row cap this replaces was treating the symptom.
+ *
+ * The approach is the boring one, which is the point: measure a row, keep a
+ * window of rows either side of the viewport, and pad above and below with
+ * two spacer rows so the scrollbar is the size it would have been. No
+ * library, no absolute positioning, no transform — a `<tr>` with a tall
+ * `<td>` is enough, and it keeps the table a real table, so column widths,
+ * sticky headers, text selection and Find-in-page all keep working.
+ *
+ * Deliberately not animated and deliberately not smoothed. Scrolling is the
+ * most repeated interaction in the tool; anything that lags the content
+ * behind the scrollbar is felt every single time.
+ */
+
+/** Rows kept beyond the viewport on each side, so a flick does not show gaps. */
+const OVERSCAN = 12;
+
+/** Below this many rows, windowing costs more than it saves. */
+export const VIRTUAL_THRESHOLD = 300;
+
+/**
+ * Take over a tbody, rendering only what is visible.
+ *
+ * @param {object} options
+ * @param {HTMLElement} options.scroller   the element that actually scrolls
+ * @param {HTMLTableSectionElement} options.tbody
+ * @param {Array} options.rows             every row, not just the visible ones
+ * @param {(row: any, index: number) => HTMLTableRowElement} options.renderRow
+ * @param {number} options.columns         for the spacers' colspan
+ * @returns {() => void} a teardown function
+ */
+export function virtualise({ scroller, tbody, rows, renderRow, columns }) {
+  /* Measured from a real rendered row rather than assumed. Row height
+     depends on font, zoom and content — a hardcoded guess drifts, and the
+     drift shows up as the scrollbar disagreeing with the content. */
+  let rowHeight = 0;
+  let first = -1;
+  let last = -1;
+  let frame = 0;
+  /** Guards the one repaint a height correction is allowed to cause. */
+  let correcting = false;
+
+  const topSpacer = spacerRow(columns);
+  const bottomSpacer = spacerRow(columns);
+
+  /**
+   * Height of a row, from rows actually rendered.
+   *
+   * Sampled from several rows rather than the first, because the first is not
+   * a fair sample: a row whose only reference column is null renders a bare
+   * `null` where every other row renders a chip with padding, and measuring
+   * that one row makes every offset in the table slightly short.
+   *
+   * Spread through the data rather than taken from the top, so a table whose
+   * first screenful is unrepresentative does not set the height for all of it.
+   */
+  function measure() {
+    const at = [0, Math.floor(rows.length / 3), Math.floor((rows.length * 2) / 3), rows.length - 1]
+      .filter((i, n, all) => i >= 0 && all.indexOf(i) === n);
+    const samples = at.map((i) => renderRow(rows[i], i));
+    tbody.replaceChildren(...samples);
+    rowHeight = Math.max(...samples.map((r) => r.getBoundingClientRect().height), 0) || 26;
+  }
+
+  function windowFor() {
+    const viewportTop = scroller.scrollTop;
+    const viewportHeight = scroller.clientHeight || 600;
+    /* The table does not start at the top of the scroller — there is a
+       breadcrumb, tabs and a header above it — so the offset is measured
+       rather than assumed to be zero. */
+    const tableTop = tbody.parentElement.offsetTop;
+    const relative = Math.max(0, viewportTop - tableTop);
+    const start = Math.max(0, Math.floor(relative / rowHeight) - OVERSCAN);
+    const visible = Math.ceil(viewportHeight / rowHeight) + OVERSCAN * 2;
+    return { start, end: Math.min(rows.length, start + visible) };
+  }
+
+  function paint() {
+    const { start, end } = windowFor();
+    // Nothing to do if the window has not moved: scroll fires far more often
+    // than the window actually changes.
+    if (start === first && end === last) return;
+    first = start;
+    last = end;
+
+    topSpacer.firstChild.style.height = `${start * rowHeight}px`;
+    bottomSpacer.firstChild.style.height = `${Math.max(0, rows.length - end) * rowHeight}px`;
+
+    const painted = [topSpacer];
+    for (let i = start; i < end; i++) painted.push(renderRow(rows[i], i));
+    painted.push(bottomSpacer);
+    tbody.replaceChildren(...painted);
+
+    correct(painted[1]);
+  }
+
+  /**
+   * Check the assumption against what was actually drawn, once.
+   *
+   * Every offset in this file is `index * rowHeight`, so a height that is
+   * wrong by a pixel is wrong by a pixel *per row* — at forty thousand rows
+   * that is a scrollbar which disagrees with its content by the height of a
+   * screenful, and the rows under the cursor are not the rows the scrollbar
+   * says.
+   *
+   * The measurement can be right when taken and wrong later: a webfont
+   * arriving after first paint changes every row, and so does a browser zoom
+   * that the ResizeObserver sees only after the fact. Rather than enumerate
+   * the causes, this compares the number against the thing it describes and
+   * corrects it — which covers the causes nobody thought of too.
+   *
+   * Once per paint, and only when the disagreement is real: a repaint that
+   * triggers another correction that triggers another repaint is a loop, and
+   * sub-pixel differences are noise from `getBoundingClientRect`.
+   */
+  function correct(sample) {
+    if (correcting || !sample || sample === bottomSpacer) return;
+    const actual = sample.getBoundingClientRect().height;
+    if (!actual || Math.abs(actual - rowHeight) < 0.5) return;
+    correcting = true;
+    rowHeight = actual;
+    first = -1;
+    last = -1;
+    paint();
+    correcting = false;
+  }
+
+  const onScroll = () => {
+    // One paint per frame at most. Scroll can fire many times per frame and
+    // rebuilding the window on each is how a virtual list ends up slower
+    // than the thing it replaced.
+    if (frame) return;
+    frame = requestAnimationFrame(() => {
+      frame = 0;
+      paint();
+    });
+  };
+
+  measure();
+  paint();
+  scroller.addEventListener('scroll', onScroll, { passive: true });
+
+  /* A resize changes how many rows fit, and a zoom changes how tall they are,
+     so both invalidate the measurement. */
+  const observer = new ResizeObserver(() => {
+    first = -1;
+    last = -1;
+    paint();
+  });
+  observer.observe(scroller);
+
+  return () => {
+    scroller.removeEventListener('scroll', onScroll);
+    observer.disconnect();
+    if (frame) cancelAnimationFrame(frame);
+  };
+}
+
+function spacerRow(columns) {
+  const cell = document.createElement('td');
+  cell.colSpan = columns;
+  cell.style.padding = '0';
+  cell.style.border = 'none';
+  const row = document.createElement('tr');
+  row.className = 'virtual-spacer';
+  row.setAttribute('aria-hidden', 'true');
+  row.append(cell);
+  return row;
+}