xls-codec 1.0.1 → 2.0.0

package/dist/biff/record-writer.js

@@ -0,0 +1,27 @@
+import { MAX_RECORD_DATA_SIZE } from "./record-types.js";
+import { BiffWriteError } from "./write-errors.js";
+//#region src/biff/record-writer.ts
+const HEADER_SIZE = 4;
+/** Wraps one record's data in its type/size header. Throws BiffWriteError if the data exceeds the single-record maximum, rather than splitting it across Continue records. */
+function writeRecord(type, data) {
+	if (data.length > 8224) throw new BiffWriteError(`record 0x${type.toString(16)} would carry ${data.length} bytes of data, above the ${MAX_RECORD_DATA_SIZE}-byte maximum a single record can hold ([MS-XLS] 2.1.4); this writer does not split oversized records into Continue chains`);
+	const out = new Uint8Array(HEADER_SIZE + data.length);
+	const view = new DataView(out.buffer);
+	view.setUint16(0, type, true);
+	view.setUint16(2, data.length, true);
+	out.set(data, HEADER_SIZE);
+	return out;
+}
+/** Concatenates already-framed records (or any byte sequences) into one stream, in the order given. */
+function concatRecords(...parts) {
+	const total = parts.reduce((sum, part) => sum + part.length, 0);
+	const out = new Uint8Array(total);
+	let offset = 0;
+	for (const part of parts) {
+		out.set(part, offset);
+		offset += part.length;
+	}
+	return out;
+}
+//#endregion
+export { concatRecords, writeRecord };

package/dist/biff/string-writer.cjs

@@ -0,0 +1,58 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_biff_write_errors = require("./write-errors.cjs");
+const require_biff_builder = require("./builder.cjs");
+//#region src/biff/string-writer.ts
+/** Bit 0 of a string's flags byte: set when each character occupies a full two-byte UTF-16 code unit ([MS-XLS] 2.5.293/2.5.294/2.5.240's own fHighByte). */
+const FLAG_HIGH_BYTE = 1;
+/** The largest character count a ShortXLUnicodeString's one-byte cch can name. */
+const MAX_SHORT_STRING_LENGTH = 255;
+/** The largest character count an XLUnicodeString/XLUnicodeRichExtendedString's two-byte cch can name. */
+const MAX_STRING_LENGTH = 65535;
+/** Whether every UTF-16 code unit in `text` fits in a single byte -- the compressed-encoding eligibility test, checked per code UNIT rather than per code point so an astral character (whose two surrogate units are each above 0xFF) is correctly ruled ineligible. */
+function encodeCharacters(text) {
+	let needsHighByte = false;
+	for (let index = 0; index < text.length; index += 1) if (text.charCodeAt(index) > 255) {
+		needsHighByte = true;
+		break;
+	}
+	const builder = new require_biff_builder.RecordBuilder();
+	for (let index = 0; index < text.length; index += 1) {
+		const unit = text.charCodeAt(index);
+		if (needsHighByte) builder.u16(unit);
+		else builder.u8(unit);
+	}
+	return {
+		highByte: needsHighByte,
+		units: builder.build()
+	};
+}
+function checkedLength(text, max, shape) {
+	if (text.length > max) throw new require_biff_write_errors.BiffWriteError(`${shape} cannot hold ${text.length} UTF-16 code units, above its own ${max}-unit limit (text: ${JSON.stringify(text.length > 40 ? `${text.slice(0, 40)}...` : text)})`);
+	return text.length;
+}
+/** An XLUnicodeString ([MS-XLS] 2.5.294): a two-byte character count, a flags byte, then the characters. */
+function writeXLUnicodeString(text) {
+	const cch = checkedLength(text, MAX_STRING_LENGTH, "XLUnicodeString");
+	const { highByte, units } = encodeCharacters(text);
+	return new require_biff_builder.RecordBuilder().u16(cch).u8(highByte ? FLAG_HIGH_BYTE : 0).bytes(units).build();
+}
+/** A ShortXLUnicodeString ([MS-XLS] 2.5.240): as above, with a one-byte character count. */
+function writeShortXLUnicodeString(text) {
+	const cch = checkedLength(text, MAX_SHORT_STRING_LENGTH, "ShortXLUnicodeString");
+	const { highByte, units } = encodeCharacters(text);
+	return new require_biff_builder.RecordBuilder().u8(cch).u8(highByte ? FLAG_HIGH_BYTE : 0).bytes(units).build();
+}
+/**
+* An XLUnicodeRichExtendedString ([MS-XLS] 2.5.293): the SST's own element shape.
+*
+* Always written with no formatting runs and no phonetic payload -- this package reads a shared string's text only (see biff/strings.ts's own readRichExtendedString), so there is never run or phonetic data to re-emit. The rich/extended flag bits are left clear accordingly.
+*/
+function writeRichExtendedString(text) {
+	const cch = checkedLength(text, MAX_STRING_LENGTH, "XLUnicodeRichExtendedString");
+	const { highByte, units } = encodeCharacters(text);
+	return new require_biff_builder.RecordBuilder().u16(cch).u8(highByte ? FLAG_HIGH_BYTE : 0).bytes(units).build();
+}
+//#endregion
+exports.writeRichExtendedString = writeRichExtendedString;
+exports.writeShortXLUnicodeString = writeShortXLUnicodeString;
+exports.writeXLUnicodeString = writeXLUnicodeString;

package/dist/biff/string-writer.d.cts

@@ -0,0 +1,13 @@
+//#region src/biff/string-writer.d.ts
+/** An XLUnicodeString ([MS-XLS] 2.5.294): a two-byte character count, a flags byte, then the characters. */
+declare function writeXLUnicodeString(text: string): Uint8Array<ArrayBuffer>;
+/** A ShortXLUnicodeString ([MS-XLS] 2.5.240): as above, with a one-byte character count. */
+declare function writeShortXLUnicodeString(text: string): Uint8Array<ArrayBuffer>;
+/**
+ * An XLUnicodeRichExtendedString ([MS-XLS] 2.5.293): the SST's own element shape.
+ *
+ * Always written with no formatting runs and no phonetic payload -- this package reads a shared string's text only (see biff/strings.ts's own readRichExtendedString), so there is never run or phonetic data to re-emit. The rich/extended flag bits are left clear accordingly.
+ */
+declare function writeRichExtendedString(text: string): Uint8Array<ArrayBuffer>;
+//#endregion
+export { writeRichExtendedString, writeShortXLUnicodeString, writeXLUnicodeString };

package/dist/biff/string-writer.d.ts

@@ -0,0 +1,13 @@
+//#region src/biff/string-writer.d.ts
+/** An XLUnicodeString ([MS-XLS] 2.5.294): a two-byte character count, a flags byte, then the characters. */
+declare function writeXLUnicodeString(text: string): Uint8Array<ArrayBuffer>;
+/** A ShortXLUnicodeString ([MS-XLS] 2.5.240): as above, with a one-byte character count. */
+declare function writeShortXLUnicodeString(text: string): Uint8Array<ArrayBuffer>;
+/**
+ * An XLUnicodeRichExtendedString ([MS-XLS] 2.5.293): the SST's own element shape.
+ *
+ * Always written with no formatting runs and no phonetic payload -- this package reads a shared string's text only (see biff/strings.ts's own readRichExtendedString), so there is never run or phonetic data to re-emit. The rich/extended flag bits are left clear accordingly.
+ */
+declare function writeRichExtendedString(text: string): Uint8Array<ArrayBuffer>;
+//#endregion
+export { writeRichExtendedString, writeShortXLUnicodeString, writeXLUnicodeString };

package/dist/biff/string-writer.js

@@ -0,0 +1,55 @@
+import { BiffWriteError } from "./write-errors.js";
+import { RecordBuilder } from "./builder.js";
+//#region src/biff/string-writer.ts
+/** Bit 0 of a string's flags byte: set when each character occupies a full two-byte UTF-16 code unit ([MS-XLS] 2.5.293/2.5.294/2.5.240's own fHighByte). */
+const FLAG_HIGH_BYTE = 1;
+/** The largest character count a ShortXLUnicodeString's one-byte cch can name. */
+const MAX_SHORT_STRING_LENGTH = 255;
+/** The largest character count an XLUnicodeString/XLUnicodeRichExtendedString's two-byte cch can name. */
+const MAX_STRING_LENGTH = 65535;
+/** Whether every UTF-16 code unit in `text` fits in a single byte -- the compressed-encoding eligibility test, checked per code UNIT rather than per code point so an astral character (whose two surrogate units are each above 0xFF) is correctly ruled ineligible. */
+function encodeCharacters(text) {
+	let needsHighByte = false;
+	for (let index = 0; index < text.length; index += 1) if (text.charCodeAt(index) > 255) {
+		needsHighByte = true;
+		break;
+	}
+	const builder = new RecordBuilder();
+	for (let index = 0; index < text.length; index += 1) {
+		const unit = text.charCodeAt(index);
+		if (needsHighByte) builder.u16(unit);
+		else builder.u8(unit);
+	}
+	return {
+		highByte: needsHighByte,
+		units: builder.build()
+	};
+}
+function checkedLength(text, max, shape) {
+	if (text.length > max) throw new BiffWriteError(`${shape} cannot hold ${text.length} UTF-16 code units, above its own ${max}-unit limit (text: ${JSON.stringify(text.length > 40 ? `${text.slice(0, 40)}...` : text)})`);
+	return text.length;
+}
+/** An XLUnicodeString ([MS-XLS] 2.5.294): a two-byte character count, a flags byte, then the characters. */
+function writeXLUnicodeString(text) {
+	const cch = checkedLength(text, MAX_STRING_LENGTH, "XLUnicodeString");
+	const { highByte, units } = encodeCharacters(text);
+	return new RecordBuilder().u16(cch).u8(highByte ? FLAG_HIGH_BYTE : 0).bytes(units).build();
+}
+/** A ShortXLUnicodeString ([MS-XLS] 2.5.240): as above, with a one-byte character count. */
+function writeShortXLUnicodeString(text) {
+	const cch = checkedLength(text, MAX_SHORT_STRING_LENGTH, "ShortXLUnicodeString");
+	const { highByte, units } = encodeCharacters(text);
+	return new RecordBuilder().u8(cch).u8(highByte ? FLAG_HIGH_BYTE : 0).bytes(units).build();
+}
+/**
+* An XLUnicodeRichExtendedString ([MS-XLS] 2.5.293): the SST's own element shape.
+*
+* Always written with no formatting runs and no phonetic payload -- this package reads a shared string's text only (see biff/strings.ts's own readRichExtendedString), so there is never run or phonetic data to re-emit. The rich/extended flag bits are left clear accordingly.
+*/
+function writeRichExtendedString(text) {
+	const cch = checkedLength(text, MAX_STRING_LENGTH, "XLUnicodeRichExtendedString");
+	const { highByte, units } = encodeCharacters(text);
+	return new RecordBuilder().u16(cch).u8(highByte ? FLAG_HIGH_BYTE : 0).bytes(units).build();
+}
+//#endregion
+export { writeRichExtendedString, writeShortXLUnicodeString, writeXLUnicodeString };

package/dist/biff/strings.d.cts

@@ -1,4 +1,4 @@
-import { BlockCursor } from "./cursor.cjs";
+import { t as BlockCursor } from "../cursor-VMtw9uVP.cjs";
 //#region src/biff/strings.d.ts
 /** An XLUnicodeString ([MS-XLS] 2.5.294): a two-byte character count, a flags byte, then the characters. Continuable, since the String record ([MS-XLS] 2.4.268) carrying a formula's string result is one of these and its own production admits trailing Continues. */
 declare function readXLUnicodeString(cursor: BlockCursor): string;

package/dist/biff/strings.d.ts

@@ -1,4 +1,4 @@
-import { BlockCursor } from "./cursor.js";
+import { t as BlockCursor } from "../cursor-VMtw9uVP.js";
 //#region src/biff/strings.d.ts
 /** An XLUnicodeString ([MS-XLS] 2.5.294): a two-byte character count, a flags byte, then the characters. Continuable, since the String record ([MS-XLS] 2.4.268) carrying a formula's string result is one of these and its own production admits trailing Continues. */
 declare function readXLUnicodeString(cursor: BlockCursor): string;

package/dist/biff/substreams.d.cts

@@ -1,21 +1,2 @@
-import { n as BiffRecord } from "../records-DVIqXFKk.cjs";
-//#region src/biff/substreams.d.ts
-/** One logical record: its type, its data blocks -- the base record's, then one per Continue that followed it -- and the base record's own offset in the stream. */
-interface RecordGroup {
-  readonly type: number;
-  readonly blocks: readonly Uint8Array<ArrayBuffer>[];
-  readonly offset: number;
-}
-/** One substream: the document type its BOF declared, the records between that BOF and its EOF, its ordinal position among the stream's substreams, and the stream offset of its own BOF -- which is what a BoundSheet8's lbPlyPos names. */
-interface Substream {
-  readonly documentType: number;
-  readonly records: readonly RecordGroup[];
-  readonly index: number;
-  readonly offset: number;
-}
-/** Joins each record to the Continue records following it, keeping the blocks separate. */
-declare function groupRecords(records: readonly BiffRecord[]): readonly RecordGroup[];
-/** Splits a grouped record sequence into its substreams, verifying each BOF declares BIFF8. */
-declare function splitSubstreams(groups: readonly RecordGroup[]): readonly Substream[];
-//#endregion
+import { i as splitSubstreams, n as Substream, r as groupRecords, t as RecordGroup } from "../substreams-Ddtvn_Vr.cjs";
 export { RecordGroup, Substream, groupRecords, splitSubstreams };

package/dist/biff/substreams.d.ts

@@ -1,21 +1,2 @@
-import { n as BiffRecord } from "../records-DVIqXFKk.js";
-//#region src/biff/substreams.d.ts
-/** One logical record: its type, its data blocks -- the base record's, then one per Continue that followed it -- and the base record's own offset in the stream. */
-interface RecordGroup {
-  readonly type: number;
-  readonly blocks: readonly Uint8Array<ArrayBuffer>[];
-  readonly offset: number;
-}
-/** One substream: the document type its BOF declared, the records between that BOF and its EOF, its ordinal position among the stream's substreams, and the stream offset of its own BOF -- which is what a BoundSheet8's lbPlyPos names. */
-interface Substream {
-  readonly documentType: number;
-  readonly records: readonly RecordGroup[];
-  readonly index: number;
-  readonly offset: number;
-}
-/** Joins each record to the Continue records following it, keeping the blocks separate. */
-declare function groupRecords(records: readonly BiffRecord[]): readonly RecordGroup[];
-/** Splits a grouped record sequence into its substreams, verifying each BOF declares BIFF8. */
-declare function splitSubstreams(groups: readonly RecordGroup[]): readonly Substream[];
-//#endregion
+import { i as splitSubstreams, n as Substream, r as groupRecords, t as RecordGroup } from "../substreams-D7dQiJbp.js";
 export { RecordGroup, Substream, groupRecords, splitSubstreams };

package/dist/biff/write-errors.cjs

@@ -0,0 +1,10 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/biff/write-errors.ts
+var BiffWriteError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "BiffWriteError";
+	}
+};
+//#endregion
+exports.BiffWriteError = BiffWriteError;

package/dist/biff/write-errors.d.cts

@@ -0,0 +1,6 @@
+//#region src/biff/write-errors.d.ts
+declare class BiffWriteError extends Error {
+  constructor(message: string);
+}
+//#endregion
+export { BiffWriteError };

package/dist/biff/write-errors.d.ts

@@ -0,0 +1,6 @@
+//#region src/biff/write-errors.d.ts
+declare class BiffWriteError extends Error {
+  constructor(message: string);
+}
+//#endregion
+export { BiffWriteError };

package/dist/biff/write-errors.js

@@ -0,0 +1,9 @@
+//#region src/biff/write-errors.ts
+var BiffWriteError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "BiffWriteError";
+	}
+};
+//#endregion
+export { BiffWriteError };

package/dist/biff/xf-colors.cjs

@@ -0,0 +1,374 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let document_schema_js = require("document-schema.js");
+//#region src/biff/xf-colors.ts
+/** FLSNULL: no fill pattern -- the cell's fill colour fields carry no meaning. */
+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. */
+const FILL_PATTERN_SOLID = 1;
+const ALC_GENERAL = 0;
+const ALC_LEFT = 1;
+const ALC_CENTER = 2;
+const ALC_RIGHT = 3;
+const ALC_JUSTIFY = 5;
+const ALCV_TOP = 0;
+const ALCV_CENTER = 1;
+const ALCV_BOTTOM = 2;
+/** 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. */
+function resolveHorizontalAlignment(alc) {
+	switch (alc) {
+		case ALC_LEFT: return "left";
+		case ALC_CENTER: return "center";
+		case ALC_RIGHT: return "right";
+		case ALC_JUSTIFY: return "justify";
+		default: return;
+	}
+}
+/** 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. */
+function horizAlignTokenFor(alignment) {
+	switch (alignment) {
+		case "left": return ALC_LEFT;
+		case "center": return ALC_CENTER;
+		case "right": return ALC_RIGHT;
+		case "justify": return ALC_JUSTIFY;
+		default: return ALC_GENERAL;
+	}
+}
+/** 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. */
+function resolveVerticalAlignment(alcV) {
+	switch (alcV) {
+		case ALCV_TOP: return "top";
+		case ALCV_CENTER: return "middle";
+		default: return;
+	}
+}
+/** 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. */
+function vertAlignTokenFor(verticalAlignment) {
+	switch (verticalAlignment) {
+		case "top": return ALCV_TOP;
+		case "middle": return ALCV_CENTER;
+		default: return ALCV_BOTTOM;
+	}
+}
+const BORDER_STYLE_NONE = 0;
+const BORDER_STYLE_THIN = 1;
+const BORDER_STYLE_MEDIUM = 2;
+const BORDER_STYLE_DASHED = 3;
+const BORDER_STYLE_DOTTED = 4;
+const BORDER_STYLE_THICK = 5;
+const BORDER_STYLE_DOUBLE = 6;
+const BORDER_STYLE_HAIR = 7;
+const BORDER_STYLE_MEDIUM_DASHED = 8;
+const BORDER_STYLE_DASHDOT = 9;
+const BORDER_STYLE_MEDIUM_DASHDOT = 10;
+const BORDER_STYLE_DASHDOTDOT = 11;
+const BORDER_STYLE_MEDIUM_DASHDOTDOT = 12;
+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. */
+const ICV_AUTOMATIC_FOREGROUND = 64;
+const ICV_AUTOMATIC_BACKGROUND = 65;
+const RGB_BYTE_MAX = 255;
+function rgb255(r, g, b) {
+	return {
+		r: r / RGB_BYTE_MAX,
+		g: g / RGB_BYTE_MAX,
+		b: b / RGB_BYTE_MAX
+	};
+}
+/** Icv values 0x00-0x07: the eight fixed built-in colour constants every BIFF8 reader recognises regardless of a Palette record. This package's own writer never emits one of these (IcvXF's own field documentation: "This value SHOULD NOT be ... less than or equal to 0x07" -- the default-palette table below duplicates all eight at icv 8-15, which is what this writer uses instead), but a real third-party file may still carry one, so the read side resolves them. */
+const FIXED_COLOR_TABLE = [
+	rgb255(0, 0, 0),
+	rgb255(255, 255, 255),
+	rgb255(255, 0, 0),
+	rgb255(0, 255, 0),
+	rgb255(0, 0, 255),
+	rgb255(255, 255, 0),
+	rgb255(255, 0, 255),
+	rgb255(0, 255, 255)
+];
+/** 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. */
+const PALETTE_BASE_ICV = 8;
+/** A Palette record's own fixed entry count ([MS-XLS] 2.4.188: "The value MUST be 56"). */
+const PALETTE_ENTRY_COUNT = 56;
+/** The 56-entry default colour table icv 8-63 resolve through when no Palette record is present ([MS-XLS] "Icv"'s own default-red/green/blue columns), in icv order (index 0 = icv 8). Entries 0-7 duplicate the eight fixed colours above at their own icv+8 position -- the reason this package's writer allocates a fixed colour there rather than at icv 0-7 directly. */
+const DEFAULT_PALETTE_TABLE = [
+	rgb255(0, 0, 0),
+	rgb255(255, 255, 255),
+	rgb255(255, 0, 0),
+	rgb255(0, 255, 0),
+	rgb255(0, 0, 255),
+	rgb255(255, 255, 0),
+	rgb255(255, 0, 255),
+	rgb255(0, 255, 255),
+	rgb255(128, 0, 0),
+	rgb255(0, 128, 0),
+	rgb255(0, 0, 128),
+	rgb255(128, 128, 0),
+	rgb255(128, 0, 128),
+	rgb255(0, 128, 128),
+	rgb255(192, 192, 192),
+	rgb255(128, 128, 128),
+	rgb255(153, 153, 255),
+	rgb255(153, 51, 102),
+	rgb255(255, 255, 204),
+	rgb255(204, 255, 255),
+	rgb255(102, 0, 102),
+	rgb255(255, 128, 128),
+	rgb255(0, 102, 204),
+	rgb255(204, 204, 255),
+	rgb255(0, 0, 128),
+	rgb255(255, 0, 255),
+	rgb255(255, 255, 0),
+	rgb255(0, 255, 255),
+	rgb255(128, 0, 128),
+	rgb255(128, 0, 0),
+	rgb255(0, 128, 128),
+	rgb255(0, 0, 255),
+	rgb255(0, 204, 255),
+	rgb255(204, 255, 255),
+	rgb255(204, 255, 204),
+	rgb255(255, 255, 153),
+	rgb255(153, 204, 255),
+	rgb255(255, 153, 204),
+	rgb255(204, 153, 255),
+	rgb255(255, 204, 153),
+	rgb255(51, 102, 255),
+	rgb255(51, 204, 204),
+	rgb255(153, 204, 0),
+	rgb255(255, 204, 0),
+	rgb255(255, 153, 0),
+	rgb255(255, 102, 0),
+	rgb255(102, 102, 153),
+	rgb255(150, 150, 150),
+	rgb255(0, 51, 102),
+	rgb255(51, 153, 102),
+	rgb255(0, 51, 0),
+	rgb255(51, 51, 0),
+	rgb255(153, 51, 0),
+	rgb255(153, 51, 102),
+	rgb255(51, 51, 153),
+	rgb255(51, 51, 51)
+];
+/** 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. */
+const DEFAULT_PALETTE_HEX_TO_ICV = new Map(DEFAULT_PALETTE_TABLE.map((color, index) => [(0, document_schema_js.colorToRgbHex)(color), 8 + index]));
+/**
+* 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.
+*/
+function resolveIcvColor(icv, palette) {
+	if (icv >= 0 && icv < FIXED_COLOR_TABLE.length) return FIXED_COLOR_TABLE[icv];
+	if (icv >= 8 && icv < 64) {
+		const index = icv - 8;
+		return palette === void 0 ? DEFAULT_PALETTE_TABLE[index] : palette[index];
+	}
+}
+/** Every BorderStyle token this reader resolves to a (weight, pattern) pair -- BORDER_STYLE_NONE has no entry, since "no border" is handled by the caller before consulting this table. The dash-family tokens (dashDot/dashDotDot and their medium/slant variants) collapse to 'dashed', the closest ContentStrokeStyle member, exactly as ooxml.js's own XLSX_BORDER_STYLE table does for the equivalent xlsx tokens. */
+const BIFF_BORDER_STYLE = {
+	[1]: {
+		weight: "thin",
+		pattern: "solid"
+	},
+	[2]: {
+		weight: "medium",
+		pattern: "solid"
+	},
+	[3]: {
+		weight: "thin",
+		pattern: "dashed"
+	},
+	[4]: {
+		weight: "thin",
+		pattern: "dotted"
+	},
+	[5]: {
+		weight: "thick",
+		pattern: "solid"
+	},
+	[6]: {
+		weight: "thin",
+		pattern: "double"
+	},
+	[7]: {
+		weight: "hair",
+		pattern: "solid"
+	},
+	[8]: {
+		weight: "medium",
+		pattern: "dashed"
+	},
+	[9]: {
+		weight: "thin",
+		pattern: "dashed"
+	},
+	[10]: {
+		weight: "medium",
+		pattern: "dashed"
+	},
+	[11]: {
+		weight: "thin",
+		pattern: "dashed"
+	},
+	[12]: {
+		weight: "medium",
+		pattern: "dashed"
+	},
+	[13]: {
+		weight: "medium",
+		pattern: "dashed"
+	}
+};
+/** 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). */
+function resolveBorderEdge(edge, palette) {
+	if (edge.style === 0) return;
+	const resolved = BIFF_BORDER_STYLE[edge.style];
+	if (resolved === void 0) return;
+	const color = resolveIcvColor(edge.icv, palette);
+	if (color === void 0) return;
+	const result = {
+		color,
+		widthPt: document_schema_js.BORDER_WIDTH_PT[resolved.weight]
+	};
+	if (resolved.pattern !== "solid") result.style = resolved.pattern;
+	return result;
+}
+/** The BorderStyle token each named weight's own plain solid stroke is spelled with. */
+const SOLID_BORDER_STYLE = {
+	hair: 7,
+	thin: 1,
+	medium: 2,
+	thick: 5
+};
+/** 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. */
+function borderStyleTokenFor(border) {
+	switch (border.style) {
+		case "double": return 6;
+		case "dotted": return 4;
+		case "dashed": return (0, document_schema_js.dashedBorderWeightForWidthPt)(border.widthPt) === "medium" ? 8 : 3;
+		case "solid":
+		case void 0: return SOLID_BORDER_STYLE[(0, document_schema_js.borderWeightForWidthPt)(border.widthPt)];
+	}
+}
+/** 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. */
+function resolveFillBackground(fillPattern, foregroundIcv, palette) {
+	if (fillPattern !== 1) return;
+	return resolveIcvColor(foregroundIcv, palette);
+}
+const UNDECORATED_EDGE = {
+	style: 0,
+	icv: 0
+};
+/** 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. */
+const UNDECORATED_XF_FIELDS = {
+	fillPattern: 0,
+	fillForegroundIcv: 64,
+	left: UNDECORATED_EDGE,
+	right: UNDECORATED_EDGE,
+	top: UNDECORATED_EDGE,
+	bottom: UNDECORATED_EDGE
+};
+/** 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. */
+function unpackXfAlignment(word1) {
+	const alc = word1 & 7;
+	const alcV = word1 >>> 4 & 7;
+	return {
+		horizontal: resolveHorizontalAlignment(alc),
+		vertical: resolveVerticalAlignment(alcV)
+	};
+}
+/** 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/...). */
+function unpackXfDecoration(word2, word3, word4) {
+	const dgLeft = word2 & 15;
+	const dgRight = word2 >>> 4 & 15;
+	const dgTop = word2 >>> 8 & 15;
+	const dgBottom = word2 >>> 12 & 15;
+	const icvLeft = word2 >>> 16 & 127;
+	const icvRight = word2 >>> 23 & 127;
+	const icvTop = word3 & 127;
+	const icvBottom = word3 >>> 7 & 127;
+	return {
+		fillPattern: word3 >>> 26 & 63,
+		fillForegroundIcv: word4 & 127,
+		left: {
+			style: dgLeft,
+			icv: icvLeft
+		},
+		right: {
+			style: dgRight,
+			icv: icvRight
+		},
+		top: {
+			style: dgTop,
+			icv: icvTop
+		},
+		bottom: {
+			style: dgBottom,
+			icv: icvBottom
+		}
+	};
+}
+/**
+* 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
+*/
+function packXfDecorationWords(decoration = UNDECORATED_XF_FIELDS) {
+	const { left, right, top, bottom } = decoration;
+	return {
+		word2: left.style & 15 | (right.style & 15) << 4 | (top.style & 15) << 8 | (bottom.style & 15) << 12 | (left.icv & 127) << 16 | (right.icv & 127) << 23 | 0,
+		word3: top.icv & 127 | (bottom.icv & 127) << 7 | 0 | (decoration.fillPattern & 63) << 26,
+		word4: (decoration.fillPattern === 1 ? decoration.fillForegroundIcv : 64) & 127 | 8320
+	};
+}
+/** 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. */
+function readLongRgbColor(cursor) {
+	const r = cursor.u8();
+	const g = cursor.u8();
+	const b = cursor.u8();
+	cursor.u8();
+	return rgb255(r, g, b);
+}
+/** 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. */
+function longRgbBytesOf(color) {
+	return [
+		Math.round(color.r * RGB_BYTE_MAX),
+		Math.round(color.g * RGB_BYTE_MAX),
+		Math.round(color.b * RGB_BYTE_MAX),
+		0
+	];
+}
+//#endregion
+exports.BORDER_STYLE_DASHDOT = BORDER_STYLE_DASHDOT;
+exports.BORDER_STYLE_DASHDOTDOT = BORDER_STYLE_DASHDOTDOT;
+exports.BORDER_STYLE_DASHED = BORDER_STYLE_DASHED;
+exports.BORDER_STYLE_DOTTED = BORDER_STYLE_DOTTED;
+exports.BORDER_STYLE_DOUBLE = BORDER_STYLE_DOUBLE;
+exports.BORDER_STYLE_HAIR = BORDER_STYLE_HAIR;
+exports.BORDER_STYLE_MEDIUM = BORDER_STYLE_MEDIUM;
+exports.BORDER_STYLE_MEDIUM_DASHDOT = BORDER_STYLE_MEDIUM_DASHDOT;
+exports.BORDER_STYLE_MEDIUM_DASHDOTDOT = BORDER_STYLE_MEDIUM_DASHDOTDOT;
+exports.BORDER_STYLE_MEDIUM_DASHED = BORDER_STYLE_MEDIUM_DASHED;
+exports.BORDER_STYLE_NONE = BORDER_STYLE_NONE;
+exports.BORDER_STYLE_SLANT_DASHDOT = BORDER_STYLE_SLANT_DASHDOT;
+exports.BORDER_STYLE_THICK = BORDER_STYLE_THICK;
+exports.BORDER_STYLE_THIN = BORDER_STYLE_THIN;
+exports.DEFAULT_PALETTE_HEX_TO_ICV = DEFAULT_PALETTE_HEX_TO_ICV;
+exports.FILL_PATTERN_NONE = FILL_PATTERN_NONE;
+exports.FILL_PATTERN_SOLID = FILL_PATTERN_SOLID;
+exports.ICV_AUTOMATIC_BACKGROUND = ICV_AUTOMATIC_BACKGROUND;
+exports.ICV_AUTOMATIC_FOREGROUND = ICV_AUTOMATIC_FOREGROUND;
+exports.PALETTE_BASE_ICV = PALETTE_BASE_ICV;
+exports.PALETTE_ENTRY_COUNT = PALETTE_ENTRY_COUNT;
+exports.UNDECORATED_XF_FIELDS = UNDECORATED_XF_FIELDS;
+exports.borderStyleTokenFor = borderStyleTokenFor;
+exports.horizAlignTokenFor = horizAlignTokenFor;
+exports.longRgbBytesOf = longRgbBytesOf;
+exports.packXfDecorationWords = packXfDecorationWords;
+exports.readLongRgbColor = readLongRgbColor;
+exports.resolveBorderEdge = resolveBorderEdge;
+exports.resolveFillBackground = resolveFillBackground;
+exports.resolveHorizontalAlignment = resolveHorizontalAlignment;
+exports.resolveIcvColor = resolveIcvColor;
+exports.resolveVerticalAlignment = resolveVerticalAlignment;
+exports.unpackXfAlignment = unpackXfAlignment;
+exports.unpackXfDecoration = unpackXfDecoration;
+exports.vertAlignTokenFor = vertAlignTokenFor;

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

@@ -0,0 +1,2 @@
+import { A as readLongRgbColor, C as XfAlignmentFields, D as horizAlignTokenFor, E as borderStyleTokenFor, F as resolveVerticalAlignment, I as unpackXfAlignment, L as unpackXfDecoration, M as resolveFillBackground, N as resolveHorizontalAlignment, O as longRgbBytesOf, P as resolveIcvColor, R as vertAlignTokenFor, S as UNDECORATED_XF_FIELDS, T as XfDecorationFields, _ as FILL_PATTERN_SOLID, a as BORDER_STYLE_DOUBLE, b as PALETTE_BASE_ICV, c as BORDER_STYLE_MEDIUM_DASHDOT, d as BORDER_STYLE_NONE, f as BORDER_STYLE_SLANT_DASHDOT, g as FILL_PATTERN_NONE, h as DEFAULT_PALETTE_HEX_TO_ICV, i as BORDER_STYLE_DOTTED, j as resolveBorderEdge, k as packXfDecorationWords, l as BORDER_STYLE_MEDIUM_DASHDOTDOT, m as BORDER_STYLE_THIN, n as BORDER_STYLE_DASHDOTDOT, o as BORDER_STYLE_HAIR, p as BORDER_STYLE_THICK, r as BORDER_STYLE_DASHED, s as BORDER_STYLE_MEDIUM, t as BORDER_STYLE_DASHDOT, u as BORDER_STYLE_MEDIUM_DASHED, v as ICV_AUTOMATIC_BACKGROUND, w as XfBorderEdge, x as PALETTE_ENTRY_COUNT, y as ICV_AUTOMATIC_FOREGROUND } from "../xf-colors-CehHZtBy.cjs";
+export { BORDER_STYLE_DASHDOT, BORDER_STYLE_DASHDOTDOT, BORDER_STYLE_DASHED, BORDER_STYLE_DOTTED, BORDER_STYLE_DOUBLE, BORDER_STYLE_HAIR, BORDER_STYLE_MEDIUM, BORDER_STYLE_MEDIUM_DASHDOT, BORDER_STYLE_MEDIUM_DASHDOTDOT, BORDER_STYLE_MEDIUM_DASHED, BORDER_STYLE_NONE, BORDER_STYLE_SLANT_DASHDOT, BORDER_STYLE_THICK, BORDER_STYLE_THIN, DEFAULT_PALETTE_HEX_TO_ICV, FILL_PATTERN_NONE, FILL_PATTERN_SOLID, ICV_AUTOMATIC_BACKGROUND, ICV_AUTOMATIC_FOREGROUND, PALETTE_BASE_ICV, PALETTE_ENTRY_COUNT, UNDECORATED_XF_FIELDS, XfAlignmentFields, XfBorderEdge, XfDecorationFields, borderStyleTokenFor, horizAlignTokenFor, longRgbBytesOf, packXfDecorationWords, readLongRgbColor, resolveBorderEdge, resolveFillBackground, resolveHorizontalAlignment, resolveIcvColor, resolveVerticalAlignment, unpackXfAlignment, unpackXfDecoration, vertAlignTokenFor };