Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

22.9 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// About: what THIS FILE is — its identity, its size, its properties, its
// history, and the JSON it is made of.
//
// A self-contained document has nowhere else to put any of this. PLATFORM §3
// (identity, and the one sanctioned way to change it) and §7 (the JSON round
// trip) both need a surface, and this is it.
//
// THE SPLIT, AND WHY. This dialog used to hold everything: what the file is,
// its properties, updates, language, appearance, password, version history and
// the JSON round trip — eight sections, 1361px tall in a 429px viewport, which
// is three and a bit screens of scroll. Nothing in it was wrong; they were
// simply not one thing, and a reader looking for "what language is this in"
// scrolled past their own password to find it.
//
// The seam is one the codebase had already drawn. Language, theme and the
// update check follow the READER and are kept in this browser (PLATFORM §8);
// everything here travels in the FILE. So:
//
//   · settings.ts — language, appearance, updates, the network switch. Yours.
//   · about.ts    — identity, properties, history, the document as JSON. The
//                   file's.
//   · saveui.ts   — the password, with the other decisions about how this
//                   workbook gets WRITTEN (a template, a read-only copy, a
//                   fork). It is not a fact about the file and it is not a
//                   preference of the reader's: it is an instruction about
//                   every save from now on, and rule 3 of that file already
//                   reasons about encryption on every export path.
//
// The test for a new control is which of those three sentences it finishes.
// There is no fourth.
//
// TWO THINGS HERE ARE NOT COSMETIC and are the reason this is a module rather
// than a slab of markup in main.ts:
//
//   · REPLACING THE WORKBOOK CAN CRASH THE GRID. `Grid.sheet` throws when the
//     sheet id it holds is not in the document, and it reads it from a `doc`
//     listener registered before every other one — so a workbook arriving with
//     different sheet ids takes down the dirty flag and the chart with it.
//     `planReplace` below is the fix.
//   · THE DIALOG SITS INSIDE TWO DOCUMENT-LEVEL HANDLERS. main.ts routes bare
//     keystrokes into the grid and sniffs every paste for CSV; both would fire
//     while someone is typing an author name or pasting JSON in here. Both are
//     stopped in dialog.ts, for both surfaces at once.

import { openDialog } from './dialog.ts'
import { openSettings, updateWaiting, type SettingsHooks } from './settings.ts'
import { APP_VERSION } from '../../kernel/src/update.ts'
import { canWriteInPlace, isBodySealed, openedFileName } from '../../kernel/src/save.ts'
import { addVersion, listVersions } from '../../kernel/src/autosave.ts'
// CIRCULAR, DELIBERATELY, and safe: recovery.ts imports `planReplace` from
// here. Both directions are used only inside function bodies — nothing at
// the time either is called, under Node's loader and Vite's bundler alike.
// The alternative was a third module for one banner, or a hook wired through
// main.ts that a future edit could quietly forget to pass, which would put the
// two restore paths straight back into disagreeing about reversibility.
import { offerUndoRestore, restoredWorkbook } from './recovery.ts'
import { t } from './i18n.ts'
import { docBudget, docBytes, parseDoc, rowCount, type DashDoc, type DocMeta , docForExport } from './model.ts'

// The update check and the theme moved to settings.ts with the surface that
// shows them. They are re-exported because main.ts calls `checkAtLaunch` from
// here — that import is boot code owned by another module, and a rename that
// buys nothing is a merge conflict that buys nothing.
export { shouldCheckAtLaunch, checkAtLaunch, openSettings } from './settings.ts'

export interface AboutHooks extends SettingsHooks {
  /** The sheet the grid is showing. Not derivable here — the grid owns it. */
  showingSheet: () => string
  /** Point the grid at another sheet (and repaint it). */
  showSheet: (id: string) => void
  /**
   * The document changed outside `Store.commit`. Document properties are
   * written straight onto `doc.meta` (see setMeta), so nothing emits `doc` for
   * them and the dirty flag would never light — which means "close the tab and
   * lose it" for a field the author just typed.
   */
  onDirty: () => void
}

// --- pure decisions, testable without a DOM ---------------------------------

/** What a workbook swap has to do to survive the grid. */
export interface ReplacePlan {
  /** the sheet the grid must be showing afterwards */
  show: string
  /**
   * Carry the sheet the grid is CURRENTLY showing through an intermediate
   * document. `Store.replaceDoc` emits `doc` synchronously and the grid's
   * listener — first in line, registered in its constructor — immediately
   * reads `grid.sheet`, which THROWS when the incoming workbook has no sheet
   * with that id. The throw escapes mid-emit, so every listener registered
   * after the grid (the chart, the 3D panel, the dirty flag) never runs, and
   * the workbook is left swapped with the app half-updated.
   *
   * There is no way to point the grid somewhere safe first: `setSheet` paints
   * immediately, and the destination does not exist in the outgoing document.
   * So the swap goes through a document containing BOTH — the new sheets plus
   * the one being left — which is a valid workbook that neither the grid nor
   * anything else can trip over, and is replaced again before it can be saved.
   */
  carry: boolean
}

/**
 * Decide how to swap in `next` while the grid is showing `showing`.
 * Null means the incoming document has no table sheet — nothing to show, so
 * the swap is refused rather than performed into an empty screen.
 */
export function planReplace(next: DashDoc, showing: string): ReplacePlan | null {
  const tables = next.sheets.filter((s) => s.kind === 'table')
  if (!tables.length) return null
  // Keeping the reader where they were matters more than it looks: the common
  // case is an agent handing back the SAME workbook edited, which keeps every
  // sheet id, and jumping to sheet one on every round trip would be a tell
  // that something was rebuilt underneath.
  if (tables.some((s) => s.id === showing)) return { show: showing, carry: false }
  return { show: tables[0].id, carry: true }
}

const newDocId = (): string =>
  typeof crypto !== 'undefined' && crypto.randomUUID
    ? crypto.randomUUID()
    : `doc-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`

/**
 * A fork: same content, new identity (PLATFORM §3 — the ONLY sanctioned way a
 * docId changes).
 *
 * The docId keys autosave recovery and the local version timeline, so a
 * duplicate that kept it would inherit the original's history and overwrite
 * its recovery snapshot — two files racing to restore each other's work.
 *
 * THE ONE COPY OF THIS RULE. About used to offer "Duplicate as new workbook…"
 * beside the Save menu's "Save as new workbook…", which was the same fork
 * written twice — and the two spellings had already drifted (the menu's kept
 * `template: true`, so a fork of a template was a template). The button is gone
 * from the dialog; this function stayed, and the menu calls it.
 */
export function duplicateWorkbook(doc: DashDoc, docId: string = newDocId()): DashDoc {
  const clone = JSON.parse(JSON.stringify(doc)) as DashDoc
  clone.docId = docId
  // The FILE is the capability (PLATFORM §5): a copy carrying `collab` joins
  // the original's session and writes into it. dash mints no credentials yet,
  // but the field is in the model and a hand-written or imported workbook can
  // arrive with one — dropping it now costs nothing and cannot be retrofitted
  // into copies already made.
  delete clone.collab
  // `template: true` means "every open starts a fresh document". A duplicate is
  // a document, not a template.
  delete clone.template
  return clone
}

export interface WorkbookStats {
  sheets: number
  tables: number
  rows: number
  columns: number
  bytes: number
}

export function workbookStats(doc: DashDoc): WorkbookStats {
  let tables = 0
  let columns = 0
  for (const s of doc.sheets) {
    if (s.kind !== 'table') continue
    tables++
    columns += s.columns.length
  }
  return { sheets: doc.sheets.length, tables, rows: rowCount(doc), columns, bytes: docBytes(doc) }
}

// --- the local version timeline ---------------------------------------------

/** Roughly one kept version per this much editing. Slides' number. */
const VERSION_EVERY_MS = 120_000
let lastVersionAt = 0

/**
 * Add this workbook to the local timeline the About dialog restores from,
 * at most once per VERSION_EVERY_MS.
 *
 * NEVER for an encrypted workbook: a snapshot is the document as plain JSON,
 * so writing one puts in IndexedDB exactly what the password exists to keep off
 * the disk. The kernel does not guard this — every app has to, and dash already
 * remembers it for `putRecovery`; this is the second store and the same rule.
 */
export async function rememberVersion(doc: DashDoc): Promise<void> {
  if (isBodySealed()) return
  if (Date.now() - lastVersionAt < VERSION_EVERY_MS) return
  lastVersionAt = Date.now()
  await addVersion(doc)
}

// --- the dialog ---------------------------------------------------------------

/** Wire the ways in. The wordmark and the version chip are already in the top
 *  bar and neither does anything else, which is how slides does it too.
 *
 *  THE CHIP GOES TO SETTINGS, not here. It reads `v0.3.0`, and when the launch
 *  check finds something it reads `v0.3.0 → v0.4.0` — the question it raises is
 *  "am I running the newest app", which is now a Settings question. The ⓘ
 *  button and the mark, which say *this workbook*, open this dialog. That is
 *  the whole of the promise that you can tell which surface holds what from
 *  the name of the thing you clicked.
 *
 *  A `[data-act="settings"]` button is wired if the top bar has one. It is
 *  optional because the top bar is another module's, and About's own footer
 *  reaches Settings either way. */
export function mountAbout(app: HTMLElement, hooks: AboutHooks): void {
  const arm = (el: HTMLElement, title: string, open: () => void) => {
    el.dataset.about = '1'
    el.tabIndex = 0
    el.setAttribute('role', 'button')
    el.title = title
    el.addEventListener('click', open)
    el.addEventListener('keydown', (e) => {
      if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); open() }
    })
  }
  for (const el of app.querySelectorAll<HTMLElement>('.dx-mark')) {
    arm(el, t('About this workbook'), () => openAbout(hooks))
  }
  for (const el of app.querySelectorAll<HTMLElement>('.dx-ver')) {
    arm(el, t('Settings — language, appearance and updates'), () => openSettings(hooks))
  }
  for (const el of app.querySelectorAll<HTMLElement>('[data-act="settings"]')) {
    el.addEventListener('click', () => openSettings(hooks))
  }
}

export function openAbout(hooks: AboutHooks): void {
  const { store } = hooks
  const d = openDialog(t('About this workbook'))
  const { card, note, close } = d

  // --- what this is ---------------------------------------------------------
  const stats = workbookStats(store.doc)
  const lede = document.createElement('p')
  lede.className = 'dx-about-lede'
  lede.textContent = t(
    'bento/dash {version} · {sheets} sheet(s), {rows} row(s), {columns} column(s). The workbook, the grid and the formula engine are all in this one file.',
    { version: APP_VERSION, sheets: stats.sheets, rows: stats.rows, columns: stats.columns },
  )
  card.append(d.h(t('This file')), lede)

  const opened = openedFileName()
  if (opened) card.append(d.row(t('File'), d.value(opened)))
  card.append(d.row(t('Size'), d.value(t('{size} of a {budget} budget', {
    size: bytes(stats.bytes), budget: bytes(docBudget(canWriteInPlace())),
  }))))
  // The docId is the identity every restore, recovery and future merge keys
  // off, and the only place a reader can see it is here.
  card.append(d.row(t('Document id'), d.value(store.doc.docId ?? t('(none — this workbook has no id)'))))
  if (!canWriteInPlace()) {
    card.append(note(t('This browser cannot write back to the file, so every save makes a new copy. Chrome and Edge on a computer can save in place.')))
  }
  if (store.readOnly) {
    card.append(note(t('This workbook is open read-only, so nothing here writes to it.')))
  }

  // --- document properties --------------------------------------------------
  //
  // These go STRAIGHT onto doc.meta and are not undoable, which is a deliberate
  // gap rather than an oversight: the patch union has no op that writes above
  // the sheet except setTitle, and faking one (commit a setTitle with the
  // current title) would put an entry in the undo stack whose undo visibly does
  // nothing. Better a property that ⌘Z ignores than a ⌘Z that lies.
  card.append(d.h(t('Document properties')))
  const setMeta = (key: string, v: string) => {
    if (store.readOnly) return
    const meta: DocMeta = store.doc.meta ?? (store.doc.meta = {})
    if (v) meta[key] = v
    else delete meta[key]
    // an empty object is noise in a file whose bytes are the budget
    if (!Object.keys(meta).length) delete store.doc.meta
    store.touch()
    hooks.onDirty()
  }
  const META: Array<[string, string]> = [
    ['author', t('Author')],
    ['company', t('Company')],
    ['subject', t('Subject')],
    ['keywords', t('Keywords')],
  ]
  for (const [key, label] of META) {
    const input = document.createElement('input')
    input.className = 'dx-about-in'
    input.value = String(store.doc.meta?.[key] ?? '')
    input.disabled = store.readOnly
    input.addEventListener('change', () => setMeta(key, input.value.trim()))
    card.append(d.row(label, input))
  }
  // The title is edited in the top bar and only there — a second field for it
  // here would have to be kept in step with that input, and the loser of that
  // race silently overwrites the winner.
  card.append(note(t('Properties travel in the file. The title is edited in the top bar.')))

  // VERSION HISTORY AND THE JSON ROUND TRIP MOVED TO THE SAVE MENU, as slides
  // moved them: they are operations on the document as a FILE, and slides'
  // Save ▾ is where both apps keep those. About keeps what the workbook IS.
  card.append(note(t('Copies, version history and the document as JSON: the ▾ beside Save.')))

  // --- the footer -----------------------------------------------------------
  // The way ACROSS, beside the way out. About and Settings are two halves of
  // one question people ask in one breath ("what is this thing / how do I make
  // it speak French"), and a reader who guessed wrong should be one click from
  // right rather than back in the top bar hunting.
  const toSettings = d.button(t('Settings'), () => openSettings(hooks))
  toSettings.title = t('Settings — language, appearance and updates')
  // …and it carries the update dot, because the badge that brought the reader
  // to ⓘ has to lead somewhere. The release itself is offered in Settings.
  if (updateWaiting()) toSettings.classList.add('dx-update-badge')
  const foot = d.actions(toSettings, d.button(t('Close'), close))
  foot.classList.add('dx-about-foot')
  card.append(foot)
  d.mount()
}

// --- version history and the document as JSON ----------------------------------
//
// Opened from the Save ▾ menu (saveui.ts), where slides keeps the same three
// commands. Each is its own small dialog rather than a section of About.

/** The local timeline: restore an earlier auto-saved version. */
export function openVersionHistory(hooks: AboutHooks): void {
  const { store } = hooks
  const d = openDialog(t('Version history'))
  const { card, note, close } = d
  card.append(d.h(t('Version history')))
  const versions = document.createElement('div')
  versions.className = 'dx-about-vers'
  card.append(versions)
  card.append(note(t('Versions are kept in this browser only — never in the file, never online. Restoring replaces the whole workbook, and offers one undo.')))
  void listVersions(store.doc.docId).then((list) => {
    if (!list.length) {
      versions.replaceChildren(note(t('No versions kept yet — they accumulate as you edit.')))
      return
    }
    versions.replaceChildren(...list.map((snap, i) => {
      const b = document.createElement('button')
      b.className = 'dx-about-ver'
      b.disabled = store.readOnly
      const stamp = new Date(snap.at).toLocaleString([], {
        month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit',
      })
      const when = document.createElement('span')
      when.textContent = stamp + (i === 0 ? ` · ${t('most recent')}` : '')
      const doIt = document.createElement('span')
      doIt.textContent = t('Restore')
      b.append(when, doIt)
      b.addEventListener('click', () => {
        // A snapshot is this app's own JSON, but it is still parsed rather than
        // trusted: it may predate an id repair, or a sheet this build refuses.
        // And its docId, room, keys and locks are THIS workbook's, not the
        // snapshot's — see FROM_LIVE in recovery.ts for why a stored version
        // is not evidence of any of them.
        const restored = restoredWorkbook(snap.json, store.doc)
        if (!restored) { alert(t('That version could not be read.')); return }
        // Held BEFORE the swap: `replaceDoc` empties both undo stacks, so this
        // object is the only route back to the workbook on screen right now.
        const before = store.doc
        if (!replaceWorkbook(hooks, restored)) {
          alert(t('That version has no table sheet to show.'))
          return
        }
        close()
        // THE SAME OFFER THE RECOVERY BANNER MAKES, from the same function —
        // a way back AFTER, when the reader can see what they agreed to.
        offerUndoRestore(hooks, before, t('Restored the version from {when}.', { when: stamp }))
      })
      return b
    }))
  })
  const foot = d.actions(d.button(t('Close'), close))
  foot.classList.add('dx-about-foot')
  card.append(foot)
  d.mount()
}

/**
 * "Copy document JSON": the workbook as text, for an AI or another tool.
 * STRIPPED (`docForExport`) — this lands on a clipboard and then, often, in a
 * chat window, so no collaboration key rides along. Resolves to the size
 * copied, or null when the browser refused the clipboard.
 */
export async function copyDocJson(doc: DashDoc): Promise<string | null> {
  const text = JSON.stringify(docForExport(doc), null, 2)
  try {
    if (!navigator.clipboard) return null
    await navigator.clipboard.writeText(text)
    return bytes(text.length)
  } catch {
    return null
  }
}

/** "Replace from JSON…": paste a whole workbook back in. */
export function openReplaceJson(hooks: AboutHooks): void {
  const { store } = hooks
  const d = openDialog(t('Replace from JSON…'))
  const { card, note, close } = d
  card.append(d.h(t('Replace from JSON…')))
  const outNote = note(t('The whole workbook is plain JSON inside this file — copy it into any tool or AI, and bring the edited JSON back.'))
  card.append(outNote)
  const ta = document.createElement('textarea')
  ta.className = 'dx-about-paste'
  ta.spellcheck = false
  ta.placeholder = t('Paste bento/dash document JSON here')
  ta.disabled = store.readOnly
  card.append(ta)
  // SAY WHAT IT KEEPS: the paste replaces the content and not the room.
  if ((store.doc as { collab?: { on?: boolean } }).collab?.on) {
    card.append(note(t('Sharing stays with this workbook: the pasted JSON replaces the content, not the live session or its keys.')))
  }
  if (store.readOnly) card.append(note(t('This workbook is open read-only.')))
  const go = d.button(t('Replace workbook'), () => {
    // Loads a document into the running app, which is the one thing a frozen
    // workbook must not do — see replaceWorkbook.
    if (store.readOnly) { outNote.textContent = t('This workbook is open read-only.'); return }
    if (!ta.value.trim()) { ta.focus(); return }
    const res = parseDoc(ta.value)
    if (!res.ok) {
      outNote.textContent = t('That is not a bento/dash workbook: {why}',
        { why: 'detail' in res ? res.detail : res.err })
      return
    }
    // Undo does NOT reach across this. Store.replaceDoc empties both stacks,
    // so unlike slides there is no ⌘Z back — say so before, not after.
    if (!confirm(t('Replace this workbook with the pasted JSON? This cannot be undone.'))) return
    // THE ROOM BELONGS TO THIS FILE, NOT TO THE PASTED TEXT. Content is
    // replaced; the collaboration credentials are this workbook's and stay.
    //
    // Both directions were wrong, and #338 turned the first from rare into
    // routine by stripping `collab` out of "Copy document JSON":
    //
    //   · a STRIPPED paste — now the ordinary AI round trip — carried no
    //     credentials, so replacing silently ENDED the live session.
    //   · a paste carrying SOMEBODY ELSE'S credentials silently JOINED their
    //     room, with them holding the owner key that can revoke.
    //
    // The line is the one #338 draws itself — a saved FILE carrying its own
    // capability is the design, and pasted text is not a file. So a dropped
    // or opened workbook still adopts its own room; this does not.
    //
    // Not folded into `replaceWorkbook`: the Save menu's fork goes through it
    // too and mints fresh credentials ON PURPOSE.
    const keep = (store.doc as { collab?: unknown }).collab
    const merged = keep === undefined
      ? res.doc
      : { ...res.doc, collab: keep } as DashDoc
    if (!replaceWorkbook(hooks, merged)) {
      outNote.textContent = t('That workbook has no table sheet to show.')
      return
    }
    close()
  })
  go.disabled = store.readOnly
  const foot = d.actions(go, d.button(t('Cancel'), close))
  foot.classList.add('dx-about-foot')
  card.append(foot)
  d.mount()
  if (!store.readOnly) ta.focus()
}

/**
 * Swap the whole workbook in, keeping the grid on its feet. False when the
 * incoming document has nothing the grid can show.
 */
function replaceWorkbook(hooks: AboutHooks, next: DashDoc): boolean {
  const { store } = hooks
  // replaceDoc does NOT check store.readOnly — it is the load/restore path, not
  // an edit path — so a workbook frozen by an unknown policy or a future format
  // version has to be defended here or About becomes the way to write to it.
  if (store.readOnly) return false
  const showing = hooks.showingSheet()
  const plan = planReplace(next, showing)
  if (!plan) return false
  if (plan.carry) {
    const carried = store.doc.sheets.find((s) => s.id === showing)
    // Never saved and never autosaved: the second replaceDoc lands in the same
    // turn, and the recovery snapshot is 2.5s behind on a timer.
    store.replaceDoc(carried ? { ...next, sheets: [...next.sheets, carried] } : next)
    hooks.showSheet(plan.show)
  }
  store.replaceDoc(next)
  return true
}

const bytes = (n: number): string =>
  n >= 1024 * 1024 ? `${(n / 1048576).toFixed(1)} MB` : `${Math.max(1, Math.round(n / 1024))} KB`