tablewalk 0.0.1

package/dist/client/nested.js

@@ -0,0 +1,255 @@
+/**
+ * A row's children, opened in place.
+ *
+ * The view composer answers "how many" with an aggregate — count the invoice
+ * lines, sum their value — and deliberately refuses to LEFT JOIN a has-many,
+ * because that multiplies the base row and makes every other number on it a
+ * lie. That refusal is correct and it leaves a question unanswered: *which
+ * ones*. Today the only way to see them is to open the record, which loses the
+ * list you were reading them in.
+ *
+ * Expanding a row is the answer that does not multiply it. The children live in
+ * their own row underneath, one query per relationship keyed on that row, so
+ * the base row remains one row and its numbers remain its own.
+ *
+ * Fetched when opened rather than with the page. A twenty-row page with four
+ * incoming relationships would be eighty queries to fill in something nobody
+ * has asked to see; opening one is one query, and the answer is kept so that
+ * closing and reopening is free.
+ */
+import { api, el, findTable, go, keyOf, quote, refsTo, rowView, tableView, whenRemoved } from './core.js';
+import { renderGrid } from './table.js';
+
+/** Rows of a child table shown inline before it needs its own page. */
+const INLINE = 5;
+
+/** Answers already fetched, by row and relationship. Cleared with the grid. */
+let cache = new Map();
+
+export function resetNested() {
+  cache = new Map();
+}
+
+/** Whether expanding would show anything at all. */
+export const hasChildren = (table) => Boolean(table) && refsTo(table.id).length > 0;
+
+/**
+ * The little triangle, and the row it opens.
+ *
+ * The detail lives in a sibling `<tr>` rather than inside the row's own cell,
+ * because a table row cannot contain another table without the columns of the
+ * inner one being laid out by the outer one — every child grid would inherit
+ * the parent's column widths, which are about entirely different data.
+ */
+export function expander(table, row, tr) {
+  const key = keyOf(table, row);
+  if (!key) return null;
+
+  const cell = el('td', { class: 'expander-cell' });
+  let open = false;
+  let detail = null;
+
+  const button = el('button', {
+    type: 'button',
+    class: 'expander',
+    'aria-expanded': 'false',
+    'aria-label': 'Show what points at this row',
+    title: 'Show what points at this row',
+    text: '▸',
+    onclick: (e) => {
+      /* The row itself navigates. Opening the detail is a different intent and
+         must not also walk away from the table you are opening it in. */
+      e.stopPropagation();
+      open = !open;
+      button.setAttribute('aria-expanded', String(open));
+      button.textContent = open ? '▾' : '▸';
+      tr.classList.toggle('expanded', open);
+
+      if (!open) {
+        detail?.remove();
+        detail = null;
+        return;
+      }
+      detail = el('tr', { class: 'detail-row' }, el('td', {
+        class: 'detail-cell',
+        colspan: tr.cells.length,
+      }, el('p', { class: 'loading', text: 'Looking…' })));
+      tr.after(detail);
+      void fill(table, key, detail.firstChild);
+    },
+  });
+
+  cell.append(button);
+  return cell;
+}
+
+async function fill(table, key, host) {
+  const cacheKey = `${table.id}:${JSON.stringify(key)}`;
+  let sections = cache.get(cacheKey);
+
+  if (!sections) {
+    sections = await Promise.all(refsTo(table.id).map(async (fk) => {
+      const child = findTable(fk.from.table);
+      if (!child) return null;
+
+      /* Every column of the key has to match, which is what makes this correct
+         for a composite key and not only for a single-column one. */
+      const conditions = fk.to.columns.map((parentColumn, i) => ({
+        column: fk.from.columns[i] ?? fk.from.columns[0],
+        op: '=',
+        value: key[parentColumn],
+      }));
+      if (conditions.some((c) => c.value === undefined || c.value === null)) return null;
+
+      const filter = { groups: [conditions] };
+      try {
+        const [data, total] = await Promise.all([
+          api('/api/query', { table: child.id, filter, limit: INLINE, offset: 0 }),
+          api('/api/count', { table: child.id, filter }),
+        ]);
+        return { fk, child, data, total: total.count, exact: total.exact };
+      } catch (err) {
+        return { fk, child, error: err.message };
+      }
+    }));
+    sections = sections.filter(Boolean).filter((s) => s.error || s.data.rows.length);
+    cache.set(cacheKey, sections);
+  }
+
+  if (!host.isConnected) return;
+
+  if (!sections.length) {
+    host.replaceChildren(el('p', { class: 'note', text: 'Nothing points at this row.' }));
+    return;
+  }
+
+  host.replaceChildren(...sections.map((section) => {
+    if (section.error) {
+      return el('div', { class: 'detail-section' }, [
+        el('h4', { text: section.child.name }),
+        el('p', { class: 'sql-error', text: section.error }),
+      ]);
+    }
+    const { fk, child, data, total, exact } = section;
+    const more = total > data.rows.length;
+
+    return el('div', { class: 'detail-section' }, [
+      el('div', { class: 'detail-head' }, [
+        el('h4', { text: child.name }),
+        el('span', { class: 'detail-via', text: `via ${fk.from.columns.join(', ')}` }),
+        el('span', {
+          class: 'detail-count',
+          text: exact === false ? `~${total.toLocaleString()}` : total.toLocaleString(),
+        }),
+        more
+          ? el('button', {
+              type: 'button', class: 'ghost detail-all',
+              text: 'See all →',
+              onclick: () => {
+                const conditions = fk.from.columns
+                  .map((col, i) => `${col} = ${quote(key[fk.to.columns[i]])}`)
+                  .join(' and ');
+                go(tableView(child.id, `${child.id} ${conditions}`), 'push');
+              },
+            })
+          : null,
+      ].filter(Boolean)),
+      renderGrid(child, data, {
+        onRowClick: (childRow) => {
+          const childKey = keyOf(child, childRow);
+          if (childKey) go(rowView(child.id, childKey, String(Object.values(childKey).join('/'))));
+        },
+      }),
+    ]);
+  }));
+}
+
+/* ---------- all of them at once ---------- */
+
+/** Rows started per batch, and the pause between batches. */
+const BATCH = 4;
+const BREATH_MS = 60;
+
+/**
+ * Open or close every row on the page.
+ *
+ * Expanding one row is a handful of counted queries; expanding twenty at once
+ * on a schema where the table has a dozen things pointing at it is two
+ * hundred and forty, fired simultaneously at the same connection that is
+ * serving the page. So rows are started a few at a time — the top of the
+ * table fills in immediately, the rest follows, and the database is never
+ * asked for everything at once.
+ *
+ * Collapsing has no such cost and is done in one pass.
+ *
+ * It works by clicking the row's own expander rather than reimplementing what
+ * that does. Two code paths for opening a row is exactly how the open one
+ * ends up fetching something the other does not.
+ */
+export function expandAllControl(tbody) {
+  let busy = false;
+
+  const buttons = () => [...tbody.querySelectorAll('button.expander')];
+  const anyClosed = () => buttons().some((b) => b.getAttribute('aria-expanded') !== 'true');
+
+  const button = el('button', {
+    type: 'button',
+    class: 'expander expand-all',
+    title: 'Expand every row',
+    'aria-label': 'Expand every row',
+    text: '\u25b8',
+    onclick: async (e) => {
+      e.stopPropagation();
+      if (busy) return;
+      const opening = anyClosed();
+
+      if (!opening) {
+        for (const b of buttons()) {
+          if (b.getAttribute('aria-expanded') === 'true') b.click();
+        }
+        sync();
+        return;
+      }
+
+      busy = true;
+      button.classList.add('working');
+      try {
+        const closed = buttons().filter((b) => b.getAttribute('aria-expanded') !== 'true');
+        for (let i = 0; i < closed.length; i += BATCH) {
+          /* Re-checked rather than trusted: a row the reader collapsed while
+             this was running should stay collapsed, not be reopened by a
+             batch that was queued before they touched it. */
+          for (const b of closed.slice(i, i + BATCH)) {
+            if (b.isConnected && b.getAttribute('aria-expanded') !== 'true') b.click();
+          }
+          if (i + BATCH < closed.length) {
+            await new Promise((resolve) => setTimeout(resolve, BREATH_MS));
+          }
+        }
+      } finally {
+        busy = false;
+        button.classList.remove('working');
+        sync();
+      }
+    },
+  });
+
+  function sync() {
+    const closed = anyClosed();
+    button.textContent = closed ? '\u25b8' : '\u25be';
+    button.title = closed ? 'Expand every row' : 'Collapse every row';
+    button.setAttribute('aria-label', button.title);
+    button.setAttribute('aria-expanded', String(!closed));
+  }
+
+  /* A row expanded or collapsed on its own changes what this control should
+     say next, and the rows do not report to it. Watching the body is cheaper
+     than threading a callback through every expander. */
+  const watch = new MutationObserver(sync);
+  watch.observe(tbody, { childList: true });
+  // Stopped with the table: one of these was left running per render.
+  whenRemoved(tbody, () => watch.disconnect());
+
+  sync();
+  return button;
+}