@bakery-framework/plugin-db-explorer 2.0.0-alpha.4 → 2.0.0-alpha.6

package/src/client/dom.ts

@@ -0,0 +1,144 @@
+/**
+ * The only place this client creates a node.
+ *
+ * **Nothing here writes `innerHTML`, and `client/safety.test.ts` asserts that
+ * no client module does.** Every value the grid renders is a database row —
+ * whatever the last writer put there — and the operator's origin owns
+ * `/api/_db/rows`, so a string that reached the DOM as markup would be stored
+ * XSS to arbitrary row writes. `textContent` is not a style preference; it is
+ * the reason this plugin has no XSS surface. The dashboard's grid, which
+ * concatenates into `innerHTML` and escapes by hand at each of eight call
+ * sites, is the counter-example this one exists not to repeat.
+ */
+
+export interface ElOptions {
+  class?: string
+  text?: string
+  title?: string
+  id?: string
+  /** `aria-*`, `role`, `data-*` — anything set through `setAttribute`. */
+  attrs?: Record<string, string | number | boolean | null | undefined>
+}
+
+export function el<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  options: ElOptions = {},
+): HTMLElementTagNameMap[K] {
+  const node = document.createElement(tag)
+  if (options.class) node.className = options.class
+  if (options.text !== undefined) node.textContent = options.text
+  if (options.title !== undefined) node.title = options.title
+  if (options.id) node.id = options.id
+  applyAttrs(node, options.attrs)
+  return node
+}
+
+/** Named so the loop is not an inline body inside `el` (see the module rule). */
+function applyAttrs(node: HTMLElement, attrs: ElOptions['attrs']): void {
+  if (!attrs) return
+  for (const [name, value] of Object.entries(attrs)) {
+    if (value === null || value === undefined || value === false) continue
+    node.setAttribute(name, String(value))
+  }
+}
+
+export function button(
+  label: string,
+  onClick: () => void,
+  options: ElOptions = {},
+): HTMLButtonElement {
+  const node = el('button', { ...options, text: label })
+  node.type = 'button'
+  node.addEventListener('click', onClick)
+  return node
+}
+
+/** `<div class=…>` with children, the shape most of this UI is made of. */
+export function box(cls: string, ...children: (Node | null)[]): HTMLDivElement {
+  const node = el('div', { class: cls })
+  append(node, children)
+  return node
+}
+
+export function append(parent: Node, children: (Node | null)[]): void {
+  for (const child of children) {
+    if (child) parent.appendChild(child)
+  }
+}
+
+/**
+ * Render a list through a named factory.
+ *
+ * Exists so a caller never writes `for (…) { …twenty lines… }` inline: an
+ * inline loop body counts against the enclosing function's cognitive
+ * complexity, and a named one does not. The rule is mechanical and this is the
+ * tool that makes it cheap to follow.
+ */
+export function each<T>(
+  parent: Node,
+  items: readonly T[],
+  make: (item: T, index: number) => Node | null,
+): void {
+  items.forEach((item, index) => {
+    const node = make(item, index)
+    if (node) parent.appendChild(node)
+  })
+}
+
+export function clear(node: Node): void {
+  ;(node as Element).replaceChildren()
+}
+
+/** A pending region: visibly disabled and announced as such. */
+export function setBusy(node: HTMLElement, busy: boolean): void {
+  node.setAttribute('aria-busy', busy ? 'true' : 'false')
+  node.classList.toggle('busy', busy)
+}
+
+export function on<K extends keyof HTMLElementEventMap>(
+  node: HTMLElement | Document | Window,
+  type: K,
+  handler: (event: HTMLElementEventMap[K]) => void,
+): void {
+  node.addEventListener(type, handler as EventListener)
+}
+
+/** A `<select>` over `{value,label}` options, with the current one selected. */
+export function select(
+  options: readonly { value: string; label: string }[],
+  current: string,
+  onChange: (value: string) => void,
+  cls = 'sel',
+): HTMLSelectElement {
+  const node = el('select', { class: cls })
+  each(node, options, option => {
+    const item = el('option', { text: option.label })
+    item.value = option.value
+    item.selected = option.value === current
+    return item
+  })
+  node.addEventListener('change', () => onChange(node.value))
+  return node
+}
+
+/**
+ * Hand the browser a file without a server round trip.
+ *
+ * An object URL rather than a `data:` one: a rejected-rows export of a 50,000
+ * row import is megabytes, and Chrome refuses a `data:` navigation past a size
+ * that is not documented anywhere.
+ */
+export function downloadText(
+  filename: string,
+  text: string,
+  type = 'text/csv',
+): void {
+  const url = URL.createObjectURL(new Blob([text], { type }))
+  const link = el('a')
+  link.href = url
+  link.download = filename
+  link.click()
+  // The object URL owns the blob until it is revoked; the click is synchronous
+  // but the download is not, so the revoke waits a turn.
+  setTimeout(() => URL.revokeObjectURL(url), 10_000)
+}

package/src/client/edit-session.ts

@@ -0,0 +1,219 @@
+/**
+ * The per-row dirty buffer, and the statement it becomes.
+ *
+ * **Pure — no DOM, no fetch.** This is where the editing model actually lives,
+ * so it is the part with tests. The grid is a view over it.
+ *
+ * Three properties it exists to hold:
+ *
+ *  1. **A row is one save.** Editing three columns produces one PATCH carrying
+ *     all three, not three PATCHes. The dashboard's save-on-blur produced the
+ *     latter, which means a reader can observe the row a third of the way
+ *     through an edit the user considers atomic.
+ *  2. **The pre-image is kept.** `expect` is built from the row as it was
+ *     *read*, never from a re-read at save time — a re-read would defeat the
+ *     concurrency check it exists to perform.
+ *  3. **Unchanged columns are dropped**, by `updatePlan`, so two people editing
+ *     different columns of one row do not collide.
+ */
+
+import { type ColumnKind, comparableKind, sameValue } from '../shared/coerce'
+import { updatePlan } from '../shared/plan'
+
+/**
+ * A row's identity, flattened to a string.
+ *
+ * `JSON.stringify` over the identity columns in their declared order — the
+ * order is the server's, from `identity.cols`, so it is stable across pages and
+ * across a composite key's spelling. `null` when the row does not carry every
+ * identity column, which is the same condition `updatePlan` reports as
+ * `missingIdentity` and means the row cannot be addressed at all.
+ */
+export function rowId(
+  row: Record<string, unknown>,
+  identity: readonly string[],
+): string | null {
+  if (!identity.length) return null
+  const parts: unknown[] = []
+  for (const column of identity) {
+    if (!(column in row)) return null
+    parts.push(row[column])
+  }
+  return JSON.stringify(parts)
+}
+
+export interface RowPlan {
+  /** Columns that actually differ, and the values to write. */
+  set: Record<string, unknown>
+  /** The identity predicate, from the pre-image. */
+  where: Record<string, unknown>
+  /** The pre-image of every changed column that SQL can compare. */
+  expect: Record<string, unknown>
+  /**
+   * Changed columns SQL cannot compare — `json` and `buffer`. The server
+   * refuses these in `expect` and demands `force: true` to write them without
+   * a concurrency check, so the UI has to say so rather than retry blindly.
+   */
+  unguardable: string[]
+  /** Edited keys whose value matched what was already there. */
+  unchanged: string[]
+  /** Identity columns the pre-image does not carry. Non-empty means unusable. */
+  missingIdentity: string[]
+}
+
+export type KindLookup = (column: string) => ColumnKind | undefined
+
+/**
+ * Staged edits for the rows currently on screen.
+ *
+ * Bounded by construction: an entry exists only for a row the user has typed
+ * into, they are dropped on save and on revert, and changing table or page
+ * clears the whole session — there is no key here a page of data does not
+ * already hold (convention 6).
+ */
+export class EditSession {
+  private readonly edits = new Map<string, Map<string, unknown>>()
+  private readonly originals = new Map<string, Record<string, unknown>>()
+
+  /**
+   * Record an edited value.
+   *
+   * Staging a value equal to the original **unstages** it, so typing a change
+   * and typing it back leaves the row clean rather than dirty-with-no-diff.
+   * `sameValue` rather than `===`, for the reason its own comment gives: the
+   * original came from a driver and the edit came from an input, and `1` vs
+   * `true` is not an edit the user made.
+   */
+  stage(
+    id: string,
+    original: Record<string, unknown>,
+    column: string,
+    value: unknown,
+  ): void {
+    if (!this.originals.has(id)) this.originals.set(id, original)
+    const pre = this.originals.get(id)!
+    const row = this.edits.get(id) ?? new Map<string, unknown>()
+    if (sameValue(pre[column], value)) row.delete(column)
+    else row.set(column, value)
+    if (row.size) this.edits.set(id, row)
+    else this.drop(id)
+  }
+
+  /** The value to show in a cell: the staged one, else the original. */
+  value(id: string, column: string, fallback: unknown): unknown {
+    const row = this.edits.get(id)
+    return row?.has(column) ? row.get(column) : fallback
+  }
+
+  isStaged(id: string, column: string): boolean {
+    return this.edits.get(id)?.has(column) ?? false
+  }
+
+  changedColumns(id: string): string[] {
+    return [...(this.edits.get(id)?.keys() ?? [])]
+  }
+
+  isDirty(id: string): boolean {
+    return (this.edits.get(id)?.size ?? 0) > 0
+  }
+
+  /** How many rows are dirty. What the header badge and the unload guard read. */
+  dirtyRows(): number {
+    return this.edits.size
+  }
+
+  dirtyIds(): string[] {
+    return [...this.edits.keys()]
+  }
+
+  original(id: string): Record<string, unknown> | undefined {
+    return this.originals.get(id)
+  }
+
+  drop(id: string): void {
+    this.edits.delete(id)
+    this.originals.delete(id)
+  }
+
+  clear(): void {
+    this.edits.clear()
+    this.originals.clear()
+  }
+
+  /**
+   * One row's edits as an UPDATE.
+   *
+   * `where` comes from the pre-image and `set` from the edits, which is what
+   * lets a primary key itself be edited — see `updatePlan`'s own note.
+   */
+  plan(
+    id: string,
+    identity: readonly string[],
+    kindOf: KindLookup,
+  ): RowPlan | null {
+    const original = this.originals.get(id)
+    const edits = this.edits.get(id)
+    if (!original || !edits?.size) return null
+
+    const plan = updatePlan({
+      original,
+      edits: Object.fromEntries(edits),
+      identity,
+    })
+
+    const expect: Record<string, unknown> = {}
+    const unguardable: string[] = []
+    for (const column of Object.keys(plan.set)) {
+      const kind = kindOf(column)
+      // Unknown kind is treated as guardable: the column came out of the
+      // server's own schema report, so an absent entry is a bug rather than a
+      // JSON column, and including it in `expect` fails loudly at validation
+      // instead of silently dropping the concurrency check.
+      if (kind && !comparableKind(kind)) unguardable.push(column)
+      else expect[column] = original[column]
+    }
+
+    return { ...plan, expect, unguardable }
+  }
+}
+
+export interface UndoEntry {
+  label: string
+  /** Runs the inverse. Rejects like any other request; the caller reports it. */
+  undo: () => Promise<void>
+}
+
+/**
+ * The last twenty things that happened, newest first.
+ *
+ * Twenty rather than unlimited because each entry closes over a row's
+ * pre-image, and an unbounded stack of those is exactly the module-level
+ * unbounded cache convention 6 forbids. The pre-image is already being kept for
+ * the concurrency check, so undo costs nothing extra to record — only to keep.
+ */
+export class UndoStack {
+  private readonly entries: UndoEntry[] = []
+
+  constructor(readonly limit = 20) {}
+
+  push(entry: UndoEntry): void {
+    this.entries.unshift(entry)
+    if (this.entries.length > this.limit) this.entries.length = this.limit
+  }
+
+  get size(): number {
+    return this.entries.length
+  }
+
+  peek(): UndoEntry | undefined {
+    return this.entries[0]
+  }
+
+  pop(): UndoEntry | undefined {
+    return this.entries.shift()
+  }
+
+  clear(): void {
+    this.entries.length = 0
+  }
+}

package/src/client/editors.ts

@@ -0,0 +1,283 @@
+/**
+ * One editor per `WidgetKind`, chosen through a record rather than an if-chain.
+ *
+ * **The null toggle is the point of this module.** Every editor here carries a
+ * `∅` button that is *separate from the input*, because SQL NULL and the empty
+ * string are different values, the server enforces the difference
+ * (`coerce.ts`'s `empty_string` code), and an editor with only a text box can
+ * express one of them. The dashboard's editor read every cell as a string, so
+ * clearing a field wrote `''` into a numeric column and got `0`.
+ */
+
+import { coerceValue } from '../shared/coerce'
+import { el, on } from './dom'
+import {
+  columnKind,
+  columnMeta,
+  type SchemaColumn,
+  type WidgetKind,
+} from './meta'
+
+export interface EditorHooks {
+  /** Every keystroke's worth: stage into the row buffer, never save. */
+  onInput: (value: unknown) => void
+  /** Forwarded to the grid's reducer. The editor decides nothing itself. */
+  onKey: (event: KeyboardEvent) => void
+}
+
+export interface EditorHandle {
+  node: HTMLElement
+  focus: () => void
+  /** The current value, already NULL-aware. Not coerced — that is the caller's. */
+  read: () => unknown
+}
+
+interface Control {
+  /** The focusable element. */
+  input: HTMLElement
+  read: () => unknown
+  /** Put a non-null value back after the null toggle is switched off. */
+  write: (value: unknown) => void
+}
+
+type Factory = (column: SchemaColumn, value: unknown) => Control
+
+/** `<input type=text>` with the value pre-filled as text, the common case. */
+function textControl(_column: SchemaColumn, value: unknown): Control {
+  const input = el('input', { class: 'ed' })
+  input.type = 'text'
+  input.value = value === null || value === undefined ? '' : String(value)
+  return {
+    input,
+    read: () => input.value,
+    write: next => {
+      input.value = next === null || next === undefined ? '' : String(next)
+    },
+  }
+}
+
+/**
+ * The same text column, in a box you can actually read.
+ *
+ * Used **only by the row panel**, which is where a description or a rendered
+ * template is edited; the grid keeps the one-line input because a textarea in a
+ * table cell breaks row height and the Tab-commits-right key model. Opting in
+ * rather than switching on the value's current length matters: a column whose
+ * first row happens to be short would otherwise get a different editor from the
+ * same column two rows down.
+ */
+function longTextControl(_column: SchemaColumn, value: unknown): Control {
+  const input = el('textarea', { class: 'ed ed-long' })
+  input.rows = 5
+  input.value = value === null || value === undefined ? '' : String(value)
+  return {
+    input,
+    read: () => input.value,
+    write: next => {
+      input.value = next === null || next === undefined ? '' : String(next)
+    },
+  }
+}
+
+function enumControl(column: SchemaColumn, value: unknown): Control {
+  const input = el('select', { class: 'ed' })
+  for (const option of column.enum ?? []) {
+    const item = el('option', { text: option })
+    item.value = option
+    item.selected = option === value
+    input.appendChild(item)
+  }
+  return {
+    input,
+    read: () => input.value,
+    write: next => {
+      input.value = String(next ?? '')
+    },
+  }
+}
+
+/**
+ * A checkbox, and it reads back a real boolean.
+ *
+ * A driver hands a boolean column back as `1`/`0` on SQLite and MySQL, so the
+ * *initial* state has to accept those spellings — but what leaves here is
+ * `true`/`false`, which is what `coerceValue` wants and what makes `sameValue`
+ * agree that nothing changed when nothing did.
+ */
+function booleanControl(_column: SchemaColumn, value: unknown): Control {
+  const input = el('input', { class: 'ed ed-check' })
+  input.type = 'checkbox'
+  input.checked =
+    value === true || value === 1 || value === '1' || value === 'true'
+  return {
+    input,
+    read: () => input.checked,
+    write: next => {
+      input.checked = next === true || next === 1
+    },
+  }
+}
+
+/**
+ * `datetime-local`, fed and read in the format that control insists on.
+ *
+ * It refuses an ISO string with a `Z` and refuses one carrying milliseconds, so
+ * the value is trimmed to `YYYY-MM-DDTHH:mm` going in and handed back as a full
+ * ISO string going out — `coerceValue`'s `date` branch parses either, but the
+ * round trip has to be lossless in the direction the user sees.
+ */
+function dateControl(_column: SchemaColumn, value: unknown): Control {
+  const input = el('input', { class: 'ed' })
+  input.type = 'datetime-local'
+  input.value = toLocalInput(value)
+  return {
+    input,
+    read: () => (input.value ? new Date(input.value).toISOString() : ''),
+    write: next => {
+      input.value = toLocalInput(next)
+    },
+  }
+}
+
+function toLocalInput(value: unknown): string {
+  if (value === null || value === undefined || value === '') return ''
+  const date = value instanceof Date ? value : new Date(String(value))
+  if (Number.isNaN(date.getTime())) return ''
+  // Local, not UTC: the control shows local time, so feeding it a UTC string
+  // shifts every timestamp by the viewer's offset the moment it is opened.
+  const pad = (n: number) => String(n).padStart(2, '0')
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+    `T${pad(date.getHours())}:${pad(date.getMinutes())}`
+  )
+}
+
+/** A textarea, because a JSON document does not fit on one line. */
+function jsonControl(_column: SchemaColumn, value: unknown): Control {
+  const input = el('textarea', { class: 'ed ed-json' })
+  input.rows = 6
+  input.value = jsonText(value)
+  return {
+    input,
+    read: () => input.value,
+    write: next => {
+      input.value = jsonText(next)
+    },
+  }
+}
+
+function jsonText(value: unknown): string {
+  if (value === null || value === undefined) return ''
+  if (typeof value === 'string') return value
+  try {
+    return JSON.stringify(value, null, 2)
+  } catch {
+    // Cyclic or BigInt-bearing. The textarea still needs something to show,
+    // and the underlying value is not touched by what is displayed.
+    return String(value)
+  }
+}
+
+const CONTROLS: Record<WidgetKind, Factory> = {
+  enum: enumControl,
+  boolean: booleanControl,
+  date: dateControl,
+  json: jsonControl,
+  text: textControl,
+}
+
+export interface EditorOptions {
+  /**
+   * Render a `text` column as a textarea. The row panel passes this; the grid
+   * does not, because a textarea in a table cell breaks the row height and the
+   * Tab-commits-right key model.
+   */
+  multiline?: boolean
+}
+
+/**
+ * An editor for one cell.
+ *
+ * The wrapper owns three things the control does not: the null toggle, the
+ * validity message, and key forwarding. Validation runs `coerceValue` — the
+ * same function the server runs — so the message the user sees before sending
+ * is the message they would have got back.
+ */
+export function createEditor(
+  column: SchemaColumn,
+  value: unknown,
+  hooks: EditorHooks,
+  options: EditorOptions = {},
+): EditorHandle {
+  const meta = columnMeta(column)
+  const wrap = el('div', { class: 'editor' })
+  const kind = columnKind(column)
+  const factory =
+    options.multiline && kind === 'text' ? longTextControl : CONTROLS[kind]
+  const control = factory(column, value)
+  let isNull = value === null || value === undefined
+  let lastNonNull: unknown = isNull ? '' : control.read()
+
+  const note = el('div', { class: 'ed-note' })
+  const nullToggle = el('button', {
+    class: 'ed-null',
+    text: '∅',
+    title: column.nullable
+      ? 'set SQL NULL (not the empty string)'
+      : 'this column cannot be NULL',
+    attrs: { 'aria-pressed': String(isNull), 'aria-label': 'null' },
+  })
+  nullToggle.type = 'button'
+  nullToggle.disabled = !column.nullable
+
+  const read = () => (isNull ? null : control.read())
+
+  /**
+   * `touched` is why the initial paint does not call `onInput`.
+   *
+   * Two consumers break if merely *opening* an editor counts as input. The
+   * insert dialog decides whether to send a column at all from whether it was
+   * given a value, so an opening notification would put every column in the
+   * record as null and defeat every default in the schema. And a real `DATE`
+   * column round trips through `datetime-local` as a different string than the
+   * driver returned, so the row panel would mark a row dirty for opening it.
+   */
+  const refresh = (touched: boolean) => {
+    ;(control.input as HTMLInputElement).disabled = isNull
+    nullToggle.setAttribute('aria-pressed', String(isNull))
+    wrap.classList.toggle('is-null', isNull)
+    const current = read()
+    const result = coerceValue(current, meta)
+    note.textContent = result.ok ? '' : result.message
+    wrap.classList.toggle('invalid', !result.ok)
+    control.input.setAttribute('aria-invalid', String(!result.ok))
+    if (touched) hooks.onInput(current)
+  }
+
+  on(nullToggle, 'click', () => {
+    if (!isNull) lastNonNull = control.read()
+    isNull = !isNull
+    if (!isNull) control.write(lastNonNull)
+    refresh(true)
+    control.input.focus()
+  })
+
+  control.input.addEventListener('input', () => refresh(true))
+  control.input.addEventListener('change', () => refresh(true))
+  control.input.addEventListener('keydown', event => {
+    hooks.onKey(event as KeyboardEvent)
+  })
+
+  wrap.append(control.input, nullToggle, note)
+  // Paints the initial validity only. See the note on `touched`.
+  refresh(false)
+
+  return {
+    node: wrap,
+    focus: () => {
+      control.input.focus()
+      if (control.input instanceof HTMLInputElement) control.input.select()
+    },
+    read,
+  }
+}