xls-codec 1.0.2 → 2.0.0

package/dist/written-cells.cjs

@@ -0,0 +1,26 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/written-cells.ts
+/**
+* Whether a cell carries real formatting beyond General/bottom-aligned/undecorated: a background fill, a border on at least one side, a non-default horizontal alignment, or a non-default vertical alignment.
+*
+* A present `borders` object is not enough on its own -- one with no side set describes no border at all, and treating it as formatting would mint an XF byte-identical to the undecorated one and, for an empty cell, a Blank record the reader would then correctly drop again. write.ts's own resolveDecorationForCell answers "no decoration" for exactly this set through this same predicate, so the two cannot disagree about what an empty-but-present borders object means.
+*/
+function cellCarriesFormatting(cell) {
+	if (cell.background !== void 0) return true;
+	if (cell.alignment !== void 0) return true;
+	if (cell.verticalAlignment !== void 0) return true;
+	const { borders } = cell;
+	if (borders === void 0) return false;
+	return borders.left !== void 0 || borders.right !== void 0 || borders.top !== void 0 || borders.bottom !== void 0;
+}
+/**
+* Whether the writer emits a cell record for this cell: a value record for anything carrying a value, or a Blank record for an `empty`-kind cell whose formatting is the only thing it has to say.
+*
+* An unformatted empty cell is written as nothing at all, which is what round-trips: content.ts's reader drops an unformatted blank cell, and a merged range's empty anchor is reconstructed from the MergeCells record alone. A formatted one is not that case -- its fill, borders, and alignment live only in the XF a cell record points at, so writing nothing for it discards them.
+*/
+function writesCellRecord(cell) {
+	return cell.value.kind !== "empty" || cellCarriesFormatting(cell);
+}
+//#endregion
+exports.cellCarriesFormatting = cellCarriesFormatting;
+exports.writesCellRecord = writesCellRecord;

package/dist/written-cells.d.cts

@@ -0,0 +1,16 @@
+import { ContentSheetCell } from "document-schema.js";
+//#region src/written-cells.d.ts
+/**
+ * Whether a cell carries real formatting beyond General/bottom-aligned/undecorated: a background fill, a border on at least one side, a non-default horizontal alignment, or a non-default vertical alignment.
+ *
+ * A present `borders` object is not enough on its own -- one with no side set describes no border at all, and treating it as formatting would mint an XF byte-identical to the undecorated one and, for an empty cell, a Blank record the reader would then correctly drop again. write.ts's own resolveDecorationForCell answers "no decoration" for exactly this set through this same predicate, so the two cannot disagree about what an empty-but-present borders object means.
+ */
+declare function cellCarriesFormatting(cell: ContentSheetCell): boolean;
+/**
+ * Whether the writer emits a cell record for this cell: a value record for anything carrying a value, or a Blank record for an `empty`-kind cell whose formatting is the only thing it has to say.
+ *
+ * An unformatted empty cell is written as nothing at all, which is what round-trips: content.ts's reader drops an unformatted blank cell, and a merged range's empty anchor is reconstructed from the MergeCells record alone. A formatted one is not that case -- its fill, borders, and alignment live only in the XF a cell record points at, so writing nothing for it discards them.
+ */
+declare function writesCellRecord(cell: ContentSheetCell): boolean;
+//#endregion
+export { cellCarriesFormatting, writesCellRecord };

package/dist/written-cells.d.ts

@@ -0,0 +1,16 @@
+import { ContentSheetCell } from "document-schema.js";
+//#region src/written-cells.d.ts
+/**
+ * Whether a cell carries real formatting beyond General/bottom-aligned/undecorated: a background fill, a border on at least one side, a non-default horizontal alignment, or a non-default vertical alignment.
+ *
+ * A present `borders` object is not enough on its own -- one with no side set describes no border at all, and treating it as formatting would mint an XF byte-identical to the undecorated one and, for an empty cell, a Blank record the reader would then correctly drop again. write.ts's own resolveDecorationForCell answers "no decoration" for exactly this set through this same predicate, so the two cannot disagree about what an empty-but-present borders object means.
+ */
+declare function cellCarriesFormatting(cell: ContentSheetCell): boolean;
+/**
+ * Whether the writer emits a cell record for this cell: a value record for anything carrying a value, or a Blank record for an `empty`-kind cell whose formatting is the only thing it has to say.
+ *
+ * An unformatted empty cell is written as nothing at all, which is what round-trips: content.ts's reader drops an unformatted blank cell, and a merged range's empty anchor is reconstructed from the MergeCells record alone. A formatted one is not that case -- its fill, borders, and alignment live only in the XF a cell record points at, so writing nothing for it discards them.
+ */
+declare function writesCellRecord(cell: ContentSheetCell): boolean;
+//#endregion
+export { cellCarriesFormatting, writesCellRecord };

package/dist/written-cells.js

@@ -0,0 +1,24 @@
+//#region src/written-cells.ts
+/**
+* Whether a cell carries real formatting beyond General/bottom-aligned/undecorated: a background fill, a border on at least one side, a non-default horizontal alignment, or a non-default vertical alignment.
+*
+* A present `borders` object is not enough on its own -- one with no side set describes no border at all, and treating it as formatting would mint an XF byte-identical to the undecorated one and, for an empty cell, a Blank record the reader would then correctly drop again. write.ts's own resolveDecorationForCell answers "no decoration" for exactly this set through this same predicate, so the two cannot disagree about what an empty-but-present borders object means.
+*/
+function cellCarriesFormatting(cell) {
+	if (cell.background !== void 0) return true;
+	if (cell.alignment !== void 0) return true;
+	if (cell.verticalAlignment !== void 0) return true;
+	const { borders } = cell;
+	if (borders === void 0) return false;
+	return borders.left !== void 0 || borders.right !== void 0 || borders.top !== void 0 || borders.bottom !== void 0;
+}
+/**
+* Whether the writer emits a cell record for this cell: a value record for anything carrying a value, or a Blank record for an `empty`-kind cell whose formatting is the only thing it has to say.
+*
+* An unformatted empty cell is written as nothing at all, which is what round-trips: content.ts's reader drops an unformatted blank cell, and a merged range's empty anchor is reconstructed from the MergeCells record alone. A formatted one is not that case -- its fill, borders, and alignment live only in the XF a cell record points at, so writing nothing for it discards them.
+*/
+function writesCellRecord(cell) {
+	return cell.value.kind !== "empty" || cellCarriesFormatting(cell);
+}
+//#endregion
+export { cellCarriesFormatting, writesCellRecord };

package/dist/xf-colors-CehHZtBy.d.cts

@@ -0,0 +1,91 @@
+import { t as BlockCursor } from "./cursor-VMtw9uVP.cjs";
+import { Alignment, Color, ContentBorder } from "document-schema.js";
+//#region src/biff/xf-colors.d.ts
+/** FLSNULL: no fill pattern -- the cell's fill colour fields carry no meaning. */
+declare const FILL_PATTERN_NONE = 0;
+/** FLSSOLID: a solid fill, the only pattern this package maps onto ContentSheetCell.background -- "If this value is 1 ... then only icvFore is rendered" ([MS-XLS] CellXF). Every other pattern (50%/75%/25% gray, the stripe and crosshatch families, ...) is a real information-loss case this reader does not approximate: see resolveFillBackground below. */
+declare const FILL_PATTERN_SOLID = 1;
+/** alc (a CellXF/StyleXF payload's word1, bits 0-2) -> ContentSheetCell.alignment, or undefined for ALCGEN (the value-kind default this field being absent already requests) and for the three HorizAlign members (ALCFILL/ALCCONTCTR/ALCDIST) Alignment has no member for -- matching ooxml.js's readHorizontalAlignment policy of only the four direct members surviving. */
+declare function resolveHorizontalAlignment(alc: number): Alignment | undefined;
+/** ContentSheetCell.alignment -> the alc token to pack into word1 -- undefined maps to ALCGEN, the "use the value-kind default" token every genuinely unaligned cell already carried before this module modelled alignment at all. */
+declare function horizAlignTokenFor(alignment: Alignment | undefined): number;
+/** alcV (word1, bits 4-6) -> ContentSheetCell.verticalAlignment, or undefined for ALCVBOT (the schema's own documented default for an absent verticalAlignment) and for the two VertAlign members (ALCVJUST/ALCVDIST) the schema has no member for -- matching ooxml.js's readVerticalAlignment policy. */
+declare function resolveVerticalAlignment(alcV: number): "top" | "middle" | "bottom" | undefined;
+/** ContentSheetCell.verticalAlignment -> the alcV token to pack into word1 -- undefined (meaning 'bottom', the schema's own documented default) and the literal 'bottom' both map to ALCVBOT, exactly what an unaligned cell already carried before this module modelled alignment at all. */
+declare function vertAlignTokenFor(verticalAlignment: "top" | "middle" | "bottom" | undefined): number;
+/** The alignment fields word1's alc/alcV carry, read or write side alike -- undefined in either field means the value-kind default (horizontal) or ALCVBOT (vertical), the identical meaning ContentSheetCell.alignment/verticalAlignment being absent already carries. */
+interface XfAlignmentFields {
+  readonly horizontal: Alignment | undefined;
+  readonly vertical: "top" | "middle" | "bottom" | undefined;
+}
+declare const BORDER_STYLE_NONE = 0;
+declare const BORDER_STYLE_THIN = 1;
+declare const BORDER_STYLE_MEDIUM = 2;
+declare const BORDER_STYLE_DASHED = 3;
+declare const BORDER_STYLE_DOTTED = 4;
+declare const BORDER_STYLE_THICK = 5;
+declare const BORDER_STYLE_DOUBLE = 6;
+declare const BORDER_STYLE_HAIR = 7;
+declare const BORDER_STYLE_MEDIUM_DASHED = 8;
+declare const BORDER_STYLE_DASHDOT = 9;
+declare const BORDER_STYLE_MEDIUM_DASHDOT = 10;
+declare const BORDER_STYLE_DASHDOTDOT = 11;
+declare const BORDER_STYLE_MEDIUM_DASHDOTDOT = 12;
+declare const BORDER_STYLE_SLANT_DASHDOT = 13;
+/** IcvXF's two "Automatic" special values: the foreground/background pair a real Excel-written XF with no explicit fill carries, and what this package's own writer emits for an undecorated cell. */
+declare const ICV_AUTOMATIC_FOREGROUND = 64;
+declare const ICV_AUTOMATIC_BACKGROUND = 65;
+/** icv 8-63's own base offset: icv 8 is rgColor[0] of a Palette record (or the default table's own entry 0) -- [MS-XLS] "Icv"'s own colour-table layout. */
+declare const PALETTE_BASE_ICV = 8;
+/** A Palette record's own fixed entry count ([MS-XLS] 2.4.188: "The value MUST be 56"). */
+declare const PALETTE_ENTRY_COUNT = 56;
+/** The reverse of DEFAULT_PALETTE_TABLE: a decoration colour's own hex string to the icv (8-63) it resolves to with NO Palette record present. write.ts's own colour-interning pass consults this to decide whether a workbook needs a real Palette record at all, or whether every distinct decoration colour it uses already has a home in the fixed default table. */
+declare const DEFAULT_PALETTE_HEX_TO_ICV: ReadonlyMap<string, number>;
+/**
+ * Resolves an icv colour-table index to a real colour, or undefined when the index names something this package cannot express as a fixed RGB value: 0x40/0x41 ("Automatic", a display-setting colour with no fixed literal), 0x48/0x4D-0x51/0x7FFF (chart/tooltip display colours, out of scope for a cell's own fill/border), or anything else outside the documented ranges.
+ *
+ * `palette`, when given, is the workbook's own Palette record contents (56 entries, icv 8 first); when undefined, icv 8-63 resolve through the fixed default table instead -- [MS-XLS] "Icv"'s own documented fallback for a file carrying no Palette record.
+ */
+declare function resolveIcvColor(icv: number, palette: readonly Color[] | undefined): Color | undefined;
+/** One border edge's own raw fields, as the CellXF/StyleXF trailing payload packs them: a BorderStyle line-style token and a 7-bit icv colour index. */
+interface XfBorderEdge {
+  readonly style: number;
+  readonly icv: number;
+}
+/** Resolves one border edge to a ContentBorder, or undefined when the edge carries no border (style is BORDER_STYLE_NONE), names a reserved/unrecognised style token, or its colour does not resolve to a fixed RGB value (an "Automatic" or display-setting icv, which [MS-XLS] documents as illegal for a well-formed border but a malformed file could still carry). */
+declare function resolveBorderEdge(edge: XfBorderEdge, palette: readonly Color[] | undefined): ContentBorder | undefined;
+/** The inverse of resolveBorderEdge's style resolution: picks the BorderStyle token carrying a ContentBorder's own pattern at the closest named weight, bucketing a solid/dashed border's widthPt back to a weight through document-schema.js's own shared quantisation -- the same one resolveBorderEdge's widths came out of, and the same one ooxml.js's borderToXlsxStyle buckets xlsx's string tokens through. */
+declare function borderStyleTokenFor(border: ContentBorder): number;
+/** A solid fill's own foreground colour resolved to a real background, or undefined for every other FillPattern value -- FLSNULL (no fill at all) and every pattern beyond solid (50%/75%/25% gray, the stripe and crosshatch family) alike. A non-solid pattern is a real information-loss case rather than an oversight: ContentSheetCell.background models one flat colour, and approximating a striped or crosshatched fill as its foreground colour alone would misrepresent what the cell actually shows -- see xls-codec's README for this package's own stated judgment call. */
+declare function resolveFillBackground(fillPattern: number, foregroundIcv: number, palette: readonly Color[] | undefined): Color | undefined;
+/** Every decoration field the trailing payload's word2/word3/word4 carry ([MS-XLS] 2.4.353's own CellXF/StyleXF "Data" field), read or write side alike: which fill pattern (if any) and its foreground colour, and each of the four sides' own border style plus colour. Diagonal borders (dgDiag/grbitDiag/icvDiag) are out of this package's scope -- ContentCellBordersSchema has no diagonal member -- and are always read as absent / always written as none. */
+interface XfDecorationFields {
+  readonly fillPattern: number;
+  readonly fillForegroundIcv: number;
+  readonly left: XfBorderEdge;
+  readonly right: XfBorderEdge;
+  readonly top: XfBorderEdge;
+  readonly bottom: XfBorderEdge;
+}
+/** The fields a genuinely undecorated cell XF carries -- no fill, no borders -- matching exactly what xf-writer.ts wrote before this module existed (icvFore/icvBack at the "Automatic" special values, fls/dg all 0), so packXfDecorationWords() with no argument reproduces the identical bytes. */
+declare const UNDECORATED_XF_FIELDS: XfDecorationFields;
+/** Unpacks word1 -- the CellXF/StyleXF trailing payload's leading word ([MS-XLS] 2.4.353's own field table, cited in full in xf-writer.ts's packAlignmentPrefix) -- into the two fields this package's schema can express: alc (bits 0-2) and alcV (bits 4-6). Every other field the word carries (fWrap, fJustLast, trot, cIndent, fShrinkToFit, iReadOrder, the fAtr* inheritance flags) has no ContentSheetCell counterpart and is not read. */
+declare function unpackXfAlignment(word1: number): XfAlignmentFields;
+/** Unpacks the three raw words a CellXF/StyleXF trailing payload's border/fill fields live in ([MS-XLS] 2.4.353's own field table, cited in full in xf-writer.ts's packXfDecorationWords below) into XfDecorationFields. word2 is the 32-bit border word (dgLeft/dgRight/dgTop/dgBottom/icvLeft/icvRight/grbitDiag), word3 the 32-bit fill-pattern word (icvTop/icvBottom/icvDiag/dgDiag/fHasXFExt/fls), word4 the 16-bit fill-colour word (icvFore/icvBack/...). */
+declare function unpackXfDecoration(word2: number, word3: number, word4: number): XfDecorationFields;
+/**
+ * Packs XfDecorationFields back into the three raw words unpackXfDecoration reads -- the write-side mirror, and (with no argument) the exact bytes a genuinely undecorated XF always carried before this module existed: word2/word3 all zero (no borders, no fill pattern), word4 at the "Automatic" foreground/background pair. Diagonal fields (grbitDiag, dgDiag, icvDiag, fHasXFExt/reserved2) are always written as 0 -- this package's writer never emits a diagonal border.
+ *
+ * [MS-XLS] 2.4.353's own CellXF field table, the layout every bit position below is cited to: word2 = dgLeft(4) dgRight(4) dgTop(4) dgBottom(4) icvLeft(7) icvRight(7) grbitDiag(2); word3 = icvTop(7) icvBottom(7) icvDiag(7) dgDiag(4) fHasXFExt(1) fls(6); word4 = icvFore(7) icvBack(7) fsxButton(1) reserved3(1). https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-xls/671c8577-901f-4215-9ebf-6f5890e5896d
+ */
+declare function packXfDecorationWords(decoration?: XfDecorationFields): {
+  word2: number;
+  word3: number;
+  word4: number;
+};
+/** LongRGB: red, green, blue, then a reserved byte that MUST be 0 -- one entry of a Palette record's rgColor array, or of the fixed-length buffer this package's own writer emits. */
+declare function readLongRgbColor(cursor: BlockCursor): Color;
+/** The inverse of readLongRgbColor: a colour's own red/green/blue/reserved bytes, rounded to the nearest byte (the same rounding colorToRgbHex applies) -- exact for any colour this package itself constructed via rgbHexToColor, which is what write.ts's own palette-colour interning does. */
+declare function longRgbBytesOf(color: Color): readonly [number, number, number, number];
+//#endregion
+export { readLongRgbColor as A, XfAlignmentFields as C, horizAlignTokenFor as D, borderStyleTokenFor as E, resolveVerticalAlignment as F, unpackXfAlignment as I, unpackXfDecoration as L, resolveFillBackground as M, resolveHorizontalAlignment as N, longRgbBytesOf as O, resolveIcvColor as P, vertAlignTokenFor as R, UNDECORATED_XF_FIELDS as S, XfDecorationFields as T, FILL_PATTERN_SOLID as _, BORDER_STYLE_DOUBLE as a, PALETTE_BASE_ICV as b, BORDER_STYLE_MEDIUM_DASHDOT as c, BORDER_STYLE_NONE as d, BORDER_STYLE_SLANT_DASHDOT as f, FILL_PATTERN_NONE as g, DEFAULT_PALETTE_HEX_TO_ICV as h, BORDER_STYLE_DOTTED as i, resolveBorderEdge as j, packXfDecorationWords as k, BORDER_STYLE_MEDIUM_DASHDOTDOT as l, BORDER_STYLE_THIN as m, BORDER_STYLE_DASHDOTDOT as n, BORDER_STYLE_HAIR as o, BORDER_STYLE_THICK as p, BORDER_STYLE_DASHED as r, BORDER_STYLE_MEDIUM as s, BORDER_STYLE_DASHDOT as t, BORDER_STYLE_MEDIUM_DASHED as u, ICV_AUTOMATIC_BACKGROUND as v, XfBorderEdge as w, PALETTE_ENTRY_COUNT as x, ICV_AUTOMATIC_FOREGROUND as y };

package/dist/xf-colors-CpykR3B9.d.ts

@@ -0,0 +1,91 @@
+import { t as BlockCursor } from "./cursor-VMtw9uVP.js";
+import { Alignment, Color, ContentBorder } from "document-schema.js";
+//#region src/biff/xf-colors.d.ts
+/** FLSNULL: no fill pattern -- the cell's fill colour fields carry no meaning. */
+declare const FILL_PATTERN_NONE = 0;
+/** FLSSOLID: a solid fill, the only pattern this package maps onto ContentSheetCell.background -- "If this value is 1 ... then only icvFore is rendered" ([MS-XLS] CellXF). Every other pattern (50%/75%/25% gray, the stripe and crosshatch families, ...) is a real information-loss case this reader does not approximate: see resolveFillBackground below. */
+declare const FILL_PATTERN_SOLID = 1;
+/** alc (a CellXF/StyleXF payload's word1, bits 0-2) -> ContentSheetCell.alignment, or undefined for ALCGEN (the value-kind default this field being absent already requests) and for the three HorizAlign members (ALCFILL/ALCCONTCTR/ALCDIST) Alignment has no member for -- matching ooxml.js's readHorizontalAlignment policy of only the four direct members surviving. */
+declare function resolveHorizontalAlignment(alc: number): Alignment | undefined;
+/** ContentSheetCell.alignment -> the alc token to pack into word1 -- undefined maps to ALCGEN, the "use the value-kind default" token every genuinely unaligned cell already carried before this module modelled alignment at all. */
+declare function horizAlignTokenFor(alignment: Alignment | undefined): number;
+/** alcV (word1, bits 4-6) -> ContentSheetCell.verticalAlignment, or undefined for ALCVBOT (the schema's own documented default for an absent verticalAlignment) and for the two VertAlign members (ALCVJUST/ALCVDIST) the schema has no member for -- matching ooxml.js's readVerticalAlignment policy. */
+declare function resolveVerticalAlignment(alcV: number): "top" | "middle" | "bottom" | undefined;
+/** ContentSheetCell.verticalAlignment -> the alcV token to pack into word1 -- undefined (meaning 'bottom', the schema's own documented default) and the literal 'bottom' both map to ALCVBOT, exactly what an unaligned cell already carried before this module modelled alignment at all. */
+declare function vertAlignTokenFor(verticalAlignment: "top" | "middle" | "bottom" | undefined): number;
+/** The alignment fields word1's alc/alcV carry, read or write side alike -- undefined in either field means the value-kind default (horizontal) or ALCVBOT (vertical), the identical meaning ContentSheetCell.alignment/verticalAlignment being absent already carries. */
+interface XfAlignmentFields {
+  readonly horizontal: Alignment | undefined;
+  readonly vertical: "top" | "middle" | "bottom" | undefined;
+}
+declare const BORDER_STYLE_NONE = 0;
+declare const BORDER_STYLE_THIN = 1;
+declare const BORDER_STYLE_MEDIUM = 2;
+declare const BORDER_STYLE_DASHED = 3;
+declare const BORDER_STYLE_DOTTED = 4;
+declare const BORDER_STYLE_THICK = 5;
+declare const BORDER_STYLE_DOUBLE = 6;
+declare const BORDER_STYLE_HAIR = 7;
+declare const BORDER_STYLE_MEDIUM_DASHED = 8;
+declare const BORDER_STYLE_DASHDOT = 9;
+declare const BORDER_STYLE_MEDIUM_DASHDOT = 10;
+declare const BORDER_STYLE_DASHDOTDOT = 11;
+declare const BORDER_STYLE_MEDIUM_DASHDOTDOT = 12;
+declare const BORDER_STYLE_SLANT_DASHDOT = 13;
+/** IcvXF's two "Automatic" special values: the foreground/background pair a real Excel-written XF with no explicit fill carries, and what this package's own writer emits for an undecorated cell. */
+declare const ICV_AUTOMATIC_FOREGROUND = 64;
+declare const ICV_AUTOMATIC_BACKGROUND = 65;
+/** icv 8-63's own base offset: icv 8 is rgColor[0] of a Palette record (or the default table's own entry 0) -- [MS-XLS] "Icv"'s own colour-table layout. */
+declare const PALETTE_BASE_ICV = 8;
+/** A Palette record's own fixed entry count ([MS-XLS] 2.4.188: "The value MUST be 56"). */
+declare const PALETTE_ENTRY_COUNT = 56;
+/** The reverse of DEFAULT_PALETTE_TABLE: a decoration colour's own hex string to the icv (8-63) it resolves to with NO Palette record present. write.ts's own colour-interning pass consults this to decide whether a workbook needs a real Palette record at all, or whether every distinct decoration colour it uses already has a home in the fixed default table. */
+declare const DEFAULT_PALETTE_HEX_TO_ICV: ReadonlyMap<string, number>;
+/**
+ * Resolves an icv colour-table index to a real colour, or undefined when the index names something this package cannot express as a fixed RGB value: 0x40/0x41 ("Automatic", a display-setting colour with no fixed literal), 0x48/0x4D-0x51/0x7FFF (chart/tooltip display colours, out of scope for a cell's own fill/border), or anything else outside the documented ranges.
+ *
+ * `palette`, when given, is the workbook's own Palette record contents (56 entries, icv 8 first); when undefined, icv 8-63 resolve through the fixed default table instead -- [MS-XLS] "Icv"'s own documented fallback for a file carrying no Palette record.
+ */
+declare function resolveIcvColor(icv: number, palette: readonly Color[] | undefined): Color | undefined;
+/** One border edge's own raw fields, as the CellXF/StyleXF trailing payload packs them: a BorderStyle line-style token and a 7-bit icv colour index. */
+interface XfBorderEdge {
+  readonly style: number;
+  readonly icv: number;
+}
+/** Resolves one border edge to a ContentBorder, or undefined when the edge carries no border (style is BORDER_STYLE_NONE), names a reserved/unrecognised style token, or its colour does not resolve to a fixed RGB value (an "Automatic" or display-setting icv, which [MS-XLS] documents as illegal for a well-formed border but a malformed file could still carry). */
+declare function resolveBorderEdge(edge: XfBorderEdge, palette: readonly Color[] | undefined): ContentBorder | undefined;
+/** The inverse of resolveBorderEdge's style resolution: picks the BorderStyle token carrying a ContentBorder's own pattern at the closest named weight, bucketing a solid/dashed border's widthPt back to a weight through document-schema.js's own shared quantisation -- the same one resolveBorderEdge's widths came out of, and the same one ooxml.js's borderToXlsxStyle buckets xlsx's string tokens through. */
+declare function borderStyleTokenFor(border: ContentBorder): number;
+/** A solid fill's own foreground colour resolved to a real background, or undefined for every other FillPattern value -- FLSNULL (no fill at all) and every pattern beyond solid (50%/75%/25% gray, the stripe and crosshatch family) alike. A non-solid pattern is a real information-loss case rather than an oversight: ContentSheetCell.background models one flat colour, and approximating a striped or crosshatched fill as its foreground colour alone would misrepresent what the cell actually shows -- see xls-codec's README for this package's own stated judgment call. */
+declare function resolveFillBackground(fillPattern: number, foregroundIcv: number, palette: readonly Color[] | undefined): Color | undefined;
+/** Every decoration field the trailing payload's word2/word3/word4 carry ([MS-XLS] 2.4.353's own CellXF/StyleXF "Data" field), read or write side alike: which fill pattern (if any) and its foreground colour, and each of the four sides' own border style plus colour. Diagonal borders (dgDiag/grbitDiag/icvDiag) are out of this package's scope -- ContentCellBordersSchema has no diagonal member -- and are always read as absent / always written as none. */
+interface XfDecorationFields {
+  readonly fillPattern: number;
+  readonly fillForegroundIcv: number;
+  readonly left: XfBorderEdge;
+  readonly right: XfBorderEdge;
+  readonly top: XfBorderEdge;
+  readonly bottom: XfBorderEdge;
+}
+/** The fields a genuinely undecorated cell XF carries -- no fill, no borders -- matching exactly what xf-writer.ts wrote before this module existed (icvFore/icvBack at the "Automatic" special values, fls/dg all 0), so packXfDecorationWords() with no argument reproduces the identical bytes. */
+declare const UNDECORATED_XF_FIELDS: XfDecorationFields;
+/** Unpacks word1 -- the CellXF/StyleXF trailing payload's leading word ([MS-XLS] 2.4.353's own field table, cited in full in xf-writer.ts's packAlignmentPrefix) -- into the two fields this package's schema can express: alc (bits 0-2) and alcV (bits 4-6). Every other field the word carries (fWrap, fJustLast, trot, cIndent, fShrinkToFit, iReadOrder, the fAtr* inheritance flags) has no ContentSheetCell counterpart and is not read. */
+declare function unpackXfAlignment(word1: number): XfAlignmentFields;
+/** Unpacks the three raw words a CellXF/StyleXF trailing payload's border/fill fields live in ([MS-XLS] 2.4.353's own field table, cited in full in xf-writer.ts's packXfDecorationWords below) into XfDecorationFields. word2 is the 32-bit border word (dgLeft/dgRight/dgTop/dgBottom/icvLeft/icvRight/grbitDiag), word3 the 32-bit fill-pattern word (icvTop/icvBottom/icvDiag/dgDiag/fHasXFExt/fls), word4 the 16-bit fill-colour word (icvFore/icvBack/...). */
+declare function unpackXfDecoration(word2: number, word3: number, word4: number): XfDecorationFields;
+/**
+ * Packs XfDecorationFields back into the three raw words unpackXfDecoration reads -- the write-side mirror, and (with no argument) the exact bytes a genuinely undecorated XF always carried before this module existed: word2/word3 all zero (no borders, no fill pattern), word4 at the "Automatic" foreground/background pair. Diagonal fields (grbitDiag, dgDiag, icvDiag, fHasXFExt/reserved2) are always written as 0 -- this package's writer never emits a diagonal border.
+ *
+ * [MS-XLS] 2.4.353's own CellXF field table, the layout every bit position below is cited to: word2 = dgLeft(4) dgRight(4) dgTop(4) dgBottom(4) icvLeft(7) icvRight(7) grbitDiag(2); word3 = icvTop(7) icvBottom(7) icvDiag(7) dgDiag(4) fHasXFExt(1) fls(6); word4 = icvFore(7) icvBack(7) fsxButton(1) reserved3(1). https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-xls/671c8577-901f-4215-9ebf-6f5890e5896d
+ */
+declare function packXfDecorationWords(decoration?: XfDecorationFields): {
+  word2: number;
+  word3: number;
+  word4: number;
+};
+/** LongRGB: red, green, blue, then a reserved byte that MUST be 0 -- one entry of a Palette record's rgColor array, or of the fixed-length buffer this package's own writer emits. */
+declare function readLongRgbColor(cursor: BlockCursor): Color;
+/** The inverse of readLongRgbColor: a colour's own red/green/blue/reserved bytes, rounded to the nearest byte (the same rounding colorToRgbHex applies) -- exact for any colour this package itself constructed via rgbHexToColor, which is what write.ts's own palette-colour interning does. */
+declare function longRgbBytesOf(color: Color): readonly [number, number, number, number];
+//#endregion
+export { readLongRgbColor as A, XfAlignmentFields as C, horizAlignTokenFor as D, borderStyleTokenFor as E, resolveVerticalAlignment as F, unpackXfAlignment as I, unpackXfDecoration as L, resolveFillBackground as M, resolveHorizontalAlignment as N, longRgbBytesOf as O, resolveIcvColor as P, vertAlignTokenFor as R, UNDECORATED_XF_FIELDS as S, XfDecorationFields as T, FILL_PATTERN_SOLID as _, BORDER_STYLE_DOUBLE as a, PALETTE_BASE_ICV as b, BORDER_STYLE_MEDIUM_DASHDOT as c, BORDER_STYLE_NONE as d, BORDER_STYLE_SLANT_DASHDOT as f, FILL_PATTERN_NONE as g, DEFAULT_PALETTE_HEX_TO_ICV as h, BORDER_STYLE_DOTTED as i, resolveBorderEdge as j, packXfDecorationWords as k, BORDER_STYLE_MEDIUM_DASHDOTDOT as l, BORDER_STYLE_THIN as m, BORDER_STYLE_DASHDOTDOT as n, BORDER_STYLE_HAIR as o, BORDER_STYLE_THICK as p, BORDER_STYLE_DASHED as r, BORDER_STYLE_MEDIUM as s, BORDER_STYLE_DASHDOT as t, BORDER_STYLE_MEDIUM_DASHED as u, ICV_AUTOMATIC_BACKGROUND as v, XfBorderEdge as w, PALETTE_ENTRY_COUNT as x, ICV_AUTOMATIC_FOREGROUND as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xls-codec",
-  "version": "1.0.2",
+  "version": "2.0.0",
   "description": "Hand-written reader for the legacy Excel Binary File Format (.xls, BIFF8) as specified by [MS-XLS], mapping a workbook's record stream onto the shared document-schema.js spreadsheet model - the .xls codec for the documents.js family.",
   "type": "module",
   "repository": {
@@ -67,8 +67,9 @@
   },
   "packageManager": "pnpm@11.6.0",
   "dependencies": {
-    "archive-codec": "^1.3.0",
-    "document-schema.js": "^5.5.0"
+    "archive-codec": "^1.4.0",
+    "document-schema.js": "^5.5.1",
+    "excel-number-format": "^1.0.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",

package/dist/number-format.cjs

@@ -1,298 +0,0 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-//#region src/number-format.ts
-/** Excel honours at most four sections (positive; negative; zero; text); a fifth is malformed and is dropped rather than guessed at. */
-const MAX_SECTIONS = 4;
-/** Mirrors String.prototype.charAt's past-the-end contract, but over a CODE POINT array, so a rare astral currency symbol stays one token instead of splitting into two lone surrogates. */
-function at(chars, index) {
-	return chars[index] ?? "";
-}
-function tokenize(formatCode) {
-	const chars = [...formatCode];
-	const tokens = [];
-	let index = 0;
-	while (index < chars.length) {
-		const char = at(chars, index);
-		if (char === "\"") {
-			let text = "";
-			index += 1;
-			while (index < chars.length && at(chars, index) !== "\"") {
-				text += at(chars, index);
-				index += 1;
-			}
-			index += 1;
-			tokens.push({
-				kind: "literal",
-				text
-			});
-			continue;
-		}
-		if (char === "\\" || char === "_" || char === "*") {
-			tokens.push({
-				kind: "literal",
-				text: at(chars, index + 1)
-			});
-			index += 2;
-			continue;
-		}
-		if (char === "[") {
-			let body = "";
-			index += 1;
-			while (index < chars.length && at(chars, index) !== "]") {
-				body += at(chars, index);
-				index += 1;
-			}
-			index += 1;
-			tokens.push({
-				kind: "bracket",
-				body
-			});
-			continue;
-		}
-		if (char === ";") {
-			tokens.push({ kind: "separator" });
-			index += 1;
-			continue;
-		}
-		tokens.push({
-			kind: "code",
-			char
-		});
-		index += 1;
-	}
-	return tokens;
-}
-/** Splits on separator tokens only: a ';' inside a quote or bracket was already consumed as part of that token, so it can never split a section here. */
-function splitSections(tokens) {
-	const sections = [];
-	let current = [];
-	for (const token of tokens) {
-		if (token.kind === "separator") {
-			sections.push(current);
-			current = [];
-			continue;
-		}
-		current.push(token);
-	}
-	sections.push(current);
-	return sections.slice(0, MAX_SECTIONS);
-}
-/** The Unicode Currency_Symbol category IS the definition of "this character means money", so it is tested directly rather than against a hand-listed subset that would omit whichever symbol a real file happens to use. */
-const CURRENCY_SYMBOL = /\p{Sc}/u;
-/** `[$GBP-809]` carries an ISO 4217 code; `[$£-809]` carries a display symbol instead. Only the three-ASCII-letter shape counts as a code, because ContentCellValue's `currency` field is documented as the ISO code and there is no faithful symbol-to-code mapping ('$' alone is USD, CAD, AUD and a dozen others). */
-function isIsoCurrencyCodeShape(marker) {
-	if (marker.length !== 3) return false;
-	for (const char of marker) {
-		const upper = char.toUpperCase();
-		if (upper < "A" || upper > "Z") return false;
-	}
-	return true;
-}
-/** An elapsed-time bucket is a bracket holding one repeated h/m/s and nothing else -- the marker that the value is a DURATION, which may legitimately exceed 24 hours, rather than a time of day. */
-function isElapsedBracketBody(body) {
-	let letter;
-	for (const char of body) {
-		const lower = char.toLowerCase();
-		if (letter === void 0) {
-			if (lower !== "h" && lower !== "m" && lower !== "s") return false;
-			letter = lower;
-		} else if (lower !== letter) return false;
-	}
-	return letter !== void 0;
-}
-function classifyBracket(body) {
-	if (body.startsWith("$")) {
-		const rest = body.slice(1);
-		const dashIndex = rest.indexOf("-");
-		const marker = dashIndex === -1 ? rest : rest.slice(0, dashIndex);
-		if (marker === "") return { kind: "none" };
-		return isIsoCurrencyCodeShape(marker) ? {
-			kind: "currency",
-			code: marker.toUpperCase()
-		} : { kind: "currency" };
-	}
-	return isElapsedBracketBody(body) ? { kind: "elapsed" } : { kind: "none" };
-}
-const AMPM_MARKERS = ["am/pm", "a/p"];
-const AMPM_LETTER = "ampm";
-function matchesAt(chars, index, marker) {
-	return [...marker].every((char, offset) => at(chars, index + offset).toLowerCase() === char);
-}
-function codeRunsOf(section) {
-	const chars = [];
-	for (const token of section) if (token.kind === "code") chars.push(token.char);
-	const runs = [];
-	let index = 0;
-	while (index < chars.length) {
-		const marker = AMPM_MARKERS.find((candidate) => matchesAt(chars, index, candidate));
-		if (marker !== void 0) {
-			runs.push({
-				letter: AMPM_LETTER,
-				length: marker.length
-			});
-			index += marker.length;
-			continue;
-		}
-		const char = at(chars, index).toLowerCase();
-		let length = 0;
-		while (index + length < chars.length && at(chars, index + length).toLowerCase() === char) length += 1;
-		runs.push({
-			letter: char,
-			length
-		});
-		index += length;
-	}
-	return runs;
-}
-/** The letters an ambiguous 'm' looks past its neighbours for. 'm' itself is excluded: an unresolved 'm' carries no information for resolving another, so `hh:mm:mm` resolves both against the 'hh'. */
-const RESOLVING_LETTERS = [
-	"y",
-	"d",
-	"h",
-	"s"
-];
-function nearestResolvingLetter(runs, from, step) {
-	for (let index = from + step; index >= 0 && index < runs.length; index += step) {
-		const run = runs[index];
-		if (run !== void 0 && RESOLVING_LETTERS.includes(run.letter)) return run.letter;
-	}
-}
-/** Excel's minutes-vs-months rule: 'm'/'mm' is minutes when the nearest preceding date/time code is an hour or the nearest following one is a second, and a month otherwise. 'mmm' and longer are always month names. This is what makes `yyyy-mm-dd hh:mm:ss` resolve its two identical 'mm' runs oppositely. */
-function monthRunIsMinutes(runs, index) {
-	return nearestResolvingLetter(runs, index, -1) === "h" || nearestResolvingLetter(runs, index, 1) === "s";
-}
-const PLAIN_NUMBER = { kind: "number" };
-/** Digit placeholders ('0' required, '#' suppressed, '?' space-padded), the decimal and thousands separators. Scientific notation's 'e' is handled at its own run, since a bare 'e' also occurs inside the literal word "General". */
-const NUMERIC_CODES = [
-	"0",
-	"#",
-	"?",
-	".",
-	","
-];
-function collectSignals(section) {
-	const signals = {
-		hasDate: false,
-		hasTime: false,
-		hasElapsed: false,
-		hasPercent: false,
-		hasNumeric: false,
-		hasText: false,
-		hasCurrency: false
-	};
-	for (const token of section) {
-		if (token.kind === "literal" && CURRENCY_SYMBOL.test(token.text)) signals.hasCurrency = true;
-		if (token.kind === "bracket") {
-			const meaning = classifyBracket(token.body);
-			if (meaning.kind === "elapsed") signals.hasElapsed = true;
-			if (meaning.kind === "currency") {
-				signals.hasCurrency = true;
-				if (signals.currencyCode === void 0 && meaning.code !== void 0) signals.currencyCode = meaning.code;
-			}
-		}
-	}
-	const runs = codeRunsOf(section);
-	runs.forEach((run, index) => {
-		if (run.letter === "y" || run.letter === "d") {
-			signals.hasDate = true;
-			return;
-		}
-		if (run.letter === "h" || run.letter === "s" || run.letter === AMPM_LETTER) {
-			signals.hasTime = true;
-			return;
-		}
-		if (run.letter === "m") {
-			if (run.length <= 2 && monthRunIsMinutes(runs, index)) signals.hasTime = true;
-			else signals.hasDate = true;
-			return;
-		}
-		if (run.letter === "e") {
-			const next = runs[index + 1];
-			signals.hasNumeric = signals.hasNumeric || next?.letter === "+" || next?.letter === "-";
-			return;
-		}
-		if (run.letter === "%") {
-			signals.hasPercent = true;
-			return;
-		}
-		if (run.letter === "@") {
-			signals.hasText = true;
-			return;
-		}
-		if (NUMERIC_CODES.includes(run.letter)) {
-			signals.hasNumeric = true;
-			return;
-		}
-		if (CURRENCY_SYMBOL.test(run.letter)) signals.hasCurrency = true;
-	});
-	return signals;
-}
-/** Precedence when a format carries several signals at once, most specific first: an elapsed-time bracket beats everything (the only marker separating a duration from a time of day); any date code beats any time code (a format with both is a genuine combined date-and-time); a percent sign beats a currency marker (`[$GBP-809]0.00%` is still a percentage); and a text placeholder only wins when the section has no numeric placeholder to be a number with. */
-function classifySection(section) {
-	const signals = collectSignals(section);
-	if (signals.hasElapsed) return { kind: "elapsedTime" };
-	if (signals.hasDate) return signals.hasTime ? { kind: "dateTime" } : { kind: "date" };
-	if (signals.hasTime) return { kind: "time" };
-	if (signals.hasPercent) return { kind: "percentage" };
-	if (signals.hasCurrency) {
-		const code = signals.currencyCode;
-		return code === void 0 ? { kind: "currency" } : {
-			kind: "currency",
-			code
-		};
-	}
-	if (signals.hasText && !signals.hasNumeric) return { kind: "text" };
-	return PLAIN_NUMBER;
-}
-/** Classifies a format code, reading the FIRST section only. Sections two through four are the negative/zero/text renderings of the same underlying value: they differ in colour, parentheses, and literal text, never in what kind of thing the cell holds, and a cell whose value happens to be negative must not classify differently from the identical cell holding a positive one. */
-function classifyNumberFormat(formatCode) {
-	const first = splitSections(tokenize(formatCode))[0];
-	return first === void 0 ? PLAIN_NUMBER : classifySection(first);
-}
-/**
-* The built-in format codes, which a file never writes into its own Format records and every reader is expected to know.
-*
-* [MS-XLS] 2.4.126 constrains a Format record's own ifmt to 5-8, 23-26, 41-44, 63-66, and 164-382, so an XF pointing at any other identifier resolves through this table instead. The codes are ECMA-376 Part 1 SS18.8.30's table, which BIFF8 and xlsx share.
-*
-* Ids 23-36 are deliberately absent: that table leaves them reserved, and inventing codes for them would fabricate a mapping no specification defines -- an XF pointing at one resolves to no code at all, which the caller reports as absent rather than silently substituting General. These strings are fed through the SAME classifyNumberFormat as a producer-declared code, never a second table of pre-decided kinds, so the two feeds cannot drift apart.
-*/
-const BUILTIN_NUMBER_FORMATS = /* @__PURE__ */ new Map([
-	[0, "General"],
-	[1, "0"],
-	[2, "0.00"],
-	[3, "#,##0"],
-	[4, "#,##0.00"],
-	[5, "$#,##0_);($#,##0)"],
-	[6, "$#,##0_);[Red]($#,##0)"],
-	[7, "$#,##0.00_);($#,##0.00)"],
-	[8, "$#,##0.00_);[Red]($#,##0.00)"],
-	[9, "0%"],
-	[10, "0.00%"],
-	[11, "0.00E+00"],
-	[12, "# ?/?"],
-	[13, "# ??/??"],
-	[14, "mm-dd-yy"],
-	[15, "d-mmm-yy"],
-	[16, "d-mmm"],
-	[17, "mmm-yy"],
-	[18, "h:mm AM/PM"],
-	[19, "h:mm:ss AM/PM"],
-	[20, "h:mm"],
-	[21, "h:mm:ss"],
-	[22, "m/d/yy h:mm"],
-	[37, "#,##0 ;(#,##0)"],
-	[38, "#,##0 ;[Red](#,##0)"],
-	[39, "#,##0.00;(#,##0.00)"],
-	[40, "#,##0.00;[Red](#,##0.00)"],
-	[41, "_(* #,##0_);_(* \\(#,##0\\);_(* \"-\"_);_(@_)"],
-	[42, "_(\"$\"* #,##0_);_(\"$\"* \\(#,##0\\);_(\"$\"* \"-\"_);_(@_)"],
-	[43, "_(* #,##0.00_);_(* \\(#,##0.00\\);_(* \"-\"??_);_(@_)"],
-	[44, "_(\"$\"* #,##0.00_);_(\"$\"* \\(#,##0.00\\);_(\"$\"* \"-\"??_);_(@_)"],
-	[45, "mm:ss"],
-	[46, "[h]:mm:ss"],
-	[47, "mmss.0"],
-	[48, "##0.0E+0"],
-	[49, "@"]
-]);
-//#endregion
-exports.BUILTIN_NUMBER_FORMATS = BUILTIN_NUMBER_FORMATS;
-exports.classifyNumberFormat = classifyNumberFormat;

package/dist/number-format.d.cts

@@ -1,32 +0,0 @@
-//#region src/number-format.d.ts
-/** What a format code says the value is. `elapsedTime` is kept distinct from `time` because a duration may exceed 24 hours and so has no wall-clock spelling in the schema. */
-type NumberFormatClass = {
-  kind: "number";
-} | {
-  kind: "text";
-} | {
-  kind: "percentage";
-} | {
-  kind: "currency";
-  code?: string;
-} | {
-  kind: "date";
-} | {
-  kind: "time";
-} | {
-  kind: "dateTime";
-} | {
-  kind: "elapsedTime";
-};
-/** Classifies a format code, reading the FIRST section only. Sections two through four are the negative/zero/text renderings of the same underlying value: they differ in colour, parentheses, and literal text, never in what kind of thing the cell holds, and a cell whose value happens to be negative must not classify differently from the identical cell holding a positive one. */
-declare function classifyNumberFormat(formatCode: string): NumberFormatClass;
-/**
- * The built-in format codes, which a file never writes into its own Format records and every reader is expected to know.
- *
- * [MS-XLS] 2.4.126 constrains a Format record's own ifmt to 5-8, 23-26, 41-44, 63-66, and 164-382, so an XF pointing at any other identifier resolves through this table instead. The codes are ECMA-376 Part 1 SS18.8.30's table, which BIFF8 and xlsx share.
- *
- * Ids 23-36 are deliberately absent: that table leaves them reserved, and inventing codes for them would fabricate a mapping no specification defines -- an XF pointing at one resolves to no code at all, which the caller reports as absent rather than silently substituting General. These strings are fed through the SAME classifyNumberFormat as a producer-declared code, never a second table of pre-decided kinds, so the two feeds cannot drift apart.
- */
-declare const BUILTIN_NUMBER_FORMATS: ReadonlyMap<number, string>;
-//#endregion
-export { BUILTIN_NUMBER_FORMATS, NumberFormatClass, classifyNumberFormat };