tablewalk 0.0.1

package/dist/client/grid.js

@@ -0,0 +1,205 @@
+/**
+ * Moving around a result without a mouse.
+ *
+ * A table of rows you can only click is a table you have to keep leaving the
+ * keyboard for. The query bar, the sidebar and the palette are all reachable
+ * by key; the grid the whole tool exists to show was the one surface that was
+ * not, so reading a wide result meant typing, then reaching for the mouse,
+ * then typing again.
+ *
+ * Arrow keys move a cell cursor, Enter opens the row's record — which is the
+ * walk, done from the keyboard. Everything else here follows from those two
+ * and from the grid pattern people already know from a spreadsheet.
+ *
+ * The position is held as `(row, column)` **indices, not elements**. Above a
+ * few hundred rows the table is virtualised and the `<tr>` under the cursor is
+ * destroyed the moment it scrolls out of the window, so a reference to it is a
+ * reference to a node that will be thrown away. Indices survive that; the
+ * element is looked up again on every move, and when the row has not been
+ * painted yet the scroller is moved and the lookup retried.
+ */
+/** Rows moved by PageUp/PageDown when the viewport cannot be measured. */
+const PAGE_FALLBACK = 20;
+
+/** How many frames to wait for the virtualiser to paint a row we scrolled to. */
+const PAINT_TRIES = 4;
+
+/**
+ * @param {HTMLElement} wrap        the element holding the table
+ * @param {object} options
+ * @param {HTMLTableSectionElement} options.tbody
+ * @param {number} options.rowCount    logical rows, not painted ones
+ * @param {number} options.columnCount data columns
+ * @param {number} options.offset      leading cells before the first data column
+ * @param {(index: number) => void} [options.onOpen]  Enter on a row
+ */
+export function initGrid(wrap, { tbody, rowCount, columnCount, offset = 0, onOpen, totalRows, firstRow = 0 }) {
+  if (!rowCount || !columnCount) return;
+
+  const table = wrap.querySelector('table');
+  if (!table) return;
+  table.setAttribute('role', 'grid');
+
+  /* How much there is, and where in it this page sits.
+  
+     Without these a screen reader announces "row 3 of 20" on a table of
+     63,010 — it can only count the rows in the DOM, and a paged grid puts
+     twenty of them there. The visual reader has "20 of 63,010 rows" in the
+     header; this is the same sentence for everyone else. `aria-rowindex` on
+     each row is what makes the count mean anything: it says which twenty. */
+  table.setAttribute('aria-colcount', String(columnCount + offset));
+  if (typeof totalRows === 'number') {
+    table.setAttribute('aria-rowcount', String(totalRows));
+    /* Every row carries its index, including on the first page. A count with
+       no indexes to anchor it is worse than neither: the reader is told there
+       are sixty-three thousand rows and given no way to know which of them
+       these twenty are. Header first — `aria-rowindex` is 1-based across the
+       whole grid, and the header is row 1 of it. */
+    table.querySelector('thead tr')?.setAttribute('aria-rowindex', '1');
+    for (let i = 0; i < rowCount; i += 1) {
+      tbody.querySelector(`tr[data-row="${i}"]`)?.setAttribute('aria-rowindex', String(firstRow + i + 2));
+    }
+  }
+
+  let row = -1;
+  let col = 0;
+
+  const scrollerOf = () => wrap.closest('.content') ?? document.scrollingElement;
+  const rowAt = (i) => tbody.querySelector(`tr[data-row="${i}"]`);
+  const cellAt = (i, c) => rowAt(i)?.children[c + offset] ?? null;
+
+  /** Rows that fit on screen, for PageUp and PageDown. */
+  const pageSize = () => {
+    const sample = tbody.querySelector('tr[data-row]');
+    const height = sample?.getBoundingClientRect().height;
+    const view = scrollerOf()?.clientHeight;
+    if (!height || !view) return PAGE_FALLBACK;
+    return Math.max(1, Math.floor(view / height) - 1);
+  };
+
+  /**
+   * Put the cursor on a cell, painting the row first if it does not exist.
+   *
+   * The retry is what makes this work on a virtualised table: scrolling
+   * schedules a repaint rather than performing one, so the row asked for is
+   * not in the DOM on the line after the scroll. Rather than guess at a delay,
+   * it looks again on the next frame, a few times, and gives up quietly — a
+   * cursor that does not move is better than one that throws.
+   */
+  const focusCell = (tries = PAINT_TRIES) => {
+    const cell = cellAt(row, col);
+    if (!cell) {
+      if (tries <= 0) return;
+      const sample = tbody.querySelector('tr[data-row]');
+      const height = sample?.getBoundingClientRect().height ?? 0;
+      const scroller = scrollerOf();
+      if (scroller && height) {
+        scroller.scrollTop = Math.max(0, row * height - scroller.clientHeight / 2);
+      }
+      requestAnimationFrame(() => focusCell(tries - 1));
+      return;
+    }
+    for (const stale of tbody.querySelectorAll('.cell-cursor')) {
+      stale.classList.remove('cell-cursor');
+      stale.removeAttribute('tabindex');
+    }
+    cell.classList.add('cell-cursor');
+    cell.tabIndex = 0;
+    /* The grid's tab stop moves to the cell, so tabbing in returns to where
+       the cursor was left rather than to the top-left corner — and the table
+       and the cell are never both stops, which would make Tab pass through
+       the same grid twice. */
+    table.tabIndex = -1;
+    cell.focus({ preventScroll: true });
+    /* `nearest` rather than `center`: the cursor usually moves one row, and
+       re-centring the table on every arrow press turns a walk down a column
+       into the page jumping under you. */
+    cell.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+  };
+
+  const moveTo = (nextRow, nextCol) => {
+    row = Math.max(0, Math.min(rowCount - 1, nextRow));
+    col = Math.max(0, Math.min(columnCount - 1, nextCol));
+    focusCell();
+  };
+
+  /* Reachable by Tab.
+  
+     One stop for the whole grid, not one per cell: a table of twenty rows and
+     eight columns is a hundred and sixty tab stops between the query bar and
+     whatever is after it, which is not navigation, it is a wall. */
+  table.tabIndex = 0;
+  table.addEventListener('focus', (e) => {
+    if (e.target !== table) return;
+    moveTo(row < 0 ? 0 : row, col);
+  });
+
+  // A click is also a way of saying where the cursor is, so the keyboard and
+  // the mouse do not disagree about where you are.
+  tbody.addEventListener('mousedown', (e) => {
+    const cell = e.target.closest('td');
+    const tr = cell?.closest('tr[data-row]');
+    if (!cell || !tr) return;
+    row = Number(tr.dataset.row);
+    col = Math.max(0, [...tr.children].indexOf(cell) - offset);
+  });
+
+  table.addEventListener('keydown', (e) => {
+    if (e.target.closest('input, textarea, select, [contenteditable]')) return;
+    if (e.altKey) return;
+
+    const jump = e.metaKey || e.ctrlKey;
+    switch (e.key) {
+      case 'ArrowDown': moveTo(jump ? rowCount - 1 : row + 1, col); break;
+      case 'ArrowUp': moveTo(jump ? 0 : row - 1, col); break;
+      case 'ArrowRight': moveTo(row, jump ? columnCount - 1 : col + 1); break;
+      case 'ArrowLeft': moveTo(row, jump ? 0 : col - 1); break;
+      case 'Home': moveTo(jump ? 0 : row, 0); break;
+      case 'End': moveTo(jump ? rowCount - 1 : row, columnCount - 1); break;
+      case 'PageDown': moveTo(row + pageSize(), col); break;
+      case 'PageUp': moveTo(row - pageSize(), col); break;
+      case 'Enter':
+        if (row >= 0 && onOpen) onOpen(row);
+        break;
+      case 'Escape':
+        /* Back to the query bar rather than nowhere. Escape from a grid means
+           "I am done here", and the thing you do next is nearly always type. */
+        table.blur();
+        document.getElementById('query')?.focus();
+        break;
+      case 'c':
+        if (!jump) return;
+        // The cell under the cursor, not the row: someone pressing ⌘C on a
+        // reference id wants that id.
+        void copyCell(cellAt(row, col));
+        break;
+      default:
+        return;
+    }
+    e.preventDefault();
+  });
+}
+
+/**
+ * Copy one cell.
+ *
+ * `title` before `textContent`, because a value the table shortened shows an
+ * ellipsis and keeps the whole thing in its tooltip — copying what is drawn
+ * would hand back a truncated value that looks complete.
+ */
+async function copyCell(cell) {
+  if (!cell) return;
+  const text = cell.getAttribute('title') ?? cell.textContent ?? '';
+  try {
+    await navigator.clipboard.writeText(text);
+    flash(cell);
+  } catch {
+    /* Clipboard access can be refused, and there is nothing useful to say
+       about it: the value is on screen and can be selected by hand. */
+  }
+}
+
+function flash(cell) {
+  cell.classList.add('cell-copied');
+  setTimeout(() => cell.classList.remove('cell-copied'), 400);
+}

package/dist/client/handoff.js

@@ -0,0 +1,153 @@
+/**
+ * Hand the walk to an agent.
+ *
+ * The MCP server is the agent→database half of this tool. This is the other
+ * half: a person walks to something interesting — three joins deep, a filter
+ * they arrived at by clicking — and now wants an agent to carry on from
+ * exactly there. Retyping the position into a chat window is where that
+ * hand-off usually dies, because the query is the easy part and the shape,
+ * the connection and the keys are the parts people leave out.
+ *
+ * What it writes is deliberately not the rows. The rows are on screen and
+ * the person can copy them; pasting them into a chat window sends them
+ * somewhere, and that should stay a decision rather than a side effect of
+ * clicking "copy". What it writes is everything an agent needs to fetch the
+ * rows itself, against the same connection, with the same question.
+ */
+
+/** `name → type` with the markers the rest of the tool uses for keys and references. */
+function columnLine(column) {
+  const parts = [column.name];
+  if (column.type) parts.push(column.type);
+  if (column.primaryKey) parts.push('key');
+  if (column.nullable === false && !column.primaryKey) parts.push('not null');
+  if (column.references) parts.push(`→ ${column.references.table}.${column.references.column}`);
+  return `- ${parts.join(' · ')}`;
+}
+
+/**
+ * The walk position as markdown, ready to paste into an agent.
+ *
+ * Pure so it can be pinned without a browser — the failure this feature has
+ * is silently omitting a field, and the only way to see that is to read the
+ * whole document a test wrote.
+ */
+export function agentContext(position) {
+  const { connection, dialect, table, query, columns = [], shown, total, meta, trail = [], record } = position;
+  const lines = [];
+
+  lines.push(`# ${table} — a position in tablewalk`);
+  lines.push('');
+  lines.push(`Connection \`${connection ?? 'default'}\`${dialect ? ` (${dialect})` : ''}.`);
+  lines.push('');
+
+  if (record) {
+    lines.push(`One row of \`${table}\`: **${record.label}**`);
+    lines.push('');
+    lines.push('```json');
+    lines.push(JSON.stringify(record.key));
+    lines.push('```');
+    lines.push('');
+  } else {
+    lines.push('The question on screen is:');
+    lines.push('');
+    lines.push('```');
+    lines.push(query);
+    lines.push('```');
+    lines.push('');
+  }
+
+  if (!record && typeof shown === 'number') {
+    const of = typeof total === 'number' && total > shown
+      ? ` of ${total.toLocaleString()} matching`
+      : '';
+    lines.push(`Showing ${shown.toLocaleString()} row${shown === 1 ? '' : 's'}${of}.`);
+    lines.push('');
+  }
+
+  /* The columns the *query* returned, not the whole table: a projection is
+     part of the position, and an agent handed the full table would widen the
+     question without being told it had. */
+  if (!record && columns.length) {
+    lines.push(`Columns on screen: ${columns.join(', ')}`);
+    lines.push('');
+  }
+
+  if (meta?.columns?.length) {
+    lines.push(`## ${meta.id ?? table}`);
+    lines.push('');
+    for (const column of meta.columns) lines.push(columnLine(column));
+    lines.push('');
+  }
+
+  /* How they got here. A filter arrived at by three clicks reads as one
+     opaque `where` clause, and the trail is what makes it a story again. */
+  if (trail.length > 1) {
+    lines.push('## The walk');
+    lines.push('');
+    for (const step of trail) lines.push(`- ${step}`);
+    lines.push('');
+  }
+
+  lines.push('## Carry on from here');
+  lines.push('');
+  lines.push(`This database is available over MCP as \`tablewalk\`. ${
+    record ? 'To read this row and everything pointing at it:' : 'To see the same rows:'
+  }`);
+  lines.push('');
+  lines.push('```json');
+  lines.push(JSON.stringify(
+    record
+      ? { name: 'record', arguments: { connection: connection ?? undefined, table, key: record.key } }
+      : { name: 'query', arguments: { connection: connection ?? undefined, q: query, limit: shown ?? 20 } },
+    null,
+    2,
+  ));
+  lines.push('```');
+  lines.push('');
+  lines.push(
+    '`table` describes a table, `find` says where a name or a value lives, and '
+    + '`query` runs the same language as the box above. The values themselves are '
+    + 'not included here — fetch them if you need them.',
+  );
+
+  return lines.join('\n');
+}
+
+/**
+ * Everything the current walk knows about where it is.
+ *
+ * Reads `state` rather than taking it apart at each call site, because the
+ * two callers — a result and a record — differ in one field and agreeing on
+ * the other seven by hand is how they drift.
+ */
+export function positionOf(state, entry, extra = {}) {
+  const meta = state.schema?.tables?.find((t) => t.id === entry.table) ?? null;
+  return {
+    connection: state.activeConnection ?? state.schema?.label ?? null,
+    dialect: state.schema?.dialect ?? null,
+    table: entry.table,
+    query: entry.query ?? entry.table,
+    meta,
+    /* The trail as it reads in the breadcrumb: the query for a result, the
+       row's name for a record. */
+    trail: (state.stack ?? []).map((step) => (step.kind === 'table' ? step.query : step.label)),
+    ...extra,
+  };
+}
+
+/**
+ * Copy a position, and say so.
+ *
+ * The clipboard can be refused — an insecure origin, a permission denied —
+ * and a button that silently does nothing is worse than one that says it
+ * could not. The text is not shown as a fallback because it is a page long.
+ */
+export async function copyPosition(position, toast) {
+  try {
+    await navigator.clipboard.writeText(agentContext(position));
+    toast('Position copied — paste it into an agent.', 'info');
+  } catch {
+    toast('The browser refused clipboard access, so nothing was copied.', 'error');
+  }
+}

package/dist/client/help.css

@@ -0,0 +1,145 @@
+/* The query reference: the panel behind `?`, and the runnable examples on the
+   landing page.
+
+   In its own file rather than style.css because it is a self-contained feature
+   and the stylesheet is already 1600 lines. Nothing here names a colour: every
+   value is one of the tokens defined at the top of style.css, so the panel
+   follows the dark scheme without a second set of rules to keep in step. */
+
+/* ---------- the landing page's examples ---------- */
+
+.landing-examples { margin-bottom: 26px; }
+.landing-examples-head {
+  display: flex; align-items: baseline; gap: 12px;
+  margin-bottom: 10px;
+}
+.landing-examples-head .landing-heading { margin: 0; }
+.help-more { font-size: 11.5px; padding: 3px 9px; }
+
+/* Wrapping columns rather than a row: three queries on a narrow window
+   otherwise shrink until the text they are teaching is ellipsised, which is
+   the one thing an example cannot survive. */
+.help-starters {
+  display: grid; gap: 8px;
+  grid-template-columns: repeat(auto-fit, minmax(19rem, 1fr));
+}
+
+/* ---------- an example, wherever it appears ---------- */
+
+/* A button that looks like a line of query text, because that is what it puts
+   in the bar. The border only firms up under the pointer: a page of examples
+   each in its own box reads as a form to fill in. */
+.help-example {
+  display: flex; flex-direction: column; align-items: flex-start; gap: 3px;
+  width: 100%; padding: 9px 11px; text-align: left; cursor: pointer;
+  background: var(--surface);
+  border: 1px solid var(--border); border-radius: 8px;
+  font: inherit; color: var(--text);
+  transition: border-color var(--t-hover) var(--ease-out),
+              background var(--t-hover) var(--ease-out);
+}
+.help-example:hover,
+.help-example:focus-visible {
+  border-color: var(--accent); background: var(--accent-soft); outline: none;
+}
+.help-query {
+  font: 12.5px/1.5 var(--mono); color: var(--text);
+  /* Long paths wrap instead of scrolling sideways: an example you have to
+     scroll to read is one you cannot decide to click. */
+  overflow-wrap: anywhere;
+}
+.help-example:hover .help-query,
+.help-example:focus-visible .help-query { color: var(--accent); }
+.help-caption { font-size: 11.5px; color: var(--text-dim); }
+
+/* ---------- the panel ---------- */
+
+.help-backdrop {
+  position: fixed; inset: 0; z-index: 60;
+  background: rgb(0 0 0 / 0.28);
+  display: flex; justify-content: center;
+  padding: 8vh 16px 16px;
+}
+.help-panel {
+  width: min(720px, 96vw); max-height: 84vh;
+  display: flex; flex-direction: column;
+  background: var(--surface);
+  border: 1px solid var(--border-strong);
+  border-radius: 10px;
+  box-shadow: 0 18px 60px rgb(0 0 0 / 0.28);
+  overflow: hidden;
+}
+@media (prefers-reduced-motion: no-preference) {
+  .help-panel {
+    animation: help-in var(--t-panel) var(--ease-out);
+  }
+  @keyframes help-in {
+    from { opacity: 0; transform: translateY(-6px); }
+  }
+}
+
+.help-head {
+  display: flex; align-items: flex-start; gap: 12px;
+  padding: 14px 16px; flex: none;
+  border-bottom: 1px solid var(--border);
+}
+.help-title { margin: 0; font: 600 15px var(--sans); letter-spacing: -0.01em; }
+.help-sub { margin: 3px 0 0; font-size: 12px; color: var(--text-dim); }
+.help-close {
+  margin-left: auto; flex: none;
+  padding: 2px 8px; line-height: 1.2;
+  background: none; border: 1px solid transparent; border-radius: 6px;
+  color: var(--text-faint); cursor: pointer; font: 16px var(--mono);
+}
+.help-close:hover, .help-close:focus-visible {
+  color: var(--accent); border-color: var(--border); outline: none;
+}
+
+.help-body { overflow-y: auto; padding: 4px 16px 16px; }
+
+.help-section { padding: 14px 0; border-bottom: 1px solid var(--border); }
+.help-section:last-child { border-bottom: none; }
+.help-section-title {
+  margin: 0 0 4px;
+  font: 600 10.5px var(--sans); text-transform: uppercase; letter-spacing: 0.07em;
+  color: var(--text-dim);
+}
+.help-note { margin: 0 0 10px; font-size: 12.5px; color: var(--text); max-width: 60ch; }
+
+/* Syntax on the left, what it means on the right. A two-column grid rather
+   than a table so a long form wraps under itself instead of squeezing the
+   meaning into a column an inch wide. */
+.help-grammar {
+  margin: 0 0 10px;
+  display: grid; grid-template-columns: minmax(9rem, auto) 1fr;
+  gap: 3px 14px; align-items: baseline;
+}
+.help-grammar > div { display: contents; }
+.help-grammar dt { margin: 0; }
+.help-grammar dt code {
+  font: 12px var(--mono); color: var(--accent);
+  background: var(--accent-soft); border-radius: 4px; padding: 1px 5px;
+}
+.help-grammar dd { margin: 0; font-size: 11.5px; color: var(--text-dim); }
+
+.help-examples { display: grid; gap: 6px; }
+.help-examples .help-example { background: var(--surface-2); }
+.help-examples .help-example:hover,
+.help-examples .help-example:focus-visible { background: var(--accent-soft); }
+
+.help-absent { margin: 0; font-size: 12px; color: var(--text-faint); }
+
+@media (max-width: 560px) {
+  .help-grammar { grid-template-columns: 1fr; gap: 1px; }
+  .help-grammar dd { margin-bottom: 6px; }
+}
+
+/* ---------- the examples, as the summary card's foot ---------- */
+
+/* Inside the shape card they are a continuation of it, not a section: the
+   heading and the margin that separated two stacked panels were pure cost
+   once there was only one panel. */
+.shape-body .landing-examples { margin: 12px 0 0; padding-top: 11px; border-top: 1px solid var(--border); }
+.shape-body .landing-examples-head { margin-bottom: 8px; }
+.shape-body .landing-heading { font: 10px var(--mono); text-transform: uppercase; letter-spacing: 0.06em; color: var(--text-faint); }
+.shape-body .help-example { padding: 7px 10px; }