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

package/src/client/bulk.ts

@@ -0,0 +1,357 @@
+/**
+ * Actions over a selection: set one column across it, delete it, or add rows.
+ *
+ * **Every count that reaches a dialog comes from a `dryRun`.** The server
+ * executes the statements inside a transaction and rolls back, so the number is
+ * what would actually happen — not the number of checkboxes, which is the same
+ * number only when nothing has changed underneath and no key has gone missing.
+ * `confirm.ts` turns that count into the right amount of ceremony.
+ */
+
+import { coerceValue, omittableOnInsert } from '../shared/coerce'
+import { bulkEdit, deleteRows, insertRows, messageOf } from './api'
+import { confirmDanger, notify, offerUndo } from './confirm'
+import { append, box, button, each, el, select } from './dom'
+import type { UndoStack } from './edit-session'
+import { createEditor } from './editors'
+import { columnMeta, type SchemaColumn, type SchemaTable } from './meta'
+
+export interface BulkContext {
+  table: SchemaTable
+  columns: SchemaColumn[]
+  editable: boolean
+  selectedKeys: () => Record<string, unknown>[]
+  selectedRows: () => Record<string, unknown>[]
+  reload: () => Promise<void>
+  undo: UndoStack
+  openImport: () => void
+}
+
+export interface BulkToolbar {
+  node: HTMLElement
+  setCount: (count: number) => void
+}
+
+export function bulkToolbar(ctx: BulkContext): BulkToolbar {
+  const node = box('toolbar')
+  const count = el('span', { class: 'note' })
+
+  if (!ctx.editable) {
+    node.appendChild(
+      el('span', { class: 'note', text: ctx.table.reason ?? 'read-only' }),
+    )
+    return { node, setCount: () => {} }
+  }
+
+  const setColumn = button('Set column…', () => void openSetColumn(ctx), {
+    class: 'btn',
+  })
+  const remove = button('Delete', () => void runDelete(ctx), {
+    class: 'btn danger-btn',
+  })
+  const add = button('Add rows…', () => openInsert(ctx), { class: 'btn' })
+  const importer = button('Import CSV…', ctx.openImport, { class: 'btn' })
+
+  append(node, [add, importer, setColumn, remove, count])
+
+  const setCount = (selected: number) => {
+    count.textContent = selected ? `${selected} selected` : ''
+    setColumn.disabled = selected === 0
+    remove.disabled = selected === 0
+  }
+  setCount(0)
+  return { node, setCount }
+}
+
+// ------------------------------------------------------------ set one column
+
+/**
+ * One column, one value, across the selection.
+ *
+ * The value goes through the same editor the grid uses, so an enum is a select
+ * and a nullable column can be set to NULL — the operation people actually
+ * reach for and the one a plain text prompt cannot express.
+ */
+async function openSetColumn(ctx: BulkContext): Promise<void> {
+  const editable = ctx.columns.filter(column => !column.autoIncrement)
+  const first = editable[0]
+  if (!first) return
+
+  const dialog = el('dialog', { class: 'danger' })
+  dialog.appendChild(el('h3', { text: 'Set a column across the selection' }))
+
+  let column = first
+  let value: unknown = null
+  const slot = box('panel-field')
+
+  const paint = () => {
+    slot.replaceChildren()
+    const editor = createEditor(column, null, {
+      onInput: next => {
+        value = next
+      },
+      onKey: () => {},
+    })
+    slot.appendChild(editor.node)
+    value = editor.read()
+  }
+
+  const picker = select(
+    editable.map(c => ({ value: c.name, label: `${c.name} — ${c.type}` })),
+    column.name,
+    name => {
+      column = editable.find(c => c.name === name) ?? column
+      paint()
+    },
+  )
+  paint()
+
+  const apply = button(
+    'Apply',
+    () => {
+      dialog.close()
+      void applySetColumn(ctx, column, value)
+    },
+    { class: 'btn primary' },
+  )
+  const cancel = button('Cancel', () => dialog.close(), { class: 'btn' })
+  const bar = box('row-bar', cancel, apply)
+  append(dialog, [picker, slot, bar])
+
+  document.body.appendChild(dialog)
+  dialog.addEventListener('close', () => dialog.remove())
+  dialog.showModal()
+}
+
+async function applySetColumn(
+  ctx: BulkContext,
+  column: SchemaColumn,
+  value: unknown,
+): Promise<void> {
+  const check = coerceValue(value, columnMeta(column))
+  if (!check.ok) {
+    notify(`${column.name}: ${check.message}`, 'error')
+    return
+  }
+
+  const edits = ctx
+    .selectedKeys()
+    .map(key => ({ key, set: { [column.name]: check.value } }))
+  if (!edits.length) return
+
+  const dry = await run(() =>
+    bulkEdit({ table: ctx.table.name, edits, dryRun: true }),
+  )
+  if (!dry) return
+
+  const decision = await confirmDanger({
+    verb: `set ${column.name}`,
+    count: dry.changed,
+    table: ctx.table.name,
+    detail: `to ${describe(check.value)}`,
+  })
+  if (decision.refusal) return notify(decision.refusal, 'error')
+  if (!decision.ok) return
+
+  await run(async () => {
+    const result = await bulkEdit({ table: ctx.table.name, edits })
+    notify(`${result.changed} rows updated`)
+    await ctx.reload()
+  })
+}
+
+function describe(value: unknown): string {
+  if (value === null) return 'NULL'
+  if (typeof value === 'string') return JSON.stringify(value)
+  return String(value)
+}
+
+// -------------------------------------------------------------------- delete
+
+async function runDelete(ctx: BulkContext): Promise<void> {
+  const keys = ctx.selectedKeys()
+  const rows = ctx.selectedRows()
+  if (!keys.length) return
+
+  const dry = await run(() =>
+    deleteRows({ table: ctx.table.name, keys, dryRun: true }),
+  )
+  if (!dry) return
+
+  const decision = await confirmDanger({
+    verb: 'delete',
+    count: dry.deleted,
+    table: ctx.table.name,
+    detail: dry.conflicts.length
+      ? `${dry.conflicts.length} of the selected rows no longer match`
+      : undefined,
+  })
+  if (decision.refusal) return notify(decision.refusal, 'error')
+  if (!decision.ok) return
+
+  await run(async () => {
+    const result = await deleteRows({ table: ctx.table.name, keys })
+    await ctx.reload()
+    offerDeleteUndo(ctx, rows, result.deleted)
+  })
+}
+
+/**
+ * A ten-second offer to put the row back.
+ *
+ * Only for the immediate tier — anything above one row went through a dialog,
+ * and re-inserting a hundred rows from the browser's memory is a second bulk
+ * write dressed up as a safety net. The pre-image is already in hand because
+ * the grid holds the rows it rendered.
+ */
+function offerDeleteUndo(
+  ctx: BulkContext,
+  rows: Record<string, unknown>[],
+  deleted: number,
+): void {
+  if (deleted !== 1 || rows.length !== 1) {
+    notify(`${deleted} rows deleted`)
+    return
+  }
+  const row = rows[0]!
+  const restore = async () => {
+    await run(async () => {
+      await insertRows({ table: ctx.table.name, rows: [row] })
+      await ctx.reload()
+    })
+  }
+  ctx.undo.push({ label: `delete from ${ctx.table.name}`, undo: restore })
+  offerUndo('1 row deleted', restore)
+}
+
+// -------------------------------------------------------------------- insert
+
+/**
+ * Add rows by hand.
+ *
+ * A column is sent only when the user gave it a value or when the database
+ * cannot supply one — `omittableOnInsert` is the same predicate the importer's
+ * blocking check uses. Sending every column would defeat every default in the
+ * schema and would make an auto-increment key impossible to leave alone.
+ */
+function openInsert(ctx: BulkContext): void {
+  const columns = ctx.columns.filter(column => !column.autoIncrement)
+  const dialog = el('dialog', { class: 'danger wide' })
+  dialog.appendChild(el('h3', { text: `Add rows to ${ctx.table.name}` }))
+
+  const list = box('insert-rows')
+  const drafts: Map<string, unknown>[] = []
+
+  const addRow = () => {
+    const draft = new Map<string, unknown>()
+    drafts.push(draft)
+    const row = box('insert-row')
+    row.appendChild(el('span', { class: 'note', text: `row ${drafts.length}` }))
+    each(row, columns, column => insertField(column, draft))
+    list.appendChild(row)
+  }
+  addRow()
+
+  const message = el('p', { class: 'row-error' })
+  const submit = button(
+    'Insert',
+    () => {
+      const built = buildInsertRows(columns, drafts)
+      if (built.errors.length) {
+        message.textContent = built.errors.join('; ')
+        return
+      }
+      dialog.close()
+      void run(async () => {
+        const result = await insertRows({
+          table: ctx.table.name,
+          rows: built.rows,
+        })
+        notify(`${result.inserted} rows inserted`)
+        await ctx.reload()
+      })
+    },
+    { class: 'btn primary' },
+  )
+
+  const bar = box(
+    'row-bar',
+    button('+ row', addRow, { class: 'btn' }),
+    button('Cancel', () => dialog.close(), { class: 'btn' }),
+    submit,
+  )
+  append(dialog, [list, message, bar])
+  document.body.appendChild(dialog)
+  dialog.addEventListener('close', () => dialog.remove())
+  dialog.showModal()
+}
+
+function insertField(column: SchemaColumn, draft: Map<string, unknown>): Node {
+  const wrap = box('panel-field')
+  wrap.appendChild(el('label', { class: 'panel-label', text: column.name }))
+  const editor = createEditor(column, null, {
+    onInput: value => draft.set(column.name, value),
+    onKey: () => {},
+  })
+  wrap.appendChild(editor.node)
+  return wrap
+}
+
+interface BuiltRows {
+  rows: Record<string, unknown>[]
+  errors: string[]
+}
+
+/**
+ * Drafts to records, with the same coercion the server will apply.
+ *
+ * Named rather than inlined into the submit handler because it is the decision
+ * in this file worth stating: an untouched omittable column is *absent* from
+ * the record, and an untouched required one is an error named here rather than
+ * a database exception later.
+ */
+function buildInsertRows(
+  columns: readonly SchemaColumn[],
+  drafts: readonly Map<string, unknown>[],
+): BuiltRows {
+  const rows: Record<string, unknown>[] = []
+  const errors: string[] = []
+
+  drafts.forEach((draft, index) => {
+    const record: Record<string, unknown> = {}
+    for (const column of columns) {
+      const meta = columnMeta(column)
+      const given = draft.has(column.name)
+      if (!given && omittableOnInsert(meta)) continue
+      const result = coerceValue(draft.get(column.name) ?? null, meta)
+      if (!result.ok) {
+        errors.push(`row ${index + 1} · ${column.name}: ${result.message}`)
+        continue
+      }
+      record[column.name] = result.value
+    }
+    rows.push(record)
+  })
+
+  return { rows, errors }
+}
+
+// ------------------------------------------------------------------ plumbing
+
+/**
+ * Run a call, reporting its failure rather than throwing at the click handler.
+ *
+ * A rejected promise from an event listener is an unhandled rejection and a
+ * silent no-op on screen, which is the one outcome a destructive action must
+ * not have. `null` is the failure, so a dry run's caller checks the result and
+ * an action's caller ignores it — they were two identically-bodied functions
+ * until the second was noticed to be the first with the value discarded.
+ */
+async function run<T>(call: () => Promise<T>): Promise<T | null> {
+  try {
+    return await call()
+  } catch (error) {
+    notify(messageOf(error), 'error')
+    return null
+  }
+}

package/src/client/cell.ts

@@ -0,0 +1,139 @@
+/**
+ * Keyboard navigation, as a reducer.
+ *
+ * **Pure, and the reason it exists apart from the grid.** A key handler that
+ * reads the DOM to decide what to do can only be tested by building a DOM;
+ * this one takes a plain `{key, shiftKey}` and a plain cursor and answers with
+ * an action, so `cell.test.ts` pins the whole interaction model — including the
+ * two rules that are easy to regress, *Enter commits and moves down* and
+ * *blur is not in this table at all* — without happy-dom.
+ *
+ * **Blur is deliberately absent.** The dashboard saves on blur, so a stray
+ * click into another cell is a write, and a three-column edit is three
+ * statements with two moments in between where the row is half-updated. Here
+ * blur only stages into the row's dirty buffer; the only things that commit are
+ * Enter, Tab, and the row's own Save button.
+ */
+
+/** The parts of a `KeyboardEvent` this reducer reads. Nothing DOM-shaped. */
+export interface KeyEvent {
+  key: string
+  shiftKey?: boolean
+  ctrlKey?: boolean
+  metaKey?: boolean
+  altKey?: boolean
+}
+
+export interface CellState {
+  row: number
+  col: number
+  /** Rows on the current page. */
+  rows: number
+  /** Columns in the grid. */
+  cols: number
+  /** Is an editor open on the focused cell? */
+  editing: boolean
+  /** May this table be edited at all? Decided once, before first paint. */
+  editable: boolean
+}
+
+export type CellAction =
+  | { type: 'none' }
+  | { type: 'move'; row: number; col: number }
+  | { type: 'edit' }
+  /** Write the editor's value into the row buffer, then move. */
+  | { type: 'commit'; move: 'down' | 'right' | 'left' | 'none' }
+  /** Throw the editor's value away and restore the cell. */
+  | { type: 'cancel' }
+  /** Stage SQL NULL — distinct from staging the empty string. */
+  | { type: 'null' }
+
+const NONE: CellAction = { type: 'none' }
+
+type Rule = (event: KeyEvent, state: CellState) => CellAction
+
+function clamp(value: number, max: number): number {
+  if (value < 0) return 0
+  return value > max ? max : value
+}
+
+/** A move, or nothing when the cursor is already against that edge. */
+function moveBy(
+  state: CellState,
+  rowStep: number,
+  colStep: number,
+): CellAction {
+  const row = clamp(state.row + rowStep, state.rows - 1)
+  const col = clamp(state.col + colStep, state.cols - 1)
+  if (row === state.row && col === state.col) return NONE
+  return { type: 'move', row, col }
+}
+
+function moveTo(state: CellState, row: number, col: number): CellAction {
+  const next = {
+    row: clamp(row, state.rows - 1),
+    col: clamp(col, state.cols - 1),
+  }
+  if (next.row === state.row && next.col === state.col) return NONE
+  return { type: 'move', ...next }
+}
+
+/** Only when the table is editable — a read-only grid still navigates. */
+function whenEditable(action: CellAction): Rule {
+  return (_event, state) => (state.editable ? action : NONE)
+}
+
+/**
+ * While an editor is open. Four keys, and everything else belongs to the input
+ * — a `default` that swallowed keys here would make the editor unable to
+ * receive a literal `a`.
+ */
+const EDITING: Record<string, Rule> = {
+  Enter: () => ({ type: 'commit', move: 'down' }),
+  Tab: event => ({ type: 'commit', move: event.shiftKey ? 'left' : 'right' }),
+  Escape: () => ({ type: 'cancel' }),
+}
+
+/** While a cell is merely selected. */
+const BROWSING: Record<string, Rule> = {
+  ArrowUp: (_e, state) => moveBy(state, -1, 0),
+  ArrowDown: (_e, state) => moveBy(state, 1, 0),
+  ArrowLeft: (_e, state) => moveBy(state, 0, -1),
+  ArrowRight: (_e, state) => moveBy(state, 0, 1),
+  Tab: (event, state) => moveBy(state, 0, event.shiftKey ? -1 : 1),
+  Home: (event, state) => moveTo(state, event.ctrlKey ? 0 : state.row, 0),
+  End: (event, state) =>
+    moveTo(state, event.ctrlKey ? state.rows - 1 : state.row, state.cols - 1),
+  PageUp: (_e, state) => moveBy(state, -10, 0),
+  PageDown: (_e, state) => moveBy(state, 10, 0),
+  Enter: whenEditable({ type: 'edit' }),
+  F2: whenEditable({ type: 'edit' }),
+  // Delete stages NULL rather than clearing to `''`. They are different
+  // values, the server enforces the difference, and a grid that offers only
+  // one of them cannot express the other.
+  Delete: whenEditable({ type: 'null' }),
+}
+
+/**
+ * One key, one action.
+ *
+ * An empty page answers `none` for everything: a cursor over zero rows has no
+ * valid position, and returning a move to `-1` would be a subscript the caller
+ * has to guard at every call site instead of here once.
+ */
+export function keyOnCell(event: KeyEvent, state: CellState): CellAction {
+  if (state.rows <= 0 || state.cols <= 0) return NONE
+  const rule = (state.editing ? EDITING : BROWSING)[event.key]
+  return rule ? rule(event, state) : NONE
+}
+
+/** Where a `commit` leaves the cursor. Same clamping as a bare move. */
+export function afterCommit(
+  state: CellState,
+  move: 'down' | 'right' | 'left' | 'none',
+): CellAction {
+  if (move === 'down') return moveBy(state, 1, 0)
+  if (move === 'right') return moveBy(state, 0, 1)
+  if (move === 'left') return moveBy(state, 0, -1)
+  return NONE
+}

package/src/client/confirm.ts

@@ -0,0 +1,203 @@
+/**
+ * Friction proportionate to blast radius, in the spirit of `db:sync`'s DANGER
+ * ZONE.
+ *
+ * `frictionFor` is **pure and tested**; the dialog below is the DOM half. The
+ * split matters because the ladder is policy — the thresholds are the answer to
+ * "how bad is this if it was a mis-click" — and policy that lives inside a
+ * click handler cannot be asserted.
+ *
+ * **The count fed to this must come from a `dryRun`, never from the page.** A
+ * selection of eight checkboxes on a filtered page can delete eight rows or,
+ * if the caller built the keys from something wider, rather more; the server's
+ * own preview is the only number that is the number.
+ */
+
+import { button, el } from './dom'
+
+export type Friction = 'immediate' | 'confirm' | 'typed' | 'refuse'
+
+/**
+ * How much ceremony `count` rows deserve.
+ *
+ * - **≤ 1** — immediate, with an undo. One row is recoverable and a dialog per
+ *   row makes the tool unusable for the thing it is for.
+ * - **2–100** — a dialog naming the count and what changes.
+ * - **101–10 000** — the same, plus typing the table name. At this size the
+ *   user is doing something deliberate and should have to prove it.
+ * - **> 10 000** — refused. Not a dialog: there is no phrasing of "are you
+ *   sure" that makes a ten-thousand-row unreviewed write a good idea, and the
+ *   honest answer is to narrow it with a filter.
+ */
+export function frictionFor(count: number): Friction {
+  if (!Number.isFinite(count) || count <= 1) return 'immediate'
+  if (count <= 100) return 'confirm'
+  if (count <= 10_000) return 'typed'
+  return 'refuse'
+}
+
+export interface DangerRequest {
+  /** What is about to happen, in the user's words: `delete`, `set status`. */
+  verb: string
+  /** The exact count, from a dry run. */
+  count: number
+  table: string
+  /** A second line: which column, which filter, whatever narrows it. */
+  detail?: string
+}
+
+export interface DangerOutcome {
+  ok: boolean
+  /** Present when refused by the ladder rather than by the user. */
+  refusal?: string
+}
+
+/**
+ * Ask, at the level `frictionFor` decided.
+ *
+ * Returns rather than throws, and returns `{ok: false}` for a dismissal and for
+ * a refusal alike — the caller does one check. The refusal carries its reason
+ * so the message names the ceiling instead of failing silently.
+ */
+export async function confirmDanger(
+  request: DangerRequest,
+): Promise<DangerOutcome> {
+  const level = frictionFor(request.count)
+  if (level === 'immediate') return { ok: true }
+  if (level === 'refuse') {
+    return {
+      ok: false,
+      refusal:
+        `${request.count} rows is past the ${(10_000).toLocaleString()} row ` +
+        'ceiling for one action — narrow it with a filter',
+    }
+  }
+  const ok = await openDialog(request, level === 'typed')
+  return { ok }
+}
+
+/**
+ * Ask, unconditionally.
+ *
+ * For the questions that are not about blast radius. Discarding one row of
+ * unsaved typing deserves a prompt even though `frictionFor(1)` is `immediate`
+ * — the ladder is about how much damage a mis-click does to the *database*,
+ * and this one is about work the user has done and the database has not seen.
+ */
+export async function confirmChoice(request: DangerRequest): Promise<boolean> {
+  return await openDialog(request, false)
+}
+
+/**
+ * A modal `<dialog>`.
+ *
+ * The native element rather than a hand-rolled overlay: it traps focus, closes
+ * on Escape, and is inert to the page behind it without a single line of
+ * script. Resolved through a `close` listener so a dismissal by any route —
+ * Escape, the backdrop, the button — lands in one place.
+ */
+function openDialog(request: DangerRequest, typed: boolean): Promise<boolean> {
+  const dialog = el('dialog', { class: 'danger' })
+  const title = el('h3', {
+    text: `${request.verb} ${request.count.toLocaleString()} row${
+      request.count === 1 ? '' : 's'
+    }`,
+  })
+  const where = el('p', {
+    class: 'note',
+    text: `in ${request.table}${request.detail ? ` · ${request.detail}` : ''}`,
+  })
+  dialog.append(title, where)
+
+  let accepted = false
+  const confirm = button(
+    request.verb,
+    () => {
+      accepted = true
+      dialog.close()
+    },
+    { class: 'btn danger-btn' },
+  )
+
+  if (typed) {
+    const prompt = el('p', {
+      class: 'note',
+      text: `Type ${request.table} to confirm.`,
+    })
+    const input = el('input', { class: 'ed' })
+    input.type = 'text'
+    input.setAttribute('aria-label', 'table name')
+    confirm.disabled = true
+    input.addEventListener('input', () => {
+      confirm.disabled = input.value.trim() !== request.table
+    })
+    dialog.append(prompt, input)
+  }
+
+  const cancel = button('Cancel', () => dialog.close(), { class: 'btn' })
+  const bar = el('div', { class: 'row-bar' })
+  bar.append(cancel, confirm)
+  dialog.appendChild(bar)
+
+  // `settle` is narrowed to `(value: boolean) => void` rather than used as the
+  // executor's own `resolve`, whose parameter is `boolean | PromiseLike<boolean>`
+  // — calling that reads as an unhandled promise to the floating-promise rule.
+  let settle: (value: boolean) => void = () => {}
+  const answered = new Promise<boolean>(resolve => {
+    settle = resolve
+  })
+  dialog.addEventListener('close', () => {
+    dialog.remove()
+    settle(accepted)
+  })
+
+  document.body.appendChild(dialog)
+  dialog.showModal()
+  return answered
+}
+
+/**
+ * A short-lived bar offering to put one thing back.
+ *
+ * Ten seconds, and the timer is the undo window rather than a toast animation:
+ * the action already happened. Returns a disposer so a second action can
+ * retire the first offer instead of stacking two.
+ */
+export function offerUndo(
+  message: string,
+  undo: () => Promise<void>,
+  seconds = 10,
+): () => void {
+  const bar = el('div', { class: 'undo-bar', attrs: { role: 'status' } })
+  bar.appendChild(el('span', { text: message }))
+
+  const remove = () => {
+    clearTimeout(timer)
+    bar.remove()
+  }
+  bar.appendChild(
+    button(
+      'Undo',
+      () => {
+        remove()
+        void undo()
+      },
+      { class: 'btn' },
+    ),
+  )
+
+  const timer = setTimeout(remove, seconds * 1000)
+  document.body.appendChild(bar)
+  return remove
+}
+
+/** A message that is not a question. Used for a refusal and for a failure. */
+export function notify(message: string, kind: 'info' | 'error' = 'info'): void {
+  const bar = el('div', {
+    class: `undo-bar ${kind}`,
+    text: message,
+    attrs: { role: kind === 'error' ? 'alert' : 'status' },
+  })
+  document.body.appendChild(bar)
+  setTimeout(() => bar.remove(), 6000)
+}