Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
//
// Captions, automatic figure/table numbering, and cross-references.
//
// This is the feature a long document cannot be maintained without, and the one
// LaTeX users will not give up: you write "see Table 2", someone inserts a table
// three pages earlier, and the sentence still says the right thing.
//
// ═══════════════════════════════════════════════════════ NEEDS FROM THE CORE
//
// Everything below is written and tested against the model as it will be. The
// numbering, the resolution and the atom/string plumbing are complete and run
// in node today (scripts/test-type-xref.ts); what they cannot do without these
// edits is REACH the editor, because a feature module may not add a block kind
// or an inline atom by itself. Each is minimal and each says why.
//
// 1. type/src/model.ts — the caption block kind
// - BlockKind: add 'caption'
// export type BlockKind = … | 'cell' | 'caption';
// - add, beside CellRef:
// export interface CaptionRef { kind: 'table' | 'figure'; of?: string }
// - Block: add
// /** caption placement; only meaningful on a `caption` block */
// caption?: CaptionRef;
// /** cross-references, by offset into `text` — atoms, like `notes` */
// refs?: XrefRef[]; // { to: string; at: number; style?: 'label'|'page'|'both' }
// WHY a block and not a field on the table: there IS no table block to hang
// a caption on (a table is a run of `cell` blocks sharing an id), and a
// caption must have its own stable id anyway — that id is what a reference
// points at, and what the redline aligns on so an edited caption reports as
// an edited caption. It is also what makes a figure caption drop in later
// with no redesign: same block, `kind:'figure'`, `of` naming the image.
//
// 2. type/src/model.ts — parseDoc, in the per-block loop, after the `cell` case:
// if (kind === 'caption') {
// const c = isObj(b.caption) ? b.caption as Partial<CaptionRef> : undefined;
// out.caption = { kind: c?.kind === 'figure' ? 'figure' : 'table',
// ...(typeof c?.of === 'string' && c.of ? { of: c.of } : {}) };
// }
// const refs = Array.isArray(b.refs)
// ? (b.refs as XrefRef[]).filter(r => isObj(r) && typeof r.to === 'string' && typeof r.at === 'number')
// .map(r => ({ to: r.to, at: Math.max(0, Math.min(r.at, text.length)),
// ...(r.style === 'page' || r.style === 'both' ? { style: r.style } : {}) }))
// .sort((x, y) => x.at - y.at)
// : undefined;
// if (refs?.length) out.refs = refs;
// NOTE — and this is a deliberate difference from footnotes: DO NOT drop a
// reference whose target is missing. parseDoc drops dangling `notes` because
// a marker with no note behind it renders as a number pointing at nothing.
// A dangling REFERENCE is the opposite case: the author wrote "see ⟨that
// table⟩" and the table was deleted. Dropping it silently deletes the
// sentence's meaning and leaves prose reading "see ." Keeping it renders a
// visible ?? that says out loud that something must be fixed — the LaTeX
// behaviour, and the only safe one. See `BROKEN_TEXT` below.
//
// 3. type/src/model.ts — spliceText, so a reference follows the edit exactly as
// a footnote anchor does. Beneath `if (block.notes?.length) { … }` add:
// if (block.refs?.length) {
// const r = shiftRefs(block.refs, at, removed, added.length);
// if (r.length) out.refs = r; else delete out.refs;
// }
// with `import { shiftRefs } from './xref.ts';` at the top. That import is
// safe: this module imports NOTHING from model.ts at value level (only
// types), precisely so the core can call into it without a cycle — which is
// also why `mint()` below exists instead of importing model's `uid`.
//
// 4. type/src/render.ts — the atom and the caption label
// import { captionPrefixHtml, isXrefAtom, refAtoms, readXrefs } from './xref.ts';
// - TAG: add `caption: 'figcaption'`
// - blockHtml: merge `refAtoms(b)` into the `inject` map (they are offsets
// into the same text as the note anchors), and return
// `captionPrefixHtml(b) + (html || '<br>')`
// - readBlock: pass `el => isNoteAtom(el) || isXrefAtom(el)` as the atom
// predicate, and after the notes line add
// const refs = readXrefs(atoms); if (refs.length) out.refs = refs; else delete out.refs;
// - renderBody: after `numberNotes(host, doc)` call `numberXrefs(host, doc)`
// (A general "atom registry" in render.ts would be tidier and would suit the
// next feature that needs one — comments, index entries. It is a bigger
// change than this feature is owed, so this mirrors how notes are wired.)
//
// 5. type/src/print.ts — one line, so paper agrees with screen. After the body
// HTML is assembled (the `out.join('')` that feeds `.t-body`):
// import { fillXrefsHtml, captionIndex } from './xref.ts';
// html = fillXrefsHtml(html, captionIndex(doc.body, docLang(doc)));
// The DOM pass and the string pass fill the SAME atoms from the SAME index,
// which is what stops the printed numbering drifting from the screen's.
//
// 6. type/src/registry.ts — `import './xref.ts';` (mine to add, and added).
//
// Until 1–5 land, the interface augmentation at the bottom of this file keeps
// `tsc` honest and the pure functions keep working; delete it when they do. The
// two entry points refuse to run until then (see `corePatched`), so a build
// carrying this file ahead of the patch cannot damage a document.
//
// VERIFIED, not asserted: patches 1–4 were applied to a throwaway copy of
// type/src outside the repo, where `tsc --noEmit` is clean and a caption block
// renders `<span class="t-cap-num" data-cap="c1">Table 1.</span>Fee schedule`,
// a reference renders `Table 1`, spliceText moves a reference anchor from 6 to
// 9 on a three-character insertion, and parseDoc round-trips both fields.
//
// ═════════════════════════════════════════ WHY A REFERENCE IS AN ATOM, NOT TEXT
//
// A reference sits inside a paragraph's text. It could be (a) literal text the
// feature rewrites, (b) a MARK over a run whose text is the number, or (c) an
// ATOM at an offset that occupies no characters — what a footnote marker
// already is. It is (c), and the three properties this app is built on each
// rule out the other two:
//
// · THE REDLINE DIFFS PLAIN TEXT, WORD BY WORD. With (a) or (b) the
// characters "Table 2" live in `text`, so inserting an unrelated table on
// page 1 rewrites every later reference — and the review pane reports a
// dozen edits nobody made, in a document whose whole point is that a
// reviewer can trust what it says changed. As an atom the text never moves:
// renumbering is invisible to the diff, which is correct, because nobody
// edited anything.
// · SIGNATURES CANONICALISE THE MODEL. A stored number is content, so it is
// signed. Renumbering would then break every signature on the document
// without a human touching a word — and, worse, a signature would attest to
// a number the reader is not being shown once it re-derives. The atom
// stores an id and a style, both of which are stable under renumbering.
// · THE CARET IS (blockId, offset). An atom has a position and no width, and
// spliceText's arithmetic for exactly that already exists and is tested —
// `shiftRefs` here is the same rule as the notes rule, on purpose, so there
// is one concept in the codebase and not two.
//
// The cost is that the visible words are not in the model, so anything reading
// the document as prose (search, export to plain text) must resolve references
// itself. `refText()` is that function and it is pure.
//
// ═══════════════════════════════════════════════ WHOSE LANGUAGE SAYS "TABLE"?
//
// The word "Table" in "Table 2" is USER-VISIBLE and translatable, and it is NOT
// t(). t() follows the READER: locale comes from navigator.language, and
// language never enters the document format. That is right for chrome, and
// wrong here, because this string is not chrome — it renders INTO the document,
// between the author's sentences, and gets printed and signed alongside them.
//
// Follow the reader's locale and a French contract reads "Le calendrier des
// paiements figure au Table 2" for an English reader and "…au Tableau 2" for a
// French one: the label disagrees with the prose around it, and the SAME BYTES
// show two different documents to two people. For an app whose differentiator
// is that a signed document says one thing, that is disqualifying — nobody can
// sign "whatever this renders as in your browser".
//
// So the caption label follows the DOCUMENT's language, `doc.lang` (BCP 47,
// default 'en'; format-additive, so old files simply say English). That is not
// a viewer preference sneaking into the format — it is the same fact `<html
// lang>` carries, content metadata about what language the words are in, no
// different from `title` being in the document. The chrome around the feature —
// the buttons, the panel, the picker — stays on t() and follows the reader,
// which is the correct split: the reader's UI in the reader's language, the
// author's document in the author's.
//
// Hence CAPTION_WORDS below rather than t() calls: a t() catalog is keyed by the
// viewer's locale and cannot answer "what is 'Table' in the document's
// language". The two are different questions and only one of them is i18n.
import type { Block, TypeDoc } from './model.ts';
import { blockHtml, TAG } from './render.ts';
import { registerKey, registerPanel, registerTool,
type FeatureContext } from './features.ts';
import { t } from './i18n.ts';
// ───────────────────────────────────────────────────────────────────── model
export type CaptionKind = 'table' | 'figure';
export type RefStyle = 'label' | 'page' | 'both';
/** What a caption block captions. `of` names the object; numbering never uses it. */
export interface CaptionRef { kind: CaptionKind; of?: string }
/** A cross-reference anchored INTO a block's text, by character offset. */
export interface XrefRef { to: string; at: number; style?: RefStyle }
/** The block kind a caption is. Cast until model.ts learns the kind (patch 1). */
export const CAPTION: Block['kind'] = 'caption' as unknown as Block['kind'];
/** What a broken reference renders as. Visible, and deliberately ugly. */
export const BROKEN_TEXT = '??';
/**
* A fresh id. Mirrors model.ts `uid`, and is a copy rather than an import so
* that model.ts can import `shiftRefs` from here without a value-level cycle.
*/
const mint = (p = 'b'): string => {
const r = globalThis.crypto?.randomUUID?.();
return r ? `${p}-${r.slice(0, 8)}` : `${p}-${Math.random().toString(36).slice(2, 10)}`;
};
// ───────────────────────────────────────────────────── the document's language
/**
* The words that render into the document, per language.
*
* Not t(): see the header. These follow `doc.lang`, not the reader. The eight
* languages are the suite's UI languages, which is a reasonable starting set
* and not a limit — an unknown language falls back to English rather than to
* nothing, because "Table 2" is wrong in Finnish but readable, and "" is not.
*/
export const CAPTION_WORDS: Record<string, { table: string; figure: string; page: string }> = {
en: { table: 'Table', figure: 'Figure', page: 'page' },
fr: { table: 'Tableau', figure: 'Figure', page: 'page' },
de: { table: 'Tabelle', figure: 'Abbildung', page: 'Seite' },
es: { table: 'Tabla', figure: 'Figura', page: 'página' },
it: { table: 'Tabella', figure: 'Figura', page: 'pagina' },
ja: { table: '表', figure: '図', page: 'ページ' },
'zh-hans': { table: '表', figure: '图', page: '页' },
'zh-hant': { table: '表', figure: '圖', page: '頁' },
};
/** The document's language tag, normalised. `lang` is format-additive. */
export function docLang(doc: Partial<TypeDoc> | Record<string, unknown>): string {
const raw = (doc as Record<string, unknown>).lang;
return typeof raw === 'string' && raw.trim() ? raw.trim().toLowerCase() : 'en';
}
/** Resolve a BCP 47 tag onto the word table: exact, then script, then base. */
function words(lang: string): { table: string; figure: string; page: string } {
const l = lang.toLowerCase();
if (CAPTION_WORDS[l]) return CAPTION_WORDS[l];
// zh-CN / zh-TW / zh-Hant-HK → the two written forms
if (l.startsWith('zh')) {
const trad = /hant|tw|hk|mo/.test(l);
return CAPTION_WORDS[trad ? 'zh-hant' : 'zh-hans'];
}
const base = l.split('-')[0];
return CAPTION_WORDS[base] ?? CAPTION_WORDS.en;
}
export const captionWord = (kind: CaptionKind, lang = 'en'): string => words(lang)[kind];
export const pageWord = (lang = 'en'): string => words(lang).page;
/** "Table 2" — the label, in the document's language. A space separates it in
* Latin scripts; CJK sets the number tight against the word, as those
* typographies do. */
export function joinLabel(word: string, n: number, lang = 'en'): string {
return /^(ja|zh|ko)/.test(lang.toLowerCase()) ? `${word}${n}` : `${word} ${n}`;
}
// ───────────────────────────────────────────────────────────────── numbering
export interface CaptionEntry {
/** the caption BLOCK's id — this is what a reference points at */
id: string;
kind: CaptionKind;
/** DERIVED, never stored */
n: number;
/** "Table" in the document's language */
word: string;
/** "Table 2" */
label: string;
/** the caption's own words */
text: string;
/** the object captioned, when known (a table id, later an image block id) */
of?: string;
/** position in `body`, for ordering and for the panel's jump */
index: number;
}
const captionOf = (b: Block): CaptionRef | undefined =>
b.kind === CAPTION ? (b.caption ?? { kind: 'table' }) : undefined;
/**
* Every caption, numbered in DOCUMENT ORDER with a counter per kind.
*
* Numbering is derived on every read and stored nowhere. Insert a table in the
* middle and everything after it renumbers, which is the whole point; a number
* written into the JSON would be wrong the instant that happened — the rule
* render.ts's numberNotes already follows for footnotes, for the same reason.
*/
export function captionEntries(body: readonly Block[], lang = 'en'): CaptionEntry[] {
const counters: Record<CaptionKind, number> = { table: 0, figure: 0 };
const out: CaptionEntry[] = [];
body.forEach((b, index) => {
const cap = captionOf(b);
if (!cap) return;
const kind: CaptionKind = cap.kind === 'figure' ? 'figure' : 'table';
const n = ++counters[kind];
const word = captionWord(kind, lang);
out.push({ id: b.id, kind, n, word, label: joinLabel(word, n, lang),
text: b.text, ...(cap.of ? { of: cap.of } : {}), index });
});
return out;
}
/** The same, keyed by caption id — what reference resolution looks things up in. */
export function captionIndex(body: readonly Block[], lang = 'en'): Map<string, CaptionEntry> {
return new Map(captionEntries(body, lang).map(e => [e.id, e]));
}
// ─────────────────────────────────────────────────────────────── resolution
export type Resolved =
| { ok: true; text: string; entry: CaptionEntry }
| { ok: false; text: string };
/**
* What a reference renders as.
*
* A MISSING TARGET IS NOT AN ERROR TO SWALLOW. It renders as `??` — visible,
* styled as a problem, and never empty. A reference that renders as nothing is
* the worst outcome available: the sentence silently becomes "as shown in ."
* and nobody proof-reading a 90-page contract will catch it. LaTeX prints ??
* for the same reason, and this keeps the reference in the model so that
* restoring the deleted table (undo, or accepting a rejected redline) makes
* every reference to it correct again with no repair step.
*
* `pageOf` is optional: page numbers exist only where pagination has been
* computed (the editor, print), so a style that asks for one degrades to the
* label rather than to a lie.
*/
export function refText(index: Map<string, CaptionEntry>, ref: XrefRef,
opts: { lang?: string; pageOf?: (blockId: string) => number | undefined } = {}): Resolved {
const entry = index.get(ref.to);
if (!entry) return { ok: false, text: BROKEN_TEXT };
const style = ref.style ?? 'label';
const page = style === 'label' ? undefined : opts.pageOf?.(entry.id);
const pw = pageWord(opts.lang ?? 'en');
if (style === 'page' && page !== undefined) return { ok: true, text: `${pw} ${page}`, entry };
if (style === 'both' && page !== undefined) return { ok: true, text: `${entry.label} (${pw} ${page})`, entry };
return { ok: true, text: entry.label, entry };
}
/** Every reference in the document, in order. */
export function refsIn(body: readonly Block[]): Array<{ block: Block; ref: XrefRef }> {
const out: Array<{ block: Block; ref: XrefRef }> = [];
for (const b of body) for (const ref of b.refs ?? []) out.push({ block: b, ref });
return out;
}
/** The ones pointing at nothing — what the panel shows and what a pre-send
* check should refuse to ignore. */
export function brokenRefs(body: readonly Block[]): Array<{ block: Block; ref: XrefRef }> {
const index = captionIndex(body);
return refsIn(body).filter(({ ref }) => !index.has(ref.to));
}
// ────────────────────────────────────────────────────────── offset arithmetic
/**
* Move reference anchors to follow an edit that replaced [at, at+removed) with
* `added` characters. THE SAME RULE footnote anchors use — deliberately: an
* anchor inside the replaced span is dropped because the words it sat in are
* gone, and everything after it shifts.
*
* model.ts spliceText calls this (patch 3). It is here, and pure, so it can be
* tested without a DOM and without the core edit having landed.
*/
export function shiftRefs(refs: readonly XrefRef[], at: number, removed: number, added: number): XrefRef[] {
const end = at + removed;
const delta = added - removed;
return refs
.filter(r => !(r.at > at && r.at < end))
.map(r => (r.at >= end ? { ...r, at: r.at + delta } : { ...r }))
.sort((x, y) => x.at - y.at);
}
/** Add a reference to a block at an offset. Pure — the caller commits it. */
export function withRef(block: Block, at: number, to: string, style?: RefStyle): Block {
const ref: XrefRef = { to, at: Math.max(0, Math.min(at, block.text.length)),
...(style && style !== 'label' ? { style } : {}) };
return { ...block, refs: [...(block.refs ?? []), ref].sort((x, y) => x.at - y.at) };
}
/** A new caption block for an object. Its id is minted ONCE and never again:
* it is what every reference to this table points at, so re-minting it would
* break every sentence that mentions the table. */
export function newCaption(kind: CaptionKind, of?: string, text = ''): Block {
return { id: mint('cap'), kind: CAPTION, text,
caption: { kind, ...(of ? { of } : {}) } };
}
/**
* Where a caption for the block at `i` belongs, and what it captions.
*
* Inside a table the caption goes AFTER the whole run of cells sharing the
* table id — a caption in the middle of a table would split it into two tables,
* since grouping is by adjacency.
*/
export function captionSite(body: readonly Block[], i: number):
{ at: number; kind: CaptionKind; of?: string } | null {
const here = body[i];
if (!here) return null;
if (here.kind === CAPTION) return null; // already a caption
if (here.kind === 'cell' && here.cell) {
const table = here.cell.table;
let end = i;
while (end + 1 < body.length && body[end + 1].kind === 'cell'
&& body[end + 1].cell?.table === table) end++;
return { at: end + 1, kind: 'table', of: table };
}
return { at: i + 1, kind: 'figure' };
}
/** Does this table already have a caption? Keeps the button from making two. */
export function captionForObject(body: readonly Block[], of: string): Block | undefined {
return body.find(b => b.kind === CAPTION && b.caption?.of === of);
}
// ──────────────────────────────────────────────────── atoms: model → markup
//
// Two placeholder atoms are emitted with the block's HTML and FILLED afterwards
// from the index — the numbering cannot be known block-locally, and doing it in
// a second pass is exactly what numberNotes does. There are two consumers: the
// editor fills DOM nodes, print fills a string. Both read the same index, so
// paper and screen cannot disagree.
const ESC: Record<string, string> = { '&': '&', '<': '<', '>': '>', '"': '"' };
const esc = (s: string) => s.replace(/[&<>"]/g, c => ESC[c]);
/** The atoms a block contributes, keyed by offset — merged into blockHtml's
* inject map beside the footnote markers. */
export function refAtoms(b: Block): Map<number, string> {
const m = new Map<number, string>();
for (const r of b.refs ?? []) {
const prev = m.get(r.at) ?? '';
m.set(r.at, prev + `<span class="t-xref" data-xref="${esc(r.to)}"` +
`${r.style && r.style !== 'label' ? ` data-style="${esc(r.style)}"` : ''}` +
` contenteditable="false">${BROKEN_TEXT}</span>`);
}
return m;
}
/** The label that precedes a caption's own words. Empty for every other kind. */
export function captionPrefixHtml(b: Block): string {
if (b.kind !== CAPTION) return '';
return `<span class="t-cap-num" data-cap="${esc(b.id)}" contenteditable="false"></span>`;
}
/** Is this element one of ours? Both atoms are invisible to the model: the
* reference is an id, and the caption label is DERIVED, so neither may come
* back through readBlock as text. */
export const isXrefAtom = (el: Element): boolean =>
el.tagName === 'SPAN' && (el.classList.contains('t-xref') || el.classList.contains('t-cap-num'));
/** Read reference atoms back out of a parsed block. Caption labels carry no
* `data-xref` and so vanish here, which is correct — they are derived. */
export function readXrefs(atoms: Array<{ at: number; el: Element }>): XrefRef[] {
const out: XrefRef[] = [];
for (const a of atoms) {
const el = a.el as HTMLElement;
const to = el.dataset?.xref;
if (!to) continue;
const style = el.dataset.style;
out.push({ to, at: a.at, ...(style === 'page' || style === 'both' ? { style } : {}) });
}
return out.sort((x, y) => x.at - y.at);
}
// ─────────────────────────────────────────────────────────────── filling in
/** Fill both atom kinds in a STRING of block HTML — the print path. Pure, so
* the rig can assert that paper renders the same words as the screen. */
export function fillXrefsHtml(html: string, index: Map<string, CaptionEntry>,
opts: { lang?: string; pageOf?: (id: string) => number | undefined } = {}): string {
return html.replace(/<span class="t-(xref|cap-num)"([^>]*)>.*?<\/span>/g, (_m, which: string, attrs: string) => {
const id = /data-(?:xref|cap)="([^"]*)"/.exec(attrs)?.[1] ?? '';
if (which === 'cap-num') {
const e = index.get(id);
return `<span class="t-cap-num" data-cap="${esc(id)}">${e ? esc(e.label) + '.' : ''}</span>`;
}
const style = /data-style="([^"]*)"/.exec(attrs)?.[1] as RefStyle | undefined;
const r = refText(index, { to: id, at: 0, ...(style ? { style } : {}) }, opts);
return `<span class="t-xref${r.ok ? '' : ' t-xref-broken'}" data-xref="${esc(id)}">${esc(r.text)}</span>`;
});
}
/**
* Fill both atom kinds in a rendered host — the editor path, called from
* renderBody after numberNotes.
*
* Writes only text and one class, never structure, so it cannot disturb the
* caret: nothing an author can put a caret in changes size or identity.
*/
export function numberXrefs(host: HTMLElement, doc: TypeDoc,
pageOf?: (id: string) => number | undefined): void {
const lang = docLang(doc);
const index = captionIndex(doc.body, lang);
for (const el of host.querySelectorAll<HTMLElement>('span.t-cap-num')) {
const e = index.get(el.dataset.cap ?? '');
el.textContent = e ? `${e.label}.` : '';
}
for (const el of host.querySelectorAll<HTMLElement>('span.t-xref')) {
const style = el.dataset.style as RefStyle | undefined;
const r = refText(index, { to: el.dataset.xref ?? '', at: 0, ...(style ? { style } : {}) },
{ lang, ...(pageOf ? { pageOf } : {}) });
el.textContent = r.text;
el.classList.toggle('t-xref-broken', !r.ok);
el.title = r.ok ? r.text : t('This reference points at something that is no longer in the document');
}
}
/** The document as prose, with references resolved — for search, plain-text
* export, and anything that must read what the reader reads. */
export function resolvedText(doc: TypeDoc): string {
const lang = docLang(doc);
const index = captionIndex(doc.body, lang);
return doc.body.map(b => {
const cap = captionOf(b);
const head = cap ? `${index.get(b.id)?.label ?? ''}. ` : '';
if (!b.refs?.length) return head + b.text;
let out = '', cut = 0;
for (const r of [...b.refs].sort((x, y) => x.at - y.at)) {
out += b.text.slice(cut, r.at) + refText(index, r, { lang }).text;
cut = r.at;
}
return head + out + b.text.slice(cut);
}).join('\n');
}
// ══════════════════════════════════════════════════════════════════════ chrome
//
// From here down is the editor surface: two toolbar buttons, a picker, a panel
// and a shortcut, all registered through features.ts so main.ts is untouched.
// Every string here is CHROME and goes through t() — it is the reader's UI, in
// the reader's language, which is the other half of the argument in the header.
const svg = (body: string) =>
`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16" fill="none" ` +
`stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${body}</svg>`;
const ICON_CAPTION = svg('<rect x="3" y="4" width="18" height="11" rx="2"/><line x1="6" y1="19" x2="18" y2="19"/>');
const ICON_XREF = svg('<path d="M4 7h9"/><path d="M4 12h6"/><path d="M4 17h9"/><path d="M15 12l5 5-5 5" transform="translate(0,-7)"/>');
/**
* Is this build's core patched (patches 1 and 4)?
*
* Until it is, a caption block would ask the renderer for TAG['caption'] and
* get `undefined`, and a reference would be committed into a document that
* renders it as nothing — the exact failure this feature exists to prevent,
* caused by the feature itself. So the two entry points refuse rather than
* damage a document, and say why. PROBED, not assumed: the check renders a
* throwaway block and looks for the atom, so it goes green the moment the
* patch lands and needs no second edit here.
*
* (The import of render.ts is a cycle once patch 4 lands. It is safe: neither
* module touches the other at evaluation time, only inside functions.)
*/
let probed: boolean | null = null;
export function corePatched(): boolean {
if (probed === null) {
const probe: Block = { id: 'probe', kind: 'para', text: 'x', refs: [{ to: 'nothing', at: 0 }] };
probed = CAPTION in TAG && blockHtml(probe).includes('t-xref');
}
return probed;
}
const refuse = (ctx: FeatureContext): boolean => {
if (corePatched()) return false;
ctx.toast(t('This build cannot render captions yet — apply the core patch listed at the top of xref.ts'));
return true;
};
/** The block the caret is in, as an index into body. */
function caretIndex(ctx: FeatureContext): number {
const c = ctx.editor.caret();
if (!c) return -1;
return ctx.store.doc.body.findIndex(b => b.id === c.id);
}
/** Add a caption to the table (or the block) the caret is in. */
export function addCaption(ctx: FeatureContext): void {
if (refuse(ctx)) return;
const i = caretIndex(ctx);
if (i < 0) { ctx.toast(t('Put the caret in the table or paragraph to caption')); return; }
const site = captionSite(ctx.store.doc.body, i);
if (!site) { ctx.toast(t('That is already a caption')); return; }
if (site.of) {
const existing = captionForObject(ctx.store.doc.body, site.of);
if (existing) { ctx.editor.setCaret({ id: existing.id, at: existing.text.length }); ctx.toast(t('This already has a caption')); return; }
}
const block = newCaption(site.kind, site.of);
ctx.store.breakRun();
ctx.store.commit(d => { d.body.splice(site.at, 0, block); });
ctx.refresh();
ctx.editor.setCaret({ id: block.id, at: 0 });
}
/** Insert a cross-reference at the caret. */
export function insertRef(ctx: FeatureContext, to: string, style: RefStyle = 'label'): void {
const c = ctx.editor.caret();
if (!c) { ctx.toast(t('Put the caret where the reference goes')); return; }
const at = c.at;
ctx.store.breakRun();
ctx.store.commit(d => {
const i = d.body.findIndex(b => b.id === c.id);
if (i < 0) return;
d.body[i] = withRef(d.body[i], at, to, style);
}, { scope: { block: c.id } });
ctx.refresh();
ctx.editor.setCaret({ id: c.id, at });
}
/**
* The picker — a reference is chosen from a list, never typed as an id.
*
* An id is a thing the author has no reason to know and every reason to get
* wrong; the list shows what they actually wrote, "Table 2 — Fee schedule".
*/
export function openPicker(ctx: FeatureContext): void {
if (refuse(ctx)) return;
const c = ctx.editor.caret();
if (!c) { ctx.toast(t('Put the caret where the reference goes')); return; }
const entries = captionEntries(ctx.store.doc.body, docLang(ctx.store.doc));
if (!entries.length) { ctx.toast(t('Nothing to refer to yet — caption a table first')); return; }
const back = document.createElement('div');
back.className = 't-overlay';
const box = document.createElement('div');
box.className = 't-dlg t-xref-pick';
box.innerHTML = `<h3>${t('Insert a cross-reference')}</h3>`;
const styleRow = document.createElement('div');
styleRow.className = 't-xref-style';
const sel = document.createElement('select');
for (const [value, label] of [['label', t('Label — “Table 2”')],
['page', t('Page — “page 7”')],
['both', t('Both — “Table 2 (page 7)”')]] as const) {
const o = document.createElement('option');
o.value = value; o.textContent = label;
sel.appendChild(o);
}
styleRow.append(sel);
box.appendChild(styleRow);
const list = document.createElement('div');
list.className = 't-xref-list';
for (const e of entries) {
const b = document.createElement('button');
b.type = 'button';
b.innerHTML = `<b>${esc(e.label)}</b><span>${esc(e.text || t('(untitled)'))}</span>`;
b.addEventListener('click', () => {
close();
insertRef(ctx, e.id, sel.value as RefStyle);
});
list.appendChild(b);
}
box.appendChild(list);
const foot = document.createElement('div');
foot.className = 't-xref-foot';
const cancel = document.createElement('button');
cancel.type = 'button';
cancel.className = 't-btn';
cancel.textContent = t('Cancel');
cancel.addEventListener('click', () => close());
foot.appendChild(cancel);
box.appendChild(foot);
const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') { e.preventDefault(); close(); } };
function close() {
window.removeEventListener('keydown', onKey, true);
back.remove();
// the caret was preserved by mousedown-preventDefault on the toolbar; put
// it back explicitly for the keyboard path, where focus moved into the box
if (c) ctx.editor.setCaret(c);
}
back.addEventListener('mousedown', e => { if (e.target === back) close(); });
window.addEventListener('keydown', onKey, true);
back.appendChild(box);
document.body.appendChild(back);
(list.querySelector('button') as HTMLElement | null)?.focus();
}
// ──────────────────────────────────────────────────────────────── the panel
function paintPanel(host: HTMLElement, ctx: FeatureContext): void {
const doc = ctx.store.doc;
const entries = captionEntries(doc.body, docLang(doc));
const broken = brokenRefs(doc.body);
host.replaceChildren();
if (!entries.length) {
const p = document.createElement('p');
p.className = 't-hint';
p.textContent = t('No captions yet. Put the caret in a table and press the caption button; numbering and every reference to it follow automatically.');
host.appendChild(p);
}
for (const e of entries) {
const a = document.createElement('a');
a.href = '#';
a.className = 't-xref-item';
a.innerHTML = `<b>${esc(e.label)}</b> ${esc(e.text || t('(untitled)'))}`;
a.addEventListener('click', ev => {
ev.preventDefault();
ctx.editor.setCaret({ id: e.id, at: 0 });
document.querySelector(`[data-id="${CSS.escape(e.id)}"]`)?.scrollIntoView({ block: 'center' });
});
host.appendChild(a);
}
if (broken.length) {
const h = document.createElement('p');
h.className = 't-xref-broken-head';
h.textContent = t('{n} broken reference(s)').replace('{n}', String(broken.length));
host.appendChild(h);
for (const { block } of broken) {
const a = document.createElement('a');
a.href = '#';
a.className = 't-xref-item t-xref-broken';
a.textContent = block.text.slice(0, 60) || t('(empty paragraph)');
a.addEventListener('click', ev => {
ev.preventDefault();
ctx.editor.setCaret({ id: block.id, at: 0 });
document.querySelector(`[data-id="${CSS.escape(block.id)}"]`)?.scrollIntoView({ block: 'center' });
});
host.appendChild(a);
}
}
}
// ─────────────────────────────────────────────────────────────── registration
registerTool({
id: 'caption', icon: ICON_CAPTION, group: 'insert', order: 30, label: () => t('Caption'),
get title() { return t('Caption this table or figure'); },
run: addCaption,
});
registerTool({
id: 'xref', icon: ICON_XREF, group: 'insert', order: 31, label: () => t('Cross-reference'),
get title() { return t('Insert a cross-reference to a caption'); },
run: openPicker,
});
// NO ⋯ entry: this is the same action as the Insert tool above, and a thing
// with two homes teaches that neither is where it lives. Inserting is what the
// Insert menu is for; ⋯ is for document-level actions.
// ⌥⌘R: R for reference. ⌘R is the browser's reload and ⇧⌘R its hard reload, so
// neither is available; Alt keeps it out of both.
registerKey({ key: 'r', mod: true, alt: true, run: openPicker });
registerPanel({
id: 'figures', order: 30,
get label() { return t('Figures'); },
// a VIEW of the Navigate tab: a figure list answers "where is it"
host: 'figuresHost',
mount(host, ctx) {
paintPanel(host, ctx);
// PanelSpec.update is declared in features.ts and main.ts never calls it,
// so a panel keeps itself current by subscribing. Said here rather than
// left as a surprise for the next feature.
ctx.store.on(() => paintPanel(host, ctx));
},
update: paintPanel,
});
// ────────────────────────────────────────────────────────────────────────────
// Until core patch 1 lands, teach TypeScript about the two fields it adds.
// DELETE THIS BLOCK when model.ts carries them.
declare module './model.ts' {
interface Block {
caption?: CaptionRef;
refs?: XrefRef[];
}
}