Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

22.6 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// Per-cell APPEARANCE, on BOTH kinds of sheet.
//
// dash has two kinds of sheet and the difference is where the TYPE lives
// (docs/dash-sheet-kinds.md): a spreadsheet (`kind:'canvas'`) is typed by the
// CELL, a dataset (`kind:'table'`) is typed by the COLUMN. That difference is
// real and worth keeping. It is not a reason for one of them to be unable to
// bold a cell — which is where this file starts: the spreadsheet kind had
// format, bold, align and colours per cell and the dataset kind had none, so
// ⌘B did different things depending on which tab you were looking at.
//
// ═══ THE ONE LINE THIS FILE EXISTS TO HOLD ════════════════════════════════
//
//   ON A DATASET, APPEARANCE IS NOT A BACK DOOR TO A TYPE.
//
// The column type is what earns a dataset its column formulas, its refusal to
// guess on import, its chart binding and its columnar speed. So everything
// here changes how a cell is DRAWN and nothing here changes what it IS:
//
//   * Nothing in this file ever writes `v`, `f`, `was`, `xlsxF`, `froze`,
//     `by`, `at` or `why` on a `CellOverride`. `APPEARANCE_FIELDS` is the
//     complete set of keys it may touch, and `appearancePatch` writes through
//     it rather than spreading an object.
//   * `format` on a dataset cell is a DISPLAY PATTERN AND NOTHING ELSE.
//     `overrideFormatPatch` stamps the pattern and never re-reads the value.
//     That is the whole difference from the spreadsheet kind, where applying a
//     format DOES re-read (cellprops.ts rules 6–8) because on that kind the
//     format is how an author declares what the cell is. Same control, same
//     word on screen, deliberately different depth — and the dataset panel
//     says so in a note rather than leaving the reader to find out.
//   * An appearance-only override carries no `v`, so every reader of the
//     overlay skips it: they all ask `'v' in over` (grid.ts, preview.ts,
//     steps.ts `applyOverrides`, xlsx export) rather than testing the
//     override's existence. Bolding a cell therefore cannot change a total, a
//     chart, a pivot or an export by one digit. That is checked, not assumed —
//     `scripts/test-dash-cellfmt.ts` runs a sum through `sourceOf` before and
//     after bolding every cell in the sheet.
//
// The one place the line is genuinely blurry is worth naming rather than
// hiding: `wrap` changes a row's HEIGHT, so it is appearance that has a layout
// consequence, and on a dataset the row heights are uniform. It is stored per
// cell (a wrapped cell is what the author marked) and the grid grows the row it
// is in — the same thing a column width does, and nobody calls a width a type.
//
// ═══ WHY A SEPARATE FILE FROM cellprops.ts ════════════════════════════════
//
// cellprops.ts is the SPREADSHEET kind's file and its header says so: nine
// coercion rules about what a cell IS, which are meaningless on a dataset. If
// appearance had been added there, the dataset would have had to import the
// spreadsheet's type engine to bold a cell — and the first person to reuse a
// helper across that seam would have carried the coercion with it. So the
// vocabulary lives here, both kinds import it, and cellprops.ts keeps the
// rules. cellprops.ts's `stylePatch` still exists and is still the canvas
// writer; it now writes through `applyAppearance` so the two kinds cannot
// drift on what "clear" means.
//
// NOTHING HERE IMPORTS grid.ts, for the reason cellprops.ts gives: the grid is
// meant to call in, and a module the grid imports must not import it back.

import './cellprops.css'
import { t } from './i18n.ts'
import { APPEARANCE_FIELDS, type AppearanceField } from './model.ts'
import type { CellOverride, Column, TableSheet } from './model.ts'
import type { Patch } from './store.ts'

// --- the vocabulary ---------------------------------------------------------

/**
 * The field list lives in model.ts, because sync/crdt.ts needs it too and that
 * file may not import this one (it runs in a node rig with no DOM). Re-exported
 * here because this is the module every writer and painter goes through, and
 * "which fields are appearance" is a question about this file.
 */
export { APPEARANCE_FIELDS }
export type { AppearanceField }

const IS_APPEARANCE = new Set<string>(APPEARANCE_FIELDS)

/** Is this key one this file is allowed to write? The guard, not a hint. */
export const isAppearanceField = (k: string): k is AppearanceField => IS_APPEARANCE.has(k)

/**
 * What a cell can look like. Structurally a subset of BOTH `CanvasCell` and
 * `CellOverride`, which is what lets one painter and one panel serve the two.
 */
export interface Appearance {
  bold?: boolean
  italic?: boolean
  underline?: boolean
  wrap?: boolean
  align?: string
  color?: string
  bg?: string
  border?: string
  borderColor?: string
  borderStyle?: string
}

/** A write. `null` CLEARS — and clearing DELETES the key (see `applyAppearance`). */
export type AppearanceEdit = Partial<Record<AppearanceField, string | boolean | null>>

export const ALIGNS = ['left', 'center', 'right'] as const
export const BORDER_STYLES = ['solid', 'dashed', 'dotted'] as const
/** Edges, in the order `border` spells them. */
export const EDGES = ['t', 'r', 'b', 'l'] as const

/**
 * The edge sets the dropdown offers. Anything else a file carries is "custom"
 * and the dropdown stays out of it, exactly as cellprops.ts does with a
 * hand-written number pattern.
 *
 * "Box" is every edge OF EVERY SELECTED CELL, not a perimeter around the
 * selection — those are different pictures and the label has to be the one
 * that is true. A perimeter needs to know which cell is on which side of the
 * selection, which is a per-cell edge decision this control does not make.
 */
export const BORDER_PRESETS = ['', 'trbl', 'b', 't', 'l', 'r'] as const

/** A `border` string, normalised: known edges, in `EDGES` order, no repeats. */
export function normaliseEdges(spec: unknown): string {
  if (typeof spec !== 'string') return ''
  const has = new Set(spec.toLowerCase().split(''))
  return EDGES.filter((e) => has.has(e)).join('')
}

// --- writing ----------------------------------------------------------------

/**
 * Apply an edit to a cell, returning the cell to store — or `null` when there
 * is nothing left in it at all.
 *
 * A CLEARED FIELD IS DELETED. `false`, `''` and `null` all mean absent, and
 * absent is what gets written: a stored `bold: false` says what absence
 * already says, and it makes an un-bolded cell unequal to a cell nobody ever
 * bolded — which is a difference in the saved file and, under collaboration, a
 * fingerprint that does not match. cellprops.ts made this argument for the
 * canvas kind first; this is the same rule, now in one place for both.
 *
 * Keys OUTSIDE `APPEARANCE_FIELDS` are ignored rather than written. On a
 * dataset that is the type boundary made mechanical: a caller that passes `v`
 * cannot smuggle it through this function.
 */
export function applyAppearance<T extends Record<string, unknown>>(
  prev: T | undefined, edit: AppearanceEdit,
): T | null {
  const next = { ...(prev ?? {}) } as Record<string, unknown>
  for (const [k, v] of Object.entries(edit)) {
    if (!isAppearanceField(k)) continue
    if (v === null || v === undefined || v === '' || v === false) delete next[k]
    else next[k] = v
  }
  return Object.keys(next).length ? next as T : null
}

/** Shallow equality over a cell's own keys — is this write a no-op? */
export function sameCell(
  a: Record<string, unknown> | null, b: Record<string, unknown> | undefined,
): boolean {
  if (a === null) return b === undefined
  if (b === undefined) return false
  const ka = Object.keys(a)
  const kb = Object.keys(b)
  if (ka.length !== kb.length) return false
  return ka.every((k) => a[k] === b[k])
}

/**
 * What ⌘B should DO to this selection.
 *
 * Every cell already on → turn it off; anything else → turn it all on. The
 * alternative (follow the anchor cell) is Excel's, and it means the same
 * keystroke over the same pixels does opposite things depending on which
 * corner the drag started in. Whole-selection agreement is the rule a person
 * can predict without looking at their own cursor.
 */
export function toggleTarget(
  cells: ReadonlyArray<Record<string, unknown> | undefined>, field: AppearanceField,
): boolean {
  if (!cells.length) return true
  return !cells.every((c) => c?.[field] === true)
}

// --- painting ---------------------------------------------------------------

const cssColor = (v: unknown): string | null =>
  typeof v === 'string' && /^#[0-9a-f]{3,8}$/i.test(v.trim()) ? v.trim() : null

/**
 * The inline CSS a cell's appearance produces — the ONE answer both grids need.
 *
 * Returned as a `;`-prefixed fragment because both of grid.ts's paint loops
 * build a style string by `+=`, which is the shape the hook has to fit. It
 * emits nothing at all for a cell with no appearance, so the common row costs
 * one function call and no string.
 *
 * COLOURS ARE FILTERED, and that is not paranoia about our own panel — a
 * document is untrusted input (docs/PLATFORM.md, and the kernel's own rule
 * since #277). These values are interpolated into a `style="…"` attribute
 * built by string concatenation, so a `bg` of `red;background:url(...)` would
 * be a stylesheet somebody else wrote. Only `#rrggbb`-shaped strings pass.
 */
export function appearanceCss(cell: Appearance | undefined | null): string {
  if (!cell) return ''
  let st = ''
  const bg = cssColor(cell.bg)
  if (bg) st += `;background:${bg}`
  const fg = cssColor(cell.color)
  if (fg) st += `;color:${fg}`
  if (cell.bold) st += ';font-weight:600'
  if (cell.italic) st += ';font-style:italic'
  if (cell.underline) st += ';text-decoration:underline'
  if (cell.wrap) st += ';white-space:normal;overflow-wrap:anywhere'
  const edges = normaliseEdges(cell.border)
  if (edges) {
    const style = (BORDER_STYLES as readonly string[]).includes(String(cell.borderStyle))
      ? String(cell.borderStyle) : 'solid'
    const col = cssColor(cell.borderColor) ?? 'currentColor'
    const side = { t: 'top', r: 'right', b: 'bottom', l: 'left' } as const
    for (const e of EDGES) {
      if (edges.includes(e)) st += `;border-${side[e]}:1px ${style} ${col}`
    }
  }
  return st
}


// --- dataset addressing -----------------------------------------------------

export interface Pos { row: number; col: number }
export interface CellRange { anchor: Pos; head: Pos }

/**
 * Row index → rid, honouring the view's order vector.
 *
 * A COPY of grid.ts's private `ridAt`, and the duplication is deliberate for
 * now: this file must stay callable from a rig with no DOM, and grid.ts drags
 * in the whole editor. Exporting the grid's one is the tidier end state and is
 * named in this task's report as a hook worth having.
 */
export function ridAt(sheet: TableSheet, order: number[] | undefined, i: number): number {
  const idx = order ? order[i] : i
  if (idx === undefined) return -1
  let seen = 0
  for (const [start, count] of sheet.rids) {
    if (idx < seen + count) return start + (idx - seen)
    seen += count
  }
  return -1
}

/** More cells than one edit should carry — cellprops.ts's cap, shared. */
export const KEY_CAP = 50_000

/**
 * Every `<colId>:<rid>` the selection covers, once, in reading order.
 *
 * `visible` is the VISIBLE column list, because the selection counts painted
 * positions and a hidden column would otherwise shift every key one to the
 * left — a bold landing on the wrong column, silently. panels.ts already
 * computes exactly this list for the Column section.
 *
 * A row or column the selection runs past yields nothing rather than a key
 * with `-1` in it: a dataset ends, and the selection model does not know that.
 */
export function overrideKeys(
  sheet: TableSheet, order: number[] | undefined,
  visible: readonly Column[], ranges: readonly CellRange[],
): string[] {
  const seen = new Set<string>()
  const out: string[] = []
  for (const r of ranges) {
    const top = Math.min(r.anchor.row, r.head.row)
    const bottom = Math.max(r.anchor.row, r.head.row)
    const left = Math.min(r.anchor.col, r.head.col)
    const right = Math.max(r.anchor.col, r.head.col)
    for (let row = top; row <= bottom; row++) {
      const rid = ridAt(sheet, order, row)
      if (rid < 0) continue
      for (let col = left; col <= right; col++) {
        const c = visible[col]
        if (!c) continue
        if (out.length >= KEY_CAP) return out
        const k = `${c.id}:${rid}`
        if (seen.has(k)) continue
        seen.add(k)
        out.push(k)
      }
    }
  }
  return out
}

/** "12 cells", or the single address, for the panel's header row. */
export function describeOverrideSelection(keys: readonly string[], cursor: string): string {
  if (keys.length <= 1) return cursor
  return t('{n} cells').replace('{n}', String(keys.length))
}

// --- dataset patches --------------------------------------------------------
//
// ONE PATCH FOR THE WHOLE SELECTION, always — the rule cellprops.ts already
// holds for the spreadsheet kind and `test-dash-cellprops.ts` already pins
// ("formatting twenty cells is ONE patch and ONE undo"). `setOverrides` carries
// many keys for exactly this reason, so the dataset kind gets it for free and
// must not be allowed to lose it: twenty patches would be twenty undo steps,
// twenty CRDT ops and a ⌘Z that leaves a selection half-formatted.

/**
 * Set or clear appearance across a dataset selection, as ONE `setOverrides`.
 *
 * Cells the edit would not change are left OUT — applying "align: auto" to
 * forty untouched cells must write nothing, or the sparse overlay grows forty
 * entries because somebody clicked a control that did nothing. On this kind
 * that matters more than on the spreadsheet: the overlay is the file's record
 * of where a human disagreed with the data, and forty inert entries are forty
 * false positives in `validate.ts`'s override findings.
 *
 * `dropEmpty` is set when the sheet had no overlay at all, so clearing the last
 * one leaves the sheet exactly as it was found rather than carrying `cells: {}`
 * — twelve bytes, and a document that does not equal the same document reached
 * another way (store.ts and crdt.ts are both emphatic about this one).
 */
export function appearancePatch(
  sheet: TableSheet, keys: readonly string[], edit: AppearanceEdit,
): Patch | null {
  const outKeys: string[] = []
  const vals: Array<CellOverride | null> = []
  for (const key of keys) {
    const prev = sheet.cells?.[key]
    const next = applyAppearance<CellOverride>(prev, edit)
    if (sameCell(next as Record<string, unknown> | null, prev as Record<string, unknown> | undefined)) continue
    outKeys.push(key)
    vals.push(next)
  }
  if (!outKeys.length) return null
  return {
    op: 'setOverrides', sheet: sheet.id, keys: outKeys, v: vals,
    dropEmpty: true,
  }
}

/**
 * Stamp a display pattern across a dataset selection. DISPLAY ONLY.
 *
 * The spreadsheet kind's `formatPatch` re-reads every value the new format
 * touches, because there the format is the cell's type declaration. Here the
 * COLUMN says what the value is, so this writes the pattern and stops. There
 * is no `refused` count to report because nothing was attempted on a value.
 *
 * A pattern equal to the column's own is stored as ABSENCE: an override that
 * repeats what the column already says is an entry in the overlay that means
 * nothing, and it would survive a later change to the column format as a cell
 * that mysteriously refuses to follow.
 */
export function overrideFormatPatch(
  sheet: TableSheet, keys: readonly string[], fmt: string | undefined,
): Patch | null {
  const outKeys: string[] = []
  const vals: Array<CellOverride | null> = []
  const colFormat = new Map(sheet.columns.map((c) => [c.id, typeof c.format === 'string' ? c.format : undefined]))
  for (const key of keys) {
    const prev = sheet.cells?.[key]
    const want = fmt === (colFormat.get(key.slice(0, key.indexOf(':'))) ?? undefined) ? undefined : fmt
    const next: CellOverride = { ...(prev ?? {}) }
    if (want === undefined || want === '') delete next.format
    else next.format = want
    const out = Object.keys(next).length ? next : null
    if (sameCell(out as Record<string, unknown> | null, prev as Record<string, unknown> | undefined)) continue
    outKeys.push(key)
    vals.push(out)
  }
  if (!outKeys.length) return null
  return {
    op: 'setOverrides', sheet: sheet.id, keys: outKeys, v: vals,
    dropEmpty: true,
  }
}

/** The pattern a dataset cell prints with: its own, else its column's. */
export function effectiveFormat(sheet: TableSheet, key: string): string | undefined {
  const own = sheet.cells?.[key]?.format
  if (typeof own === 'string' && own !== '') return own
  const col = sheet.columns.find((c) => c.id === key.slice(0, key.indexOf(':')))
  return typeof col?.format === 'string' && col.format !== '' ? col.format : undefined
}

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

/** The row builders panels.ts owns. Structurally the same shape cellprops.ts
 *  declares — passed in so there is ONE spelling of a row (see its PanelKit). */
export interface AppearanceKit {
  section(host: HTMLElement, title: string): void
  row(host: HTMLElement, label: string, control: HTMLElement): void
  note(host: HTMLElement, message: string): void
  select(
    options: ReadonlyArray<readonly [string, string]>, value: string,
    onChange: (v: string) => void,
  ): HTMLSelectElement
  check(value: boolean, onChange: (v: boolean) => void): HTMLInputElement
}

export interface AppearanceCtx {
  host: HTMLElement
  kit: AppearanceKit
  /** the cell under the cursor, whichever kind it came from */
  cell: Appearance | undefined
  readOnly: boolean
  write(edit: AppearanceEdit): void
}

const alignLabel = (a: string): string =>
  a === 'left' ? t('Left') : a === 'center' ? t('Center') : t('Right')

const borderLabel = (b: string): string =>
  b === '' ? t('None')
    : b === 'trbl' ? t('Box')
      : b === 'b' ? t('Bottom')
        : b === 't' ? t('Top')
          : b === 'l' ? t('Left') : t('Right')

const styleLabel = (s: string): string =>
  s === 'solid' ? t('Solid') : s === 'dashed' ? t('Dashed') : t('Dotted')

/**
 * The Appearance section — ONE builder, both kinds.
 *
 * Written as a function over a kit rather than duplicated in cellprops.ts and
 * panels.ts, because the release note this closes was itself about the two
 * kinds drifting. Two copies of this section would drift again inside a month,
 * and the way you find out is a reader saying "underline is missing on the
 * other tab".
 */
export function buildAppearanceSection(ctx: AppearanceCtx): void {
  const { host, kit, cell, readOnly } = ctx
  const w = (edit: AppearanceEdit): void => { if (!readOnly) ctx.write(edit) }

  kit.section(host, t('Appearance'))

  for (const [field, label] of [
    ['bold', t('Bold')], ['italic', t('Italic')], ['underline', t('Underline')],
  ] as const) {
    const cb = kit.check(cell?.[field] === true, (v) => w({ [field]: v ? true : null }))
    cb.disabled = readOnly
    kit.row(host, label, cb)
  }

  const align = kit.select(
    [['auto', t('Auto')] as const, ...ALIGNS.map((a) => [a, alignLabel(a)] as const)],
    typeof cell?.align === 'string' && (ALIGNS as readonly string[]).includes(cell.align)
      ? cell.align : 'auto',
    (v) => w({ align: v === 'auto' ? null : v }),
  )
  align.disabled = readOnly
  kit.row(host, t('Align'), align)

  const wrap = kit.check(cell?.wrap === true, (v) => w({ wrap: v ? true : null }))
  wrap.disabled = readOnly
  kit.row(host, t('Wrap text'), wrap)

  kit.row(host, t('Text colour'), colourControl(
    typeof cell?.color === 'string' ? cell.color : '', '#1e2a3a', readOnly,
    (v) => w({ color: v }), t('Use the default colour')))
  kit.row(host, t('Background'), colourControl(
    typeof cell?.bg === 'string' ? cell.bg : '', '#fff3cd', readOnly,
    (v) => w({ bg: v }), t('No background')))

  // Borders. An edge set a file carries that no preset spells shows as Custom
  // and the dropdown leaves it alone — cellprops.ts's rule for a hand-written
  // number pattern, and for the same reason: a control that cannot express
  // what is stored must not silently respell it on the next click.
  const edges = normaliseEdges(cell?.border)
  const known = (BORDER_PRESETS as readonly string[]).includes(edges)
  const bsel = kit.select(
    [
      ...BORDER_PRESETS.map((b) => [b || 'none', borderLabel(b)] as const),
      ...(known ? [] : [['custom', t('Custom')] as const]),
    ],
    known ? (edges || 'none') : 'custom',
    (v) => { if (v !== 'custom') w({ border: v === 'none' ? null : v }) },
  )
  bsel.disabled = readOnly
  kit.row(host, t('Borders'), bsel)

  if (edges) {
    kit.row(host, t('Border colour'), colourControl(
      typeof cell?.borderColor === 'string' ? cell.borderColor : '', '#9aa7b4', readOnly,
      (v) => w({ borderColor: v }), t('Use the default colour')))

    const ssel = kit.select(
      BORDER_STYLES.map((s) => [s, styleLabel(s)] as const),
      (BORDER_STYLES as readonly string[]).includes(String(cell?.borderStyle))
        ? String(cell?.borderStyle) : 'solid',
      (v) => w({ borderStyle: v === 'solid' ? null : v }),
    )
    ssel.disabled = readOnly
    kit.row(host, t('Border style'), ssel)
  }
}

/**
 * A colour with an OFF state, which `<input type="color">` does not have.
 *
 * MOVED here from cellprops.ts, which now imports it: two copies of this
 * control is two × buttons that drift apart, and it is the only control in
 * either section that is not a plain kit row.
 */
export function colourControl(
  value: string, fallback: string, readOnly: boolean,
  onChange: (v: string | null) => void, clearTitle: string,
): HTMLElement {
  const wrap = document.createElement('span')
  wrap.className = 'dc-colour'
  const input = document.createElement('input')
  input.type = 'color'
  input.value = /^#[0-9a-f]{6}$/i.test(value) ? value : fallback
  input.disabled = readOnly
  // UNSET is an empty well (cellprops.css), never the fallback colour: the
  // fallback is only where the OS picker opens. Said in words too, for anyone
  // not reading the swatch.
  if (!value) {
    wrap.classList.add('dc-colour-off')
    input.title = t('Not set')
  }
  // `change`, never `input`: a drag through the OS colour wheel fires input on
  // every pixel, and every one of those would be an undo step.
  input.addEventListener('change', () => onChange(input.value))
  const clear = document.createElement('button')
  clear.type = 'button'
  clear.className = 'dc-clear'
  clear.textContent = '×'
  clear.title = clearTitle
  clear.disabled = readOnly || !value
  clear.addEventListener('click', () => onChange(null))
  wrap.append(input, clear)
  return wrap
}