tablewalk 0.0.1

package/dist/client/arrange.js

@@ -0,0 +1,254 @@
+/**
+ * Arranging a group of fields: which ones, and in what order.
+ *
+ * Two builders ask this question. The page builder asks it of a page section;
+ * the record layout builder asks it of a block on a record. They asked it in
+ * two different ways for months — the page builder with a draggable list, the
+ * record builder with a grid of checkboxes — and the difference was an
+ * accident of which was written second, not a decision anybody made. The
+ * checkbox grid answers "which fields" and cannot answer "in what order",
+ * which is half the question: fields fill their columns left to right, so the
+ * order *is* the layout.
+ *
+ * So this module owns the answer and both builders ask it. It knows nothing
+ * about pages or record templates — it is handed a list of candidates, the
+ * ones currently on, and a function to call when that changes. What the
+ * caller stores, and where, stays the caller's business: the page builder
+ * writes `undefined` when the arrangement is the table's own order, and the
+ * record builder always writes the list. Those are two different storage
+ * rules over one interaction, which is exactly the split worth having.
+ *
+ * The classes stay `pb-*`. They were named for the page builder because that
+ * is where this was written, and renaming them would churn a stylesheet and a
+ * browser suite to say something the file header already says.
+ */
+import { el } from './core.js';
+
+/**
+ * A field mid-drag, when one is: its name, the group it left, and how to take
+ * it out of that group.
+ *
+ * Module state because the drag starts inside one group's arranger and ends
+ * on another group's row — two closures that otherwise never speak. There is
+ * one pointer and one drag, so there is one of these.
+ */
+let carried = null;
+
+/** The field being dragged between groups, or null. */
+export const carriedField = () => carried;
+
+/** Drop the carried field into a group that is not the one it came from. */
+export function dropCarried(owner, receive, redraw) {
+  if (!carried || carried.owner === owner) return;
+  const drag = carried;
+  carried = null;
+  drag.take();
+  receive(drag.name);
+  redraw();
+}
+
+/**
+ * The arranger for one group.
+ *
+ * @param {object} spec
+ * @param {string[]} spec.all      every candidate, in the source's own order
+ * @param {string[]} spec.chosen   the ones on now, in the order they are laid out
+ * @param {number} [spec.columns]  how many columns the group draws in
+ * @param {(name: string) => string} [spec.label]   what to show on the row
+ * @param {(name: string) => string} [spec.typeOf]  the type, dimmed beside it
+ * @param {(next: string[]) => void} spec.onChange  called with the new list
+ * @param {object} spec.owner      identity of this group, for cross-group drags
+ * @param {Array<{title: string, receive: (name: string) => void}>} [spec.others]
+ *        the other groups a field can be sent to
+ * @param {() => void} [spec.onSend]  redraw everything after a hand-over
+ * @param {string} [spec.noun]     what a field is taken off — "page", "layout"
+ * @param {string|null} [spec.heading]  the panel's own label, or null where
+ *        whatever the arranger is inside already says what these are
+ */
+export function fieldArranger({
+  all,
+  chosen: initial,
+  columns = 1,
+  noun = 'layout',
+  heading = 'Fields',
+  label = (name) => name,
+  typeOf = () => '',
+  onChange,
+  owner,
+  others = [],
+  onSend,
+}) {
+  let chosen = [...initial];
+
+  const list = el('div', { class: 'pb-arrange' });
+  const pool = el('div', { class: 'pb-pool' });
+  const count = el('span', { class: 'pb-field-count' });
+
+  const commit = () => {
+    onChange([...chosen]);
+    count.textContent = `${chosen.length} of ${all.length} · drag to arrange`;
+  };
+
+  const move = (from, to) => {
+    if (to < 0 || to >= chosen.length || from === to) return;
+    const [item] = chosen.splice(from, 1);
+    chosen.splice(to, 0, item);
+    commit();
+    paintList({ focus: to });
+  };
+
+  let dragging = null;
+
+  function paintList({ focus = -1 } = {}) {
+    list.style.gridTemplateColumns = `repeat(${columns}, minmax(0, 1fr))`;
+    list.replaceChildren(...chosen.map((name, i) => {
+      const row = el('div', {
+        class: 'pb-arrange-row',
+        draggable: 'true',
+        tabindex: '0',
+        role: 'listitem',
+        'aria-label': `${name} — position ${i + 1} of ${chosen.length}`,
+        ondragstart: (e) => {
+          dragging = i;
+          /* Also offered to every other group's row: reordering inside this
+             list and carrying to another group are the same grip. `take` is
+             how the receiving side removes the field from here without
+             reaching into this closure's state. */
+          carried = {
+            name,
+            owner,
+            take: () => {
+              const at = chosen.indexOf(name);
+              if (at >= 0) chosen.splice(at, 1);
+              commit();
+            },
+          };
+          row.classList.add('dragging');
+          e.dataTransfer.effectAllowed = 'move';
+          /* Firefox will not start a drag without something on the transfer,
+             and the payload is never read — the index above is the state. */
+          e.dataTransfer.setData('text/plain', name);
+        },
+        ondragend: () => { dragging = null; carried = null; paintList(); },
+        ondragover: (e) => {
+          if (dragging === null || dragging === i) return;
+          e.preventDefault();
+          const at = dragging;
+          dragging = i;
+          const [item] = chosen.splice(at, 1);
+          chosen.splice(i, 0, item);
+          commit();
+          paintList();
+          /* Re-marked after the repaint, or the row under the pointer loses
+             the class that says it is the one being carried. */
+          list.children[i]?.classList.add('dragging');
+        },
+        ondrop: (e) => { e.preventDefault(); },
+        onkeydown: (e) => {
+          if (!e.altKey) return;
+          if (e.key === 'ArrowUp') { e.preventDefault(); move(i, i - 1); }
+          if (e.key === 'ArrowDown') { e.preventDefault(); move(i, i + 1); }
+        },
+      }, [
+        el('span', { class: 'pb-grip', 'aria-hidden': 'true', text: '∷' }),
+        el('span', { class: 'pb-field-name', text: label(name), title: name }),
+        el('span', { class: 'pb-field-type', text: typeOf(name) }),
+        others.length
+          ? el('button', {
+              type: 'button', class: 'ghost pb-send',
+              text: '→',
+              title: 'Move this field to another group',
+              'aria-label': `Move ${name} to another group`,
+              onclick: () => sendTo(name, i),
+            })
+          : null,
+        el('button', {
+          type: 'button', class: 'ghost pb-remove', text: '×',
+          title: `Take this field off the ${noun}`,
+          'aria-label': `Remove ${name}`,
+          onclick: () => {
+            chosen.splice(i, 1);
+            commit();
+            paintList();
+            paintPool();
+          },
+        }),
+      ].filter(Boolean));
+      return row;
+    }));
+    if (focus >= 0) list.children[focus]?.focus();
+    if (!chosen.length) {
+      list.replaceChildren(el('p', { class: 'note', text: 'No fields in this group yet.' }));
+    }
+  }
+
+  /* Sending a field elsewhere redraws whatever the caller draws, because two
+     groups change and the other one may be open. */
+  function sendTo(name, i) {
+    if (others.length === 1) return handOver(name, i, others[0]);
+    /* More than one candidate, so it is a choice — made in the row rather
+       than in a dialog, which would cover the thing being arranged. */
+    const menu = el('div', { class: 'pb-send-menu' }, others.map((other) => el('button', {
+      type: 'button', class: 'ghost',
+      text: other.title,
+      onclick: () => handOver(name, i, other),
+    })));
+    const row = list.children[i];
+    row?.querySelector('.pb-send-menu')?.remove();
+    row?.append(menu);
+    menu.querySelector('button')?.focus();
+    return undefined;
+  }
+
+  function handOver(name, i, other) {
+    chosen.splice(i, 1);
+    commit();
+    other.receive(name);
+    onSend?.();
+  }
+
+  function paintPool() {
+    const rest = all.filter((n) => !chosen.includes(n));
+    pool.replaceChildren(
+      el('span', { class: 'pb-label', text: rest.length ? 'Add' : `Every field is on the ${noun}` }),
+      ...rest.map((name) => el('button', {
+        type: 'button', class: 'ghost pb-add-field',
+        text: label(name),
+        title: `Add ${name} to this group`,
+        /* Named for what pressing it does. The visible text is the field's
+           own name, which reads as a label rather than as a control to
+           anyone hearing the page one element at a time. */
+        'aria-label': `Add ${name}`,
+        onclick: () => {
+          chosen.push(name);
+          commit();
+          paintList();
+          paintPool();
+        },
+      })),
+    );
+  }
+
+  count.textContent = `${chosen.length} of ${all.length} · drag to arrange`;
+  paintList();
+  paintPool();
+
+  return el('div', { class: 'pb-panel' }, [
+    el('div', { class: 'pb-panel-head' }, [
+      heading ? el('span', { class: 'pb-label', text: heading }) : null,
+      count,
+      el('span', { class: 'pb-spacer' }),
+      el('button', {
+        type: 'button', class: 'ghost', text: 'All',
+        title: 'Every field, in the table’s own order',
+        onclick: () => { chosen = [...all]; commit(); paintList(); paintPool(); },
+      }),
+      el('button', {
+        type: 'button', class: 'ghost', text: 'None',
+        onclick: () => { chosen = []; commit(); paintList(); paintPool(); },
+      }),
+    ].filter(Boolean)),
+    list,
+    pool,
+  ]);
+}

package/dist/client/ask.js

@@ -0,0 +1,133 @@
+/**
+ * The query bar, in the middle of the screen.
+ *
+ * The bar in the header is right for refining what you are already looking at
+ * — it holds the query you ran, a click away, and it is where the answer's
+ * sort clause gets rewritten. It is the wrong surface for *writing* one. It is
+ * a single line about 90 characters wide sharing the header with a wordmark, a
+ * connection picker and four buttons, and a real question outgrows it:
+ *
+ *     invoice where total > 100 count, sum total as billed by month invoice_date sort billed desc
+ *
+ * scrolls sideways in the bar while you are still deciding what to ask. So
+ * this is the same input given room — centred, wrapped, nothing else on
+ * screen — on ⌘/ , beside ⌘K. The pairing is the point: **⌘K goes to things,
+ * ⌘/ asks things.**
+ *
+ * It deliberately does not run the query itself. The decision about *which
+ * endpoint answers a line* — a `by` clause means a breakdown, everything else
+ * is a view — belongs in one place, and a modal that re-made it would be the
+ * second place for it to go stale. The caller hands in `onRun`, which is the
+ * same function the header's form submits to.
+ *
+ * A textarea rather than an input, purely so a long line wraps instead of
+ * scrolling. The language is single-line, so Enter runs and any newline that
+ * arrives by paste is flattened rather than being quietly sent to a parser
+ * that has no idea what to do with it.
+ */
+import { el, trapFocus } from './core.js';
+
+let panel = null;
+let restoreFocus = null;
+/** Undoes the Tab trap. The focus restore below is this module's own. */
+let release = null;
+
+export const askIsOpen = () => panel !== null;
+
+export function closeAsk() {
+  if (!panel) return;
+  release?.();
+  release = null;
+  panel.remove();
+  panel = null;
+  document.removeEventListener('keydown', onKey, true);
+  /* Back to whatever opened it. Without this, closing left the caret on
+     `document.body`, where the single-key shortcuts do work — so an Escape
+     followed by a stray `h` went home from a view somebody had just decided
+     not to leave. */
+  restoreFocus?.focus?.();
+  restoreFocus = null;
+}
+
+function onKey(e) {
+  if (e.key !== 'Escape') return;
+  /* Stopped as well as prevented, the same rule the palette follows: the page
+     under a modal listens for Escape too, and one press must not close two
+     things. */
+  e.preventDefault();
+  e.stopPropagation();
+  closeAsk();
+}
+
+/**
+ * Open it.
+ *
+ * `initial` is the line to start from — the one in the bar, so this is "edit
+ * what I ran" as much as "write something new" — and it arrives selected, so
+ * typing replaces it and an arrow key keeps it.
+ */
+export function openAsk({ initial = '', onRun } = {}) {
+  if (panel) return;
+  restoreFocus = document.activeElement;
+
+  const input = el('textarea', {
+    class: 'ask-input',
+    rows: '3',
+    spellcheck: 'false',
+    autocomplete: 'off',
+    'aria-label': 'Query',
+    placeholder: 'customer active = true sort name limit 20',
+  });
+  input.value = initial;
+
+  const run = () => {
+    /* Flattened rather than trimmed at the ends: a pasted two-line query would
+       otherwise reach the parser with a newline in the middle of it, and the
+       message that comes back is about whatever token followed it. */
+    const text = input.value.replace(/\s+/g, ' ').trim();
+    if (!text) return;
+    closeAsk();
+    onRun?.(text);
+  };
+
+  input.addEventListener('keydown', (e) => {
+    if (e.key !== 'Enter' || e.shiftKey) return;
+    e.preventDefault();
+    run();
+  });
+
+  const box = el('div', {
+    class: 'ask',
+    role: 'dialog',
+    'aria-modal': 'true',
+    'aria-label': 'Write a query',
+  }, [
+    input,
+    el('div', { class: 'ask-foot' }, [
+      /* What the language can do that the placeholder cannot show, in the one
+         place someone is definitely about to write one. `by` is here because
+         it is the newest clause and the least guessable — nothing else in the
+         bar hints that grouping exists at all. */
+      el('span', { class: 'ask-hint' }, [
+        el('code', { text: 'by' }),
+        document.createTextNode(' groups — '),
+        el('code', { text: 'invoice count by status' }),
+      ]),
+      el('span', { class: 'ask-keys', text: 'Enter to run · Esc to cancel' }),
+    ]),
+  ]);
+
+  panel = el('div', {
+    class: 'ask-backdrop',
+    /* Clicking away is a cancel, but only on the backdrop itself — a click
+       that started on the box and drifted out while selecting text is not a
+       request to throw the line away. */
+    onmousedown: (e) => { if (e.target === panel) closeAsk(); },
+  }, box);
+
+  document.body.append(panel);
+  release = trapFocus(panel);
+  document.addEventListener('keydown', onKey, true);
+  input.focus();
+  input.select();
+}