tablewalk 0.0.1

package/dist/client/history.js

@@ -0,0 +1,222 @@
+/**
+ * Query history: the last 50 queries that ran, per connection.
+ *
+ * Two things shape this file.
+ *
+ * The first is that history is a convenience, never a dependency. Every
+ * `localStorage` call is wrapped, because the API throws rather than returning
+ * null in three ordinary situations — Safari's private mode, a browser set to
+ * block site data, and a full quota — and a database browser that fails to
+ * paint because it could not remember what you typed is worse than one that
+ * never offered to. When storage refuses, the list falls back to memory and
+ * works until the tab is closed.
+ *
+ * The second is that history is per connection. The stored value is keyed by
+ * `state.activeConnection`, so switching from staging to production does not
+ * offer you queries against tables the new database may not even have.
+ */
+import { $, el, loadJson, saveJson, state, toast } from './core.js';
+
+const KEY = 'tablewalk.history.v1';
+
+/* Enough to cover a session's worth of exploration, small enough that the
+   whole record stays well inside a quota even with long queries. */
+const MAX_ENTRIES = 50;
+
+/** The whole record: `{ [connectionId]: [{ q, at }] }`. Never throws. */
+function readAll() {
+  const parsed = loadJson(KEY, {});
+  // Anything could be under this key — an older shape, or another tool's.
+  // Refusing to trust it is cheaper than defending every read site.
+  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+}
+
+/* The in-memory mirror, and the reason a failed write is not a failed feature:
+   the dropdown reads from here, so history keeps working for the session even
+   when nothing can be persisted. */
+const cache = new Map();
+
+const scope = () => state.activeConnection ?? 'default';
+
+/** The history for the connection in use, newest first. */
+export function historyFor(connection = scope()) {
+  if (!cache.has(connection)) {
+    const stored = readAll()[connection];
+    cache.set(connection, Array.isArray(stored) ? stored.filter((e) => e && typeof e.q === 'string') : []);
+  }
+  return cache.get(connection);
+}
+
+/**
+ * Remember a query that ran.
+ *
+ * Re-running something moves it to the top instead of adding a second copy:
+ * the list is meant to answer "what have I been looking at", and twelve
+ * identical rows of `customer` push the query you actually want off the end.
+ */
+export function recordQuery(text) {
+  const q = String(text ?? '').trim();
+  if (!q) return;
+  const connection = scope();
+  const kept = historyFor(connection).filter((entry) => entry.q !== q);
+  kept.unshift({ q, at: Date.now() });
+  kept.length = Math.min(kept.length, MAX_ENTRIES);
+  cache.set(connection, kept);
+
+  const all = readAll();
+  all[connection] = kept;
+  // Best effort: saveJson swallows a full or unavailable localStorage, and
+  // the in-memory copy above keeps the list working for the session either way.
+  saveJson(KEY, all);
+  cursor = -1;
+  draft = null;
+  if (panel && !panel.hidden) fillPanel();
+}
+
+function clearHistory() {
+  const connection = scope();
+  cache.set(connection, []);
+  const all = readAll();
+  delete all[connection];
+  saveJson(KEY, all);
+  fillPanel();
+  toast('Query history cleared.');
+}
+
+/* ---------- the control ---------- */
+
+let panel = null;
+let toggle = null;
+let installed = false;
+
+/* Where in the list the ↑/↓ walk currently is: -1 means "on what you typed",
+   and `draft` holds that text so walking back down returns it rather than
+   leaving the last history entry in the box. */
+let cursor = -1;
+let draft = null;
+
+function ago(at) {
+  const seconds = Math.max(0, Math.round((Date.now() - at) / 1000));
+  if (seconds < 60) return 'just now';
+  if (seconds < 3600) return `${Math.round(seconds / 60)}m ago`;
+  if (seconds < 86400) return `${Math.round(seconds / 3600)}h ago`;
+  return `${Math.round(seconds / 86400)}d ago`;
+}
+
+function fillPanel() {
+  const entries = historyFor();
+  panel.replaceChildren();
+  if (!entries.length) {
+    panel.append(el('p', {
+      class: 'history-empty',
+      text: 'Nothing yet. Queries appear here once they run.',
+    }));
+    return;
+  }
+  const list = el('ul', { class: 'history-list' });
+  for (const entry of entries) {
+    list.append(el('li', {}, el('button', {
+      type: 'button',
+      class: 'history-item',
+      onclick: () => runEntry(entry.q),
+    }, [
+      el('span', { class: 'history-q', text: entry.q }),
+      el('span', { class: 'history-age', text: ago(entry.at ?? Date.now()) }),
+    ])));
+  }
+  panel.append(list, el('button', {
+    type: 'button',
+    class: 'history-clear',
+    text: `Clear ${entries.length} ${entries.length === 1 ? 'query' : 'queries'}`,
+    onclick: clearHistory,
+  }));
+}
+
+function runEntry(q) {
+  const input = $('query');
+  input.value = q;
+  setOpen(false);
+  cursor = -1;
+  draft = null;
+  /* `requestSubmit` rather than `submit`: it fires the form's submit event, so
+     the one handler in app.js decides what a query means. `submit()` would
+     skip it and reload the page. */
+  $('querybar').requestSubmit();
+}
+
+function setOpen(open) {
+  panel.hidden = !open;
+  toggle.setAttribute('aria-expanded', String(open));
+  if (open) fillPanel();
+}
+
+/** Step through the list in the input itself, without opening the panel. */
+function step(direction) {
+  const entries = historyFor();
+  if (!entries.length) return;
+  const input = $('query');
+  if (cursor === -1) draft = input.value;
+  const next = Math.min(Math.max(cursor + direction, -1), entries.length - 1);
+  cursor = next;
+  input.value = next === -1 ? (draft ?? '') : entries[next].q;
+  // Caret to the end, or the browser leaves it where it was and the next
+  // keystroke lands in the middle of the recalled query.
+  input.setSelectionRange(input.value.length, input.value.length);
+}
+
+/**
+ * Attached on import rather than from a boot function.
+ *
+ * app.js wires the chrome, and this feature deliberately adds no line to it:
+ * importing the module is enough to get the control, which keeps the query bar
+ * working the same whether or not history is compiled in.
+ */
+export function initHistory() {
+  if (installed) return;
+  const bar = $('querybar');
+  const input = $('query');
+  if (!bar || !input) return;
+  installed = true;
+
+  /* No button in the header any more.
+
+     Recent queries are reached two better ways: Ctrl/Cmd+↑ in the query bar,
+     which is where your hands already are, and ⌘K, which searches them
+     alongside everything else. A permanent button for a list you open once a
+     session was the most expensive way to offer it. */
+  toggle = el('button', { type: 'button', class: 'ghost history-toggle', hidden: true });
+  panel = el('div', { class: 'history-panel', hidden: true });
+  bar.append(panel);
+
+  input.addEventListener('keydown', (e) => {
+    // Ctrl/Cmd rather than a bare arrow: the query bar is a text field, and
+    // stealing plain ↑/↓ would break moving the caret in a long query.
+    if ((e.metaKey || e.ctrlKey) && (e.key === 'ArrowUp' || e.key === 'ArrowDown')) {
+      e.preventDefault();
+      step(e.key === 'ArrowUp' ? 1 : -1);
+      return;
+    }
+    if (e.key === 'Escape' && !panel.hidden) {
+      e.stopPropagation();
+      setOpen(false);
+    }
+  });
+
+  // Typing means you have left the recalled entry and are writing your own.
+  input.addEventListener('input', () => {
+    cursor = -1;
+    draft = null;
+  });
+
+  /* Closed by a click anywhere else, which is what a menu is expected to do —
+     on pointerdown so it happens before the click lands on whatever is behind. */
+  document.addEventListener('pointerdown', (e) => {
+    if (!panel.hidden && !panel.contains(e.target) && e.target !== toggle) setOpen(false);
+  });
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', initHistory, { once: true });
+} else {
+  initHistory();
+}

package/dist/client/index.html

@@ -0,0 +1,116 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>tablewalk</title>
+    <link rel="stylesheet" href="/style.css" />
+    <link rel="stylesheet" href="/features.css" />
+    <link rel="stylesheet" href="/composer.css" />
+    <link rel="stylesheet" href="/sql.css" />
+    <link rel="stylesheet" href="/help.css" />
+    <link rel="stylesheet" href="/page.css" />
+    <link
+      rel="icon"
+      href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><text y='13' font-size='13'>&#128279;</text></svg>"
+    />
+  </head>
+  <body>
+    <header class="topbar">
+      <button type="button" class="brand" id="home-button" title="Back to the schema (h)">
+        <span class="brand-mark"></span>
+        <span class="brand-name">tablewalk</span>
+      </button>
+      <!-- The name of the connection is also the way in to managing them.
+           The sidebar has a gear beside the picker, but the sidebar collapses,
+           and "which database am I on" is the one question the top bar answers
+           at all times. Clicking the answer is the obvious gesture. -->
+      <button
+        type="button"
+        class="brand-db"
+        id="db-label"
+        title="Connections…"
+        aria-label="Connections"
+      ></button>
+      <!-- Which database, and the way to a different one, in the chrome that
+           is always on screen. It lived in the sidebar, which collapses, and
+           which is otherwise entirely about the tables *within* one database
+           — the wrong altitude for the control that chooses between them. -->
+      <div class="conn-picker" id="conn-picker"></div>
+      <form class="querybar" id="querybar" autocomplete="off">
+        <input
+          id="query"
+          type="text"
+          spellcheck="false"
+          placeholder="customer active = true sort name limit 20"
+          aria-label="Query"
+        />
+        <button type="submit">Run</button>
+      </form>
+      <div class="topbar-actions">
+        <button
+          type="button"
+          id="sql-toggle"
+          class="icon-button"
+          aria-pressed="false"
+          title="Show the SQL under the query bar"
+          aria-label="Show the SQL"
+        >
+          SQL
+        </button>
+        <button
+          type="button"
+          id="search-button"
+          class="icon-button"
+          title="Go to a table, view or database (⌘K)"
+          aria-label="Search"
+        >
+          <span aria-hidden="true">⌘K</span>
+        </button>
+        <button
+          type="button"
+          id="more-button"
+          class="icon-button"
+          title="More"
+          aria-label="More"
+          aria-haspopup="menu"
+          aria-expanded="false"
+        >
+          <span aria-hidden="true">···</span>
+        </button>
+        <button type="button" id="write-toggle" class="mode" aria-pressed="false">Read only</button>
+      </div>
+    </header>
+
+    <div class="explain-pane" id="explain-pane" hidden>
+      <pre class="explain" id="explain"></pre>
+      <button
+        type="button"
+        id="explain-edit"
+        class="explain-edit"
+        title="Open this statement in the SQL editor"
+        aria-label="Edit this statement and run it"
+      >Edit</button>
+    </div>
+    <div class="errors" id="errors" hidden></div>
+    <div class="toast" id="toast" role="status" hidden></div>
+
+    <main class="layout">
+      <nav class="sidebar" aria-label="Tables">
+        <input id="table-filter" type="search" placeholder="Filter tables…" aria-label="Filter tables" />
+        <ul id="table-list"></ul>
+      </nav>
+
+      <section class="content" id="content">
+        <div class="empty" id="empty">
+          <h1>Walk the database, don't list it.</h1>
+          <p>
+            Pick a table on the left, or type a query above. Click any row to open it, and
+            tablewalk will show you every row elsewhere that points at it.
+          </p>
+        </div>
+      </section>
+    </main>
+  </body>
+  <script type="module" src="/app.js"></script>
+</html>

package/dist/client/insert.js

@@ -0,0 +1,151 @@
+/**
+ * Adding a row, in a form the schema wrote.
+ *
+ * Nobody declares a form for this: the columns, their types, what is
+ * required and what the database will fill are all in the catalog already.
+ * Required is NOT NULL with no default and no auto-assigned key; everything
+ * else is optional, and an empty box means "leave it to the database" — its
+ * defaults are part of the schema's design and pre-filling them here would
+ * turn every default into a value somebody appears to have chosen.
+ *
+ * What this form deliberately is not: a validator. It marks what the
+ * catalog says and sends what was typed; a UNIQUE violation or a bad
+ * reference comes back in the database's own words, which name the
+ * constraint better than a paraphrase would.
+ */
+import { api, columnKind, el, go, rowLabel, rowView, state, toast } from './core.js';
+import { canDelete } from './delete.js';
+
+/** The same gate every write affordance uses: writable, write mode, a table. */
+export const canInsert = canDelete;
+
+export function newRowButton(table) {
+  if (!canInsert(table)) return null;
+  return el('button', {
+    type: 'button',
+    class: 'ghost table-new-row',
+    title: `Add a ${table.name} row`,
+    text: '+ New row',
+    onclick: () => openInsert(table),
+  });
+}
+
+/** A single INTEGER primary key is the database's to assign. */
+function autoKey(table) {
+  const pk = table.columns.filter((c) => c.primaryKey);
+  return pk.length === 1 && /int/i.test(pk[0].type) ? pk[0].name : null;
+}
+
+function openInsert(table) {
+  const assigned = autoKey(table);
+  const inputs = new Map();
+  const problem = el('p', { class: 'insert-problem', hidden: true });
+
+  const field = (column) => {
+    const required = !column.nullable && column.default === undefined && column.name !== assigned;
+    const hint = column.name === assigned
+      ? 'assigned by the database'
+      : column.default !== undefined
+        ? `default: ${column.default}`
+        : column.references
+          ? `→ ${column.references.table}`
+          : '';
+
+    /* A select for booleans — three states, none of them typed — and a text
+       box for everything else. Numbers and dates arrive as text and are
+       coerced against the declared type on the server, exactly as edits are. */
+    let input;
+    if (column.allowed?.length) {
+      /* The database already said what this column may hold, so typing it is
+         a chance to get it wrong for nothing. Still a free-text-shaped
+         "leave it" option, because an empty box means "the database
+         decides" here as everywhere else on this form. */
+      input = el('select', { class: 'insert-input', 'aria-label': `${column.name} (one of ${column.allowed.join(', ')})` }, [
+        el('option', { value: '', text: hint || '—' }),
+        ...column.allowed.map((value) => el('option', { value, text: value })),
+      ]);
+    } else if (columnKind(column.type) === 'boolean') {
+      input = el('select', { class: 'insert-input', 'aria-label': `${column.name} (${column.type})` }, [
+        el('option', { value: '', text: hint || '—' }),
+        el('option', { value: '1', text: 'yes' }),
+        el('option', { value: '0', text: 'no' }),
+      ]);
+    } else {
+      input = el('input', {
+        type: 'text',
+        class: 'insert-input',
+        placeholder: hint,
+        'aria-label': `${column.name} (${column.type})`,
+        autocomplete: 'off',
+        spellcheck: 'false',
+      });
+    }
+    inputs.set(column.name, input);
+
+    return el('div', { class: 'insert-field' }, [
+      el('label', {}, [
+        document.createTextNode(column.name),
+        el('span', { class: 'type', text: column.type.toLowerCase() }),
+        column.primaryKey ? el('span', { class: 'pk', text: 'key' }) : null,
+        required ? el('span', { class: 'req', title: 'NOT NULL with no default', text: 'required' }) : null,
+      ].filter(Boolean)),
+      input,
+    ]);
+  };
+
+  const save = async () => {
+    /* Only what was typed. An empty box is not the empty string — it is
+       "the database decides", which is what makes defaults and the
+       auto-assigned key work without this form knowing how to compute
+       either. */
+    const values = {};
+    for (const [name, input] of inputs) {
+      if (input.value !== '') values[name] = input.value;
+    }
+
+    let result;
+    try {
+      result = await api('/api/insert', { table: table.id, values });
+    } catch (err) {
+      problem.textContent = err.message;
+      problem.hidden = false;
+      return;
+    }
+    if (result.errors?.length) {
+      problem.textContent = result.errors[0].message;
+      problem.hidden = false;
+      return;
+    }
+
+    dialog.close();
+    const label = result.row ? rowLabel(table, result.row) : Object.values(result.key).join('/');
+    toast(`Added ${table.name} · ${label}`, 'ok');
+    /* Straight to the new record: the form's answer is the row the database
+       stored — defaults filled, key assigned — and the record page is where
+       that answer is legible. */
+    go(rowView(table.id, result.key, label), 'push');
+  };
+
+  const dialog = el('dialog', { class: 'confirm insert-dialog' }, [
+    el('h2', { text: `New ${table.name}` }),
+    el('p', {
+      class: 'insert-lede',
+      text: 'Empty fields are left to the database — defaults apply, keys are assigned.',
+    }),
+    el('div', { class: 'insert-fields' }, table.columns.map(field)),
+    problem,
+    el('div', { class: 'confirm-actions' }, [
+      el('button', { type: 'button', class: 'ghost', text: 'Cancel', onclick: () => dialog.close() }),
+      el('button', { type: 'button', class: 'primary', text: 'Add row', onclick: () => void save() }),
+    ]),
+  ]);
+
+  dialog.addEventListener('close', () => dialog.remove());
+  document.body.append(dialog);
+  dialog.showModal();
+  /* The first box someone has to fill, not the first box. */
+  const firstRequired = table.columns.find(
+    (c) => !c.nullable && c.default === undefined && c.name !== assigned,
+  );
+  (inputs.get(firstRequired?.name) ?? inputs.values().next().value)?.focus();
+}

package/dist/client/menu.js

@@ -0,0 +1,160 @@
+/**
+ * The overflow menu, and the registry behind it.
+ *
+ * The toolbar had six buttons of equal weight — Run, SQL, Recent, Schema,
+ * Views, Read only — which is six things with no order of importance between
+ * them. Two of them were duplicates of something else (Schema is what the
+ * wordmark already does; Recent is what ⌘K now covers), one is a mode rather
+ * than an action, and one is the primary action. Flattening all of that into
+ * a row of identical outlined rectangles makes the reader read every label
+ * every time to find the one they want.
+ *
+ * So: `Run` stays attached to the field it runs, the mode sits apart at the
+ * far end because it is a state and not a verb, and everything else lives
+ * behind one button. The registry exists so a module can add its own item
+ * without reaching into the header — the composer adds "Views…" the same way
+ * the app adds "Show SQL", and neither needs to know the other exists.
+ */
+import { $, el } from './core.js';
+
+/** @type {Array<{label: string, onSelect: () => void, checked?: () => boolean, detail?: string, group?: string}>} */
+const items = [];
+
+/**
+ * Register a menu item. Order of registration is order of appearance.
+ *
+ * `checked` makes the item a toggle: it is read each time the menu opens, so
+ * an item reflects the current state rather than the state at registration.
+ */
+export function addMenuItem(item) {
+  items.push(item);
+}
+
+/**
+ * Replace every item in a group.
+ *
+ * Registration is a one-time act for the fixed commands, and wrong for the
+ * ones that come from data: the pages this connection has change when someone
+ * builds one, deletes one, or switches database. Adding them again would
+ * leave the old ones beside the new, and a page you deleted still listed in
+ * ⌘K is a command that opens nothing.
+ *
+ * By group rather than by id, because "these are the pages now" is the whole
+ * statement — anything previously in the group that is not in the list is
+ * gone, which is the part a per-item update cannot say.
+ */
+/**
+ * Who to tell when the registered commands change.
+ *
+ * The palette snapshots the commands when it opens, and a group registered
+ * a beat later — pages arriving from the server on a fresh load — was
+ * invisible until it was closed and reopened. Searching for a page you can
+ * see in the menu and being told nothing matches is the palette lying.
+ */
+const watchers = new Set();
+
+/** Register for command-list changes. Returns the way to stop listening. */
+export function whenMenuChanges(run) {
+  watchers.add(run);
+  return () => watchers.delete(run);
+}
+
+export function setMenuGroup(group, entries) {
+  for (let i = items.length - 1; i >= 0; i -= 1) {
+    if (items[i].group === group) items.splice(i, 1);
+  }
+  items.push(...entries.map((entry) => ({ ...entry, group })));
+  for (const run of [...watchers]) run();
+}
+
+/**
+ * Everything registered, for anywhere else that wants to offer it.
+ *
+ * The command palette lists these alongside tables, so an action is reachable
+ * by typing its name as well as by opening the menu — registered once, offered
+ * twice. Two lists of commands maintained separately is how a menu item ends
+ * up missing from search.
+ */
+export const menuItems = () => items;
+
+/** A menu item's detail, which may be a function of the moment. */
+export const detailOf = (item) =>
+  (typeof item.detail === 'function' ? item.detail() : item.detail);
+
+let list = null;
+
+function close() {
+  if (!list || list.hidden) return;
+  list.hidden = true;
+  $('more-button')?.setAttribute('aria-expanded', 'false');
+  document.removeEventListener('pointerdown', onOutside, true);
+  document.removeEventListener('keydown', onKey, true);
+  window.removeEventListener('scroll', close, true);
+  window.removeEventListener('resize', close);
+}
+
+function onOutside(e) {
+  if (!list.contains(e.target) && e.target !== $('more-button')) close();
+}
+
+function onKey(e) {
+  if (e.key === 'Escape') {
+    // Stopped as well: see the palette. An open menu owns the key.
+    e.preventDefault();
+    e.stopPropagation();
+    close();
+    $('more-button')?.focus();
+  }
+}
+
+function open() {
+  const button = $('more-button');
+  list.replaceChildren(...items.map((item, i) => {
+    const checked = item.checked?.() ?? null;
+    return el('div', {
+      class: `more-item${checked ? ' checked' : ''}`,
+      role: checked === null ? 'menuitem' : 'menuitemcheckbox',
+      'aria-checked': checked === null ? undefined : String(checked),
+      tabindex: -1,
+      onclick: () => { close(); item.onSelect(); },
+      onkeydown: (e) => {
+        if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); close(); item.onSelect(); }
+        if (e.key === 'ArrowDown') { e.preventDefault(); list.children[i + 1]?.focus(); }
+        if (e.key === 'ArrowUp') { e.preventDefault(); list.children[i - 1]?.focus(); }
+      },
+    }, [
+      // A tick column, always present, so labels line up whether or not the
+      // item is a toggle.
+      el('span', { class: 'more-tick', 'aria-hidden': 'true', text: checked ? '✓' : '' }),
+      el('span', { class: 'more-label', text: item.label }),
+      /* Read when the menu opens, not when the item was registered, so a
+         detail that describes current state — "credit_limit on customer 4" —
+         is the state now rather than the state at boot. */
+      detailOf(item) ? el('span', { class: 'more-detail', text: detailOf(item) }) : null,
+    ].filter(Boolean));
+  }));
+
+  list.hidden = false;
+  button.setAttribute('aria-expanded', 'true');
+
+  // Fixed to the viewport, like every other menu here, so a scrolling
+  // ancestor cannot clip it.
+  const box = button.getBoundingClientRect();
+  list.style.position = 'fixed';
+  list.style.top = `${box.bottom + 6}px`;
+  list.style.right = `${Math.max(8, window.innerWidth - box.right)}px`;
+
+  list.children[0]?.focus();
+  document.addEventListener('pointerdown', onOutside, true);
+  document.addEventListener('keydown', onKey, true);
+  window.addEventListener('scroll', close, true);
+  window.addEventListener('resize', close);
+}
+
+export function initMenu() {
+  const button = $('more-button');
+  if (!button) return;
+  list = el('div', { class: 'more-list', role: 'menu', hidden: true });
+  document.body.append(list);
+  button.addEventListener('click', () => (list.hidden ? open() : close()));
+}