@svgrid/enterprise 3.0.2 → 3.0.3

package/dist/sheet/cell-types.d.ts

@@ -0,0 +1,58 @@
+import type { StructuralEdit } from './refs.js';
+import { type Rect } from './rects.js';
+/** Excel writes a ticked box as TRUE and an unticked one as FALSE. */
+export declare const CHECKED = "TRUE";
+export declare const UNCHECKED = "FALSE";
+export type CellTypeKind = 'checkbox' | 'button' | 'radio';
+export type CellTypeRegion = {
+    id: string;
+    rects: ReadonlyArray<Rect>;
+    kind: CellTypeKind;
+    /**
+     * A checkbox's two values, when the sheet wants something other than
+     * Excel's TRUE and FALSE (a Yes / No column, say). Compared as text,
+     * ignoring case, the way the engine compares a boolean typed by hand.
+     */
+    checked?: string;
+    unchecked?: string;
+    /** A button's face. The cell's own text when this is absent. */
+    label?: string;
+    /** What a button press reports through `onCellAction`. */
+    action?: string;
+    /** A radio group's choices, in order. */
+    choices?: ReadonlyArray<string>;
+};
+export declare const newCellTypeId: () => string;
+/** The region that applies at a cell, or null. The last one wins. */
+export declare function cellTypeAt(regions: ReadonlyArray<CellTypeRegion>, row: number, col: number): CellTypeRegion | null;
+/** The two texts a checkbox toggles between, Excel's by default. */
+export declare const checkboxValues: (region: CellTypeRegion) => {
+    on: string;
+    off: string;
+};
+/**
+ * Is the cell ticked?
+ *
+ * Read off the cell's own text so a formula, a paste or a typed TRUE all
+ * show the same way. Anything that is not the ticked value reads as
+ * unticked, which is what Excel does with a stray entry.
+ */
+export declare function isChecked(region: CellTypeRegion, raw: string): boolean;
+/** What clicking a checkbox should write into its cell. */
+export declare function toggledValue(region: CellTypeRegion, raw: string): string;
+/** Which radio choice a cell holds, or -1. Compared ignoring case. */
+export declare function radioIndex(region: CellTypeRegion, raw: string): number;
+/** The regions after an insert or delete, moved the way the rules move. */
+export declare function shiftCellTypes(regions: ReadonlyArray<CellTypeRegion>, edit: StructuralEdit): CellTypeRegion[];
+/** The regions with the rectangles cut out: what Clear All removes. */
+export declare function removeCellTypes(regions: ReadonlyArray<CellTypeRegion>, rects: ReadonlyArray<Rect>): CellTypeRegion[];
+/**
+ * Lay a region over some cells, taking those cells out of any region that
+ * already claimed them.
+ *
+ * Without the cut, two regions would overlap and the later one would win
+ * silently; cutting makes the model say what the screen shows.
+ */
+export declare function applyCellType(regions: ReadonlyArray<CellTypeRegion>, region: CellTypeRegion): CellTypeRegion[];
+/** A deep-enough copy for the document's snapshot. */
+export declare const copyCellType: (region: CellTypeRegion) => CellTypeRegion;

package/dist/sheet/cell-types.js

@@ -0,0 +1,96 @@
+/**
+ * What a cell IS, rather than what it holds: a checkbox, a button or a
+ * group of radio choices drawn in the cell and driven from it.
+ *
+ * Excel has one of these, the checkbox its Insert tab puts in a cell, and
+ * it is deliberately thin: the cell's value is still `TRUE` or `FALSE`, so
+ * every formula over it keeps working and the file carries an ordinary
+ * boolean. That is the model here, widened to the two other controls a
+ * data-entry sheet actually asks for.
+ *
+ * The rule that keeps this honest: **a cell type is a rendering, never a
+ * second source of truth.** A checkbox is ticked because its cell reads
+ * TRUE, not because the checkbox remembers being clicked; a radio is on
+ * because the cell holds its choice. Clicking one writes the cell and
+ * nothing else, so undo, the formula engine, a paste and the file all keep
+ * working without knowing this module exists.
+ *
+ * Regions are kept and moved the way validation rules are, and the LAST
+ * region covering a cell wins, so a narrower one laid over a wider one
+ * overrides it.
+ */
+import { toText } from './coerce.js';
+import { rectContains, shiftRects, subtractRect } from './rects.js';
+/** Excel writes a ticked box as TRUE and an unticked one as FALSE. */
+export const CHECKED = 'TRUE';
+export const UNCHECKED = 'FALSE';
+let counter = 0;
+export const newCellTypeId = () => `ct${(counter += 1)}`;
+/** The region that applies at a cell, or null. The last one wins. */
+export function cellTypeAt(regions, row, col) {
+    for (let i = regions.length - 1; i >= 0; i -= 1) {
+        const region = regions[i];
+        if (region.rects.some((rect) => rectContains(rect, row, col)))
+            return region;
+    }
+    return null;
+}
+/** The two texts a checkbox toggles between, Excel's by default. */
+export const checkboxValues = (region) => ({
+    on: region.checked ?? CHECKED,
+    off: region.unchecked ?? UNCHECKED,
+});
+/**
+ * Is the cell ticked?
+ *
+ * Read off the cell's own text so a formula, a paste or a typed TRUE all
+ * show the same way. Anything that is not the ticked value reads as
+ * unticked, which is what Excel does with a stray entry.
+ */
+export function isChecked(region, raw) {
+    const { on } = checkboxValues(region);
+    return toText(raw).trim().toLowerCase() === on.trim().toLowerCase();
+}
+/** What clicking a checkbox should write into its cell. */
+export function toggledValue(region, raw) {
+    const { on, off } = checkboxValues(region);
+    return isChecked(region, raw) ? off : on;
+}
+/** Which radio choice a cell holds, or -1. Compared ignoring case. */
+export function radioIndex(region, raw) {
+    const choices = region.choices ?? [];
+    const value = toText(raw).trim().toLowerCase();
+    return choices.findIndex((choice) => choice.trim().toLowerCase() === value);
+}
+/** The regions after an insert or delete, moved the way the rules move. */
+export function shiftCellTypes(regions, edit) {
+    return shiftRects(regions, edit);
+}
+/** The regions with the rectangles cut out: what Clear All removes. */
+export function removeCellTypes(regions, rects) {
+    const out = [];
+    for (const region of regions) {
+        let kept = [...region.rects];
+        for (const hole of rects)
+            kept = kept.flatMap((rect) => subtractRect(rect, hole));
+        if (kept.length)
+            out.push({ ...region, rects: kept });
+    }
+    return out;
+}
+/**
+ * Lay a region over some cells, taking those cells out of any region that
+ * already claimed them.
+ *
+ * Without the cut, two regions would overlap and the later one would win
+ * silently; cutting makes the model say what the screen shows.
+ */
+export function applyCellType(regions, region) {
+    return [...removeCellTypes(regions, region.rects), region];
+}
+/** A deep-enough copy for the document's snapshot. */
+export const copyCellType = (region) => ({
+    ...region,
+    rects: region.rects.map((rect) => [...rect]),
+    ...(region.choices ? { choices: [...region.choices] } : {}),
+});

package/dist/sheet/coerce.d.ts

@@ -10,12 +10,46 @@
  *   - Booleans are 1 and 0 in arithmetic but are skipped by numeric aggregates.
  */
 import { type CellValue } from './ast.js';
+/** A date from a cell: a serial number, or text `new Date` can read
+ *  (`2024-03-09`, `2024-03-09 13:45`). Anything else is `#VALUE!`. */
+export declare function toDate(v: CellValue): Date;
+/** The `yyyy-mm-dd` the date functions hand back. */
+export declare const isoDate: (d: Date) => string;
+/** Excel's serial for a date, fractional when it carries a time. */
+export declare function dateSerial(d: Date): number;
+/**
+ * The serial a date or a time written as text is worth in arithmetic, or
+ * null when the text is neither. Dates are `yyyy-mm-dd` text in a sheet
+ * (see `toDate`), so `=A1+1` under one has to read it as Excel reads a
+ * date cell: as its day number, so the sum is the next day rather than
+ * `#VALUE!`. A clock time is the fraction of a day it is, `="10:30"*2` being
+ * 0.875, and `m/d/yyyy` is read the way `new Date` reads it, as toDate does.
+ */
+export declare function dateTextSerial(text: string): number | null;
 export declare function toNumber(v: CellValue): number;
 export declare function toBool(v: CellValue): boolean;
 export declare function toText(v: CellValue): string;
 /** Excel's `=` between two values. Text compares case-insensitively; a number
  *  never equals the text that looks like it. */
 export declare function looseEquals(a: CellValue, b: CellValue): boolean;
+/**
+ * Excel's wildcards, which every text criterion and exact lookup speaks:
+ * `*` stands for any run of characters, `?` for exactly one, and `~` asks
+ * for the next character itself, so `"~*"` is a literal asterisk.
+ */
+export declare function hasWildcards(pattern: string): boolean;
+/** The pattern as a regular expression, anchored at both ends and
+ *  case-insensitive, which is how Excel compares text. */
+export declare function wildcardRegExp(pattern: string): RegExp;
+/** The pattern with its `~` escapes taken off, which is the text a plain
+ *  comparison should look for: `"~*"` means a literal asterisk. */
+export declare function unescapeWildcards(pattern: string): string;
+/** Does this cell match a wildcard pattern? Only text takes part: Excel
+ *  never turns a number into text to match `"1*"`. */
+export declare function wildcardMatches(value: CellValue, pattern: string): boolean;
+/** Equality as a criterion or an exact lookup reads it: a pattern carrying
+ *  wildcards matches, anything else compares as `=` does. */
+export declare function patternEquals(value: CellValue, operand: CellValue): boolean;
 /** Ordering for `<` and friends. Excel orders number < text < boolean. */
 export declare function compare(a: CellValue, b: CellValue): number;
 /** The numeric members of a flattened argument list. Blanks, text and booleans
@@ -29,3 +63,9 @@ export declare function isBlank(v: CellValue): boolean;
  * plural forms, which all share this grammar.
  */
 export declare function matchesCriterion(value: CellValue, criterion: CellValue): boolean;
+/** The indexes in `range` that meet `criterion`, for the IF family. */
+export declare function criteriaHits(range: ReadonlyArray<CellValue>, criterion: CellValue): number[];
+/** SUMIFS and its family: every (range, criterion) pair must match at an index. */
+export declare function multiCriteriaHits(pairs: Array<[ReadonlyArray<CellValue>, CellValue]>): number[];
+/** The (range, criterion) pairs of a *IFS call, starting at argument `from`. */
+export declare function criteriaPairs(args: ReadonlyArray<ReadonlyArray<CellValue>>, from: number): Array<[ReadonlyArray<CellValue>, CellValue]>;

package/dist/sheet/coerce.js

@@ -10,6 +10,64 @@
  *   - Booleans are 1 and 0 in arithmetic but are skipped by numeric aggregates.
  */
 import { FormulaError, isError } from './ast.js';
+/** The epoch Excel's date serials count from: serial 1 is 1900-01-01. Day 60
+ *  is Excel's phantom 1900-02-29, so every date from 1900-03-01 on is right
+ *  and the two months before it are a day out, which no sheet has cared
+ *  about. */
+const EXCEL_EPOCH_MS = Date.UTC(1899, 11, 30);
+/** A date from a cell: a serial number, or text `new Date` can read
+ *  (`2024-03-09`, `2024-03-09 13:45`). Anything else is `#VALUE!`. */
+export function toDate(v) {
+    if (typeof v === 'number')
+        return new Date(EXCEL_EPOCH_MS + v * 86400000);
+    const d = new Date(toText(v));
+    if (Number.isNaN(d.getTime()))
+        throw new FormulaError('#VALUE!');
+    return d;
+}
+/** The `yyyy-mm-dd` the date functions hand back. */
+export const isoDate = (d) => d.toISOString().slice(0, 10);
+/** Excel's serial for a date, fractional when it carries a time. */
+export function dateSerial(d) {
+    return (d.getTime() - EXCEL_EPOCH_MS) / 86400000;
+}
+const ISO_DATE_TEXT = /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{1,2}):(\d{2})(?::(\d{2}))?)?$/;
+const SLASH_DATE_TEXT = /^(\d{1,2})\/(\d{1,2})\/(\d{4})$/;
+const CLOCK_TEXT = /^(\d{1,2}):(\d{2})(?::(\d{2}))?$/;
+/**
+ * The serial a date or a time written as text is worth in arithmetic, or
+ * null when the text is neither. Dates are `yyyy-mm-dd` text in a sheet
+ * (see `toDate`), so `=A1+1` under one has to read it as Excel reads a
+ * date cell: as its day number, so the sum is the next day rather than
+ * `#VALUE!`. A clock time is the fraction of a day it is, `="10:30"*2` being
+ * 0.875, and `m/d/yyyy` is read the way `new Date` reads it, as toDate does.
+ */
+export function dateTextSerial(text) {
+    const t = text.trim();
+    let m = ISO_DATE_TEXT.exec(t);
+    if (m) {
+        const month = Number(m[2]), day = Number(m[3]), hours = Number(m[4] ?? 0), minutes = Number(m[5] ?? 0);
+        if (month < 1 || month > 12 || day < 1 || day > 31 || hours > 23 || minutes > 59)
+            return null;
+        const ms = Date.UTC(Number(m[1]), month - 1, day, hours, minutes, Number(m[6] ?? 0));
+        return (ms - EXCEL_EPOCH_MS) / 86400000;
+    }
+    m = SLASH_DATE_TEXT.exec(t);
+    if (m) {
+        const month = Number(m[1]), day = Number(m[2]);
+        if (month < 1 || month > 12 || day < 1 || day > 31)
+            return null;
+        return (Date.UTC(Number(m[3]), month - 1, day) - EXCEL_EPOCH_MS) / 86400000;
+    }
+    m = CLOCK_TEXT.exec(t);
+    if (m) {
+        const hours = Number(m[1]), minutes = Number(m[2]), seconds = Number(m[3] ?? 0);
+        if (hours > 23 || minutes > 59 || seconds > 59)
+            return null;
+        return (hours * 3600 + minutes * 60 + seconds) / 86400;
+    }
+    return null;
+}
 export function toNumber(v) {
     if (typeof v === 'number')
         return v;
@@ -21,6 +79,9 @@ export function toNumber(v) {
         const n = Number(v);
         if (Number.isFinite(n))
             return n;
+        const serial = dateTextSerial(v);
+        if (serial !== null)
+            return serial;
         throw new FormulaError('#VALUE!');
     }
     if (isError(v))
@@ -69,6 +130,80 @@ export function looseEquals(a, b) {
         return false;
     return false;
 }
+/**
+ * Excel's wildcards, which every text criterion and exact lookup speaks:
+ * `*` stands for any run of characters, `?` for exactly one, and `~` asks
+ * for the next character itself, so `"~*"` is a literal asterisk.
+ */
+export function hasWildcards(pattern) {
+    for (let i = 0; i < pattern.length; i += 1) {
+        const ch = pattern[i];
+        if (ch === '~') {
+            i += 1;
+            continue;
+        }
+        if (ch === '*' || ch === '?')
+            return true;
+    }
+    return false;
+}
+const LITERAL = /[\\^$.*+?()[\]{}|]/g;
+/** The pattern as a regular expression, anchored at both ends and
+ *  case-insensitive, which is how Excel compares text. */
+export function wildcardRegExp(pattern) {
+    let out = '';
+    for (let i = 0; i < pattern.length; i += 1) {
+        const ch = pattern[i];
+        if (ch === '~' && i + 1 < pattern.length) {
+            out += pattern[i + 1].replace(LITERAL, '\\$&');
+            i += 1;
+            continue;
+        }
+        if (ch === '*') {
+            out += '[\\s\\S]*';
+            continue;
+        }
+        if (ch === '?') {
+            out += '[\\s\\S]';
+            continue;
+        }
+        out += ch.replace(LITERAL, '\\$&');
+    }
+    return new RegExp(`^${out}$`, 'i');
+}
+/** The pattern with its `~` escapes taken off, which is the text a plain
+ *  comparison should look for: `"~*"` means a literal asterisk. */
+export function unescapeWildcards(pattern) {
+    if (!pattern.includes('~'))
+        return pattern;
+    let out = '';
+    for (let i = 0; i < pattern.length; i += 1) {
+        const ch = pattern[i];
+        if (ch === '~' && i + 1 < pattern.length) {
+            out += pattern[i + 1];
+            i += 1;
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+/** Does this cell match a wildcard pattern? Only text takes part: Excel
+ *  never turns a number into text to match `"1*"`. */
+export function wildcardMatches(value, pattern) {
+    if (typeof value !== 'string')
+        return false;
+    return wildcardRegExp(pattern).test(value);
+}
+/** Equality as a criterion or an exact lookup reads it: a pattern carrying
+ *  wildcards matches, anything else compares as `=` does. */
+export function patternEquals(value, operand) {
+    if (typeof operand !== 'string')
+        return looseEquals(value, operand);
+    if (hasWildcards(operand))
+        return wildcardMatches(value, operand);
+    return looseEquals(value, unescapeWildcards(operand));
+}
 /** Ordering for `<` and friends. Excel orders number < text < boolean. */
 export function compare(a, b) {
     if (typeof a === 'number' && typeof b === 'number')
@@ -108,8 +243,8 @@ export function matchesCriterion(value, criterion) {
             const n = Number(rest);
             const operand = rest !== '' && Number.isFinite(n) ? n : rest;
             switch (opText) {
-                case '=': return looseEquals(value, operand);
-                case '<>': return !looseEquals(value, operand);
+                case '=': return patternEquals(value, operand);
+                case '<>': return !patternEquals(value, operand);
                 case '<': return compare(value, operand) < 0;
                 case '>': return compare(value, operand) > 0;
                 case '<=': return compare(value, operand) <= 0;
@@ -118,5 +253,37 @@ export function matchesCriterion(value, criterion) {
             }
         }
     }
-    return looseEquals(value, criterion);
+    return patternEquals(value, criterion);
+}
+/** The indexes in `range` that meet `criterion`, for the IF family. */
+export function criteriaHits(range, criterion) {
+    const out = [];
+    for (let i = 0; i < range.length; i += 1) {
+        if (matchesCriterion(range[i], criterion))
+            out.push(i);
+    }
+    return out;
+}
+/** SUMIFS and its family: every (range, criterion) pair must match at an index. */
+export function multiCriteriaHits(pairs) {
+    const firstPair = pairs[0];
+    if (!firstPair)
+        return [];
+    const out = [];
+    for (let i = 0; i < firstPair[0].length; i += 1) {
+        if (pairs.every(([range, crit]) => matchesCriterion(range[i] ?? '', crit)))
+            out.push(i);
+    }
+    return out;
+}
+/** The (range, criterion) pairs of a *IFS call, starting at argument `from`. */
+export function criteriaPairs(args, from) {
+    const pairs = [];
+    for (let i = from; i < args.length; i += 2) {
+        const range = args[i];
+        if (!range)
+            break;
+        pairs.push([range, args[i + 1]?.[0] ?? '']);
+    }
+    return pairs;
 }

package/dist/sheet/comments.d.ts

@@ -1,18 +1,52 @@
 import type { NotesMap } from './rects.js';
 export type { NotesMap } from './rects.js';
-/** The comment on (r, c), or undefined when there is none. */
-export declare function commentAt(notes: NotesMap, r: number, c: number): string | undefined;
+/** One entry of a thread: its text, who wrote it and when (ISO 8601). */
+export type CommentEntry = {
+    text: string;
+    author?: string;
+    at?: string;
+};
+/** A cell's comment: the first entry, its replies, and whether it is done. */
+export type CommentThread = CommentEntry & {
+    replies?: CommentEntry[];
+    resolved?: boolean;
+};
+/** A note as saved before threads existed, or a thread. */
+export type CommentValue = string | CommentThread;
+/** `r4` -> `B` -> the comment; the document's own shape. */
+export type CommentsMap = Record<string, Record<string, CommentValue>>;
+/** Either shape as a thread; undefined for a blank note. */
+export declare function threadOf(value: CommentValue | undefined): CommentThread | undefined;
+/** The thread on (r, c), or undefined when there is none. */
+export declare function threadAt(comments: CommentsMap, r: number, c: number): CommentThread | undefined;
+/** The comment's first text on (r, c), or undefined when there is none. */
+export declare function commentAt(comments: CommentsMap, r: number, c: number): string | undefined;
+/** True when the thread carries more than a note's text: it is written as an object. */
+export declare function isThreaded(thread: CommentThread): boolean;
+/** The thread as the text a tooltip shows: each entry under its author. */
+export declare function threadText(thread: CommentThread): string;
+/**
+ * The map with (r, c) set to `thread`, or cleared when it is null or blank.
+ * A thread with nothing but a text is written as that text, so a document
+ * that never used threads reads as it always did. A new map, never the
+ * old one changed: the grid re-reads `notes` only when the object it is
+ * handed is a different one.
+ */
+export declare function withThread(comments: CommentsMap, r: number, c: number, thread: CommentThread | null): CommentsMap;
 /**
- * The map with (r, c) set to `text`, or cleared when the text is blank.
- * A new map, never the old one changed: the grid re-reads `notes` only
- * when the object it is handed is a different one.
+ * The map with the first text of (r, c) set to `text`, or the comment
+ * removed when the text is blank. A thread keeps its author, replies and
+ * state; a note stays a note.
  */
-export declare function withComment(notes: NotesMap, r: number, c: number, text: string): NotesMap;
-/** Every comment, top to bottom then left to right. */
-export declare function listComments(notes: NotesMap): Array<{
+export declare function withComment(comments: CommentsMap, r: number, c: number, text: string): CommentsMap;
+/** The grid's `notes`: the text of every comment, for the mark and the tooltip. */
+export declare function notesOf(comments: CommentsMap): NotesMap;
+/** Every comment, top to bottom then left to right, with its first text. */
+export declare function listComments(comments: CommentsMap): Array<{
     row: number;
     col: number;
     text: string;
+    thread: CommentThread;
 }>;
 /**
  * The comment after (or before) `from`, reading the sheet row by row and
@@ -20,7 +54,7 @@ export declare function listComments(notes: NotesMap): Array<{
  * cell itself is skipped, so pressing Next on a commented cell moves on;
  * null when the sheet has no comments at all.
  */
-export declare function nextComment(notes: NotesMap, from: {
+export declare function nextComment(comments: CommentsMap, from: {
     row: number;
     col: number;
 }, dir: 1 | -1): {

package/dist/sheet/comments.js

@@ -1,30 +1,63 @@
 /**
- * Cell comments, Excel's notes: a text on a cell, shown as a corner mark
- * and read on hover. They live in the sheet document in the grid's own
- * `notes` shape (`r4` -> `B` -> text), so the grid draws the mark and the
- * tooltip and the document moves them with an insert or delete
- * (`remapNotes`). This module is the pure part: reading, writing, and
- * walking them the way Review > Previous / Next do.
+ * Cell comments: Excel's notes and its threaded comments in one map. A
+ * note is a text on a cell, shown as a corner mark and read on hover; a
+ * thread is that text with an author and a time, replies under it, and a
+ * resolved flag. They live in the sheet document keyed the way the grid's
+ * `notes` are (`r4` -> `B` -> value), so the document moves them with an
+ * insert or delete (`remapNotes`) and the grid draws the mark and the
+ * tooltip from the text projection `notesOf` makes.
+ *
+ * A value is a plain string for a note (the shape every document saved so
+ * far carries) or a `CommentThread`; `threadOf` reads either. This module
+ * is the pure part: reading, writing, and walking them the way Review >
+ * Previous / Next do.
  */
 import { colToLetters, lettersToCol } from './address.js';
-/** The comment on (r, c), or undefined when there is none. */
-export function commentAt(notes, r, c) {
-    const text = notes[`r${r}`]?.[colToLetters(c)];
-    return text && text.trim() ? text : undefined;
+/** Either shape as a thread; undefined for a blank note. */
+export function threadOf(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string')
+        return value.trim() ? { text: value } : undefined;
+    return value.text.trim() || value.replies?.length ? value : undefined;
+}
+/** The thread on (r, c), or undefined when there is none. */
+export function threadAt(comments, r, c) {
+    return threadOf(comments[`r${r}`]?.[colToLetters(c)]);
+}
+/** The comment's first text on (r, c), or undefined when there is none. */
+export function commentAt(comments, r, c) {
+    return threadAt(comments, r, c)?.text;
+}
+/** True when the thread carries more than a note's text: it is written as an object. */
+export function isThreaded(thread) {
+    return Boolean(thread.author || thread.at || thread.replies?.length || thread.resolved);
+}
+/** The thread as the text a tooltip shows: each entry under its author. */
+export function threadText(thread) {
+    const line = (entry) => (entry.author ? `${entry.author}:\n${entry.text}` : entry.text);
+    return [line(thread), ...(thread.replies ?? []).map(line)].join('\n\n');
+}
+function copy(comments) {
+    const out = {};
+    for (const [id, line] of Object.entries(comments))
+        out[id] = { ...line };
+    return out;
 }
 /**
- * The map with (r, c) set to `text`, or cleared when the text is blank.
- * A new map, never the old one changed: the grid re-reads `notes` only
- * when the object it is handed is a different one.
+ * The map with (r, c) set to `thread`, or cleared when it is null or blank.
+ * A thread with nothing but a text is written as that text, so a document
+ * that never used threads reads as it always did. A new map, never the
+ * old one changed: the grid re-reads `notes` only when the object it is
+ * handed is a different one.
  */
-export function withComment(notes, r, c, text) {
+export function withThread(comments, r, c, thread) {
     const rowId = `r${r}`;
     const columnId = colToLetters(c);
-    const out = {};
-    for (const [id, line] of Object.entries(notes))
-        out[id] = { ...line };
-    if (text.trim()) {
-        out[rowId] = { ...(out[rowId] ?? {}), [columnId]: text };
+    const out = copy(comments);
+    const kept = thread ? threadOf(thread) : undefined;
+    if (kept) {
+        out[rowId] = { ...(out[rowId] ?? {}), [columnId]: isThreaded(kept) ? kept : kept.text };
     }
     else if (out[rowId]) {
         delete out[rowId][columnId];
@@ -33,18 +66,43 @@ export function withComment(notes, r, c, text) {
     }
     return out;
 }
-/** Every comment, top to bottom then left to right. */
-export function listComments(notes) {
+/**
+ * The map with the first text of (r, c) set to `text`, or the comment
+ * removed when the text is blank. A thread keeps its author, replies and
+ * state; a note stays a note.
+ */
+export function withComment(comments, r, c, text) {
+    if (!text.trim())
+        return withThread(comments, r, c, null);
+    const before = threadAt(comments, r, c);
+    return withThread(comments, r, c, before ? { ...before, text } : { text });
+}
+/** The grid's `notes`: the text of every comment, for the mark and the tooltip. */
+export function notesOf(comments) {
+    const out = {};
+    for (const [rowId, line] of Object.entries(comments)) {
+        for (const [columnId, value] of Object.entries(line)) {
+            const thread = threadOf(value);
+            if (!thread)
+                continue;
+            out[rowId] = { ...(out[rowId] ?? {}), [columnId]: threadText(thread) };
+        }
+    }
+    return out;
+}
+/** Every comment, top to bottom then left to right, with its first text. */
+export function listComments(comments) {
     const out = [];
-    for (const [rowId, line] of Object.entries(notes)) {
+    for (const [rowId, line] of Object.entries(comments)) {
         const row = Number(rowId.slice(1));
         if (!Number.isInteger(row) || row < 0)
             continue;
-        for (const [columnId, text] of Object.entries(line)) {
+        for (const [columnId, value] of Object.entries(line)) {
             const col = lettersToCol(columnId);
-            if (col < 0 || !text || !text.trim())
+            const thread = threadOf(value);
+            if (col < 0 || !thread)
                 continue;
-            out.push({ row, col, text });
+            out.push({ row, col, text: thread.text, thread });
         }
     }
     return out.sort((a, b) => a.row - b.row || a.col - b.col);
@@ -55,8 +113,8 @@ export function listComments(notes) {
  * cell itself is skipped, so pressing Next on a commented cell moves on;
  * null when the sheet has no comments at all.
  */
-export function nextComment(notes, from, dir) {
-    const all = listComments(notes);
+export function nextComment(comments, from, dir) {
+    const all = listComments(comments);
     if (!all.length)
         return null;
     const after = (a, b) => a.row > b.row || (a.row === b.row && a.col > b.col);