tablewalk 0.0.1

package/dist/client/peek.js

@@ -0,0 +1,254 @@
+/**
+ * What is on the other end of a reference, without going there.
+ *
+ * `sold_by 4` is not an answer. It is a promise that an answer exists in
+ * another table, and collecting it costs a navigation, a look, and a click
+ * back — by which time you have lost the row you were reading. That round
+ * trip is the tax this tool charges on the thing it is best at, and most of
+ * the time the question is small: *who is 4?*
+ *
+ * So a reference answers itself on hover. A card with the referenced row's
+ * identifying fields, near the chip, gone when the pointer leaves. Walking is
+ * still there for when you actually want to be over there; this is for when
+ * you only wanted to know.
+ *
+ * Three things make it bearable rather than irritating:
+ *
+ *   - **It waits.** Crossing a column of forty references on the way to
+ *     something else must not fire forty requests, so nothing happens until
+ *     the pointer has settled.
+ *   - **It remembers.** The same reference value repeats down a column, and
+ *     the second hover should not ask again.
+ *   - **It gives up quietly.** A row that has been deleted, a key that does
+ *     not resolve, a reply that outlives the pointer — none of those are
+ *     worth a message. The card simply does not appear.
+ */
+import { api, el, findTable, labelColumn, state } from './core.js';
+
+/** How long the pointer must rest on a chip before anything is fetched. */
+const SETTLE_MS = 320;
+
+/** Fields shown before the card stops listing. */
+const FIELDS = 6;
+
+/** Rows already fetched, keyed by table, column and value. */
+const cache = new Map();
+
+let card = null;
+/** `title` attributes taken off the chip while the card is up, to be put back. */
+let suppressed = [];
+let timer = 0;
+/** Bumped on every open, so a slow reply for a chip you have left is dropped. */
+let generation = 0;
+
+/**
+ * Emptied when the schema changes underneath the cached rows.
+ *
+ * Not needed for a connection switch — the key names the connection, so the
+ * two databases' answers cannot be confused for each other. This is for a
+ * re-introspection, where the same connection may now describe different
+ * columns.
+ */
+export function clearPeekCache() {
+  cache.clear();
+}
+
+function hide() {
+  clearTimeout(timer);
+  generation += 1;
+  card?.remove();
+  card = null;
+  for (const [node, title] of suppressed) node.setAttribute('title', title);
+  suppressed = [];
+}
+
+/**
+ * Which columns are worth showing.
+ *
+ * The key, because it is what you hovered and seeing it confirms the card is
+ * about the right row; then the label column, which is the name of the thing;
+ * then whatever else fits. References are listed as plain values rather than
+ * as chips — a card you can walk out of is a menu, and this is a glance.
+ */
+function fieldsFor(table) {
+  const key = table.columns.filter((c) => c.primaryKey).map((c) => c.name);
+  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),
+  ];
+  return ordered.slice(0, FIELDS);
+}
+
+async function rowFor(table, column, value) {
+  /* The connection is part of the key.
+  
+     Without it, hovering `sold_by 4` on staging and then switching to
+     production showed staging's employee for production's reference — the
+     same table, the same id, a different database, and nothing on the card to
+     say which one it came from. */
+  const id = `${state.activeConnection ?? ''} ${table.id} ${column} ${value}`;
+  if (cache.has(id)) return cache.get(id);
+
+  const data = await api('/api/view/run', {
+    view: {
+      id: `peek:${table.id}`,
+      name: table.name,
+      base: table.id,
+      columns: fieldsFor(table).map((path) => ({ path })),
+      filter: { groups: [[{ path: column, op: '=', value }]] },
+      limit: 1,
+    },
+  });
+  const row = data.rows?.[0] ?? null;
+  cache.set(id, row);
+  return row;
+}
+
+function draw(anchor, table, value, row) {
+  hide();
+  const lines = fieldsFor(table).map((name) => el('div', { class: 'peek-line' }, [
+    el('span', { class: 'peek-name', text: name }),
+    row[name] === null || row[name] === undefined
+      ? el('span', { class: 'peek-value null', text: 'null' })
+      : el('span', { class: 'peek-value', text: String(row[name]) }),
+  ]));
+
+  card = el('div', { class: 'peek', role: 'tooltip' }, [
+    el('div', { class: 'peek-head' }, [
+      el('span', { class: 'peek-table', text: table.name }),
+      el('span', { class: 'peek-key', text: String(value) }),
+    ]),
+    el('div', { class: 'peek-body' }, lines),
+    /* Said once, at the foot: the card is a glance, and clicking the chip is
+       the walk. Without it the card looks like something you ought to be able
+       to click into. */
+    el('div', { class: 'peek-foot', text: 'click to open' }),
+  ]);
+  /* The native tooltip has to go while the card is up.
+  
+     A reference carries a `title` — "→ ledger_account", or a number's
+     unformatted value — which is a good cheap hint and a bad companion: the
+     browser draws it wherever it likes, about a second after the card has
+     already answered the same question, and lands it across the card's own
+     heading.
+  
+     Taken off the anchor *and* anything inside it, because the two are not
+     the same element: the peek is anchored to the cell, since that is what
+     the reader is pointing at and what says which edge to hang from, while
+     the title belongs to the chip within it. Only what was actually there is
+     put back — a cell with no title should not acquire an empty one for
+     having been looked at. */
+  for (const node of [anchor, ...anchor.querySelectorAll('[title]')]) {
+    const title = node.getAttribute('title');
+    if (title === null) continue;
+    suppressed.push([node, title]);
+    node.removeAttribute('title');
+  }
+
+  document.body.append(card);
+  place(anchor, card);
+}
+
+/**
+ * Put the card against the value, and inside the window.
+ *
+ * Against the *value*, not the cell. A numeric foreign key is right-aligned
+ * in a column that may be sixty characters wide, so anchoring to the cell's
+ * left edge put the card most of a screen away from the number that summoned
+ * it — near enough to be the tooltip of something else. The cell's own text
+ * alignment says which edge the reader is looking at, so the card is hung
+ * from that edge.
+ *
+ * Below by default, because a card above the pointer covers the row being
+ * read. It flips up only when there is no room below, and is nudged sideways
+ * rather than allowed off the edge — a card whose left half is outside the
+ * viewport is worse than no card.
+ */
+function place(anchor, node) {
+  const at = anchor.getBoundingClientRect();
+  const box = node.getBoundingClientRect();
+  const margin = 8;
+
+  let top = at.bottom + 4;
+  if (top + box.height > window.innerHeight - margin) {
+    const above = at.top - box.height - 4;
+    top = above > margin ? above : Math.max(margin, window.innerHeight - box.height - margin);
+  }
+
+  const align = getComputedStyle(anchor).textAlign;
+  const wanted = align === 'right' || align === 'end'
+    ? at.right - box.width
+    : align === 'center'
+      ? at.left + at.width / 2 - box.width / 2
+      : at.left;
+
+  const left = Math.min(
+    Math.max(margin, wanted),
+    Math.max(margin, window.innerWidth - box.width - margin),
+  );
+
+  node.style.top = `${Math.round(top)}px`;
+  node.style.left = `${Math.round(left)}px`;
+}
+
+/**
+ * Start peeking, if what was entered is a reference.
+ *
+ * Delegated from the document rather than bound per chip: a table redraws its
+ * rows on every page, sort and filter, and a virtualised one replaces them as
+ * you scroll — so a listener per chip is thousands of registrations with no
+ * one place to take them off again.
+ */
+function onEnter(e) {
+  const chip = e.target.closest?.('[data-ref-table]');
+  if (!chip) return;
+  const table = findTable(chip.dataset.refTable);
+  const column = chip.dataset.refColumn;
+  const value = chip.dataset.refValue;
+  if (!table || !column || !value) return;
+
+  clearTimeout(timer);
+  const mine = ++generation;
+  timer = setTimeout(async () => {
+    try {
+      const row = await rowFor(table, column, value);
+      // The pointer has moved on, or a later hover has started: this answer
+      // is about something nobody is looking at any more.
+      if (mine !== generation || !row || !chip.isConnected) return;
+      draw(chip, table, value, row);
+    } catch {
+      /* A reference pointing at a row that is not there is a fact about the
+         database, and one tablewalk reports honestly elsewhere. It is not
+         worth a popup on the way past. */
+    }
+  }, SETTLE_MS);
+}
+
+function onLeave(e) {
+  if (e.target.closest?.('[data-ref-table]')) hide();
+}
+
+export function initPeek() {
+  document.addEventListener('mouseover', onEnter);
+  document.addEventListener('mouseout', onLeave);
+  /* Focus opens it too, so the card is reachable without a pointer — the grid
+     cursor moves through these cells, and a keyboard user should get the same
+     answer a mouse user gets. */
+  document.addEventListener('focusin', onEnter);
+  document.addEventListener('focusout', onLeave);
+  document.addEventListener('keydown', (e) => { if (e.key === 'Escape') hide(); });
+  // Anything that moves the page out from under the card invalidates it.
+  window.addEventListener('scroll', hide, true);
+  window.addEventListener('resize', hide);
+}
+
+/** Mark an element as a reference worth peeking at. */
+export function peekable(node, references, value) {
+  if (!references || value === null || value === undefined || value === '') return node;
+  node.dataset.refTable = references.table;
+  node.dataset.refColumn = references.column;
+  node.dataset.refValue = String(value);
+  return node;
+}

package/dist/client/picker.js

@@ -0,0 +1,139 @@
+/**
+ * A searchable picker: type to narrow, arrow to choose.
+ *
+ * This exists because `<datalist>` does not. It is the right *idea* — a text
+ * field with a known set of answers behind it — but the browser draws its menu
+ * as a small system tooltip in the system font, ignoring the page, sized to
+ * nothing, and its matching is a plain prefix test. Next to a themed page it
+ * reads as a browser artefact rather than part of the interface.
+ *
+ * So the field stays a field and the menu is ours: same ranking as the command
+ * palette, so `pol` finds `purchase_order_line` here too, and the same
+ * keyboard contract as every other list in this app — arrows move, Enter
+ * picks, Escape closes.
+ *
+ * The menu is positioned in the viewport rather than in the flow, because the
+ * panels these live in scroll and clip, and a menu cut in half by its own
+ * container is worse than no menu.
+ */
+import { el } from './core.js';
+import { score } from './palette.js';
+
+/**
+ * @param {object} options
+ * @param {Array<{value: string, label: string, detail?: string}>} options.items
+ * @param {(value: string) => void} options.onPick
+ * @param {string} [options.placeholder]
+ * @param {string} [options.ariaLabel]
+ * @param {number} [options.max]  how many suggestions to show at once
+ */
+export function picker({ items, onPick, placeholder = 'Search…', ariaLabel = 'Search', max = 8 }) {
+  const input = el('input', {
+    type: 'text',
+    class: 'picker-input',
+    placeholder,
+    'aria-label': ariaLabel,
+    autocomplete: 'off',
+    spellcheck: 'false',
+    role: 'combobox',
+    'aria-expanded': 'false',
+    'aria-autocomplete': 'list',
+  });
+  const list = el('div', { class: 'picker-list', role: 'listbox', hidden: true });
+  const root = el('div', { class: 'picker' }, [input, list]);
+
+  let shown = [];
+  let active = 0;
+
+  const rank = () => {
+    const query = input.value.trim();
+    shown = items
+      .map((item) => ({ item, points: score(`${item.label} ${item.detail ?? ''}`.trim(), query) }))
+      .filter(({ points }) => points > 0)
+      .sort((a, b) => b.points - a.points)
+      .slice(0, max)
+      .map(({ item }) => item);
+    active = 0;
+  };
+
+  const paint = () => {
+    if (!shown.length) {
+      list.replaceChildren(el('p', { class: 'picker-empty', text: 'No table matches.' }));
+      return;
+    }
+    list.replaceChildren(...shown.map((item, i) => el('div', {
+      class: `picker-option${i === active ? ' active' : ''}`,
+      role: 'option',
+      'aria-selected': String(i === active),
+      // Pointerdown rather than click: the input is about to lose focus, and
+      // a blur handler that closed the list first would eat the click.
+      onpointerdown: (e) => { e.preventDefault(); choose(i); },
+      onmousemove: () => setActive(i),
+    }, [
+      el('span', { class: 'picker-label', text: item.label }),
+      item.detail ? el('span', { class: 'picker-detail', text: item.detail }) : null,
+    ].filter(Boolean))));
+  };
+
+  const setActive = (index) => {
+    if (!shown.length) return;
+    active = (index + shown.length) % shown.length;
+    [...list.children].forEach((node, i) => {
+      node.classList.toggle('active', i === active);
+      node.setAttribute('aria-selected', String(i === active));
+    });
+    list.children[active]?.scrollIntoView({ block: 'nearest' });
+  };
+
+  function position() {
+    const box = input.getBoundingClientRect();
+    list.style.position = 'fixed';
+    list.style.minWidth = `${box.width}px`;
+    list.style.left = `${Math.max(8, Math.min(box.left, window.innerWidth - box.width - 12))}px`;
+    list.style.top = `${box.bottom + 4}px`;
+  }
+
+  const open = () => {
+    rank();
+    paint();
+    list.hidden = false;
+    input.setAttribute('aria-expanded', 'true');
+    position();
+    window.addEventListener('scroll', close, true);
+    window.addEventListener('resize', close);
+  };
+
+  function close() {
+    if (list.hidden) return;
+    list.hidden = true;
+    input.setAttribute('aria-expanded', 'false');
+    window.removeEventListener('scroll', close, true);
+    window.removeEventListener('resize', close);
+  }
+
+  const choose = (index) => {
+    const item = shown[index];
+    if (!item) return;
+    input.value = '';
+    close();
+    onPick(item.value);
+  };
+
+  input.addEventListener('input', () => { open(); });
+  input.addEventListener('focus', () => open());
+  input.addEventListener('blur', () => setTimeout(close, 80));
+  input.addEventListener('keydown', (e) => {
+    switch (e.key) {
+      case 'ArrowDown': e.preventDefault(); if (list.hidden) open(); else setActive(active + 1); return;
+      case 'ArrowUp': e.preventDefault(); setActive(active - 1); return;
+      case 'Enter': e.preventDefault(); choose(active); return;
+      case 'Escape':
+        // Closes the list, not the view behind it.
+        if (!list.hidden) { e.preventDefault(); e.stopPropagation(); close(); }
+        return;
+      default:
+    }
+  });
+
+  return root;
+}

package/dist/client/pins.js

@@ -0,0 +1,140 @@
+/**
+ * Columns that stay put when a wide table scrolls sideways.
+ *
+ * A twenty-seven column table is wider than any window, so reading the right
+ * of it means scrolling the left of it away — and the left of it is where the
+ * key and the name live. Three columns in you are looking at values with
+ * nothing to attach them to, and the only way back is to scroll left, read the
+ * name, and scroll right again holding it in your head.
+ *
+ * Pinning is the fix every spreadsheet arrived at, and the reason it belongs
+ * here rather than in a preference nobody finds is that tablewalk already knows
+ * which columns identify a row: the primary key, and the label column it uses
+ * for breadcrumbs. Those are pinned without being asked for, on tables wide
+ * enough to need it, and anything else is one click in the column menu.
+ */
+import { labelColumn, loadJson, primaryKey, saveJson, state } from './core.js';
+
+const KEY = 'tablewalk.pins.v1';
+
+/**
+ * Below this many columns, pinning is a border and a shadow for no gain.
+ *
+ * The number is about the *window* rather than the table: eight columns of
+ * ordinary width fit, and the ones that do not are exactly the tables where
+ * losing the key hurts.
+ */
+const WIDE_ENOUGH = 8;
+
+const connectionKey = () => state.activeConnection ?? 'default';
+
+function stored() {
+  return loadJson(KEY, {})[connectionKey()] ?? {};
+}
+
+/**
+ * The columns pinned for a table: what was chosen, or what identifies a row.
+ *
+ * The derived default is not written to storage. Storing it would freeze
+ * today's guess against a schema that may gain a better label column, and it
+ * would make "I have never touched this" indistinguishable from "I chose
+ * exactly this".
+ */
+export function pinnedFor(table, columns) {
+  if (!table) return [];
+  const chosen = stored()[table.id];
+  if (chosen) return chosen.filter((c) => columns.includes(c));
+  if (columns.length < WIDE_ENOUGH) return [];
+
+  const key = primaryKey(table);
+  const label = labelColumn(table);
+  const wanted = [...key, ...(label && !key.includes(label) ? [label] : [])];
+  return wanted.filter((c) => columns.includes(c));
+}
+
+/** Whether this table has ever been decided about, for the menu's wording. */
+export const isChosen = (table) => Boolean(table && stored()[table.id]);
+
+export function togglePin(table, columns, name) {
+  if (!table) return;
+  const current = pinnedFor(table, columns);
+  const next = current.includes(name)
+    ? current.filter((c) => c !== name)
+    : [...current, name];
+
+  /* Kept in column order rather than the order they were pinned in. Pinned
+     columns are rendered as a block on the left, and a block whose internal
+     order differs from the table's is a second thing to reconcile every time
+     you read it. */
+  const ordered = columns.filter((c) => next.includes(c));
+
+  const all = loadJson(KEY, {});
+  all[connectionKey()] = { ...(all[connectionKey()] ?? {}), [table.id]: ordered };
+  saveJson(KEY, all);
+}
+
+/**
+ * Freeze the pinned columns in place, measured rather than assumed.
+ *
+ * `position: sticky` needs a `left` for each column, and the offsets are the
+ * widths of the columns before it — which are not known until the browser has
+ * laid the table out. Measuring after render is the only honest way to get
+ * them; guessing produces a gap or an overlap at every zoom level.
+ *
+ * Called again on resize by the caller, because a column's width follows its
+ * content and its content follows the window.
+ */
+export function applyPins(wrap, columns, pinned) {
+  const table = wrap.querySelector('table');
+  if (!table || !pinned.length) return;
+
+  const head = table.tHead?.rows[0];
+  if (!head) return;
+
+  /* Cell indexes, not column indexes. An expander column is a cell with no
+     name in `columns`, so the two are offset by one wherever it is present —
+     and freezing the wrong cells is worse than freezing none. */
+  const shift = head.cells.length - columns.length;
+  const indexes = pinned
+    .map((name) => columns.indexOf(name))
+    .filter((i) => i >= 0)
+    .map((i) => i + shift)
+    .sort((a, b) => a - b);
+
+  /* Rounded *down*, so consecutive frozen columns overlap by a fraction of a
+     pixel rather than leaving one. Column widths are fractional — 82.0234px —
+     and a `left` that lands after the previous column ends opens a hairline
+     through which the scrolling content behind shows as a flickering sliver. An
+     overlap of the same size is invisible. */
+  let offset = 0;
+  const lefts = new Map();
+  for (const i of indexes) {
+    lefts.set(i, Math.floor(offset));
+    offset += head.cells[i]?.getBoundingClientRect().width ?? 0;
+  }
+
+  /* The seam appears only once there is something behind it. An edge shadow on
+     an unscrolled table draws a line through the middle of it for no reason. */
+  if (!wrap.dataset.pinWatch) {
+    wrap.dataset.pinWatch = '1';
+    const mark = () => {
+      if (wrap.scrollLeft > 0) wrap.dataset.scrolled = '1';
+      else delete wrap.dataset.scrolled;
+    };
+    wrap.addEventListener('scroll', mark, { passive: true });
+    mark();
+  }
+
+  const last = indexes[indexes.length - 1];
+  for (const row of table.rows) {
+    for (const i of indexes) {
+      const cell = row.cells[i];
+      if (!cell) continue;
+      cell.classList.add('pinned');
+      // The rightmost pinned column carries the edge, so the seam between
+      // frozen and scrolling is one line rather than one per column.
+      cell.classList.toggle('pinned-edge', i === last);
+      cell.style.left = `${lefts.get(i)}px`;
+    }
+  }
+}

package/dist/client/prompt.js

@@ -0,0 +1,129 @@
+/**
+ * A themed replacement for `window.prompt`.
+ *
+ * The native one cannot be styled at all: it is drawn by the browser, says
+ * "localhost:4111 says" above whatever you asked, and appears in the system
+ * font on the system chrome regardless of the page. It also blocks the main
+ * thread, which is why it is the one dialog that cannot animate or be
+ * dismissed by clicking away.
+ *
+ * `<dialog>` gives back everything that matters — modal focus trapping,
+ * Escape to close, backdrop — so this only has to supply the shape.
+ */
+import { el } from './core.js';
+
+/**
+ * @returns {Promise<string|null>} the trimmed value, or null if cancelled.
+ */
+export function promptFor({ title, label, value = '', hint, confirmLabel = 'Save', placeholder, type = 'text' }) {
+  return new Promise((resolve) => {
+    const input = el('input', {
+      /* `date` and `datetime-local` give the browser's own picker, which is
+         the difference between typing `2026-01-01` correctly and finding out
+         you did not. Everything else stays a text box: the query language
+         takes text, and a number input would refuse the `1e6` and the leading
+         zeroes that a database column is perfectly happy to hold. */
+      type,
+      class: 'cell-edit',
+      value,
+      placeholder: placeholder ?? '',
+      'aria-label': label,
+    });
+
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+
+    const submit = () => {
+      const trimmed = input.value.trim();
+      if (!trimmed) {
+        input.focus();
+        return;
+      }
+      dialog.close();
+      finish(trimmed);
+    };
+
+    const form = el('form', { method: 'dialog', onsubmit: (e) => { e.preventDefault(); submit(); } }, [
+      el('h2', { text: title }),
+      el('label', { class: 'field-stack' }, [el('span', { text: label }), input]),
+      hint ? el('p', { class: 'confirm-params', text: hint }) : null,
+      el('div', { class: 'confirm-actions' }, [
+        el('button', { type: 'button', class: 'ghost', text: 'Cancel', onclick: () => { dialog.close(); finish(null); } }),
+        el('button', { type: 'submit', text: confirmLabel }),
+      ]),
+    ]);
+
+    const dialog = el('dialog', { class: 'confirm' }, form);
+    // Covers Escape and any other close path, so cancelling always resolves.
+    dialog.addEventListener('close', () => { finish(null); dialog.remove(); });
+    document.body.append(dialog);
+    dialog.showModal();
+    input.focus();
+    input.select();
+  });
+}
+
+/**
+ * Two values at once, for `between`.
+ *
+ * A range asked as two separate prompts is two chances to cancel halfway and
+ * a filter that means something different from what was intended if you do.
+ * It is one question — "from where to where" — so it is one dialog.
+ *
+ * Resolves `{ from, to }`, or null if cancelled. Both are required: `between`
+ * with one end is a comparison, and the menu already offers those.
+ *
+ * @returns {Promise<{from: string, to: string}|null>}
+ */
+export function promptForRange({ title, fromLabel, toLabel, hint, type = 'text', placeholder }) {
+  return new Promise((resolve) => {
+    const field = (label) => el('input', {
+      type,
+      class: 'cell-edit',
+      placeholder: placeholder ?? '',
+      'aria-label': label,
+    });
+    const from = field(fromLabel);
+    const to = field(toLabel);
+
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+
+    const submit = () => {
+      const a = from.value.trim();
+      const b = to.value.trim();
+      /* Focus the end that is missing rather than refusing as a whole: with
+         two fields, "this form is incomplete" is a worse message than putting
+         the caret where the work is. */
+      if (!a) return from.focus();
+      if (!b) return to.focus();
+      dialog.close();
+      finish({ from: a, to: b });
+    };
+
+    const form = el('form', { method: 'dialog', onsubmit: (e) => { e.preventDefault(); submit(); } }, [
+      el('h2', { text: title }),
+      el('label', { class: 'field-stack' }, [el('span', { text: fromLabel }), from]),
+      el('label', { class: 'field-stack' }, [el('span', { text: toLabel }), to]),
+      hint ? el('p', { class: 'confirm-params', text: hint }) : null,
+      el('div', { class: 'confirm-actions' }, [
+        el('button', { type: 'button', class: 'ghost', text: 'Cancel', onclick: () => { dialog.close(); finish(null); } }),
+        el('button', { type: 'submit', text: 'Apply' }),
+      ]),
+    ]);
+
+    const dialog = el('dialog', { class: 'confirm' }, form);
+    dialog.addEventListener('close', () => { finish(null); dialog.remove(); });
+    document.body.append(dialog);
+    dialog.showModal();
+    from.focus();
+  });
+}