tablewalk 0.0.1

package/dist/client/tour.js

@@ -0,0 +1,324 @@
+/**
+ * A short walk around the interface, once.
+ *
+ * The case for it is narrow and real. Almost everything here is discoverable
+ * by clicking, and four things are not: that the bar takes a language rather
+ * than SQL, that clicking a row is the whole point rather than a way to see
+ * its columns, that editing exists at all behind a switch that says "Read
+ * only", and that the thing in the corner is a database picker. Each is one
+ * sentence. A tour is worth six sentences and nothing more.
+ *
+ * What that rules out is most of what tours do. There is no progress bar, no
+ * confetti, nothing that has to be dismissed twice, and no stop that says
+ * "click here to continue" — the reader is never made to perform the
+ * interface to get out of the tour, because a tour that drives is a tour
+ * people learn to escape rather than read. Escape ends it, so does Skip, and
+ * ending it is remembered.
+ *
+ * Two things it does that a simpler version would not:
+ *
+ *   - **A stop whose anchor is not on screen is dropped**, not shown pointing
+ *     at nothing. The sidebar collapses, the toolbar sheds buttons at narrow
+ *     widths, and a card captioning an empty rectangle is worse than one
+ *     fewer stop.
+ *
+ *   - **One stop has no anchor at all.** The idea that a row is a place you
+ *     walk from is the reason this tool exists and it is not a control, so it
+ *     is not attached to one. Pinning it to whichever element happened to be
+ *     nearby would be inventing a location for an idea.
+ *
+ * It is remembered in `localStorage`, so it is per browser rather than per
+ * connection: it teaches the interface, and the interface does not change
+ * when the database does.
+ */
+import { $, el, trapFocus } from './core.js';
+import { addMenuItem } from './menu.js';
+
+const SEEN = 'tablewalk.tour.v1';
+
+/**
+ * The stops, in the order the eye takes them: where you are, what is here,
+ * how to ask, what happens when you click, what it will not do, and where the
+ * rest is.
+ */
+const STOPS = [
+  {
+    /* Two spellings of one thing, and which is on screen depends on how many
+       connections there are: the picker when there is a choice to make, the
+       plain label when there is not. A stop that named only one of them was
+       silently dropped for everybody with a config file — which is to say for
+       everybody the tour is most useful to. */
+    anchor: ['#conn-picker', '#db-label'],
+    title: 'The database you are on',
+    body: 'Click it to switch, add another, or edit one. Everything else on the '
+      + 'screen comes from whichever one is named here.',
+  },
+  {
+    anchor: '.sidebar',
+    title: 'Every table, with its size',
+    body: 'The number is how many rows are in it. Views are marked. Click one to browse it.',
+  },
+  {
+    anchor: '#querybar',
+    title: 'Ask in words, not SQL',
+    /* Set as code rather than run into the sentence. A query in prose is a
+       string of ordinary words that happens to be a literal, and the reader
+       has to be told which part to type. */
+    code: 'customer active = true sort name limit 20',
+    body: 'Table first, then conditions, then sort and limit. Press ? for the full '
+      + 'grammar, or SQL to see what it compiled to.',
+  },
+  {
+    /* No anchor: an idea, not a control. */
+    anchor: null,
+    title: 'A row is a place, not a record',
+    body: 'Click any row and you get every row elsewhere that points at it. The '
+      + 'orders on a customer, the customer on an order. No joins to write, and '
+      + 'a trail behind you that goes back the way you came.',
+  },
+  {
+    anchor: '#write-toggle',
+    title: 'Read only until you say otherwise',
+    /* Described by what it looks like, not by a label it does not carry: the
+       control is a padlock, and telling someone to look for the words "Read
+       only" sends them hunting for text that is not on the screen. */
+    body: 'A closed padlock means nothing gets written. Click it to turn editing on '
+      + 'for this connection; the window goes red while it is. ⌘Z undoes an edit.',
+  },
+  {
+    anchor: '#search-button',
+    title: 'And the rest',
+    body: '⌘K jumps to any table, view or database. ··· has the diagram, the '
+      + 'exports, saved views, and this tour again.',
+  },
+];
+
+let scrim = null;
+let card = null;
+let ring = null;
+let at = 0;
+/** Undoes the focus trap, and hands the keyboard back to what opened it. */
+let release = null;
+/** The stops that have somewhere to point today. Fixed when the tour opens. */
+let stops = [];
+
+/**
+ * The first of a stop's anchors that is actually on screen.
+ *
+ * `null` for a stop that deliberately has none, `undefined` for one whose
+ * anchors are all absent — the two mean different things and the caller acts
+ * differently on each, so they are not collapsed into one falsy answer.
+ */
+function anchorFor(anchor) {
+  if (!anchor) return null;
+  for (const selector of [anchor].flat()) {
+    const node = document.querySelector(selector);
+    if (!node) continue;
+    const box = node.getBoundingClientRect();
+    /* Zero-sized covers `display: none`, a collapsed sidebar, and a button
+       the toolbar has dropped at this width. */
+    if (box.width > 0 && box.height > 0) return node;
+  }
+  return undefined;
+}
+
+export function tourSeen() {
+  try {
+    return window.localStorage.getItem(SEEN) === 'done';
+  } catch {
+    /* Private browsing, or storage turned off. Treating that as "already
+       seen" is the right way to be wrong: a tour that cannot remember being
+       dismissed would open on every single load. */
+    return true;
+  }
+}
+
+function remember() {
+  try {
+    window.localStorage.setItem(SEEN, 'done');
+  } catch { /* Nothing to do, and nothing worth saying about it. */ }
+}
+
+export function endTour({ remembering = true } = {}) {
+  if (remembering) remember();
+  release?.();
+  release = null;
+  scrim?.remove();
+  card?.remove();
+  ring?.remove();
+  scrim = card = ring = null;
+  window.removeEventListener('resize', place);
+  window.removeEventListener('scroll', place, true);
+  document.removeEventListener('keydown', onKey, true);
+}
+
+/** Start it, or do nothing if there is nothing to show. */
+export function startTour() {
+  if (card) return;
+  stops = STOPS.filter((s) => s.anchor === null || anchorFor(s.anchor) !== undefined);
+  /* Only the anchorless stop left means the interface it describes is not on
+     screen, and one card about walking rows is not a tour. */
+  if (stops.filter((s) => s.anchor).length < 2) return;
+  at = 0;
+
+  scrim = el('div', { class: 'tour-scrim' });
+  /* A click outside ends it rather than advancing. Advancing on a stray click
+     is how someone loses the one stop they were reading. */
+  scrim.addEventListener('click', () => endTour());
+  ring = el('div', { class: 'tour-ring', 'aria-hidden': 'true' });
+  card = el('div', {
+    class: 'tour-card',
+    role: 'dialog',
+    'aria-modal': 'true',
+    'aria-labelledby': 'tour-title',
+  });
+  document.body.append(scrim, ring, card);
+  /* The scrim already blocks the mouse; without this the keyboard walked
+     straight past it into the table underneath, which is the same page
+     claiming to be sealed and behaving otherwise. */
+  release = trapFocus(card);
+  document.addEventListener('keydown', onKey, true);
+  window.addEventListener('resize', place);
+  /* Capturing, because the thing that scrolls is a pane inside the page and
+     not the window — a card pinned to a row that has scrolled away is worse
+     than no card. */
+  window.addEventListener('scroll', place, true);
+  paint();
+}
+
+function onKey(e) {
+  if (e.key === 'Escape') { e.preventDefault(); endTour(); return; }
+  if (e.key === 'ArrowRight') { e.preventDefault(); go(1); return; }
+  if (e.key === 'ArrowLeft') { e.preventDefault(); go(-1); }
+}
+
+function go(delta) {
+  const next = at + delta;
+  if (next < 0) return;
+  if (next >= stops.length) { endTour(); return; }
+  at = next;
+  paint();
+}
+
+function paint() {
+  const stop = stops[at];
+  const last = at === stops.length - 1;
+
+  const next = el('button', {
+    type: 'button',
+    class: 'tour-next',
+    text: last ? 'Done' : 'Next',
+    onclick: () => (last ? endTour() : go(1)),
+  });
+
+  card.replaceChildren(
+    el('p', { class: 'tour-step', text: `${at + 1} of ${stops.length}` }),
+    el('h2', { id: 'tour-title', class: 'tour-title', text: stop.title }),
+    ...(stop.code ? [el('code', { class: 'tour-code', text: stop.code })] : []),
+    el('p', { class: 'tour-body', text: stop.body }),
+    el('div', { class: 'tour-actions' }, [
+      el('button', {
+        type: 'button',
+        class: 'ghost tour-skip',
+        /* "Skip" while there is more, "Done" is the other button. On the last
+           stop this would be a second way to say the same thing, so it goes. */
+        text: 'Skip',
+        hidden: last,
+        onclick: () => endTour(),
+      }),
+      el('button', {
+        type: 'button', class: 'ghost', text: 'Back', hidden: at === 0, onclick: () => go(-1),
+      }),
+      next,
+    ]),
+  );
+  place();
+  next.focus();
+}
+
+/** Put the ring on the anchor and the card beside it. */
+function place() {
+  if (!card) return;
+  const stop = stops[at];
+  const node = stop.anchor ? anchorFor(stop.anchor) : null;
+
+  if (!node) {
+    /* The anchorless stop, and the fallback if an anchor vanished mid-tour —
+       a resize that collapsed the sidebar, say. Centred, with no ring, which
+       is honest about pointing at nothing. With no ring there is no hole
+       punched in anything, so the scrim does the dimming itself. */
+    ring.hidden = true;
+    scrim.classList.add('dim');
+    card.style.top = '50%';
+    card.style.left = '50%';
+    card.style.transform = 'translate(-50%, -50%)';
+    return;
+  }
+
+  card.style.transform = '';
+  scrim.classList.remove('dim');
+  const box = node.getBoundingClientRect();
+  const pad = 6;
+  ring.hidden = false;
+  ring.style.top = `${box.top - pad}px`;
+  ring.style.left = `${box.left - pad}px`;
+  ring.style.width = `${box.width + pad * 2}px`;
+  ring.style.height = `${box.height + pad * 2}px`;
+
+  const gap = 14;
+  const edge = 8;
+  const size = card.getBoundingClientRect();
+  const vw = window.innerWidth;
+  const vh = window.innerHeight;
+
+  /* Four sides, tried in order of preference, and the first that fits wins.
+  
+     "Below, or else above" is the dropdown's rule and it is wrong here,
+     because a tour points at things a dropdown never does. The sidebar is as
+     tall as the window: nothing fits below it or above it, so the card fell
+     back to the top of the screen and sat on top of the table names it was
+     describing. Something that has to cover its subject to talk about it is
+     not pointing at anything.
+  
+     Beside is what a tall anchor wants, and below is what a wide one wants,
+     so both are offered and the geometry decides. */
+  const sides = [
+    { fits: vh - box.bottom - gap >= size.height + edge, top: box.bottom + gap, left: centreX() },
+    { fits: vw - box.right - gap >= size.width + edge, top: centreY(), left: box.right + gap },
+    { fits: box.top - gap >= size.height + edge, top: box.top - gap - size.height, left: centreX() },
+    { fits: box.left - gap >= size.width + edge, top: centreY(), left: box.left - gap - size.width },
+  ];
+
+  function centreX() { return box.left + box.width / 2 - size.width / 2; }
+  function centreY() { return box.top + box.height / 2 - size.height / 2; }
+
+  /* Nothing fits — a viewport smaller than the card plus its anchor. Centred
+     is the least bad answer: the card is readable and its buttons reachable,
+     which beats a card correctly positioned half off the screen. */
+  const chosen = sides.find((s) => s.fits) ?? { top: centreY(), left: centreX() };
+
+  const clamp = (value, max) => Math.min(Math.max(edge, value), Math.max(edge, max - edge));
+  card.style.top = `${clamp(chosen.top, vh - size.height)}px`;
+  card.style.left = `${clamp(chosen.left, vw - size.width)}px`;
+}
+
+/**
+ * Offer it, and show it the first time.
+ *
+ * The menu item is registered whether or not the tour has been seen: the one
+ * thing worse than a tour nobody asked for is one that cannot be found again
+ * by somebody who now wants it.
+ */
+export function initTour() {
+  addMenuItem({
+    label: 'Take the tour',
+    detail: 'six things worth knowing',
+    onSelect: () => startTour(),
+  });
+  if (tourSeen()) return;
+  /* After the first paint, so the stops have something to measure. Two frames
+     rather than a timeout: the second one runs after the first has been
+     drawn, which is exactly the condition, rather than a guess in
+     milliseconds that is wrong on a slow machine. */
+  requestAnimationFrame(() => requestAnimationFrame(() => startTour()));
+}

package/dist/client/undo.js

@@ -0,0 +1,105 @@
+/**
+ * Undo, for writes that have already landed.
+ *
+ * Write mode is the frightening part of this tool, and most of what makes it
+ * frightening is that an edit is a one-way door. Saying "Undo" beside the
+ * confirmation is what turns a decision into a correction.
+ *
+ * This used to keep its own stack: the write path knew what every column held
+ * before it changed it, and putting those values back was a one-line call. It
+ * worked, and it covered exactly one third of the writes that reach a
+ * database through this tool. Not an insert. Not a delete. And not a single
+ * thing an agent did over MCP, which is the half of the product where a write
+ * is least likely to be watched.
+ *
+ * So the record moved to the server — `server/journal.ts`, one journal per
+ * connection, written by every door — and this asks. What is kept here is the
+ * part that was always the browser's: the keystroke, the menu item, and
+ * saying what happened afterwards.
+ *
+ * The guarantees did not move, they widened. The journal re-reads every row
+ * before it writes anything and refuses the whole revert if one has changed
+ * since, because putting an old value back over a newer one is not an undo,
+ * it is a silent overwrite. It is in-session for the same reason this was: a
+ * stack that outlives the process invites undoing something from an hour ago,
+ * by which time the row has moved on.
+ */
+import { api, state, toast } from './core.js';
+
+/* What the server last told us there was to undo. Held so the menu can name
+   it without a request per repaint — the menu's detail is a function and is
+   called on every open. Refreshed after anything that writes. */
+let pending = null;
+
+const forConnection = () => (pending && pending.connection === state.activeConnection ? pending : null);
+
+/**
+ * Ask the server what there is to undo.
+ *
+ * Failures are silent and leave the menu saying "nothing to undo", which is
+ * the safe direction to be wrong in: offering an undo that cannot happen is
+ * worse than not offering one that could.
+ */
+export async function refreshUndo() {
+  const connection = state.activeConnection;
+  if (!connection) return;
+  try {
+    const data = await api('/api/revert', {});
+    pending = { connection, next: data.next ?? null, writes: data.writes ?? [] };
+  } catch {
+    pending = { connection, next: null, writes: [] };
+  }
+}
+
+export const canUndo = () => Boolean(forConnection()?.next);
+
+/** What the menu item says it would undo, or null. */
+export function undoDescription() {
+  return forConnection()?.next?.summary ?? null;
+}
+
+/**
+ * Undo the last write on this connection.
+ *
+ * The decision about *which* write, and whether it is still safe to undo, is
+ * the journal's — this reports what it decided.
+ */
+export async function undoLast() {
+  if (!state.activeConnection) return;
+  let data;
+  try {
+    data = await api('/api/revert', { confirm: true });
+  } catch (err) {
+    toast(err.message, 'error');
+    return;
+  }
+  await refreshUndo();
+
+  if (data.reverted) {
+    toast(data.undone?.summary ? `Undone: ${data.undone.summary}.` : 'Undone.', 'ok');
+    return;
+  }
+  /* The journal's refusals are sentences meant to be read — "…has changed
+     since, so undoing would overwrite that" — so they are shown as they are
+     rather than summarised into "could not undo". */
+  const first = data.errors?.[0]?.message ?? data.errors?.[0];
+  toast(first ?? 'Nothing to undo.', first ? 'error' : 'info');
+}
+
+/**
+ * Bind ⌘Z.
+ *
+ * Stands aside for text fields, where it means "undo my typing" and taking it
+ * over would be worse than not offering it — the staged-edit inputs are
+ * exactly where someone is most likely to press it for the other reason.
+ */
+export function initUndo() {
+  document.addEventListener('keydown', (e) => {
+    if (e.key !== 'z' || !(e.metaKey || e.ctrlKey) || e.shiftKey) return;
+    const tag = document.activeElement?.tagName;
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || document.activeElement?.isContentEditable) return;
+    if (!canUndo()) return;
+    e.preventDefault();
+    void undoLast();
+  }, true);
+}

package/dist/client/url.js

@@ -0,0 +1,166 @@
+/**
+ * Deep links: the stateful half.
+ *
+ * Reads and writes `window.location`, and decides when. The serialisation
+ * itself is in deeplink.js, which touches neither the DOM nor app state.
+ */
+import { api, keyFilter, labelPath, primaryKey, render, renderCrumbs, rowLabel, state } from './core.js';
+import { pageToken } from './page.js';
+import { connectionFromHash, fromHash, hashFor } from './deeplink.js';
+import { looksLikeBreakdown } from './breakdown.js';
+
+/** Rebuilding the URL while reacting to one would loop. */
+let applying = false;
+
+/**
+ * Nothing writes the address bar until boot says the incoming link has been
+ * read.
+ *
+ * Boot renders once before applying the link — it has to, because the empty
+ * state is what a plain visit should see — and that render called `syncHash`,
+ * which wrote *the state it had* over the link that had not been applied yet.
+ * Usually the link was re-applied a moment later and the bar corrected
+ * itself; sometimes the reader was left on the wrong connection, and always
+ * there was a window in which the address bar said something nobody asked
+ * for. Opening an agent-supplied link in a fresh tab is exactly the case this
+ * tool exists to serve, so it is exactly the case that must not race.
+ */
+let settled = false;
+export function allowSync() {
+  settled = true;
+}
+
+export { connectionFromHash, fromHash, hashFor };
+
+export function toHash() {
+  /* The page half of a link is written by name where the name identifies it
+     — see `pageToken`. Supplied here because deeplink.js imports nothing. */
+  return hashFor(state.activeConnection, state.stack, { pageToken });
+}
+
+/**
+ * Fetch readable names for every row in a restored trail.
+ *
+ * Only the last entry in a stack is rendered, so on a fresh load the earlier
+ * crumbs would keep their raw keys — a shared link reading
+ * `employee › 2 › invoice sold_by = 2` where the sender saw
+ * `employee › Rina Petrova › …`. The trail is the thing being shared, so it
+ * should arrive legible.
+ *
+ * One small query per row, in parallel, and only on restore. Failures are
+ * ignored: a crumb showing its key is worse than one showing a name, and far
+ * better than a page that fails to load because a label could not be read.
+ */
+export async function resolveLabels(stack, findTableById) {
+  const rows = stack.filter((entry) => entry.kind === 'row');
+  if (!rows.length) return;
+  await Promise.allSettled(rows.map(async (entry) => {
+    const table = findTableById(entry.table);
+    if (!table) return;
+    /* As a view rather than a plain query when the name lives a hop away —
+       `party_id.display_name` — because a plain row cannot carry a joined
+       column, and a restored trail through such a table read as keys. */
+    const path = labelPath(table);
+    const result = path && path.includes('.')
+      ? await api('/api/view/run', {
+          view: {
+            id: `crumb:${entry.table}`,
+            name: table.name,
+            base: entry.table,
+            columns: [...new Set([...primaryKey(table), path])].map((p) => ({ path: p })),
+            filter: { groups: [Object.entries(entry.key).map(([p, value]) => ({ path: p, op: '=', value }))] },
+            limit: 1,
+          },
+        })
+      : await api('/api/query', {
+          table: entry.table,
+          filter: keyFilter(entry.key),
+          limit: 1,
+          offset: 0,
+        });
+    const row = result.rows[0];
+    if (!row) return;
+    const readable = rowLabel(table, row);
+    if (readable) entry.label = readable;
+  }));
+  renderCrumbs();
+}
+
+/**
+ * Write the current state into the address bar.
+ *
+ * Whether it adds a history entry depends on how you got here. A step in the
+ * walk pushes, so the browser's Back button undoes it; a refinement of the
+ * view you are already on — a sort toggle, a tab, a re-run of the same query
+ * — replaces, so Back does not spend three presses undoing sorts.
+ *
+ * This started as replaceState for everything, on the reasoning that the
+ * trail is already a back stack with its own affordance. That was wrong in a
+ * way only using it revealed: with no history entries at all, pressing Back
+ * leaves tablewalk entirely and takes the whole trail with it. Avoiding a
+ * little history noise is not worth destroying someone's work.
+ */
+export function syncHash() {
+  if (applying || !settled) return;
+  const next = toHash();
+  /* Compared against the path, and only the path. The address may carry a
+     `?` — the app is opened with one in development to defeat the module
+     cache — and comparing the whole address would find a difference on every
+     render and rewrite the bar forever. */
+  if (next === window.location.pathname) return;
+  if (state.navMode === 'push') window.history.pushState(null, '', next);
+  else window.history.replaceState(null, '', next);
+  // Anything that renders without going through go() is a refinement.
+  state.navMode = 'replace';
+}
+
+/**
+ * Apply a hash to the app. Used on load and when someone edits the address
+ * bar or uses the browser's Back button.
+ */
+export function applyHash(hash, { findTableById, selectConnection }) {
+  /* The connection is read first and separately. Parsing the trail needs the
+     schema it was written against — a link into another database names tables
+     the current one has never heard of, so every row segment fails to resolve
+     and is silently dropped. Switch first, parse second. */
+  const target = connectionFromHash(hash);
+  if (target && state.activeConnection && target !== state.activeConnection) {
+    // Handed the raw hash, not a parsed stack: it can only be parsed once
+    // the new schema is loaded.
+    void selectConnection(target, hash);
+    /* Not `true`. The switch is asynchronous and renders the target itself
+       when it lands; a caller that renders in the meantime paints the
+       *outgoing* connection — which on a cold tab is whatever another tab left
+       active on the server — into the address bar for a frame. That frame is a
+       `/other-db` URL that can be copied or bookmarked, and it is exactly what
+       the cold-link guarantee forbids. The sentinel tells the caller the
+       render is not theirs to do. */
+    return 'switching';
+  }
+
+  const parsed = fromHash(hash, findTableById, { isBreakdown: looksLikeBreakdown });
+  if (!parsed) return false;
+  applying = true;
+  try {
+    state.stack = parsed.stack;
+    state.page = 0;
+    // Restoring from the address bar must not itself add an entry, or Back
+    // would need two presses to get past the state it just restored.
+    state.navMode = 'replace';
+    render();
+    void resolveLabels(parsed.stack, findTableById);
+    return true;
+  } finally {
+    applying = false;
+  }
+}
+
+/** Suppress hash writes while a caller rebuilds state from one. */
+export function whileApplying(fn) {
+  applying = true;
+  try {
+    return fn();
+  } finally {
+    applying = false;
+  }
+}