Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

29.3 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// DATA VALIDATION — what may be ENTERED into a cell, and what happens when
// something else is.
//
// Excel's feature of the same name: a list (which draws an in-cell dropdown),
// a number range, a date range, a text length, or a formula. This is the
// single most common thing in a SHARED workbook — "Status must be one of
// Open/Won/Lost" earns its keep precisely when four people are typing into the
// same sheet — which is why it belongs in dash rather than being an Excel
// nicety to copy later.
//
// ═══ THREE THINGS IN THIS REPO ARE CALLED VALIDATION AND THIS IS NONE OF THE
//     OTHER TWO ══════════════════════════════════════════════════════════════
//
//   * `validate.ts` is DOCUMENT validation — `window.bento.validate()`, "does
//     this workbook agree with itself": a column shorter than the sheet has
//     rows, a dictionary index past the end of its dict. It answers a question
//     about a FILE. This file answers a question about a KEYSTROKE. Nothing
//     here is added to its findings and nothing there reads these rules.
//   * `isOneOf` (model.ts) is a FILTER predicate — which rows to SHOW. A list
//     rule and a one-of filter both hold a set of strings and mean opposite
//     things: one hides rows that do not match, the other refuses values that
//     do not match and hides nothing.
//   * This file.
//
// Where a rule LIVES, and why the two sheet kinds are not symmetric, is
// argued in model.ts's DATA VALIDATION block beside the types. The short
// version: a dataset's rule is on the COLUMN (a narrowing of the column type,
// written with `setColumn`), a spreadsheet's is on a RANGE in a sheet-level
// list (written with `setSheetProps`). No new patch op exists, because a rule
// belongs to a thing the format already has an op for.
//
// ═══ REJECT vs WARN, WHICH IS THE DECISION THIS FILE EXISTS TO HOLD ════════
//
// Excel offers "Stop" (refuse the entry) and "Warning" (allow it). Both make
// sense on one machine with one keyboard. On a LIVE COLLABORATIVE document a
// hard reject is a trap, and it has to be said exactly where the trap is:
//
//   A REJECT THAT RUNS ON APPLY IS EITHER A DIVERGENCE OR A SILENT DISCARD.
//
// A remote op has already been committed by the peer who made it, and every
// other replica will apply it. A replica that refused it would hold different
// content from everyone else while being certain it was right — which is worse
// than a wrong value, because a wrong value is visible and a divergence is
// not. And if the refusal happened quietly, the peer's edit would be gone from
// one screen and present on another with nothing on either saying so.
//
// So dash's reject is scoped to the one place refusing costs nobody anything:
//
//   * `reject` refuses AT THE KEYBOARD, in the cell editor, while the text is
//     still under the author's own hands. The editor stays OPEN with what they
//     typed and says why. Nothing is committed, so nothing is discarded — the
//     author still has their text, and Escape abandons it as it always did.
//   * EVERY OTHER PATH DEGRADES TO WARN: a paste, a fill, an import, an undo,
//     and above all a remote CRDT op. The value lands and the cell is MARKED.
//     (Rejecting one cell of a five-hundred-cell paste would also be its own
//     small disaster: a hole in the middle of a block nobody can see.)
//
// That is the whole rule, and it is why `DataRule.on` is not simply Excel's
// `errorStyle` under another name.
//
// ═══ DATA THAT ALREADY BREAKS A RULE YOU JUST ADDED ════════════════════════
//
// It is MARKED, never deleted and never suspended. Deleting is data loss;
// silently accepting makes the rule a lie. Excel's answer is a one-shot
// "Circle Invalid Data" command; dash's marker is always on, because a circle
// you have to ask for is a circle nobody asks for.
//
// The mark is DERIVED AT PAINT TIME and never stored. A stored flag is stale
// the instant either the value or the rule changes, it costs bytes in a map
// whose promise is sparseness, and under collaboration it would be a second
// register saying something the first two already imply. `violationOf` is
// called for the painted window only — tens of cells — and the panel's
// whole-column count is capped (`SCAN_CAP`) so a rule on a million-row sheet
// cannot cost a frame.
//
// ═══ WHAT THIS BUILD DOES NOT CHECK ════════════════════════════════════════
//
// `kind: 'formula'`. It is parsed, kept verbatim, shown in the panel, and
// round-tripped to and from .xlsx — the `CellOverride.xlsxF` bargain exactly:
// keeping what the file said is what stops a round trip from quietly deleting
// somebody's model. It is not EVALUATED, and the panel says so in a note
// rather than leaving a reader to discover it. Excel evaluates a custom
// formula with the cell under test as an implicit argument in that worksheet's
// coordinate space; doing that here needs a substitution hook in
// cellformula.ts (evaluate this expression with THIS cell holding a candidate
// value that is not in the document yet), which does not exist. A rule that is
// right most of the time is worse than one that says it is not checked —
// xlsx.ts makes the identical argument about translating column formulas.

// NO STYLESHEET IMPORT HERE, deliberately. xlsx.ts imports this module for the
// import/export mapping, and xlsx.ts's rig runs in plain node with no Vite and
// no css loader — so a `import './datavalid.css'` in this file breaks a rig
// that has nothing to do with stylesheets. The sheet is imported by grid.ts,
// which is where the markup it styles is emitted, and every rig that mounts the
// grid already stubs css because find.ts has always brought one along.
import { t } from './i18n.ts'
import { colToLetters, parseRange, parseRef } from './a1.ts'
import type {
  CanvasSheet, Column, DataRule, DataRuleKind, RangeValidation, TableSheet,
} from './model.ts'
import type { Patch } from './store.ts'
import type { SetSheetProps } from './rowcol.ts'

export type { DataRule, DataRuleKind, RangeValidation }

/** Rule kinds this build offers in the panel. `formula` is carried, not made. */
export const RULE_KINDS = ['list', 'number', 'date', 'textLength'] as const

/** Cells the panel's "how many already break this" count will read. The status
 *  bar's `SUMMARY_MAX` reasoning: a dataset is bounded by the file, and a count
 *  recomputed on every document event must not be O(million). */
export const SCAN_CAP = 200_000

/** How many list entries the in-cell dropdown will draw before it stops. A
 *  list is a hand-written set of choices; ten thousand of them is a lookup
 *  table someone pasted, and a menu that long is unusable rather than useful. */
export const LIST_CAP = 500

// --- reading a rule out of an untrusted document ----------------------------
//
// A document is untrusted input (kernel #277, docs/PLATFORM.md). Everything
// below comes out of the file, reaches a `title=` attribute and a menu label,
// and decides whether an edit is refused — so it is read through a guard
// rather than cast. An unreadable rule is treated as NO RULE: refusing to open
// the sheet would be a file nobody can repair, and enforcing a rule we could
// not parse would refuse entries for a reason nobody can see.

const str = (v: unknown): string | undefined =>
  typeof v === 'string' && v !== '' ? v : undefined

const bound = (v: unknown): number | string | undefined => {
  if (typeof v === 'number' && Number.isFinite(v)) return v
  const s = str(v)
  return s === undefined ? undefined : s
}

/**
 * Read one rule. Returns `null` for anything this build cannot make sense of.
 *
 * UNKNOWN KEYS SURVIVE. The returned object is the stored one re-read field by
 * field PLUS whatever else it carried, because a rule written by a later build
 * must round-trip untouched (PLATFORM §3) — including the extras it holds.
 */
export function readRule(v: unknown): DataRule | null {
  if (!v || typeof v !== 'object' || Array.isArray(v)) return null
  const raw = v as Record<string, unknown>
  const kind = str(raw.kind)
  if (kind === undefined) return null
  const out: DataRule = { ...raw, kind }
  const list = Array.isArray(raw.list)
    ? raw.list.filter((x): x is string => typeof x === 'string')
    : undefined
  if (list) out.list = list
  else delete out.list
  const min = bound(raw.min)
  const max = bound(raw.max)
  if (min === undefined) delete out.min; else out.min = min
  if (max === undefined) delete out.max; else out.max = max
  const f = str(raw.formula)
  if (f === undefined) delete out.formula; else out.formula = f
  const msg = str(raw.message)
  if (msg === undefined) delete out.message; else out.message = msg
  if (raw.blank === false) out.blank = false; else delete out.blank
  if (raw.noDropdown === true) out.noDropdown = true; else delete out.noDropdown
  out.on = raw.on === 'reject' ? 'reject' : 'warn'
  // A list rule with no list refuses everything, which is not a rule anyone
  // meant to write — and it would make every cell in the column red the moment
  // a `list: []` reached the file.
  if (kind === 'list' && !out.list?.length) return null
  return out
}

/** The rule on a DATASET column, if it carries a readable one. */
export const columnRule = (col: Column | undefined): DataRule | null =>
  col ? readRule((col as { validate?: unknown }).validate) : null

/**
 * A SPREADSHEET's rule list, read defensively.
 *
 * Entries whose `ref` will not parse are DROPPED from the working list and
 * left in the file: a range this build cannot read is not a range it should
 * enforce, and deleting it on the next save would throw away a rule a
 * different build understands.
 */
export function canvasRules(sheet: CanvasSheet | undefined): RangeValidation[] {
  const raw = (sheet as { validations?: unknown } | undefined)?.validations
  if (!Array.isArray(raw)) return []
  const out: RangeValidation[] = []
  for (const e of raw) {
    if (!e || typeof e !== 'object') continue
    const ref = str((e as Record<string, unknown>).ref)
    const rule = readRule((e as Record<string, unknown>).rule)
    if (!ref || !rule || !refBox(ref)) continue
    out.push({ ...(e as RangeValidation), ref, rule })
  }
  return out
}

export interface RefBox { top: number; left: number; bottom: number; right: number }

/** `B2:B100`, `B2`, or nothing. Zero-based and inclusive, normalised so a
 *  range dragged upwards means the same thing as one dragged down. */
export function refBox(ref: string): RefBox | null {
  const r = parseRange(ref)
  if (r) {
    return {
      top: Math.min(r.from.row, r.to.row), bottom: Math.max(r.from.row, r.to.row),
      left: Math.min(r.from.col, r.to.col), right: Math.max(r.from.col, r.to.col),
    }
  }
  const one = parseRef(ref)
  return one ? { top: one.row, bottom: one.row, left: one.col, right: one.col } : null
}

export const boxRef = (b: RefBox): string =>
  b.top === b.bottom && b.left === b.right
    ? `${colToLetters(b.left)}${b.top + 1}`
    : `${colToLetters(b.left)}${b.top + 1}:${colToLetters(b.right)}${b.bottom + 1}`

const inBox = (b: RefBox, row: number, col: number): boolean =>
  row >= b.top && row <= b.bottom && col >= b.left && col <= b.right

/**
 * The rule covering one spreadsheet cell.
 *
 * LAST MATCH WINS, which is the same answer a stacking order gives everywhere
 * else in this app: a rule added later over a range that overlaps an older one
 * is the author's newer decision, and searching from the front would make a
 * broad early rule permanently shadow a narrow correction to it.
 */
export function canvasEntryAt(
  rules: readonly RangeValidation[], row: number, col: number,
): RangeValidation | null {
  for (let i = rules.length - 1; i >= 0; i--) {
    const b = refBox(rules[i].ref)
    if (b && inBox(b, row, col)) return rules[i]
  }
  return null
}

/** The rule alone — what every painter and every editor wants. */
export const canvasRuleAt = (
  rules: readonly RangeValidation[], row: number, col: number,
): DataRule | null => canvasEntryAt(rules, row, col)?.rule ?? null

// --- checking a value -------------------------------------------------------

/** Is a rule one this build actually enforces? `formula` is not — see header. */
export const enforced = (rule: DataRule): boolean =>
  rule.kind === 'list' || rule.kind === 'number'
  || rule.kind === 'date' || rule.kind === 'textLength'

const isBlank = (v: unknown): boolean =>
  v === null || v === undefined || (typeof v === 'string' && v.trim() === '')

/** Loose, because a list is written by hand and typed by hand: leading space
 *  and a capital letter are not what "Won" vs "Lost" is about. */
const listKey = (s: string): string => s.trim().toLowerCase()

const asNumber = (v: unknown): number | null => {
  if (typeof v === 'number') return Number.isFinite(v) ? v : null
  if (typeof v === 'boolean') return v ? 1 : 0
  if (typeof v !== 'string') return null
  const s = v.trim().replace(/[,\s£$€¥%]/g, '')
  if (s === '') return null
  const n = Number(s)
  return Number.isFinite(n) ? n : null
}

/** A date as a day number, so a bound and a value compare without a timezone
 *  ever entering it. `YYYY-MM-DD` and anything `Date` will take. */
const asDay = (v: unknown): number | null => {
  if (v instanceof Date) return Number.isFinite(v.getTime()) ? Math.floor(v.getTime() / 86_400_000) : null
  if (typeof v === 'number') return Number.isFinite(v) ? v : null
  if (typeof v !== 'string') return null
  const s = v.trim()
  if (s === '') return null
  const iso = /^(\d{4})-(\d{2})-(\d{2})/.exec(s)
  const ms = iso
    ? Date.UTC(Number(iso[1]), Number(iso[2]) - 1, Number(iso[3]))
    : Date.parse(s)
  return Number.isFinite(ms) ? Math.floor(ms / 86_400_000) : null
}

const numBound = (v: number | string | undefined): number | null =>
  v === undefined ? null : asNumber(v)

const dayBound = (v: number | string | undefined): number | null =>
  v === undefined ? null : asDay(v)

/**
 * Why this value breaks this rule, or `null` if it does not.
 *
 * The string is what a reader sees, in a `title=`, in the panel and in the
 * editor's refusal — so `rule.message` wins when the author wrote one, exactly
 * as Excel's custom error message does.
 *
 * A value the rule cannot READ is a violation ("must be a number"), never a
 * pass. Treating an unreadable value as acceptable is how a rule becomes
 * decoration: the one entry it exists to catch is the one it cannot parse.
 */
export function violationOf(rule: DataRule, v: unknown): string | null {
  if (isBlank(v)) {
    return rule.blank === false ? (rule.message ?? t('This cell may not be empty.')) : null
  }
  if (!enforced(rule)) return null
  const say = (generated: string): string => rule.message ?? generated

  if (rule.kind === 'list') {
    const allowed = rule.list ?? []
    const key = listKey(String(v))
    if (allowed.some((a) => listKey(a) === key)) return null
    return say(t('Must be one of: {list}').replace('{list}', allowed.join(', ')))
  }

  if (rule.kind === 'number') {
    const n = asNumber(v)
    if (n === null) return say(t('Must be a number.'))
    return rangeWhy(n, numBound(rule.min), numBound(rule.max), say, (x) => String(x))
  }

  if (rule.kind === 'date') {
    const d = asDay(v)
    if (d === null) return say(t('Must be a date.'))
    return rangeWhy(d, dayBound(rule.min), dayBound(rule.max), say,
      () => '', String(rule.min ?? ''), String(rule.max ?? ''))
  }

  // textLength
  const len = String(v).length
  const lo = numBound(rule.min)
  const hi = numBound(rule.max)
  if (lo !== null && len < lo) {
    return say(t('Must be at least {n} characters.').replace('{n}', String(lo)))
  }
  if (hi !== null && len > hi) {
    return say(t('Must be at most {n} characters.').replace('{n}', String(hi)))
  }
  return null
}

function rangeWhy(
  n: number, lo: number | null, hi: number | null,
  say: (s: string) => string, show: (x: number) => string,
  loText?: string, hiText?: string,
): string | null {
  if (lo !== null && n < lo) {
    return say(t('Must be {min} or more.').replace('{min}', loText || show(lo)))
  }
  if (hi !== null && n > hi) {
    return say(t('Must be {max} or less.').replace('{max}', hiText || show(hi)))
  }
  return null
}

/** The list a dropdown draws, capped. */
export const listOptions = (rule: DataRule): string[] =>
  rule.kind === 'list' ? (rule.list ?? []).slice(0, LIST_CAP) : []

/** Does this rule draw an in-cell arrow? */
export const hasDropdown = (rule: DataRule | null): boolean =>
  !!rule && rule.kind === 'list' && rule.noDropdown !== true && (rule.list?.length ?? 0) > 0

/** One line describing the rule, for the panel and for a cell's tooltip. */
export function describeRule(rule: DataRule): string {
  if (rule.kind === 'list') {
    return t('One of: {list}').replace('{list}', (rule.list ?? []).join(', '))
  }
  if (rule.kind === 'formula') return t('Custom formula (not checked by this build)')
  const lo = rule.min
  const hi = rule.max
  const what = rule.kind === 'number' ? t('Number')
    : rule.kind === 'date' ? t('Date')
      : rule.kind === 'textLength' ? t('Text length') : rule.kind
  if (lo !== undefined && hi !== undefined) {
    return `${what} ${t('between {min} and {max}').replace('{min}', String(lo)).replace('{max}', String(hi))}`
  }
  if (lo !== undefined) return `${what} ≥ ${lo}`
  if (hi !== undefined) return `${what} ≤ ${hi}`
  return what
}

// --- how many rows already break it -----------------------------------------

/**
 * Existing values that violate a rule, capped at `SCAN_CAP`.
 *
 * `capped` is reported rather than swallowed: "at least 200,000" is a true
 * sentence and "200,000" is not.
 */
export function countViolations(
  rule: DataRule, values: Iterable<unknown>,
): { n: number; capped: boolean } {
  let n = 0
  let seen = 0
  for (const v of values) {
    if (seen++ >= SCAN_CAP) return { n, capped: true }
    if (violationOf(rule, v) !== null) n++
  }
  return { n, capped: false }
}

// --- patches ----------------------------------------------------------------
//
// No new patch op. A dataset rule is a COLUMN field (`setColumn`) and a
// spreadsheet rule is a SHEET field (`setSheetProps`), both of which already
// exist, already invert correctly and are already minted as CRDT ops.

/**
 * Set or clear a dataset column's rule.
 *
 * Clearing writes `validate: undefined`, which is `setColumn`'s spelling for a
 * delete (store.ts's `setColumn` case displaces the old value and removes the
 * key), so adding a rule and removing it again leaves the file exactly as it
 * was found — the rule `freezeAt` and `totalsPatch` both hold.
 */
export const columnRulePatch = (
  sheet: TableSheet, colId: string, rule: DataRule | null,
): Patch => ({
  op: 'setColumn', sheet: sheet.id, col: colId,
  patch: { validate: rule ?? undefined },
})

/**
 * Set, replace or remove the rule over one range on a spreadsheet.
 *
 * Keyed by `ref`: setting a rule on a range that already has one REPLACES it
 * rather than stacking a second, or the panel's own control would silently
 * grow the list on every change and `canvasRuleAt`'s last-match-wins would
 * quietly become last-EDIT-wins with a hundred dead entries underneath.
 *
 * Removing the last rule DROPS the field instead of storing `[]`, for the
 * reason every other optional container in this format is dropped: an empty
 * array is a diff, a byte cost and a document that does not equal the same
 * document reached another way.
 */
export function canvasRulePatch(
  sheet: CanvasSheet, ref: string, rule: DataRule | null,
): SetSheetProps | null {
  const box = refBox(ref)
  if (!box) return null
  const norm = boxRef(box)
  const kept = canvasRules(sheet).filter((e) => {
    const b = refBox(e.ref)
    return !b || boxRef(b) !== norm
  })
  const next = rule ? [...kept, { ref: norm, rule }] : kept
  if (!next.length) {
    if (!Array.isArray((sheet as { validations?: unknown }).validations)) return null
    return { op: 'setSheetProps', sheet: sheet.id, props: {}, drop: ['validations'] }
  }
  return { op: 'setSheetProps', sheet: sheet.id, props: { validations: next } }
}

// --- the in-cell dropdown ---------------------------------------------------

/** The marker the grid puts inside a cell whose rule draws an arrow. Both
 *  paint loops emit exactly this, so there is one thing to click and one thing
 *  to assert. */
export const DROPDOWN_HTML = '<span class="dv-arrow" data-dv-open="1">▾</span>'

/** Class on a cell whose CURRENT value breaks its rule — the always-on
 *  equivalent of Excel's "Circle Invalid Data", painted rather than stored. */
export const INVALID_CLASS = 'dv-bad'

let openMenu: (() => void) | null = null

/** Close whatever list menu is open. Safe to call when none is. */
export function closeListMenu(): void {
  const f = openMenu
  openMenu = null
  f?.()
}

/**
 * Drop a list menu under a cell.
 *
 * Mounted on `document.body` rather than inside the cell, for the reason every
 * floating surface in this repo is: the grid's cells clip, and a menu inside
 * one is a menu with two visible entries and a scrollbar.
 */
export function openListMenu(opts: {
  anchor: { getBoundingClientRect(): { left: number; bottom: number; width: number } }
  options: readonly string[]
  current?: unknown
  onPick: (v: string) => void
}): HTMLElement {
  closeListMenu()
  const menu = document.createElement('div')
  menu.className = 'dv-menu'
  menu.setAttribute('role', 'listbox')
  const rect = opts.anchor.getBoundingClientRect()
  menu.style.left = `${Math.round(rect.left)}px`
  menu.style.top = `${Math.round(rect.bottom)}px`
  menu.style.minWidth = `${Math.max(90, Math.round(rect.width))}px`
  const cur = opts.current === null || opts.current === undefined ? '' : listKey(String(opts.current))
  for (const v of opts.options) {
    const b = document.createElement('button')
    b.type = 'button'
    b.className = 'dv-opt'
    b.setAttribute('role', 'option')
    b.textContent = v
    if (listKey(v) === cur) {
      b.classList.add('dv-opt-on')
      b.setAttribute('aria-selected', 'true')
    }
    b.addEventListener('mousedown', (e) => { e.preventDefault(); e.stopPropagation() })
    b.addEventListener('click', (e) => {
      e.preventDefault()
      e.stopPropagation()
      closeListMenu()
      opts.onPick(v)
    })
    menu.appendChild(b)
  }
  // A "clear" entry, because a list rule that allows blanks has no other way
  // to say so from the menu — and typing over the cell to empty it is exactly
  // the gesture the dropdown was supposed to replace.
  const clear = document.createElement('button')
  clear.type = 'button'
  clear.className = 'dv-opt dv-opt-clear'
  clear.textContent = t('Clear')
  clear.addEventListener('mousedown', (e) => { e.preventDefault(); e.stopPropagation() })
  clear.addEventListener('click', (e) => {
    e.preventDefault(); e.stopPropagation(); closeListMenu(); opts.onPick('')
  })
  menu.appendChild(clear)

  document.body.appendChild(menu)
  const away = (): void => closeListMenu()
  document.addEventListener('mousedown', away)
  openMenu = () => {
    document.removeEventListener('mousedown', away)
    menu.parentElement?.removeChild(menu)
  }
  return menu
}

// --- the panel section, drawn once for both kinds ---------------------------

/** The row builders panels.ts owns — the same shape cellfmt.ts declares, and
 *  passed in for the same reason: ONE spelling of a row. */
export interface ValidationKit {
  section(host: HTMLElement, title: string): void
  row(host: HTMLElement, label: string, control: HTMLElement): void
  readonlyRow(host: HTMLElement, label: string, value: string): void
  note(host: HTMLElement, message: string): void
  text(value: string, onChange: (v: string) => void): HTMLInputElement
  select(
    options: ReadonlyArray<readonly [string, string]>, value: string,
    onChange: (v: string) => void,
  ): HTMLSelectElement
  check(value: boolean, onChange: (v: boolean) => void): HTMLInputElement
}

export interface ValidationCtx {
  host: HTMLElement
  kit: ValidationKit
  /** what the rule is attached to, in the reader's words: a column name, or an
   *  A1 range. Shown so "this applies to" is never a guess. */
  scope: string
  /** absent when the panel has nothing selected to attach a rule to */
  rule: DataRule | null
  readOnly: boolean
  /** how many stored values already break the rule; omitted when unknown */
  offenders?: { n: number; capped: boolean }
  write(rule: DataRule | null): void
}

const kindLabel = (k: string): string =>
  k === 'list' ? t('List')
    : k === 'number' ? t('Number')
      : k === 'date' ? t('Date')
        : k === 'textLength' ? t('Text length')
          : k === 'formula' ? t('Custom formula') : k

/**
 * The Validation section — ONE builder, both kinds, exactly as
 * `buildAppearanceSection` is. Two copies would drift, and the way you find
 * out is a reader saying "the dropdown toggle is missing on the other tab".
 */
export function buildValidationSection(ctx: ValidationCtx): void {
  const { host, kit, rule, readOnly } = ctx
  kit.section(host, t('Validation'))
  kit.readonlyRow(host, t('Applies to'), ctx.scope)

  const kind = rule?.kind ?? 'none'
  const known = kind === 'none' || (RULE_KINDS as readonly string[]).includes(kind)
  const sel = kit.select(
    [
      ['none', t('No rule')] as const,
      ...RULE_KINDS.map((k) => [k, kindLabel(k)] as const),
      // `formula` is offered as a CURRENT value only, never as a choice: this
      // build cannot check one, so a control that let someone create one would
      // be a control that manufactures a rule the app ignores. An imported one
      // stays visible and stays selectable-back-to, which is what keeps it from
      // being deleted by accident.
      ...(known ? [] : [[kind, kindLabel(kind)] as const]),
    ],
    kind,
    (v) => {
      if (v === kind) return
      if (v === 'none') { ctx.write(null); return }
      if (!(RULE_KINDS as readonly string[]).includes(v)) return
      ctx.write({ ...(rule ?? {}), kind: v as DataRuleKind, on: rule?.on ?? 'warn' })
    },
  )
  sel.disabled = readOnly
  kit.row(host, t('Rule'), sel)

  if (!rule) {
    kit.note(host, t('A rule says what may be TYPED here. Existing values are never changed by adding one — anything that breaks it is marked instead.'))
    return
  }

  const put = (edit: Partial<DataRule>): void => { if (!readOnly) ctx.write({ ...rule, ...edit }) }

  if (rule.kind === 'list') {
    const items = kit.text((rule.list ?? []).join(', '), (v) => {
      const list = v.split(',').map((s) => s.trim()).filter(Boolean)
      if (!list.length) return               // an empty list is not a rule
      put({ list })
    })
    items.placeholder = t('Open, Won, Lost')
    items.disabled = readOnly
    kit.row(host, t('Values'), items)

    const dd = kit.check(rule.noDropdown !== true, (v) => put({ noDropdown: v ? undefined : true }))
    dd.disabled = readOnly
    kit.row(host, t('In-cell dropdown'), dd)
  } else if (rule.kind === 'formula') {
    const f = kit.text(rule.formula ?? '', (v) => put({ formula: v.trim() || undefined }))
    f.disabled = true
    kit.row(host, t('Formula'), f)
    kit.note(host, t('This rule came from a spreadsheet that evaluates it. dash keeps it and writes it back out unchanged, and does not check entries against it.'))
  } else {
    const lo = kit.text(rule.min === undefined ? '' : String(rule.min), (v) => {
      put({ min: v.trim() === '' ? undefined : coerceBound(rule.kind, v) })
    })
    lo.placeholder = rule.kind === 'date' ? '2026-01-01' : t('no minimum')
    lo.disabled = readOnly
    kit.row(host, t('Minimum'), lo)

    const hi = kit.text(rule.max === undefined ? '' : String(rule.max), (v) => {
      put({ max: v.trim() === '' ? undefined : coerceBound(rule.kind, v) })
    })
    hi.placeholder = rule.kind === 'date' ? '2026-12-31' : t('no maximum')
    hi.disabled = readOnly
    kit.row(host, t('Maximum'), hi)
  }

  const blank = kit.check(rule.blank !== false, (v) => put({ blank: v ? undefined : false }))
  blank.disabled = readOnly
  kit.row(host, t('Allow empty'), blank)

  const on = kit.select(
    [['warn', t('Warn and allow')] as const, ['reject', t('Refuse the entry')] as const],
    rule.on === 'reject' ? 'reject' : 'warn',
    (v) => put({ on: v === 'reject' ? 'reject' : 'warn' }),
  )
  on.disabled = readOnly
  kit.row(host, t('On a bad value'), on)

  const msg = kit.text(rule.message ?? '', (v) => put({ message: v.trim() || undefined }))
  msg.placeholder = describeRule(rule)
  msg.disabled = readOnly
  kit.row(host, t('Message'), msg)

  if (rule.on === 'reject') {
    kit.note(host, t('Refusing applies while you type. A pasted or imported value, and an edit arriving from a collaborator, is always kept and marked — a refusal there would discard somebody else’s work or leave the two copies disagreeing.'))
  }

  const off = ctx.offenders
  if (off && off.n > 0) {
    kit.note(host, (off.capped
      ? t('At least {n} existing value(s) break this rule. They are marked, never changed.')
      : t('{n} existing value(s) break this rule. They are marked, never changed.')
    ).replace('{n}', String(off.n)))
  }
}

/** A typed bound from a panel field. A date stays the text the author typed —
 *  `2026-03-01` is what Excel stores and what a reader can read back. */
function coerceBound(kind: DataRuleKind, v: string): number | string {
  const s = v.trim()
  if (kind === 'date') return s
  const n = Number(s)
  return Number.isFinite(n) ? n : s
}