Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

18.5 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// PASTE SPECIAL — values only, formulas, formats only, transpose.
//
// Nothing here touches the DOM, and nothing here imports grid.ts. The grid and
// main.ts hand in what a cell HOLDS and where it is going; this decides what is
// written. That is what makes every rule below provable in node, which matters
// because a paste is a bulk overwrite: it is the one gesture where getting the
// answer wrong destroys a screenful of somebody's work in one keystroke, with
// no evidence left of what was there.
//
// ═══ THE RULE THIS FILE EXISTS TO HOLD ════════════════════════════════════
//
//   VALUES ONLY LANDS A VALUE. NOT A FORMULA, AND NEVER AN ERROR OBJECT.
//
// There is prior art in this codebase for getting exactly that wrong. Fill
// seeded from the COMPUTED value, so a filled formula came out as the constant
// it happened to evaluate to and a FAILED one came out as the error OBJECT,
// written into a typed column as though somebody had typed `{code:'#VALUE!'}`
// into it (scripts/test-dash-fill.ts records the measurement). Paste special
// walks the same ground from the other side: values-only DOES want the computed
// number — that is the whole command — so the fill fix ("read the source, never
// the result") is not the answer here. The answer is the second half of the
// same lesson: an error is not a value, so a cell whose formula failed pastes
// as BLANK and is COUNTED, and `plan.dropped` is what the caller reports.
// `refusesValue` is the one gate, and it refuses anything that is not a
// primitive — an error object, a Date, a stray `{}` — because a typed column
// can hold none of them.
//
// ═══ FOUR MODES, AND WHAT EACH ONE MAY TOUCH ══════════════════════════════
//
//   'all'      — what ⌘V already does; here so that transpose can compose.
//   'values'   — the computed value, and nothing else. Formulas are DISCARDED
//                (that is the command: "strip the formulas, keep the numbers",
//                the most-used clipboard verb in finance).
//   'formulas' — the formula SOURCE, with relative references translated by how
//                far the cell moved and `$A$1` left alone. A constant cell
//                pastes as its constant, which is what Excel does: a block of
//                formulas usually has literal inputs in it and dropping them
//                would paste a formula pointing at nothing.
//   'formats'  — appearance and NOTHING else. `looksOnly` says so on every
//                planned cell, and the writers honour it: a formats paste over
//                a column of totals must not change a number by one digit.
//
// APPEARANCE IS `APPEARANCE_FIELDS` AND ONLY THAT. model.ts owns the one
// runtime list (cellfmt.ts re-exports it, sync/crdt.ts reads it); a second list
// here is how "format" comes to mean two different things in two files, and
// how `v` eventually leaks through a formats-only paste. `pickLook` filters
// through the list rather than spreading an object, which is `appearancePatch`'s
// own discipline.
//
// ═══ TRANSPOSE ON A DATASET IS REFUSED, AND HERE IS WHY ═══════════════════
//
// A spreadsheet (`kind:'canvas'`) is typed by the CELL, so transposing it is a
// pure rearrangement: every cell carries its own type and lands intact. A
// dataset (`kind:'table'`) is typed by the COLUMN — that is the whole reason
// the kind exists (docs/dash-sheet-kinds.md) and it is what earns the column
// formula, the chart binding, the pivot, and the refusal to guess on import.
// Transposing a row of (text, money, date) makes ONE column that must have ONE
// type, so the operation can only complete by coercing all of it to text.
//
// The two ways to "allow" it are both worse than refusing:
//
//   * coerce silently to text — destroys the types that make the sheet a
//     dataset, on a keystroke, with no dialog;
//   * transpose into a NEW sheet — a different command wearing paste's name.
//
// And the dataset already HAS a reshape, which is the honest thing to point at:
// `unpivot` (columns → rows) and `pivot` (rows → columns) are declared in the
// step vocabulary and are what "transpose" means for a table. So the refusal
// names them. Refusing with a reason is the house behaviour (import.ts's
// date-order ambiguity, steps.ts's join fanout); allowing it with a conversion
// is the behaviour those two exist to argue against.

import { formatRef } from './a1.ts'
import { translateCellFormula } from './cellformula.ts'
import { coerce } from './import.ts'
import { APPEARANCE_FIELDS, type AppearanceField } from './model.ts'
import type { CanvasCell, CellOverride, ColumnType } from './model.ts'
import type { Patch } from './store.ts'

// --- what a clip holds ---------------------------------------------------------

/** Appearance, and nothing else — structurally a subset of both cell shapes. */
export type Look = Partial<Record<AppearanceField, unknown>>

/**
 * One copied cell.
 *
 * `v` is the value the cell SHOWED — a formula's result, an override's
 * correction, or the stored value — because that is what "values only" means.
 * `f` is the source beside it, kept separately so no mode has to reconstruct
 * one from the other. `r`/`c` are the CANONICAL position it came from, not the
 * visible one: A1 addresses name the document, so a block copied while a sort
 * is on has to translate by the distance the cells actually moved.
 */
export interface ClipCell {
  v?: unknown
  f?: string
  look?: Look
  r: number
  c: number
}

export interface Clip {
  kind: 'table' | 'canvas'
  rows: ClipCell[][]
  /** a CUT: a moved formula still means what it did, so it does not translate */
  cut?: boolean
}

export type PasteWhat = 'all' | 'values' | 'formulas' | 'formats'

export interface PasteSpecialOpts {
  what: PasteWhat
  transpose?: boolean
}

// --- the gate ------------------------------------------------------------------

/**
 * Is this something a cell may STORE?
 *
 * Only primitives. An error is an object (`FormulaError`), and so is a Date, a
 * `{}` from a mangled paste, and an array. The fill rig records what happens
 * when one gets through: `#VALUE!` sitting in a money column as though a person
 * typed it. This is the same gate stated positively, and it is deliberately a
 * whitelist — a blacklist of "not an error" would have let the Date through.
 */
export const refusesValue = (v: unknown): boolean => {
  if (v === null || v === undefined) return false
  const t = typeof v
  return !(t === 'number' || t === 'string' || t === 'boolean')
}

/** Appearance, filtered through the ONE runtime list. Never a spread. */
export function pickLook(cell: Record<string, unknown> | undefined | null): Look | undefined {
  if (!cell) return undefined
  let out: Look | undefined
  for (const k of APPEARANCE_FIELDS) {
    const v = cell[k]
    if (v === undefined) continue
    ;(out ??= {})[k] = v
  }
  return out
}

// --- the plan ------------------------------------------------------------------

export interface PlannedCell {
  /** destination, as an offset from the paste anchor */
  dr: number
  dc: number
  /** canonical source position — the writer translates a formula by dest − src */
  sr: number
  sc: number
  v?: unknown
  f?: string
  look?: Look
  /** write the appearance and LEAVE the value and formula exactly as they are */
  looksOnly?: boolean
}

export interface PastePlan {
  cells: PlannedCell[]
  rows: number
  cols: number
  /**
   * The clip was CUT. A copied formula makes a second formula that should mean
   * the same thing in its new place, so its references move; a cut moves the
   * ONE formula, and a formula that travelled with its cells still means
   * exactly what it did. Excel agrees, and getting this backwards silently
   * re-points a moved formula at the wrong data.
   */
  cut?: boolean
  /** values refused by `refusesValue` — pasted blank, and reported */
  dropped: number
  /** set when the plan is empty because the operation is not meaningful here */
  refusal?: PasteRefusal
}

/**
 * Reshape and filter a clip into what will actually be written.
 *
 * TRANSPOSE IS APPLIED TO THE DESTINATION AND NOT TO THE SOURCE COORDINATES.
 * Each planned cell keeps the canonical position it was copied FROM, so a
 * formula is translated by how far that particular cell moved. A block shift
 * would be wrong the moment the block is transposed — every cell moves by a
 * different amount — and per-cell offsets are right in both cases, so there is
 * one rule instead of two.
 */
export function planPasteSpecial(
  clip: Clip, opts: PasteSpecialOpts,
): PastePlan {
  const what = opts.what
  const transpose = opts.transpose === true
  if (transpose && clip.kind === 'table') {
    return {
      cells: [], rows: 0, cols: 0, dropped: 0,
      refusal: 'transpose-typed-columns' as PasteRefusal,
    }
  }
  const src = clip.rows
  const h = src.length
  const w = src.reduce((m, r) => Math.max(m, r.length), 0)
  const cells: PlannedCell[] = []
  let dropped = 0
  for (let i = 0; i < h; i++) {
    for (let j = 0; j < w; j++) {
      const cell = src[i]?.[j]
      if (!cell) continue
      const dr = transpose ? j : i
      const dc = transpose ? i : j
      const at: PlannedCell = { dr, dc, sr: cell.r, sc: cell.c }
      if (what === 'formats') {
        at.looksOnly = true
        at.look = cell.look
        cells.push(at)
        continue
      }
      if (what === 'all') at.look = cell.look
      const wantsFormula = (what === 'formulas' || what === 'all') && cell.f !== undefined
      if (wantsFormula) {
        at.f = cell.f
      } else {
        // values-only, or a constant inside a formulas paste
        const v = cell.v
        if (refusesValue(v)) { dropped++; at.v = null } else at.v = v ?? null
      }
      cells.push(at)
    }
  }
  return {
    cells, rows: transpose ? w : h, cols: transpose ? h : w, dropped,
    ...(clip.cut ? { cut: true } : {}),
  }
}

/**
 * Why an option is not available, as a CODE rather than a sentence.
 *
 * The English lives at the call site in main.ts, as a literal inside `t()`.
 * That is not squeamishness about strings in a pure module: the i18n sweep
 * reads t() ARGUMENTS out of the source, so a sentence reached through a
 * variable is one the extractor cannot see and one that would ship
 * untranslated in all seven locales (scripts/test-dash-i18n.ts, failure mode
 * 3). A code also makes the rig's assertion exact — it can check WHICH refusal
 * without matching prose.
 */
export type PasteRefusal = 'transpose-typed-columns'

// --- the menu ------------------------------------------------------------------

export interface PasteSpecialItem {
  id: 'values' | 'formulas' | 'formats' | 'transpose' | 'values-transpose'
  what: PasteWhat
  transpose: boolean
  /** false on this kind of sheet — shown greyed, with `why` said out loud */
  enabled: boolean
  why?: PasteRefusal
}

/**
 * The menu, decided here rather than in the markup, so that "is transpose
 * available" has ONE answer and the rig can read it. A greyed item with a
 * reason teaches; a missing item leaves the reader looking for it.
 */
export function pasteSpecialItems(kind: 'table' | 'canvas'): PasteSpecialItem[] {
  const canTranspose = kind === 'canvas'
  const why: PasteRefusal | undefined = canTranspose ? undefined : 'transpose-typed-columns'
  return [
    { id: 'values', what: 'values', transpose: false, enabled: true },
    { id: 'formulas', what: 'formulas', transpose: false, enabled: true },
    { id: 'formats', what: 'formats', transpose: false, enabled: true },
    { id: 'transpose', what: 'all', transpose: true, enabled: canTranspose, why },
    { id: 'values-transpose', what: 'values', transpose: true, enabled: canTranspose, why },
  ]
}

// --- writing: the spreadsheet kind ---------------------------------------------

export interface CanvasTarget {
  sheetId: string
  cellAt(row: number, col: number): CanvasCell | undefined
  maxRows: number
  maxCols: number
}

/**
 * A plan into `setCanvasCells` — ONE patch, so it is ONE undo step however many
 * cells it covers.
 *
 * A formats-only write REBUILDS the cell from what is there: the existing `v`
 * and `f` are carried across untouched and only the appearance keys change.
 * Spreading the clip's cell over the target instead is how a "formats" paste
 * quietly replaces a number.
 */
export function canvasPastePatches(
  target: CanvasTarget, row: number, col: number, plan: PastePlan,
): Patch[] {
  const cells: Record<string, CanvasCell | null> = {}
  for (const p of plan.cells) {
    const r = row + p.dr
    const c = col + p.dc
    if (r < 0 || c < 0 || r >= target.maxRows || c >= target.maxCols) continue
    const key = formatRef({ row: r, col: c, absRow: false, absCol: false })
    const had = target.cellAt(r, c)
    if (p.looksOnly) {
      if (!p.look) continue
      const next = { ...(had ?? {}), ...p.look } as CanvasCell
      cells[key] = next
      continue
    }
    // Keep everything that is NOT value, formula or appearance — a note, a
    // number format someone set. A paste replaces content, not annotation.
    const { v: _v, f: _f, ...rest } = (had ?? {}) as Record<string, unknown>
    for (const k of APPEARANCE_FIELDS) delete rest[k]
    const look = p.look ?? pickLook(had as Record<string, unknown> | undefined)
    if (p.f !== undefined) {
      const dRow = plan.cut ? 0 : r - p.sr
      const dCol = plan.cut ? 0 : c - p.sc
      cells[key] = { ...rest, ...(look ?? {}), f: translateCellFormula(p.f, dRow, dCol) } as CanvasCell
    } else {
      const blank = p.v == null || p.v === ''
      const body = blank ? {} : { v: p.v }
      const next = { ...rest, ...(look ?? {}), ...body } as CanvasCell
      cells[key] = Object.keys(next).length ? next : null
      if (cells[key] === null && had === undefined) delete cells[key]
    }
  }
  return Object.keys(cells).length
    ? [{ op: 'setCanvasCells', sheet: target.sheetId, cells }]
    : []
}

// --- writing: the dataset kind ---------------------------------------------------

export interface TargetColumn {
  id: string
  type: ColumnType
  /** a COMPUTED column is its expression; a paste must not write into one */
  formula?: string
  parsed?: string
  /** canonical index in `sheet.columns`, for translating a formula sideways */
  index: number
}

export interface TableTarget {
  sheetId: string
  /** visible column offset from the anchor → the column there, or null */
  colAt(dc: number): TargetColumn | null
  /** visible row offset from the anchor → the rid there, or −1 past the end */
  ridAt(dr: number): number
  /** rid → canonical data row, for translating a formula downward */
  rowOf(rid: number): number
  overrideAt(key: string): CellOverride | undefined
}

/**
 * A plan into a dataset: `setCells` for values, `setOverrides` for formulas and
 * appearance, all in ONE commit so one ⌘Z puts back the whole paste.
 *
 * TWO REFUSALS ARE BUILT IN, and both are the dataset kind showing through:
 *
 *   * a COMPUTED column is skipped, because it is defined by its expression and
 *     a pasted constant underneath it would be a number the file's own formula
 *     disagrees with (the same guard `writeBlock` and `fillVertical` make);
 *   * a value is COERCED THROUGH import.ts to the target column's type, using
 *     the convention that column was read with. Writing the clipboard's string
 *     straight into a money column is how "1.234" ends up meaning two different
 *     numbers in one column.
 */
export interface TableWrite {
  patches: Patch[]
  /**
   * Cells that had nowhere to land: past the last row of the dataset, or in a
   * COMPUTED column. A dataset has exactly the rows it has, so a paste can run
   * off the end — and a paste that silently does less than it was asked is an
   * edit the user believes happened. The caller reports this.
   */
  skipped: number
}

export function tablePastePatches(
  target: TableTarget, plan: PastePlan,
): TableWrite {
  const byCol = new Map<string, { rids: number[]; v: unknown[] }>()
  const keys: string[] = []
  const overs: Array<Record<string, unknown> | null> = []
  let skipped = 0
  for (const p of plan.cells) {
    const col = target.colAt(p.dc)
    if (!col || col.formula) { skipped++; continue }
    const rid = target.ridAt(p.dr)
    if (rid < 0) { skipped++; continue }
    const key = `${col.id}:${rid}`
    const had = target.overrideAt(key)
    if (p.looksOnly) {
      if (!p.look) continue
      keys.push(key)
      overs.push({ ...(had ?? {}), ...p.look })
      continue
    }
    if (p.f !== undefined) {
      const dRow = plan.cut ? 0 : target.rowOf(rid) - p.sr
      const dCol = plan.cut ? 0 : col.index - p.sc
      keys.push(key)
      overs.push({ ...(had ?? {}), ...(p.look ?? {}), f: translateCellFormula(p.f, dRow, dCol) })
      continue
    }
    const e = byCol.get(col.id) ?? { rids: [], v: [] }
    e.rids.push(rid)
    e.v.push(coerceInto(p.v, col))
    byCol.set(col.id, e)
    // A pasted VALUE over a formula cell has to remove the formula, or the
    // formula simply recomputes and the paste appears to have done nothing.
    if (had?.f !== undefined || p.look) {
      const { f: _f, ...rest } = (had ?? {}) as Record<string, unknown>
      const next = { ...rest, ...(p.look ?? {}) }
      keys.push(key)
      overs.push(Object.keys(next).length ? next : null)
    }
  }
  const patches: Patch[] = []
  for (const [col, e] of byCol) {
    patches.push({ op: 'setCells', sheet: target.sheetId, col, rids: e.rids, v: e.v })
  }
  if (keys.length) {
    patches.push({
      op: 'setOverrides', sheet: target.sheetId, keys, v: overs as never, dropEmpty: true,
    })
  }
  return { patches, skipped }
}

/**
 * One value into what the target column can hold.
 *
 * import.ts's `coerce` and not a second reader: the convention a column was
 * imported with is recorded on it (`parsed`), and reading "1.234" without it is
 * the decimal-comma mistake import.ts's header opens with. A value that is
 * already the right primitive is passed through untouched — coercing a number
 * by way of its own string is a round trip that can lose a digit.
 */
function coerceInto(v: unknown, col: TargetColumn): unknown {
  if (v == null || v === '') return null
  if (refusesValue(v)) return null
  const t = col.type
  if (t === 'text' || t === 'enum') return typeof v === 'string' ? v : String(v)
  if (typeof v === 'number' && (t === 'number' || t === 'money' || t === 'percent')) return v
  if (typeof v === 'boolean' && t === 'bool') return v
  return coerce(String(v), { type: t, ...(col.parsed ? { parsed: col.parsed } : {}), failed: 0 })
}