@bakery-framework/plugin-db-explorer 2.0.0-alpha.5 → 2.0.0-alpha.7

package/src/client/filter-builder.ts

@@ -0,0 +1,198 @@
+/**
+ * The filter builder: a chip per condition, combinable and each removable.
+ *
+ * This replaces a row of one text box per column, which could only ever mean
+ * "contains" and which grew a box for every column whether or not anyone wanted
+ * to filter on it. A chip is column + operator + value + remove, and the
+ * operator is the part that was missing: `eq` is what lets a foreign-key jump
+ * name a row, and `null` / `notnull` are the two questions a substring box
+ * cannot ask at all.
+ *
+ * The vocabulary and the wire shape are in `shared/filters.ts`, shared with the
+ * endpoint that validates them. Nothing here decides what an operator means.
+ */
+
+import type { Filter, FilterOp } from '../shared/filters'
+import {
+  duplicateColumns,
+  FILTER_OPS,
+  filter as makeFilter,
+  OP_LABELS,
+  opTakesValue,
+} from '../shared/filters'
+import { append, box, button, each, el, on, select } from './dom'
+import type { SchemaColumn } from './meta'
+
+export interface FilterBuilderContext {
+  columns: readonly SchemaColumn[]
+  filters: readonly Filter[]
+  /** Called with the whole new list; the caller re-fetches and repaints. */
+  onChange: (filters: Filter[]) => void
+}
+
+const OPTIONS = FILTER_OPS.map(op => ({ value: op, label: OP_LABELS[op] }))
+
+/**
+ * The bar.
+ *
+ * Every control writes a **whole new list** through `onChange` rather than
+ * mutating the one it was given — same discipline as the CSV wizard's model,
+ * and the reason a chip's state can never disagree with the URL.
+ */
+export function filterBar(ctx: FilterBuilderContext): HTMLElement {
+  const bar = box('filter-bar')
+  each(bar, ctx.filters, (entry, index) => chip(ctx, entry, index))
+  bar.appendChild(addButton(ctx))
+
+  const clashes = duplicateColumns(ctx.filters)
+  if (clashes.length) bar.appendChild(clashNote(clashes))
+  return bar
+}
+
+/**
+ * A column named twice, said out loud.
+ *
+ * The wire shape is a record keyed by column, so only the last filter on a
+ * column is sent. Rendering both chips and silently dropping one would be a
+ * screen that disagrees with the query — the one failure mode a filter builder
+ * must not have.
+ */
+function clashNote(columns: readonly string[]): HTMLElement {
+  return el('span', {
+    class: 'filter-clash',
+    text: `only the last filter on ${columns.join(', ')} is applied`,
+    title:
+      'the table-data endpoint keys filters by column, so a column can carry ' +
+      'one condition at a time',
+  })
+}
+
+function addButton(ctx: FilterBuilderContext): HTMLElement {
+  const first = ctx.columns[0]
+  const add = button(
+    '+ filter',
+    () => {
+      if (!first) return
+      ctx.onChange([...ctx.filters, makeFilter(first.name, 'eq', '')])
+    },
+    { class: 'btn filter-add', title: 'add a condition' },
+  )
+  add.disabled = !first
+  return add
+}
+
+function chip(
+  ctx: FilterBuilderContext,
+  entry: Filter,
+  index: number,
+): HTMLElement {
+  const node = box('filter-chip')
+  const replace = (next: Filter) =>
+    ctx.onChange(withAt(ctx.filters, index, next))
+
+  append(node, [
+    columnPicker(ctx, entry, replace),
+    operatorPicker(entry, replace),
+    valueInput(entry, replace),
+    removeButton(ctx, entry, index),
+  ])
+  return node
+}
+
+function columnPicker(
+  ctx: FilterBuilderContext,
+  entry: Filter,
+  replace: (next: Filter) => void,
+): HTMLElement {
+  const options = ctx.columns.map(column => ({
+    value: column.name,
+    label: `${column.name} · ${column.type}`,
+  }))
+  return select(options, entry.column, value =>
+    replace({ ...entry, column: value }),
+  )
+}
+
+function operatorPicker(
+  entry: Filter,
+  replace: (next: Filter) => void,
+): HTMLElement {
+  return select(OPTIONS, entry.op, value =>
+    // Switching to a nullary operator clears the operand rather than keeping
+    // it hidden: a value that is invisible and still in the URL is a filter
+    // nobody can see and nobody asked for.
+    replace(nextOnOp(entry, value as FilterOp)),
+  )
+}
+
+function nextOnOp(entry: Filter, op: FilterOp): Filter {
+  return { ...entry, op, value: opTakesValue(op) ? entry.value : '' }
+}
+
+/**
+ * The operand — **absent** for `null` and `notnull`.
+ *
+ * Not disabled, not hidden by CSS: not built at all. A greyed-out box still
+ * says "there is a value here", and there is not one.
+ */
+function valueInput(
+  entry: Filter,
+  replace: (next: Filter) => void,
+): HTMLElement | null {
+  if (!opTakesValue(entry.op)) return null
+  const input = el('input', {
+    class: 'filter-value',
+    attrs: {
+      'aria-label': `${entry.column} ${OP_LABELS[entry.op]}`,
+      placeholder: 'value',
+    },
+  })
+  input.value = entry.value
+  on(input, 'change', () => replace({ ...entry, value: input.value }))
+  return input
+}
+
+function removeButton(
+  ctx: FilterBuilderContext,
+  entry: Filter,
+  index: number,
+): HTMLElement {
+  return button('×', () => ctx.onChange(withoutAt(ctx.filters, index)), {
+    class: 'btn filter-drop',
+    title: `remove the filter on ${entry.column}`,
+    attrs: { 'aria-label': `remove the filter on ${entry.column}` },
+  })
+}
+
+/**
+ * Immutable list edits.
+ *
+ * Exported because they are the two operations the chip callbacks are made of,
+ * and an off-by-one in either would present as "removing one filter removed a
+ * different one" — a bug worth a test rather than a careful read.
+ */
+export function withAt(
+  filters: readonly Filter[],
+  index: number,
+  next: Filter,
+): Filter[] {
+  return filters.map((entry, at) => (at === index ? next : entry))
+}
+
+export function withoutAt(filters: readonly Filter[], index: number): Filter[] {
+  return filters.filter((_entry, at) => at !== index)
+}
+
+/**
+ * The filter a foreign-key jump becomes.
+ *
+ * One `eq` per referenced column, which is exactly a row identity — this is the
+ * function that replaced `ViewState.focus`. Values stringify because the wire
+ * carries text and the ORM binds it as a parameter; the comparison happens in
+ * the database, against the column's own type.
+ */
+export function equalityFilters(key: Record<string, unknown>): Filter[] {
+  return Object.entries(key)
+    .filter(([, value]) => value !== null && value !== undefined)
+    .map(([column, value]) => makeFilter(column, 'eq', String(value)))
+}

package/src/client/fk.ts

@@ -0,0 +1,269 @@
+/**
+ * Foreign keys: what a cell points at, and what it costs to find out.
+ *
+ * The naive version of this feature is a `fetch` per foreign-key cell on
+ * `mouseover`. A fifty-row page with three foreign keys is a hundred and fifty
+ * requests, and moving the mouse across the grid fires most of them. Three
+ * things prevent that here, and all three are load-bearing:
+ *
+ *  - **A ~350 ms arming delay.** Crossing a cell on the way somewhere else
+ *    never issues a request.
+ *  - **An `AbortController`.** `pointerleave` cancels a request already in
+ *    flight, so a fast sweep costs one aborted socket rather than fifty
+ *    completed round trips.
+ *  - **A bounded cache** (convention 6). The key is `table|col|value`, which is
+ *    per-row and therefore unbounded in principle; the bound is what makes that
+ *    safe.
+ *
+ * The pure half — which column points where, and what key a row implies — is
+ * separated out so the graph reasoning can be read without the timers.
+ */
+
+import { type LookupRef, lookupRefs } from './api'
+import { type ForeignKeyInfo, type SchemaGraph, sameTable } from './meta'
+
+/**
+ * A least-recently-used map, in nine lines.
+ *
+ * Core has `LRUCache` and this is not a preference for a private copy —
+ * `bundleModule` externalises every installed package, so importing it leaves
+ * `@bakery-framework/core/cache/lru` as a bare specifier in the emitted bundle
+ * and the browser cannot resolve it. Client code imports nothing from
+ * `@bakery-framework/*`; see the header of `shared/coerce.ts`.
+ *
+ * A `Map` iterates in insertion order, so re-inserting on read is the whole
+ * recency mechanism and the oldest key is always the first one.
+ */
+class BoundedCache<V> {
+  private readonly map = new Map<string, V>()
+  constructor(private readonly limit: number) {}
+
+  get(key: string): V | undefined {
+    const value = this.map.get(key)
+    if (value === undefined) return undefined
+    this.map.delete(key)
+    this.map.set(key, value)
+    return value
+  }
+
+  set(key: string, value: V): void {
+    this.map.delete(key)
+    this.map.set(key, value)
+    if (this.map.size > this.limit) {
+      const oldest = this.map.keys().next().value
+      if (oldest !== undefined) this.map.delete(oldest)
+    }
+  }
+
+  clear(): void {
+    this.map.clear()
+  }
+
+  get size(): number {
+    return this.map.size
+  }
+}
+
+export interface FkTarget {
+  /** Columns in *this* table that make up the key. */
+  cols: string[]
+  refTable: string
+  /** The matching columns in the referenced table, positionally. */
+  refCols: string[]
+}
+
+function toTarget(fk: ForeignKeyInfo): FkTarget {
+  return { cols: fk.cols, refTable: fk.refTable, refCols: fk.refCols }
+}
+
+/**
+ * The foreign key `column` participates in, if any.
+ *
+ * Composite keys are included rather than skipped: a two-column key renders as
+ * a button on each of its columns, and both resolve the same referenced row.
+ * Skipping them would make the feature quietly absent on exactly the schemas
+ * where following a reference by hand is hardest.
+ */
+export function fkForColumn(
+  graph: SchemaGraph | null,
+  table: string,
+  column: string,
+): FkTarget | null {
+  if (!graph) return null
+  for (const fk of Object.values(graph.foreignKeys)) {
+    if (!sameTable(fk.table, table)) continue
+    if (fk.cols.includes(column)) return toTarget(fk)
+  }
+  return null
+}
+
+/**
+ * Every foreign-key column of one table, resolved once.
+ *
+ * `fkForColumn` is a linear scan of the whole graph, and the grid asked it per
+ * cell, per paint — a fifty-row page of twenty columns against forty foreign
+ * keys is forty thousand comparisons, each of which had `sameTable` allocate
+ * two lowercased strings, and `repaintRow`/`repaintCell` run it again. The scan
+ * does not depend on the row, so it happens once when the grid is built.
+ *
+ * First declaration wins, exactly as the scan's early `return` does, so a
+ * column named by two keys resolves to the same one either way.
+ */
+export function fkMapFor(
+  graph: SchemaGraph | null,
+  table: string,
+): Map<string, FkTarget> {
+  const map = new Map<string, FkTarget>()
+  if (!graph) return map
+  for (const fk of Object.values(graph.foreignKeys)) {
+    if (!sameTable(fk.table, table)) continue
+    const target = toTarget(fk)
+    for (const column of fk.cols) {
+      if (!map.has(column)) map.set(column, target)
+    }
+  }
+  return map
+}
+
+/** Every key pointing *at* this table. The row panel's "referenced by" list. */
+export function reverseFks(
+  graph: SchemaGraph | null,
+  table: string,
+): ForeignKeyInfo[] {
+  if (!graph) return []
+  return Object.values(graph.foreignKeys).filter(fk =>
+    sameTable(fk.refTable, table),
+  )
+}
+
+/**
+ * The referenced row's identity, as this row names it.
+ *
+ * `null` when any participating column is NULL — an optional foreign key with
+ * no value points at nothing, and a predicate containing `NULL` matches no row
+ * anyway, so issuing the lookup would spend a request to learn that.
+ */
+export function fkKeyOf(
+  target: FkTarget,
+  row: Record<string, unknown>,
+): Record<string, unknown> | null {
+  const key: Record<string, unknown> = {}
+  for (let i = 0; i < target.cols.length; i++) {
+    const value = row[target.cols[i]!]
+    if (value === null || value === undefined) return null
+    key[target.refCols[i] ?? target.cols[i]!] = value
+  }
+  return key
+}
+
+/** `table|col|value` — stable across pages, which is what makes caching pay. */
+export function cacheKey(
+  refTable: string,
+  key: Record<string, unknown>,
+): string {
+  const parts = Object.keys(key)
+    .sort()
+    .map(column => `${column}=${String(key[column])}`)
+  return `${refTable}|${parts.join('|')}`
+}
+
+/**
+ * What to show for a resolved row: the label column if the table has one, the
+ * identity otherwise.
+ *
+ * `graph.labels` is the server's pick — the first text column that is not part
+ * of the identity — so a `users` row reads as `ada` rather than `41`.
+ */
+export function fkLabel(
+  graph: SchemaGraph | null,
+  refTable: string,
+  row: Record<string, unknown> | null,
+): string | null {
+  if (!row) return null
+  const label = graph?.labels?.[refTable]
+  if (label && row[label] !== null && row[label] !== undefined) {
+    return String(row[label])
+  }
+  const identity = graph?.identity?.[refTable]?.cols ?? Object.keys(row)
+  return identity.map(column => String(row[column])).join(' / ')
+}
+
+export type Resolved = Record<string, unknown> | null
+
+/**
+ * Hover-driven resolution, with the cache and the cancellation.
+ *
+ * One instance per page load, cleared when the schema graph is refetched.
+ */
+export class FkResolver {
+  /**
+   * 500 entries — ten pages of a fifty-row grid with a foreign key on every
+   * row. Past that the earliest are the ones the user has scrolled away from.
+   */
+  private readonly cache = new BoundedCache<Resolved>(500)
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private inflight: AbortController | null = null
+
+  cached(refTable: string, key: Record<string, unknown>): Resolved | undefined {
+    return this.cache.get(cacheKey(refTable, key))
+  }
+
+  /**
+   * Arm the delay. Returns a canceller for `pointerleave`.
+   *
+   * The canceller aborts an in-flight request as well as clearing an unfired
+   * timer, because the expensive case is the one that already left.
+   */
+  arm(
+    refTable: string,
+    key: Record<string, unknown>,
+    onResolved: (row: Resolved) => void,
+    delay = 350,
+  ): () => void {
+    const hit = this.cached(refTable, key)
+    if (hit !== undefined) {
+      onResolved(hit)
+      return () => {}
+    }
+    this.cancel()
+    this.timer = setTimeout(() => {
+      void this.resolve(refTable, key).then(onResolved, () => {
+        // An abort or a failed lookup leaves the cell showing its raw value,
+        // which is the state it was already in. Nothing to report: the user
+        // moved the pointer away, or the row is simply not resolvable.
+      })
+    }, delay)
+    return () => this.cancel()
+  }
+
+  cancel(): void {
+    if (this.timer !== null) clearTimeout(this.timer)
+    this.timer = null
+    this.inflight?.abort()
+    this.inflight = null
+  }
+
+  /** One batched lookup. Public so the panel can resolve without hovering. */
+  async resolve(
+    refTable: string,
+    key: Record<string, unknown>,
+  ): Promise<Resolved> {
+    const hit = this.cached(refTable, key)
+    if (hit !== undefined) return hit
+
+    const controller = new AbortController()
+    this.inflight = controller
+    const refs: LookupRef[] = [{ table: refTable, key }]
+    const rows = await lookupRefs(refs, controller.signal)
+    this.inflight = null
+
+    const row = rows[0]?.row ?? null
+    this.cache.set(cacheKey(refTable, key), row)
+    return row
+  }
+
+  clear(): void {
+    this.cancel()
+    this.cache.clear()
+  }
+}

package/src/client/grid-body.ts

@@ -0,0 +1,106 @@
+/**
+ * What goes *inside* a cell: the text, the classes, and the foreign-key button.
+ *
+ * Split out of `grid.ts` alongside the header and the row bar. This half is the
+ * one with no knowledge of the cursor or the editor — it is handed a value and
+ * returns a node — which is why it could leave.
+ *
+ * The `<button>` for a foreign key is a real button rather than a styled span,
+ * because it is activated by keyboard and read as an action by a screen reader.
+ * A `div` with a click handler is neither.
+ */
+
+import { button } from './dom'
+import { type FkResolver, type FkTarget, fkKeyOf, fkLabel } from './fk'
+import { cellProps, type SchemaColumn, type SchemaGraph } from './meta'
+
+export interface CellPaintContext {
+  table: string
+  graph: SchemaGraph | null
+  /**
+   * Which columns of `table` are foreign keys, resolved once by `fkMapFor`.
+   *
+   * Built by the grid rather than looked up here: the answer depends on the
+   * table and not on the row, and asking per cell per paint made a page repaint
+   * quadratic in the size of the schema graph.
+   */
+  fks: ReadonlyMap<string, FkTarget>
+  resolver: FkResolver
+  onFollowFk: (target: FkTarget, key: Record<string, unknown>) => void
+}
+
+/**
+ * Write one cell's value into its `<td>`.
+ *
+ * The staged flag is passed in rather than read from a session here, so this
+ * module needs no `EditSession` — a staged value and a stored value take
+ * exactly the same path and cannot diverge in how they look.
+ */
+export function paintCell(
+  td: HTMLTableCellElement,
+  ctx: CellPaintContext,
+  row: Record<string, unknown>,
+  column: SchemaColumn,
+  value: unknown,
+  staged: boolean,
+): void {
+  const props = cellProps(value, column)
+  td.replaceChildren()
+  td.className = props.className
+  if (staged) td.classList.add('staged')
+  if (props.title) td.title = props.title
+  // `props.text` is passed down rather than recomputed: `cellBody` wants the
+  // same string, and `cellProps` was being run twice for every cell.
+  td.appendChild(cellBody(ctx, row, column, props.text))
+}
+
+function cellBody(
+  ctx: CellPaintContext,
+  row: Record<string, unknown>,
+  column: SchemaColumn,
+  text: string,
+): Node {
+  const target = ctx.fks.get(column.name)
+  const key = target ? fkKeyOf(target, row) : null
+  if (!target || !key) return document.createTextNode(text)
+  return fkButton(ctx, target, key, text)
+}
+
+/**
+ * A foreign key as a link, resolving its label on hover.
+ *
+ * The resolver owns the delay, the cache and the cancellation — see `fk.ts`.
+ * All that happens here is arming it on `pointerenter` and disarming it on
+ * `pointerleave`, which is what keeps a sweep across the grid from costing
+ * fifty round trips.
+ */
+function fkButton(
+  ctx: CellPaintContext,
+  target: FkTarget,
+  key: Record<string, unknown>,
+  text: string,
+): HTMLButtonElement {
+  const node = button(text, () => ctx.onFollowFk(target, key), {
+    class: 'fk',
+    title: `→ ${target.refTable}`,
+  })
+
+  const show = (resolved: Record<string, unknown> | null) => {
+    const label = fkLabel(ctx.graph, target.refTable, resolved)
+    node.title = label ? `${target.refTable}: ${label}` : `→ ${target.refTable}`
+    if (label) node.textContent = `${text} · ${label}`
+  }
+
+  const cached = ctx.resolver.cached(target.refTable, key)
+  if (cached !== undefined) show(cached)
+
+  let disarm: (() => void) | null = null
+  node.addEventListener('pointerenter', () => {
+    disarm = ctx.resolver.arm(target.refTable, key, show)
+  })
+  node.addEventListener('pointerleave', () => {
+    disarm?.()
+    disarm = null
+  })
+  return node
+}

package/src/client/grid-header.ts

@@ -0,0 +1,65 @@
+/**
+ * The grid's header row: the select-all box and the sortable column headings.
+ *
+ * Split out of `grid.ts` when that file passed six hundred lines. It is a clean
+ * seam because the header depends on nothing the grid mutates — it is built
+ * once from the columns and the current sort, and never repainted. Cursor,
+ * editor and selection state all live on the other side of it.
+ */
+
+import { each, el, on } from './dom'
+import type { SchemaColumn } from './meta'
+
+export interface HeaderContext {
+  columns: readonly SchemaColumn[]
+  editable: boolean
+  sortBy: string | null
+  sortOrder: 'ASC' | 'DESC'
+  onSort: (column: string) => void
+  onToggleAll: (checked: boolean) => void
+}
+
+export function buildHead(ctx: HeaderContext): HTMLTableSectionElement {
+  const head = el('thead')
+  const tr = el('tr')
+  tr.appendChild(buildSelectAll(ctx))
+  each(tr, ctx.columns, column => buildHeaderCell(ctx, column))
+  head.appendChild(tr)
+  return head
+}
+
+/**
+ * The leading column exists on every table, editable or not: it carries the row
+ * panel's opener, which a read-only table needs just as much — a forty-column
+ * row is unreadable in a grid whether or not it can be changed. The select-all
+ * checkbox joins it only when there is something to select *for*.
+ */
+function buildSelectAll(ctx: HeaderContext): HTMLTableCellElement {
+  const th = el('th', { class: 'pick' })
+  if (!ctx.editable) return th
+  const check = el('input', { attrs: { 'aria-label': 'select all rows' } })
+  check.type = 'checkbox'
+  on(check, 'change', () => ctx.onToggleAll(check.checked))
+  th.appendChild(check)
+  return th
+}
+
+function buildHeaderCell(
+  ctx: HeaderContext,
+  column: SchemaColumn,
+): HTMLTableCellElement {
+  const th = el('th', {
+    text: column.name + sortArrow(ctx, column.name),
+    title: `${column.type}${column.notnull ? ' NOT NULL' : ''}`,
+    attrs: { 'data-kind': column.kind },
+  })
+  if (column.pk) th.classList.add('pk')
+  on(th, 'click', () => ctx.onSort(column.name))
+  return th
+}
+
+/** Named so the ternary chain is not folded into `buildHeaderCell`'s score. */
+function sortArrow(ctx: HeaderContext, column: string): string {
+  if (ctx.sortBy !== column) return ''
+  return ctx.sortOrder === 'ASC' ? ' ↑' : ' ↓'
+}

package/src/client/grid-rowbar.ts

@@ -0,0 +1,64 @@
+/**
+ * The strip that appears under a row the moment it is dirty.
+ *
+ * Under the row rather than in a toolbar, because "which row is this Save for"
+ * has exactly one unambiguous answer and it is proximity. It carries the
+ * changed-column list, the two buttons, and the place a failed save reports
+ * itself — a 409 belongs next to the row it is about, not in a toast.
+ */
+
+import { append, box, button, el } from './dom'
+
+export interface RowBar {
+  tr: HTMLTableRowElement
+  message: HTMLElement
+  count: HTMLElement
+}
+
+export interface RowBarHooks {
+  onSave: () => void
+  onRevert: () => void
+}
+
+export function buildRowBar(colSpan: number, hooks: RowBarHooks): RowBar {
+  const tr = el('tr', { class: 'row-bar-row' })
+  const td = el('td')
+  td.colSpan = colSpan
+
+  const bar = box('row-bar')
+  const count = el('span', { class: 'note' })
+  const message = el('span', { class: 'row-error' })
+  append(bar, [
+    count,
+    button('Save', hooks.onSave, { class: 'btn primary' }),
+    button('Revert', hooks.onRevert, { class: 'btn' }),
+    message,
+  ])
+
+  td.appendChild(bar)
+  tr.appendChild(td)
+  return { tr, message, count }
+}
+
+/**
+ * Show the bar, and say what changed.
+ *
+ * Naming the columns rather than counting them is the point: "3 columns
+ * changed" tells you that you touched something and not what, and the whole
+ * reason the buffer exists is that a row is saved as one statement.
+ */
+export function paintRowBar(bar: RowBar, changed: readonly string[]): void {
+  bar.tr.classList.toggle('open', changed.length > 0)
+  bar.count.textContent = changed.length
+    ? `${changed.length} column${changed.length === 1 ? '' : 's'} changed: ${changed.join(', ')}`
+    : ''
+  // A fresh edit clears a stale failure: the message was about the previous
+  // attempt, and leaving it up would make a retry look like it had already
+  // failed.
+  if (changed.length) bar.message.textContent = ''
+}
+
+export function setRowBarMessage(bar: RowBar, message: string): void {
+  bar.tr.classList.add('open')
+  bar.message.textContent = message
+}