tablewalk 0.0.1

package/dist/client/skeleton.js

@@ -0,0 +1,139 @@
+/**
+ * Placeholders shaped like the thing that is coming.
+ *
+ * "Running…" tells you the tool is alive and nothing else. A placeholder that
+ * matches the layout about to replace it does more: the page stops jumping
+ * when the data lands, because the space was already the right size and shape,
+ * and the eye has somewhere to be while it waits.
+ *
+ * Two rules keep this from being decoration:
+ *
+ *   - **Nothing appears immediately.** Most queries here finish in single-digit
+ *     milliseconds, and a skeleton that flashes for 40ms is worse than no
+ *     skeleton — it reads as a glitch. Placeholders are mounted only if the
+ *     work is still going after a delay long enough that the wait was real.
+ *   - **The shape is derived, not invented.** The grid placeholder uses the
+ *     table's own column count and the page size; the record placeholder uses
+ *     the record's own layout. A generic three-bar shimmer would be a lie about
+ *     what is loading, and would still make the page jump when it resolved.
+ */
+import { el } from './core.js';
+
+/**
+ * How long a wait has to last before it is worth showing anything.
+ *
+ * Under this, the result lands before a reader would register the placeholder,
+ * and showing one turns a fast response into a visible flicker.
+ */
+const DELAY = 140;
+
+/**
+ * Mount a placeholder into `host`, unless the work finishes first.
+ *
+ * Returns a function to call when it does. Calling it before the delay
+ * elapses means nothing is ever inserted; after, it removes what was.
+ *
+ * @param {Element} host
+ * @param {() => Element} build  called lazily, so a placeholder that is never
+ *                               shown costs nothing to construct
+ */
+export function placeholder(host, build) {
+  let node = null;
+  const timer = setTimeout(() => {
+    node = build();
+    host.append(node);
+  }, DELAY);
+
+  return () => {
+    clearTimeout(timer);
+    node?.remove();
+  };
+}
+
+/** One shimmering block. Width is a percentage so rows look uneven, as text is. */
+function bar(width, { height = 12 } = {}) {
+  return el('span', {
+    class: 'sk-bar',
+    style: `width:${width}%; height:${height}px`,
+    'aria-hidden': 'true',
+  });
+}
+
+/* Deterministic per position rather than random, so a placeholder does not
+   reshuffle itself if it is ever rebuilt, and two adjacent rows never come out
+   identical — which is what makes a block of bars read as text rather than as
+   a bar chart. */
+const widths = [82, 54, 71, 45, 63, 88, 38, 76, 59, 67];
+const widthAt = (i) => widths[i % widths.length];
+
+/**
+ * A grid, before its rows arrive.
+ *
+ * @param {number} columns  how many columns the table has
+ * @param {number} rows     how many rows the page will hold
+ */
+export function gridSkeleton(columns, rows) {
+  // Bounded: a forty-column table does not need forty placeholder bars to
+  // communicate "a table is coming", and the real grid scrolls sideways anyway.
+  const across = Math.min(Math.max(columns, 3), 8);
+  const down = Math.min(Math.max(rows, 3), 12);
+
+  const grid = el('div', {
+    class: 'sk-grid',
+    style: `--sk-cols:${across}`,
+    role: 'status',
+    'aria-label': 'Loading rows',
+  });
+
+  grid.append(el('div', { class: 'sk-row sk-head' },
+    Array.from({ length: across }, (_, i) => bar(40 + ((i * 17) % 30), { height: 8 }))));
+
+  for (let r = 0; r < down; r += 1) {
+    grid.append(el('div', { class: 'sk-row' },
+      Array.from({ length: across }, (_, c) => bar(widthAt(r * across + c)))));
+  }
+  return grid;
+}
+
+/**
+ * A record, before its fields arrive.
+ *
+ * Takes the section shapes from the layout that is about to be rendered, so
+ * the headings land where the headings will be and the two-column field grid
+ * is already the right height.
+ *
+ * @param {Array<{title?: string, count: number}>} sections
+ */
+export function recordSkeleton(sections) {
+  const wrap = el('div', { class: 'sk-record', role: 'status', 'aria-label': 'Loading record' });
+
+  for (const section of sections) {
+    const block = el('section', { class: 'sk-section' });
+    if (section.title) block.append(bar(14, { height: 9 }));
+    const list = el('div', { class: 'sk-fields' });
+    for (let i = 0; i < section.count; i += 1) {
+      list.append(el('div', { class: 'sk-field' }, [
+        bar(38, { height: 10 }),
+        bar(widthAt(i), { height: 12 }),
+      ]));
+    }
+    block.append(list);
+    wrap.append(block);
+  }
+  return wrap;
+}
+
+/** The Related list, before its counts arrive. */
+export function relatedSkeleton(count) {
+  const wrap = el('div', { class: 'sk-related', role: 'status', 'aria-label': 'Counting' });
+  for (let i = 0; i < Math.min(Math.max(count, 1), 8); i += 1) {
+    wrap.append(el('div', { class: 'sk-related-item' }, [
+      bar(100, { height: 14 }),
+      el('span', { class: 'sk-related-names' }, [
+        bar(widthAt(i), { height: 11 }),
+        bar(widthAt(i + 3) * 0.7, { height: 8 }),
+      ]),
+    ]));
+  }
+  return wrap;
+}

package/dist/client/sql.css

@@ -0,0 +1,126 @@
+/* The SQL editor.
+
+   A panel rather than a page: you write a statement against something you were
+   already looking at, and losing that context to a full-screen editor makes
+   every trip to SQL a trip away from the walk. It sits over the bottom of the
+   window, tall enough to read a result in and short enough that the page it
+   came from is still there behind it. */
+
+.sql-panel {
+  position: fixed; left: 0; right: 0; bottom: 0; z-index: 75;
+  display: flex; flex-direction: column;
+  max-height: 78vh;
+  background: var(--surface);
+  border-top: 1px solid var(--border-strong);
+  box-shadow: 0 -12px 40px rgb(0 0 0 / 0.16);
+}
+
+.sql-head {
+  display: flex; align-items: center; gap: 14px;
+  padding: 10px 16px;
+  border-bottom: 1px solid var(--border);
+  flex: none;
+}
+.sql-title { display: flex; align-items: baseline; gap: 10px; }
+.sql-eyebrow {
+  font: 600 12px var(--mono); color: var(--accent);
+  text-transform: uppercase; letter-spacing: 0.08em;
+}
+.sql-target { font: 11px var(--mono); color: var(--text-faint); }
+.sql-head-actions { margin-left: auto; display: flex; gap: 8px; }
+.sql-write { color: var(--danger); }
+.sql-write:hover { border-color: var(--danger); background: color-mix(in srgb, var(--danger) 10%, transparent); }
+
+.sql-editor { padding: 12px 16px; flex: none; position: relative; }
+.sql-input {
+  display: block; width: 100%; resize: none;
+  padding: 10px 12px;
+  border: 1px solid var(--border); border-radius: 7px;
+  background: var(--bg); color: var(--text);
+  font: 13px/1.55 var(--mono);
+  tab-size: 2;
+}
+.sql-input:focus { outline: none; border-color: var(--accent); }
+.sql-input::placeholder { color: var(--text-faint); }
+
+.sql-results { overflow: auto; flex: 1; min-height: 0; padding-bottom: 12px; }
+
+.sql-stats {
+  display: flex; gap: 14px; align-items: baseline;
+  padding: 2px 16px 8px;
+  font: 11px var(--mono); color: var(--text-faint);
+  font-variant-numeric: tabular-nums;
+}
+/* Says which kind of "there is more" this is: a page of a bounded read, or the
+   front of an answer the database computed in full. */
+.sql-truncated { color: var(--key); }
+
+.sql-error {
+  margin: 0 16px; padding: 10px 12px;
+  border-radius: 6px;
+  background: color-mix(in srgb, var(--danger) 10%, transparent);
+  border: 1px solid color-mix(in srgb, var(--danger) 40%, transparent);
+  color: var(--danger);
+  font: 12px/1.5 var(--mono);
+  white-space: pre-wrap;
+}
+
+/* Said before the grid, because a row that opens a record should say so before
+   it is clicked rather than after. */
+.sql-walk {
+  margin: 0 16px 6px; font: 11px var(--mono); color: var(--accent);
+}
+
+/* Anchored to the caret rather than the field — see placeAtCaret. */
+.ac-mirror {
+  position: absolute; visibility: hidden; pointer-events: none;
+  top: 0; left: -9999px;
+  overflow-wrap: break-word;
+}
+
+
+/* The statements you have kept. One row, config and personal together — to
+   whoever is looking for one they are the same thing, and the difference is
+   only whether it can be deleted. */
+.sql-saved {
+  display: flex; gap: 6px; flex-wrap: wrap;
+  padding: 0 16px 4px;
+  flex: none;
+}
+.sql-chip {
+  display: inline-flex; align-items: center;
+  border: 1px solid var(--border); border-radius: 999px;
+  background: var(--bg);
+  overflow: hidden;
+}
+.sql-chip:hover { border-color: var(--accent); }
+.sql-chip-open {
+  padding: 3px 10px;
+  background: none; border: none;
+  color: var(--text-dim); cursor: pointer;
+  font: 11.5px var(--mono);
+}
+.sql-chip:hover .sql-chip-open { color: var(--accent); }
+.sql-chip-remove {
+  padding: 3px 8px 3px 2px;
+  background: none; border: none;
+  color: var(--text-faint); cursor: pointer; font-size: 12px; line-height: 1;
+}
+.sql-chip-remove:hover { color: var(--danger); }
+/* Not a button: a config statement is not this browser's to delete, and an ×
+   that refuses is worse than no ×. */
+.sql-chip-tag {
+  padding: 2px 8px 2px 2px;
+  color: var(--text-faint);
+  font: 9px var(--mono); text-transform: uppercase; letter-spacing: 0.05em;
+}
+
+/* An empty result knows its shape, and saying so is the difference between
+   "your statement returned nothing" and "something went wrong". */
+.sql-empty {
+  margin: 0 16px; padding: 10px 12px;
+  border: 1px solid var(--border); border-radius: 6px;
+  background: var(--surface-2);
+  font: 12px/1.6 var(--mono); color: var(--text-dim);
+}
+.sql-empty strong { color: var(--text); }

package/dist/client/sql.js

@@ -0,0 +1,398 @@
+/**
+ * The SQL editor.
+ *
+ * tablewalk's argument against a SQL box is in `src/shared/query.ts`: a tool
+ * that lets people type SQL "would have to either trust them or write a SQL
+ * parser to untrust them". That is a good argument for why the *query language*
+ * exists and a bad reason to have no SQL at all — every language has a last
+ * mile, and for this one it is window functions, recursive CTEs and `EXPLAIN`.
+ * Without a SQL box that last mile means leaving for `psql`, and once you have
+ * left you do not come back for the walk.
+ *
+ * The dilemma is dissolved rather than answered: the statement is not trusted
+ * *or* parsed, it is handed to a connection that cannot write. See `runSql` in
+ * adapters/adapter.ts for what that costs and what it buys.
+ *
+ * Two ways in, on purpose. A statement typed from scratch is what people expect
+ * from a database browser. The other is the ramp: run something in the query
+ * language, open the SQL pane, and edit what it compiled to. That turns the
+ * pane from a thing you read into a thing you start from, and it is the only
+ * place in the tool that teaches the SQL behind the language.
+ */
+import { $, api, el, explainedSql, go, render, state, toast, whenConnectionChanges } from './core.js';
+import { attachComplete } from './complete.js';
+import { sqlSuggestions, tokenAt } from './sqlcomplete.js';
+import { renderGrid } from './table.js';
+import { addMenuItem } from './menu.js';
+import { promptFor } from './prompt.js';
+import { removeStatement, saveStatement, savedStatements } from './sqlsaved.js';
+
+/** The statement being edited, per connection, so switching back keeps it. */
+const drafts = new Map();
+
+const connectionKey = () => state.activeConnection ?? 'default';
+
+let panel = null;
+
+export const sqlOpen = () => Boolean(panel);
+
+export function openSql(initial) {
+  if (panel) {
+    if (initial !== undefined) setText(initial);
+    panel.querySelector('.sql-input')?.focus();
+    return;
+  }
+  if (initial !== undefined) drafts.set(connectionKey(), initial);
+  paint();
+}
+
+function setText(text) {
+  drafts.set(connectionKey(), text);
+  const input = panel?.querySelector('.sql-input');
+  if (input) {
+    input.value = text;
+    autoGrow(input);
+  }
+}
+
+function close() {
+  panel?.remove();
+  panel = null;
+  document.removeEventListener('keydown', onKey, true);
+}
+
+function onKey(e) {
+  if (e.key !== 'Escape') return;
+  // The completion list eats Escape first; this only fires when it is closed.
+  if (document.querySelector('.ac:not([hidden])')) return;
+  const tag = document.activeElement?.tagName;
+  if (tag === 'TEXTAREA' || tag === 'INPUT') { document.activeElement.blur(); return; }
+  e.preventDefault();
+  close();
+}
+
+/* A textarea that grows with its content, to a point. A fixed-height box makes
+   a six-line statement a two-line window onto a six-line statement; an
+   unbounded one pushes the results off the screen. */
+function autoGrow(input) {
+  input.style.height = 'auto';
+  input.style.height = `${Math.min(Math.max(input.scrollHeight, 84), 340)}px`;
+}
+
+function paint() {
+  const existing = panel;
+  panel = el('div', { class: 'sql-panel', role: 'dialog', 'aria-label': 'SQL' });
+
+  const writable = state.connections?.find((c) => c.id === state.activeConnection)?.writable;
+
+  const input = el('textarea', {
+    class: 'sql-input',
+    spellcheck: 'false',
+    autocapitalize: 'off',
+    autocomplete: 'off',
+    'aria-label': 'SQL statement',
+    placeholder: 'select * from customer where credit_limit > 5000',
+  });
+  input.value = drafts.get(connectionKey()) ?? '';
+
+  const results = el('div', { class: 'sql-results' });
+
+  const run = (write = false) => void execute(input.value, results, { write });
+
+  input.addEventListener('input', () => {
+    drafts.set(connectionKey(), input.value);
+    autoGrow(input);
+  });
+  input.addEventListener('keydown', (e) => {
+    // ⌘↵ runs. Plain Enter is a newline: this is a text editor, and a box where
+    // Enter submits is a box you cannot write two lines in.
+    if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+      e.preventDefault();
+      run();
+    }
+  });
+
+  const head = el('div', { class: 'sql-head' }, [
+    el('div', { class: 'sql-title' }, [
+      el('span', { class: 'sql-eyebrow', text: 'SQL' }),
+      el('span', {
+        class: 'sql-target',
+        text: `${state.schema?.label ?? ''} · ${state.schema?.dialect ?? ''}`,
+      }),
+    ]),
+    el('div', { class: 'sql-head-actions' }, [
+      /* Offered only where the server would allow it. A button that exists to
+         be refused is a button that lies. */
+      writable
+        ? el('button', {
+            type: 'button', class: 'ghost sql-write',
+            title: 'Run this statement on the write connection',
+            text: 'Run as write…',
+            onclick: () => void confirmWrite(input.value, results),
+          })
+        : null,
+      el('button', {
+        type: 'button', class: 'ghost', text: 'Save…',
+        title: 'Keep this statement under a name',
+        onclick: () => void save(input.value),
+      }),
+      el('button', { type: 'button', text: 'Run ⌘↵', onclick: () => run() }),
+      el('button', { type: 'button', class: 'ghost', text: 'Done', onclick: close }),
+    ].filter(Boolean)),
+  ]);
+
+  panel.append(head, savedBar(), el('div', { class: 'sql-editor' }, input), results);
+  document.body.append(panel);
+  existing?.remove();
+
+  attachComplete(input, sqlSuggestions, { anchor: 'caret', split: tokenAt });
+  document.addEventListener('keydown', onKey, true);
+
+  autoGrow(input);
+  input.focus();
+  input.setSelectionRange(input.value.length, input.value.length);
+}
+
+/**
+ * The statements you have kept, as one row above the editor.
+ *
+ * Config-defined and browser-saved together, because to whoever is looking for
+ * one they are the same thing — the difference is only whether it can be
+ * deleted, which is why only one of them offers an ×.
+ */
+function savedBar() {
+  const all = savedStatements();
+  if (!all.length) return el('div', { hidden: true });
+
+  const bar = el('div', { class: 'sql-saved' });
+  for (const item of all) {
+    bar.append(el('span', { class: `sql-chip source-${item.source}` }, [
+      el('button', {
+        type: 'button',
+        class: 'sql-chip-open',
+        title: item.description ?? item.sql,
+        text: item.name,
+        onclick: () => setText(item.sql),
+      }),
+      item.source === 'saved'
+        ? el('button', {
+            type: 'button', class: 'sql-chip-remove',
+            title: `Forget "${item.name}"`,
+            'aria-label': `Forget ${item.name}`,
+            text: '×',
+            onclick: () => { removeStatement(item.name); paint(); },
+          })
+        : el('span', { class: 'sql-chip-tag', title: 'Defined in tablewalk.json', text: 'config' }),
+    ]));
+  }
+  return bar;
+}
+
+async function save(sql) {
+  const statement = sql.trim();
+  if (!statement) return;
+  const name = await promptFor({
+    title: 'Name this statement',
+    label: 'Name',
+    hint: statement.length > 120 ? `${statement.slice(0, 120)}…` : statement,
+    placeholder: 'e.g. Customers over their limit',
+  });
+  if (!name) return;
+  if (saveStatement(name, statement)) {
+    toast(`Saved "${name}".`, 'ok');
+    paint();
+  }
+}
+
+/**
+ * Run a statement and render whatever comes back.
+ *
+ * Errors land beside the editor rather than as a toast that disappears: a SQL
+ * error is something you read while fixing the statement it came from, and the
+ * database's own wording is kept because any paraphrase says less.
+ */
+async function execute(text, results, { write = false } = {}) {
+  const statement = text.trim();
+  if (!statement) return;
+
+  results.replaceChildren(el('p', { class: 'loading', text: 'Running…' }));
+  let data;
+  try {
+    data = await api('/api/sql', { text: statement, limit: 500, write });
+  } catch (err) {
+    results.replaceChildren(el('p', { class: 'sql-error', text: err.message }));
+    return;
+  }
+
+  if (data.errors?.length) {
+    results.replaceChildren(el('p', { class: 'sql-error', text: data.errors[0].message }));
+    return;
+  }
+
+  if (write) {
+    toast(`${data.affected} row${data.affected === 1 ? '' : 's'} changed.`, 'ok');
+    results.replaceChildren(
+      el('p', { class: 'note', text: `${data.affected} row${data.affected === 1 ? '' : 's'} changed.` }),
+    );
+    // The schema and every open page may now be stale.
+    render();
+    return;
+  }
+
+  results.replaceChildren(...[
+    el('div', { class: 'sql-stats' }, [
+      el('span', { text: `${data.rows.length} row${data.rows.length === 1 ? '' : 's'}` }),
+      el('span', { text: `${data.ms} ms` }),
+      /* Said rather than implied. `bounded: false` means the database ran the
+         whole statement and we are showing the front of the answer — which is
+         a different fact from "there are more rows", and the reader should not
+         have to infer which one they are looking at. */
+      data.truncated
+        ? el('span', {
+            class: 'sql-truncated',
+            text: data.bounded
+              ? `first ${data.rows.length} — add a LIMIT to see a different page`
+              : `first ${data.rows.length} of what the database returned`,
+          })
+        : null,
+    ].filter(Boolean)),
+    grid(data),
+  ]);
+}
+
+/**
+ * Rows as a grid, walkable when the columns can identify a row.
+ *
+ * A result whose columns include every part of some table's primary key can be
+ * walked, which is what stops SQL being a dead end: the answer feeds back into
+ * the thing the tool is for. When it cannot, the rows are inert *and look it* —
+ * `renderGrid` is given no click handler, so nothing offers a click that does
+ * nothing.
+ */
+function grid(data) {
+  const target = walkableTable(data.columns);
+  /* `renderGrid` reads rows as objects keyed by column name; the wire format is
+     positional so duplicate names survive the trip. Rebuilt here with the
+     deduplicated names, which is the last point both are in hand. */
+  const rows = data.rows.map((row) =>
+    Object.fromEntries(data.columns.map((name, i) => [name, row[i]])),
+  );
+
+  const wrap = el('div');
+
+  /* An empty result still knows its shape, and saying so is the difference
+     between "your statement returned nothing" and "something went wrong".
+     The adapters go out of their way to report columns for a result with no
+     rows; the shared grid returns "No rows match." before it looks at them,
+     which is right for a table view and throws away the useful half here. */
+  if (!data.rows.length) {
+    wrap.append(
+      el('p', { class: 'sql-empty' }, [
+        el('strong', { text: 'No rows.' }),
+        el('span', {
+          text: data.columns.length
+            ? ` The statement returned these columns: ${data.columns.join(', ')}.`
+            : ' The statement returned no columns either.',
+        }),
+      ]),
+    );
+    return wrap;
+  }
+
+  if (target) {
+    wrap.append(el('p', { class: 'sql-walk', text: `Rows open as ${target.name} records.` }));
+  }
+  wrap.append(
+    renderGrid(target, { columns: data.columns, rows }, {
+      onRowClick: target ? (row) => openRecord(target, row) : undefined,
+    }),
+  );
+  return wrap;
+}
+
+/** The table whose rows these are, if the columns can say. */
+function walkableTable(columns) {
+  const present = new Set(columns);
+  const candidates = (state.schema?.tables ?? []).filter((t) => {
+    const key = t.columns.filter((c) => c.primaryKey).map((c) => c.name);
+    return key.length > 0 && key.every((c) => present.has(c));
+  });
+  if (!candidates.length) return null;
+  /* Several tables can share a key shape — `id` is not distinctive. The one
+     whose other columns also appear is the one the statement is about. */
+  return candidates.sort((a, b) => overlap(b, present) - overlap(a, present))[0];
+}
+
+const overlap = (table, present) => table.columns.filter((c) => present.has(c.name)).length;
+
+function openRecord(table, row) {
+  const key = {};
+  for (const column of table.columns.filter((c) => c.primaryKey)) key[column.name] = row[column.name];
+  close();
+  go({ kind: 'row', table: table.id, key, label: String(Object.values(key).join('/')) }, 'reset');
+}
+
+/**
+ * A write, with the statement in front of you.
+ *
+ * The confirm shows the exact text rather than asking "are you sure": the
+ * question worth answering is not whether you meant to press the button, it is
+ * whether the statement says what you think it says.
+ */
+async function confirmWrite(text, results) {
+  const statement = text.trim();
+  if (!statement) return;
+
+  const dialog = el('dialog', { class: 'confirm' }, [
+    el('h2', { text: 'Run this as a write?' }),
+    el('p', { text: 'This runs on the write connection. It is not undoable from here.' }),
+    el('pre', { class: 'confirm-params', text: statement }),
+    el('div', { class: 'confirm-actions' }, [
+      el('button', { type: 'button', class: 'ghost', text: 'Cancel', onclick: () => dialog.close() }),
+      el('button', {
+        type: 'button', class: 'danger', text: 'Run as write',
+        onclick: () => { dialog.close(); void execute(statement, results, { write: true }); },
+      }),
+    ]),
+  ]);
+  document.body.append(dialog);
+  dialog.addEventListener('close', () => dialog.remove());
+  dialog.showModal();
+}
+
+export function initSql() {
+  /* The ramp.
+  
+     The SQL pane has always shown what the query language compiled to, and it
+     has always been a `<pre>` — something to read. Making it a starting point
+     costs one button and changes what the pane is for: you can now build a
+     query the easy way, see the statement, and take it over at the point the
+     language runs out. That is the shortest path from knowing the language to
+     knowing the database, and nothing else in the tool offers it. */
+  $('explain-edit')?.addEventListener('click', () => openSql(explainedSql()));
+
+  /* An open editor follows the database it is switched to.
+  
+     The panel is built entirely from state — which connection it names, which
+     dialect, whether "Run as write…" is offered, and which draft is in the
+     box — and it was built once. Left open across a switch it kept the head
+     it started with: it went on naming the previous database while the
+     statement it ran went to the new one, and it kept offering a write on a
+     connection the server would refuse. `paint()` already replaces an
+     existing panel, so following the switch is one call. */
+  whenConnectionChanges(() => {
+    if (panel) paint();
+  });
+
+  addMenuItem({
+    label: 'SQL…',
+    detail: 'write a statement (⌘⇧↵)',
+    onSelect: () => openSql(),
+  });
+
+  document.addEventListener('keydown', (e) => {
+    if (e.key !== 'Enter' || !(e.metaKey || e.ctrlKey) || !e.shiftKey) return;
+    e.preventDefault();
+    openSql();
+  }, true);
+}