@shbernal/ts-xlsx 3.1.0 → 3.2.0

package/dist/io/xlsx/color-xml.js

@@ -5,7 +5,7 @@ import { numberText } from '../../xml/xml.js';
 function normalizeArgb(argb) {
     const rgb = parseArgb(argb);
     if (rgb === undefined) {
-        throw new SyntaxError(`Invalid ARGB colour ${quoted(argb)}: expected 6 or 8 hexadecimal digits`);
+        throw new SyntaxError(`invalid ARGB colour ${quoted(argb)}: expected 6 or 8 hexadecimal digits`);
     }
     return rgb;
 }

package/dist/io/xlsx/column-span.d.ts

@@ -0,0 +1,11 @@
+import type { XmlAttributes } from '../../xml/xml-scan.ts';
+import { type ColumnRecordBudget } from '../read-policy/column-budget.ts';
+/**
+ * The columns a `<col min max>` element actually applies to, or `undefined` for one that applies to
+ * none: unreadable bounds, or anything {@link clampColumnSpan} refuses. Both XML worksheet readers
+ * ask this, so the two cannot read one `<col>` as covering different columns.
+ */
+export declare function takeColumnSpan(attrs: XmlAttributes, budget: ColumnRecordBudget): {
+    first: number;
+    last: number;
+} | undefined;

package/dist/io/xlsx/column-span.js

@@ -0,0 +1,9 @@
+import { numInteger } from '../../xml/xml-attrs.js';
+import { clampColumnSpan } from '../read-policy/column-budget.js';
+export function takeColumnSpan(attrs, budget) {
+    const first = numInteger(attrs.min, 1);
+    const last = numInteger(attrs.max, 1);
+    if (first === undefined || last === undefined)
+        return undefined;
+    return clampColumnSpan(first, last, budget);
+}

package/dist/io/xlsx/comments.d.ts

@@ -48,31 +48,6 @@ export declare function commentsXml(comments: readonly CommentCell[]): string;
  * pixel-exact layout. A thread's fallback shape is `ObjectType="Note"` like any other: Excel draws the
  * threaded-comment card itself and only needs the shape to exist. */
 export declare function vmlDrawingXml(comments: readonly CommentCell[]): string;
-/** One `<comment>` read back from a comments part. */
-export interface ParsedComment {
-    readonly text: string;
-    /**
-     * The thread head id this comment is the legacy fallback for, read off its synthetic `tc={headId}`
-     * author; absent for a user's own note.
-     */
-    readonly threadId?: string;
-}
-/**
- * Parse a `comments{n}.xml` part into a map of A1 reference → comment. Text runs within one comment are
- * concatenated; an author-name run is Excel's own convention and is not stripped, so a note reads back
- * as exactly the text that was written.
- */
-export declare function parseComments(xml: string): Map<string, ParsedComment>;
-/**
- * Apply a parsed comments part onto a sheet's cells as notes, addressing each by its A1 reference.
- *
- * A thread's legacy fallback is not a note and does not become one: its text is boilerplate wrapping a
- * copy of the conversation, so surfacing it as `cell.note` hands the caller garbage, and on write it
- * would be re-emitted as a plain note, destroying the `tc=`/`xr:uid` binding and leaving Excel unable to
- * see the thread at all.
- *
- * Suppressed only for a conversation the reader actually holds: a file whose thread part is missing or
- * damaged has nothing else left, so there the boilerplate is kept rather than the content lost. Call
- * after the sheet's threads are restored, since that is what this reads to decide.
- */
-export declare function applyNotes(sheet: Worksheet, comments: ReadonlyMap<string, ParsedComment>): void;
+/** Every cell a sheet still holds, row-major: what the writer gathers a sheet's notes from, beside the
+ * notes the streaming writer took off the rows it already flushed. */
+export declare function liveCells(sheet: Worksheet): Generator<Cell, void, undefined>;

package/dist/io/xlsx/comments.js

@@ -1,7 +1,4 @@
 import { tryDecodeCellRef } from '../../core/address.js';
-import { decodeSpreadsheetText, numInteger } from '../../xml/xml-attrs.js';
-import { parseXml, TextCapture } from '../../xml/xml-read.js';
-import { localName } from '../../xml/xml-scan.js';
 import { escapeText, textAttr, textElement, XML_DECLARATION } from '../../xml/xml.js';
 import { MARKUP_COMPATIBILITY_NS, REVISION_NS, SPREADSHEETML_NS } from './namespaces.js';
 export function collectComments(cells, threads, alreadyCollected = []) {
@@ -108,66 +105,7 @@ export function vmlDrawingXml(comments) {
         .join('');
     return `${VML_HEADER}${shapes}</xml>`;
 }
-const COMMENT_EMPTY_CLOSES = new Set(['author', 'text']);
-const THREAD_AUTHOR_PREFIX = 'tc=';
-export function parseComments(xml) {
-    const comments = new Map();
-    const authors = [];
-    let currentRef;
-    let currentAuthorId;
-    const capture = new TextCapture(['author', 'text']);
-    let body = '';
-    parseXml(xml, {
-        onOpen(name, attrs, selfClosing) {
-            const local = localName(name);
-            if (local === 'comment') {
-                currentRef = attrs.ref;
-                currentAuthorId = attrs.authorId;
-                body = '';
-            }
-            capture.open(local, selfClosing);
-        },
-        onText(text) {
-            capture.text(text);
-        },
-        onClose(name) {
-            const local = localName(name);
-            const text = capture.close(local);
-            if (local === 'author') {
-                authors.push(text ?? '');
-            }
-            else if (local === 'text') {
-                body = decodeSpreadsheetText(text ?? '');
-            }
-            else if (local === 'comment' && currentRef !== undefined) {
-                const threadId = threadIdOf(authors[numInteger(currentAuthorId, 0) ?? -1]);
-                comments.set(currentRef, {
-                    text: body,
-                    ...(threadId !== undefined ? { threadId } : {}),
-                });
-                currentRef = undefined;
-                currentAuthorId = undefined;
-            }
-        },
-    }, { closeEmptyElements: COMMENT_EMPTY_CLOSES });
-    return comments;
-}
-function threadIdOf(author) {
-    if (author === undefined || !author.startsWith(THREAD_AUTHOR_PREFIX))
-        return undefined;
-    const id = author.slice(THREAD_AUTHOR_PREFIX.length);
-    return id === '' ? undefined : id;
-}
-export function applyNotes(sheet, comments) {
-    const headIds = new Set(sheet.commentThreads.flatMap((thread) => {
-        const head = thread.comments[0];
-        return head === undefined ? [] : [head.id];
-    }));
-    for (const [ref, comment] of comments) {
-        if (comment.threadId !== undefined && headIds.has(comment.threadId))
-            continue;
-        if (tryDecodeCellRef(ref) === undefined)
-            continue;
-        sheet.getCell(ref).note = comment.text;
-    }
+export function* liveCells(sheet) {
+    for (const { cells } of sheet.rows())
+        yield* cells;
 }

package/dist/io/xlsx/conditional-formatting.d.ts

@@ -1,36 +1,53 @@
 import { type ConditionalFormatting, type ConditionalFormattingRule } from '../../core/conditional-formatting.ts';
+import type { Worksheet } from '../../core/worksheet.ts';
 import { type CollectingPass } from '../../xml/xml-read.ts';
 import type { StyleRegistry } from './styles.ts';
-/** Each extended data bar's link id, keyed by rule identity: the one map both passes are handed. */
-export type DataBarExtLinks = ReadonlyMap<ConditionalFormattingRule, string>;
-export declare function dataBarExtLinks(formattings: readonly ConditionalFormatting[]): DataBarExtLinks;
 /**
- * Serialise every conditional formatting on a sheet into its `<conditionalFormatting>` blocks, in
- * insertion order. Returns '' when the sheet has none. A rule missing a `priority` is assigned the
- * next free one, so the output always satisfies Excel's requirement that every cfRule carry one.
+ * What the classic pass and the extension pass must agree on about a sheet's conditional formats,
+ * decided once and handed to both. A classic data bar's link and the `<x14:cfRule>` it names have to
+ * carry one id, and two rules in different forms must not be numbered alike, and each pass deriving its
+ * half itself makes both agreements hold by the two walks happening to visit the rules in one order.
  */
-export declare function conditionalFormattingsXml(formattings: readonly ConditionalFormatting[], styles: StyleRegistry, extLinks: DataBarExtLinks): string;
+export interface ConditionalFormattingPlan {
+    /** Every rule's priority: its own, or the next one free after every priority before it. */
+    readonly priorities: ReadonlyMap<ConditionalFormattingRule, number>;
+    /**
+     * The id of every rule with an `<x14:cfRule>`: a rule written wholly in the extension, and a classic
+     * data bar whose extra facets ride there. A rule absent from the map needs no extension.
+     */
+    readonly extensionIds: ReadonlyMap<ConditionalFormattingRule, string>;
+}
+/** Plan a sheet's conditional formats, in insertion order, for both serialisers. */
+export declare function planConditionalFormatting(formattings: readonly ConditionalFormatting[]): ConditionalFormattingPlan;
 /**
- * The worksheet `<extLst>` `<ext>` carrying the x14 data-bar extensions, or '' when no data bar needs
- * one. Each extension's `<x14:cfRule id>` is read from the same {@link dataBarExtLinks} map the classic
- * pass uses for the `<x14:id>` its cfRule carries, so the two ends of a link always match. Emitted bare
- * (no `<extLst>` wrapper) so the worksheet serialiser can gather it into a single `<extLst>` beside the
- * data-validation extension.
+ * Serialise the classic `<conditionalFormatting>` blocks of a sheet, in insertion order, leaving out
+ * every rule {@link conditionalFormattingsExtXml} writes in the extension form. Returns '' when no rule
+ * remains.
+ *
+ * A rule's formulas, its operands and a `formula` anchor alike, are stored with the function prefixes
+ * a cell formula takes, as Excel stores them; `formulaNames` is `formulaNamesInScope` for the sheet.
  */
-export declare function conditionalFormattingsExtXml(formattings: readonly ConditionalFormatting[], extLinks: DataBarExtLinks): string;
+export declare function conditionalFormattingsXml(formattings: readonly ConditionalFormatting[], styles: StyleRegistry, plan: ConditionalFormattingPlan, formulaNames: ReadonlySet<string>): string;
 /**
- * A pass reading a worksheet's conditional formatting into the model. The classic `<conditionalFormatting>`
- * blocks supply every rule; the x14 extension (`<x14:conditionalFormatting>` inside `<extLst>`) is
- * read only to enrich a classic data bar with the facets the classic element cannot carry (the
- * gradient flag and the negative-fill and axis colours) matched by the shared id the two ends link
- * on. An extension rule with no classic counterpart (a rule that lives only in x14) is ignored, so it
- * is never half-read into a broken classic rule.
+ * The worksheet `<extLst>` `<ext>` carrying the sheet's extension-form conditional formats, or '' when
+ * it needs none: every rule written wholly there, grouped under its set's range, and every classic data
+ * bar's extra facets, under the id the plan gave the link its cfRule carries. Emitted bare (no
+ * `<extLst>` wrapper) so the worksheet serialiser can gather it into a single `<extLst>` beside the
+ * data-validation extension.
  */
-export declare function conditionalFormattingPass(): CollectingPass<ConditionalFormatting[]>;
+export declare function conditionalFormattingsExtXml(formattings: readonly ConditionalFormatting[], styles: StyleRegistry, plan: ConditionalFormattingPlan, formulaNames: ReadonlySet<string>): string;
 /**
- * Extract the differential-style (`<dxf>`) fragments from styles.xml, each verbatim. Preserving the
- * raw XML, rather than reparsing and re-serialising, is what keeps a foreign dxf's number format a
- * real format code on re-write instead of a coerced `"[object Object]"`, and keeps every conditional
- * formatting's `dxfId` index pointing at the same style it did in the source file.
+ * A pass reading a worksheet's conditional formatting into the model, from both forms.
+ *
+ * The classic `<conditionalFormatting>` blocks come first. Each `<x14:conditionalFormatting>` in the
+ * worksheet extension that follows them is read as a set of its own, marked `extended`, unless its rule
+ * is a data bar a classic rule links to by id: that one only completes the classic rule with the facets
+ * and automatic anchors the classic element cannot carry. An extension rule's inline style is handed to
+ * `adoptDifferentialStyle`, which answers the index the rule then holds as its `dxfId`.
+ *
+ * A rule's formulas shed their function prefixes as a cell formula's do, against `definedNames`, the
+ * workbook's names as `definedNameKeys` spells them.
  */
-export declare function parseDxfs(stylesXml: string): string[];
+export declare function conditionalFormattingPass(definedNames: ReadonlySet<string>, adoptDifferentialStyle: (fragment: string) => number): CollectingPass<ConditionalFormatting[]>;
+/** Fold parsed conditional formattings onto a sheet, each bound to its original range. */
+export declare function applyConditionalFormattings(sheet: Worksheet, blocks: readonly ConditionalFormatting[]): void;