doc-codec 1.0.2 → 1.1.1

package/dist/table/decoration.cjs

@@ -0,0 +1,220 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_errors = require("../errors.cjs");
+const require_bytes = require("../bytes.cjs");
+const require_color = require("../color.cjs");
+//#region src/table/decoration.ts
+/** The four sides of a cell, in the order TC80 declares them ([MS-DOC] 2.9.313: brcTop, brcLeft, brcBottom, brcRight). Used as the iteration order for both directions, so a side can never be read from one offset and written to another. */
+const CELL_BORDER_SIDES = [
+	"top",
+	"left",
+	"bottom",
+	"right"
+];
+/** TableBrcOperand.bordersToApply, [MS-DOC] 2.9.305: which edges one operand formats, as the bitwise OR of any subset. Only the four rectangular sides are listed -- 0x10/0x20 are the two diagonals, which ContentCellBorders has no member for and this package neither reads nor writes. */
+const BORDERS_TO_APPLY = {
+	top: 1,
+	left: 2,
+	bottom: 4,
+	right: 8
+};
+/** Brc80's own fixed size, [MS-DOC] 2.9.17: dptLineWidth (1) + brcType (1) + ico (1) + dptSpace/fShadow/fFrame/reserved (1). */
+const BRC80_SIZE = 4;
+/** Brc's own fixed size, [MS-DOC] 2.9.16: cv (4) + dptLineWidth (1) + brcType (1) + dptSpace/fShadow/fFrame/fReserved (2). */
+const BRC_SIZE = 8;
+/** Shd's own fixed size, [MS-DOC] 2.9.247: cvFore (4) + cvBack (4) + ipat (2). */
+const SHD_SIZE = 10;
+/** Shd80's own fixed size, [MS-DOC] 2.9.248: one 16-bit word packing icoFore (5 bits), icoBack (5 bits) and ipat (6 bits). */
+const SHD80_SIZE = 2;
+/** BrcType 0x00, [MS-DOC] 2.9.22: "No border." Distinct from the Brc80MayBeNil/BrcMayBeNil all-bits-set sentinel, and the spelling a real producer (LibreOffice) uses for an undecorated cell -- both mean the same thing and both are read as no border. */
+const BRC_TYPE_NONE = 0;
+const BRC_TYPE_SINGLE = 1;
+const BRC_TYPE_DOUBLE = 3;
+const BRC_TYPE_DOTTED = 6;
+const BRC_TYPE_DASHED = 7;
+/**
+* Every BrcType [MS-DOC] 2.9.22 defines for a cell border (0x00 through 0x1B), mapped onto the four members ContentStrokeStyle has. Values 0x02 and 0x04 are absent from the published enumeration entirely and so have no entry here; 0x00 is handled by the caller before this table is consulted.
+*
+* Three families collapse, each stated rather than silently folded -- the same deliberate narrowing xls-codec's own BIFF_BORDER_STYLE makes for BIFF8's dash tokens. The dash family (dotDash 0x08, dotDotDash 0x09, dashSmallGap 0x16, dashDotStroked 0x17) collapses to 'dashed', since ContentStrokeStyle names one dashed pattern rather than a vocabulary of them. Every genuinely multi-line border collapses to 'double': the triple line (0x0A), the nine thinThick/thickThin gap variants (0x0B-0x13), the double wave (0x15), the two three-dimensional borders (0x18/0x19), and outset/inset (0x1A/0x1B, which Brc80 forbids but Brc permits). And the single wavy line (0x14) collapses to 'solid', being one continuous stroke.
+*
+* Values from 0x40 to 0xE3 are the art/image page borders, which [MS-DOC] 2.9.22 permits only "if they describe a page border" -- never a cell border -- so they have no entry and read as no border at all rather than as an invented approximation of a picture. 0xFF ("This MUST be ignored") is likewise absent.
+*/
+const BRC_TYPE_STYLE = {
+	[BRC_TYPE_SINGLE]: "solid",
+	[BRC_TYPE_DOUBLE]: "double",
+	5: "solid",
+	[BRC_TYPE_DOTTED]: "dotted",
+	[BRC_TYPE_DASHED]: "dashed",
+	8: "dashed",
+	9: "dashed",
+	10: "double",
+	11: "double",
+	12: "double",
+	13: "double",
+	14: "double",
+	15: "double",
+	16: "double",
+	17: "double",
+	18: "double",
+	19: "double",
+	20: "solid",
+	21: "double",
+	22: "dashed",
+	23: "dashed",
+	24: "double",
+	25: "double",
+	26: "double",
+	27: "double"
+};
+/** The inverse of BRC_TYPE_STYLE: the one BrcType each ContentStrokeStyle member is written as. Every collapsed family above writes back as its own family's plainest member, since that is the only one the collapsed value can honestly claim to be. */
+const STYLE_BRC_TYPE = {
+	solid: BRC_TYPE_SINGLE,
+	dashed: BRC_TYPE_DASHED,
+	dotted: BRC_TYPE_DOTTED,
+	double: BRC_TYPE_DOUBLE
+};
+/** dptLineWidth's own unit, [MS-DOC] 2.9.16/2.9.17: "the width of the border in 1/8-point increments" for every brcType below 0x40, which is every type a cell border can carry. */
+const EIGHTHS_PER_POINT = 8;
+/** "Values of less than 2 are considered to be equivalent to 2" -- the specification's own floor, applied on read so a border stating 0 or 1 resolves to the width it actually renders at rather than to a widthPt ContentBorderSchema would reject for not being positive. */
+const MIN_DPT_LINE_WIDTH = 2;
+/** dptLineWidth is a single byte, so 255 eighths (31.875pt) is the widest border the format can state at all. */
+const MAX_DPT_LINE_WIDTH = 255;
+/** The colour a border with no colour of its own resolves to. [MS-DOC]'s automatic colour (Ico 0x00, or a COLORREF with fAuto set) "designates the default color for the application" and names no components, but ContentBorder.color is required, so a border stating one has to resolve to something. Black is what an automatic border renders as against a default background, and resolving to it keeps the border itself -- which genuinely exists and genuinely renders -- rather than dropping the border outright to avoid stating a colour for it. */
+const AUTOMATIC_BORDER_COLOR = {
+	r: 0,
+	g: 0,
+	b: 0
+};
+function borderFrom(dptLineWidth, brcType, color) {
+	const style = BRC_TYPE_STYLE[brcType];
+	if (style === void 0) return void 0;
+	const border = {
+		color: color ?? AUTOMATIC_BORDER_COLOR,
+		widthPt: Math.max(dptLineWidth, MIN_DPT_LINE_WIDTH) / EIGHTHS_PER_POINT
+	};
+	if (style !== "solid") border.style = style;
+	return border;
+}
+/** Whether all `length` bytes from `offset` are 0xFF -- the all-bits-set form both nil-border spellings are defined in terms of. */
+function allBitsSet(bytes, offset, length) {
+	for (let index = 0; index < length; index += 1) if (require_bytes.readUint8(bytes, offset + index) !== 255) return false;
+	return true;
+}
+/** One TC80 border field: a Brc80MayBeNil ([MS-DOC] 2.9.18) -- a Brc80 whose all-bits-set value "specifies that the region in question has no border". Returns undefined for that sentinel, for brcType 0x00 ("No border", the spelling LibreOffice writes instead), and for any brcType outside the cell-border range BRC_TYPE_STYLE covers. An ico outside the palette's own bound resolves through decorativeIcoColor to the automatic-colour fallback (borderFrom's own AUTOMATIC_BORDER_COLOR) rather than aborting the whole document read over one cosmetic byte -- see decorativeIcoColor's own note in color.ts. */
+function readBrc80(bytes, offset) {
+	if (allBitsSet(bytes, offset, 4)) return void 0;
+	const brcType = require_bytes.readUint8(bytes, offset + 1);
+	if (brcType === BRC_TYPE_NONE) return void 0;
+	return borderFrom(require_bytes.readUint8(bytes, offset), brcType, require_color.decorativeIcoColor(require_bytes.readUint8(bytes, offset + 2)));
+}
+/** The eight bytes of one TableBrcOperand.brc field: a BrcMayBeNil ([MS-DOC] 2.9.20) -- "If the last four bytes are 0xFFFFFFFF, the BrcMayBeNil is a NilBrc that specifies that the table cells in question have no border", otherwise a Brc ([MS-DOC] 2.9.16) whose own cv states the colour exactly. */
+function readBrc(bytes, offset) {
+	if (allBitsSet(bytes, offset + 4, 4)) return void 0;
+	const brcType = require_bytes.readUint8(bytes, offset + 5);
+	if (brcType === BRC_TYPE_NONE) return void 0;
+	return borderFrom(require_bytes.readUint8(bytes, offset + 4), brcType, require_color.readColorRef(bytes, offset));
+}
+/** Brc80MayBeNil's own no-border value, [MS-DOC] 2.9.18: "When all bits are set (0xFFFFFFFF when interpreted as a 4-byte unsigned integer), this structure specifies that the region in question has no border." */
+const NIL_BRC80 = [
+	255,
+	255,
+	255,
+	255
+];
+/** dptLineWidth for a border of `widthPt`, in the 1/8-point increments [MS-DOC] states it in. Refuses a width the single-byte field cannot hold rather than silently clamping it to a thinner border than the caller asked for, matching how every other out-of-range operand in this writer is handled. */
+function dptLineWidthFor(widthPt) {
+	const eighths = Math.round(widthPt * EIGHTHS_PER_POINT);
+	if (eighths < MIN_DPT_LINE_WIDTH || eighths > MAX_DPT_LINE_WIDTH) throw new require_errors.DocFormatError(`a table cell border is ${widthPt}pt, outside the ${MIN_DPT_LINE_WIDTH / EIGHTHS_PER_POINT}..${MAX_DPT_LINE_WIDTH / EIGHTHS_PER_POINT}pt range [MS-DOC]'s own single-byte dptLineWidth can state in 1/8-point increments`);
+	return eighths;
+}
+/** One TC80 border field's own four bytes: the Brc80MayBeNil no-border sentinel for an absent border, otherwise a real Brc80 whose colour is the nearest Ico the fixed palette offers (see color.ts's nearestIco, and borderNeedsExactColor for how the exact colour still reaches the file). dptSpace, fShadow and fFrame are always zero -- ContentBorder models none of the three, so writing anything else would be inventing a fact the input never stated. */
+function writeBrc80(border) {
+	if (border === void 0) return [...NIL_BRC80];
+	return [
+		dptLineWidthFor(border.widthPt),
+		STYLE_BRC_TYPE[border.style ?? "solid"],
+		require_color.nearestIco(border.color),
+		0
+	];
+}
+/** One TableBrcOperand.brc field's own eight bytes: a real Brc carrying the border's colour exactly, as a COLORREF rather than a palette index. Only ever called for a border that exists, since a TableBrcOperand naming no sides is never emitted at all. */
+function writeBrc(border) {
+	return [
+		...require_color.colorRefBytes(border.color),
+		dptLineWidthFor(border.widthPt),
+		STYLE_BRC_TYPE[border.style ?? "solid"],
+		0,
+		0
+	];
+}
+/** Whether this border's colour survives the Ico palette Brc80 is limited to. When it does, TC80's own Brc80 already states the border exactly and the sprmTSetBrc precision layer would be pure duplication; when it does not, that layer is the only place the real colour can be stated. Compared on the written byte values rather than the floating-point components, so a colour that round-trips through colorRefBytes to the identical palette entry counts as exact. */
+function borderNeedsExactColor(border) {
+	const palette = require_color.icoColor(require_color.nearestIco(border.color));
+	if (palette === void 0) return true;
+	const wanted = require_color.colorRefBytes(border.color);
+	const approximated = require_color.colorRefBytes(palette);
+	return wanted[0] !== approximated[0] || wanted[1] !== approximated[1] || wanted[2] !== approximated[2];
+}
+/** ipatAuto, [MS-DOC] 2.9.121: "Clear, ST_Shd: clear" -- the pattern under which a cell simply shows its own cvBack, which is how both Word and LibreOffice spell a flat background colour, and the only pattern this package writes. */
+const IPAT_AUTO = 0;
+/** ipatSolid, [MS-DOC] 2.9.121: "Solid ST_Shd: solid" -- the cell is filled entirely with cvFore. */
+const IPAT_SOLID = 1;
+/**
+* One Shd ([MS-DOC] 2.9.247) as a flat background colour, or undefined where it states none.
+*
+* Only the two patterns that genuinely produce a flat fill resolve: ipatAuto, under which the cell shows cvBack (ECMA-376's own `clear` shading with a fill colour, which is what a real producer writes for a plain cell background), and ipatSolid, under which it shows cvFore. Every other Ipat -- the fourteen percentage fills, the stripe and crosshatch families, and ipatNil -- is a genuine pattern that Color cannot express, and reads as no background rather than as one of its two colours: reporting a 50% grey crosshatch as its own foreground colour would misstate what the cell actually shows. This is the same deliberate judgment xls-codec makes for BIFF8's own FillPattern enumeration, for the same reason, and it costs nothing on a round trip because this package's own writer emits ipatAuto and nothing else.
+*
+* A cvAuto colour under either pattern is likewise no background: it designates the application's own default, which for a cell background is "not shaded" rather than a colour to state. ShdAuto and ShdNil -- the two special values [MS-DOC] 2.9.247 names for "no shading is applied" -- both fall out of exactly that, with no separate check: each is a pair of cvAuto colours under ipatAuto.
+*/
+function readShd(bytes, offset) {
+	const ipat = require_bytes.readUint16LE(bytes, offset + 8);
+	if (ipat === IPAT_AUTO) return require_color.readColorRef(bytes, offset + 4);
+	if (ipat === IPAT_SOLID) return require_color.readColorRef(bytes, offset);
+}
+/** One Shd's own ten bytes: cvFore left automatic and the background stated as cvBack under ipatAuto, which is exactly how LibreOffice 26.2.5.2 writes a cell fill (confirmed against its own `.doc` output: a #ffff00 cell came back as cvFore cvAuto, cvBack `ff ff 00 00`, ipat 0x0000). An absent background writes ShdAuto -- the all-automatic value [MS-DOC] 2.9.247 defines as "no shading is applied" -- so an undecorated cell inside a row that has decorated ones still states its own lack of shading rather than inheriting a neighbour's. */
+function writeShd(background) {
+	return [
+		...require_color.autoColorRefBytes(),
+		...background === void 0 ? require_color.autoColorRefBytes() : require_color.colorRefBytes(background),
+		0,
+		0
+	];
+}
+/** Shd80Nil, [MS-DOC] 2.9.248: icoFore 0x1F, icoBack 0x1F, ipat 0x3F -- every bit set, "specifies that no shading is applied", and explicitly exempt from the Ico and Ipat bounds the fields otherwise carry. */
+const SHD80_NIL = 65535;
+/** One Shd80 ([MS-DOC] 2.9.248) as a flat background colour: the same ipatAuto/ipatSolid reading readShd applies, over the Ico palette rather than COLORREFs. This is the Word 97-era spelling of cell shading, superseded by Shd but still written -- alongside it -- by a real producer, so a file carrying only this one still reads. Never written by this package, which states shading through Shd alone. icoFore/icoBack are each a 5-bit field, so a value the 17-entry palette cannot hold is a real possibility rather than a format-level impossibility; decorativeIcoColor resolves that case to no background instead of aborting the whole document read. */
+function readShd80(value) {
+	if (value === SHD80_NIL) return void 0;
+	const icoFore = value & 31;
+	const icoBack = value >> 5 & 31;
+	const ipat = value >> 10 & 63;
+	if (ipat === IPAT_AUTO) return require_color.decorativeIcoColor(icoBack);
+	if (ipat === IPAT_SOLID) return require_color.decorativeIcoColor(icoFore);
+}
+/** A cell's four sides as a ContentCellBorders, or undefined when it has none -- the shape ContentTableCell.borders carries, with an absent side meaning that side has no border rather than an explicitly-null one. */
+function cellBordersFrom(sides) {
+	const borders = {};
+	let any = false;
+	for (const side of CELL_BORDER_SIDES) {
+		const border = sides[side];
+		if (border === void 0) continue;
+		borders[side] = border;
+		any = true;
+	}
+	return any ? borders : void 0;
+}
+//#endregion
+exports.BORDERS_TO_APPLY = BORDERS_TO_APPLY;
+exports.BRC80_SIZE = BRC80_SIZE;
+exports.BRC_SIZE = BRC_SIZE;
+exports.CELL_BORDER_SIDES = CELL_BORDER_SIDES;
+exports.SHD80_SIZE = SHD80_SIZE;
+exports.SHD_SIZE = SHD_SIZE;
+exports.borderNeedsExactColor = borderNeedsExactColor;
+exports.cellBordersFrom = cellBordersFrom;
+exports.readBrc = readBrc;
+exports.readBrc80 = readBrc80;
+exports.readShd = readShd;
+exports.readShd80 = readShd80;
+exports.writeBrc = writeBrc;
+exports.writeBrc80 = writeBrc80;
+exports.writeShd = writeShd;

package/dist/table/decoration.d.cts

@@ -0,0 +1,41 @@
+import { Color, ContentBorder, ContentCellBorders } from "document-schema.js";
+//#region src/table/decoration.d.ts
+/** The four sides of a cell, in the order TC80 declares them ([MS-DOC] 2.9.313: brcTop, brcLeft, brcBottom, brcRight). Used as the iteration order for both directions, so a side can never be read from one offset and written to another. */
+declare const CELL_BORDER_SIDES: readonly ["top", "left", "bottom", "right"];
+type CellBorderSide = (typeof CELL_BORDER_SIDES)[number];
+/** TableBrcOperand.bordersToApply, [MS-DOC] 2.9.305: which edges one operand formats, as the bitwise OR of any subset. Only the four rectangular sides are listed -- 0x10/0x20 are the two diagonals, which ContentCellBorders has no member for and this package neither reads nor writes. */
+declare const BORDERS_TO_APPLY: Readonly<Record<CellBorderSide, number>>;
+/** Brc80's own fixed size, [MS-DOC] 2.9.17: dptLineWidth (1) + brcType (1) + ico (1) + dptSpace/fShadow/fFrame/reserved (1). */
+declare const BRC80_SIZE = 4;
+/** Brc's own fixed size, [MS-DOC] 2.9.16: cv (4) + dptLineWidth (1) + brcType (1) + dptSpace/fShadow/fFrame/fReserved (2). */
+declare const BRC_SIZE = 8;
+/** Shd's own fixed size, [MS-DOC] 2.9.247: cvFore (4) + cvBack (4) + ipat (2). */
+declare const SHD_SIZE = 10;
+/** Shd80's own fixed size, [MS-DOC] 2.9.248: one 16-bit word packing icoFore (5 bits), icoBack (5 bits) and ipat (6 bits). */
+declare const SHD80_SIZE = 2;
+/** One TC80 border field: a Brc80MayBeNil ([MS-DOC] 2.9.18) -- a Brc80 whose all-bits-set value "specifies that the region in question has no border". Returns undefined for that sentinel, for brcType 0x00 ("No border", the spelling LibreOffice writes instead), and for any brcType outside the cell-border range BRC_TYPE_STYLE covers. An ico outside the palette's own bound resolves through decorativeIcoColor to the automatic-colour fallback (borderFrom's own AUTOMATIC_BORDER_COLOR) rather than aborting the whole document read over one cosmetic byte -- see decorativeIcoColor's own note in color.ts. */
+declare function readBrc80(bytes: Uint8Array, offset: number): ContentBorder | undefined;
+/** The eight bytes of one TableBrcOperand.brc field: a BrcMayBeNil ([MS-DOC] 2.9.20) -- "If the last four bytes are 0xFFFFFFFF, the BrcMayBeNil is a NilBrc that specifies that the table cells in question have no border", otherwise a Brc ([MS-DOC] 2.9.16) whose own cv states the colour exactly. */
+declare function readBrc(bytes: Uint8Array, offset: number): ContentBorder | undefined;
+/** One TC80 border field's own four bytes: the Brc80MayBeNil no-border sentinel for an absent border, otherwise a real Brc80 whose colour is the nearest Ico the fixed palette offers (see color.ts's nearestIco, and borderNeedsExactColor for how the exact colour still reaches the file). dptSpace, fShadow and fFrame are always zero -- ContentBorder models none of the three, so writing anything else would be inventing a fact the input never stated. */
+declare function writeBrc80(border: ContentBorder | undefined): number[];
+/** One TableBrcOperand.brc field's own eight bytes: a real Brc carrying the border's colour exactly, as a COLORREF rather than a palette index. Only ever called for a border that exists, since a TableBrcOperand naming no sides is never emitted at all. */
+declare function writeBrc(border: ContentBorder): number[];
+/** Whether this border's colour survives the Ico palette Brc80 is limited to. When it does, TC80's own Brc80 already states the border exactly and the sprmTSetBrc precision layer would be pure duplication; when it does not, that layer is the only place the real colour can be stated. Compared on the written byte values rather than the floating-point components, so a colour that round-trips through colorRefBytes to the identical palette entry counts as exact. */
+declare function borderNeedsExactColor(border: ContentBorder): boolean;
+/**
+ * One Shd ([MS-DOC] 2.9.247) as a flat background colour, or undefined where it states none.
+ *
+ * Only the two patterns that genuinely produce a flat fill resolve: ipatAuto, under which the cell shows cvBack (ECMA-376's own `clear` shading with a fill colour, which is what a real producer writes for a plain cell background), and ipatSolid, under which it shows cvFore. Every other Ipat -- the fourteen percentage fills, the stripe and crosshatch families, and ipatNil -- is a genuine pattern that Color cannot express, and reads as no background rather than as one of its two colours: reporting a 50% grey crosshatch as its own foreground colour would misstate what the cell actually shows. This is the same deliberate judgment xls-codec makes for BIFF8's own FillPattern enumeration, for the same reason, and it costs nothing on a round trip because this package's own writer emits ipatAuto and nothing else.
+ *
+ * A cvAuto colour under either pattern is likewise no background: it designates the application's own default, which for a cell background is "not shaded" rather than a colour to state. ShdAuto and ShdNil -- the two special values [MS-DOC] 2.9.247 names for "no shading is applied" -- both fall out of exactly that, with no separate check: each is a pair of cvAuto colours under ipatAuto.
+ */
+declare function readShd(bytes: Uint8Array, offset: number): Color | undefined;
+/** One Shd's own ten bytes: cvFore left automatic and the background stated as cvBack under ipatAuto, which is exactly how LibreOffice 26.2.5.2 writes a cell fill (confirmed against its own `.doc` output: a #ffff00 cell came back as cvFore cvAuto, cvBack `ff ff 00 00`, ipat 0x0000). An absent background writes ShdAuto -- the all-automatic value [MS-DOC] 2.9.247 defines as "no shading is applied" -- so an undecorated cell inside a row that has decorated ones still states its own lack of shading rather than inheriting a neighbour's. */
+declare function writeShd(background: Color | undefined): number[];
+/** One Shd80 ([MS-DOC] 2.9.248) as a flat background colour: the same ipatAuto/ipatSolid reading readShd applies, over the Ico palette rather than COLORREFs. This is the Word 97-era spelling of cell shading, superseded by Shd but still written -- alongside it -- by a real producer, so a file carrying only this one still reads. Never written by this package, which states shading through Shd alone. icoFore/icoBack are each a 5-bit field, so a value the 17-entry palette cannot hold is a real possibility rather than a format-level impossibility; decorativeIcoColor resolves that case to no background instead of aborting the whole document read. */
+declare function readShd80(value: number): Color | undefined;
+/** A cell's four sides as a ContentCellBorders, or undefined when it has none -- the shape ContentTableCell.borders carries, with an absent side meaning that side has no border rather than an explicitly-null one. */
+declare function cellBordersFrom(sides: Readonly<Record<CellBorderSide, ContentBorder | undefined>>): ContentCellBorders | undefined;
+//#endregion
+export { BORDERS_TO_APPLY, BRC80_SIZE, BRC_SIZE, CELL_BORDER_SIDES, CellBorderSide, SHD80_SIZE, SHD_SIZE, borderNeedsExactColor, cellBordersFrom, readBrc, readBrc80, readShd, readShd80, writeBrc, writeBrc80, writeShd };

package/dist/table/decoration.d.ts

@@ -0,0 +1,41 @@
+import { Color, ContentBorder, ContentCellBorders } from "document-schema.js";
+//#region src/table/decoration.d.ts
+/** The four sides of a cell, in the order TC80 declares them ([MS-DOC] 2.9.313: brcTop, brcLeft, brcBottom, brcRight). Used as the iteration order for both directions, so a side can never be read from one offset and written to another. */
+declare const CELL_BORDER_SIDES: readonly ["top", "left", "bottom", "right"];
+type CellBorderSide = (typeof CELL_BORDER_SIDES)[number];
+/** TableBrcOperand.bordersToApply, [MS-DOC] 2.9.305: which edges one operand formats, as the bitwise OR of any subset. Only the four rectangular sides are listed -- 0x10/0x20 are the two diagonals, which ContentCellBorders has no member for and this package neither reads nor writes. */
+declare const BORDERS_TO_APPLY: Readonly<Record<CellBorderSide, number>>;
+/** Brc80's own fixed size, [MS-DOC] 2.9.17: dptLineWidth (1) + brcType (1) + ico (1) + dptSpace/fShadow/fFrame/reserved (1). */
+declare const BRC80_SIZE = 4;
+/** Brc's own fixed size, [MS-DOC] 2.9.16: cv (4) + dptLineWidth (1) + brcType (1) + dptSpace/fShadow/fFrame/fReserved (2). */
+declare const BRC_SIZE = 8;
+/** Shd's own fixed size, [MS-DOC] 2.9.247: cvFore (4) + cvBack (4) + ipat (2). */
+declare const SHD_SIZE = 10;
+/** Shd80's own fixed size, [MS-DOC] 2.9.248: one 16-bit word packing icoFore (5 bits), icoBack (5 bits) and ipat (6 bits). */
+declare const SHD80_SIZE = 2;
+/** One TC80 border field: a Brc80MayBeNil ([MS-DOC] 2.9.18) -- a Brc80 whose all-bits-set value "specifies that the region in question has no border". Returns undefined for that sentinel, for brcType 0x00 ("No border", the spelling LibreOffice writes instead), and for any brcType outside the cell-border range BRC_TYPE_STYLE covers. An ico outside the palette's own bound resolves through decorativeIcoColor to the automatic-colour fallback (borderFrom's own AUTOMATIC_BORDER_COLOR) rather than aborting the whole document read over one cosmetic byte -- see decorativeIcoColor's own note in color.ts. */
+declare function readBrc80(bytes: Uint8Array, offset: number): ContentBorder | undefined;
+/** The eight bytes of one TableBrcOperand.brc field: a BrcMayBeNil ([MS-DOC] 2.9.20) -- "If the last four bytes are 0xFFFFFFFF, the BrcMayBeNil is a NilBrc that specifies that the table cells in question have no border", otherwise a Brc ([MS-DOC] 2.9.16) whose own cv states the colour exactly. */
+declare function readBrc(bytes: Uint8Array, offset: number): ContentBorder | undefined;
+/** One TC80 border field's own four bytes: the Brc80MayBeNil no-border sentinel for an absent border, otherwise a real Brc80 whose colour is the nearest Ico the fixed palette offers (see color.ts's nearestIco, and borderNeedsExactColor for how the exact colour still reaches the file). dptSpace, fShadow and fFrame are always zero -- ContentBorder models none of the three, so writing anything else would be inventing a fact the input never stated. */
+declare function writeBrc80(border: ContentBorder | undefined): number[];
+/** One TableBrcOperand.brc field's own eight bytes: a real Brc carrying the border's colour exactly, as a COLORREF rather than a palette index. Only ever called for a border that exists, since a TableBrcOperand naming no sides is never emitted at all. */
+declare function writeBrc(border: ContentBorder): number[];
+/** Whether this border's colour survives the Ico palette Brc80 is limited to. When it does, TC80's own Brc80 already states the border exactly and the sprmTSetBrc precision layer would be pure duplication; when it does not, that layer is the only place the real colour can be stated. Compared on the written byte values rather than the floating-point components, so a colour that round-trips through colorRefBytes to the identical palette entry counts as exact. */
+declare function borderNeedsExactColor(border: ContentBorder): boolean;
+/**
+ * One Shd ([MS-DOC] 2.9.247) as a flat background colour, or undefined where it states none.
+ *
+ * Only the two patterns that genuinely produce a flat fill resolve: ipatAuto, under which the cell shows cvBack (ECMA-376's own `clear` shading with a fill colour, which is what a real producer writes for a plain cell background), and ipatSolid, under which it shows cvFore. Every other Ipat -- the fourteen percentage fills, the stripe and crosshatch families, and ipatNil -- is a genuine pattern that Color cannot express, and reads as no background rather than as one of its two colours: reporting a 50% grey crosshatch as its own foreground colour would misstate what the cell actually shows. This is the same deliberate judgment xls-codec makes for BIFF8's own FillPattern enumeration, for the same reason, and it costs nothing on a round trip because this package's own writer emits ipatAuto and nothing else.
+ *
+ * A cvAuto colour under either pattern is likewise no background: it designates the application's own default, which for a cell background is "not shaded" rather than a colour to state. ShdAuto and ShdNil -- the two special values [MS-DOC] 2.9.247 names for "no shading is applied" -- both fall out of exactly that, with no separate check: each is a pair of cvAuto colours under ipatAuto.
+ */
+declare function readShd(bytes: Uint8Array, offset: number): Color | undefined;
+/** One Shd's own ten bytes: cvFore left automatic and the background stated as cvBack under ipatAuto, which is exactly how LibreOffice 26.2.5.2 writes a cell fill (confirmed against its own `.doc` output: a #ffff00 cell came back as cvFore cvAuto, cvBack `ff ff 00 00`, ipat 0x0000). An absent background writes ShdAuto -- the all-automatic value [MS-DOC] 2.9.247 defines as "no shading is applied" -- so an undecorated cell inside a row that has decorated ones still states its own lack of shading rather than inheriting a neighbour's. */
+declare function writeShd(background: Color | undefined): number[];
+/** One Shd80 ([MS-DOC] 2.9.248) as a flat background colour: the same ipatAuto/ipatSolid reading readShd applies, over the Ico palette rather than COLORREFs. This is the Word 97-era spelling of cell shading, superseded by Shd but still written -- alongside it -- by a real producer, so a file carrying only this one still reads. Never written by this package, which states shading through Shd alone. icoFore/icoBack are each a 5-bit field, so a value the 17-entry palette cannot hold is a real possibility rather than a format-level impossibility; decorativeIcoColor resolves that case to no background instead of aborting the whole document read. */
+declare function readShd80(value: number): Color | undefined;
+/** A cell's four sides as a ContentCellBorders, or undefined when it has none -- the shape ContentTableCell.borders carries, with an absent side meaning that side has no border rather than an explicitly-null one. */
+declare function cellBordersFrom(sides: Readonly<Record<CellBorderSide, ContentBorder | undefined>>): ContentCellBorders | undefined;
+//#endregion
+export { BORDERS_TO_APPLY, BRC80_SIZE, BRC_SIZE, CELL_BORDER_SIDES, CellBorderSide, SHD80_SIZE, SHD_SIZE, borderNeedsExactColor, cellBordersFrom, readBrc, readBrc80, readShd, readShd80, writeBrc, writeBrc80, writeShd };

package/dist/table/decoration.js

@@ -0,0 +1,205 @@
+import { DocFormatError } from "../errors.js";
+import { readUint16LE, readUint8 } from "../bytes.js";
+import { autoColorRefBytes, colorRefBytes, decorativeIcoColor, icoColor, nearestIco, readColorRef } from "../color.js";
+//#region src/table/decoration.ts
+/** The four sides of a cell, in the order TC80 declares them ([MS-DOC] 2.9.313: brcTop, brcLeft, brcBottom, brcRight). Used as the iteration order for both directions, so a side can never be read from one offset and written to another. */
+const CELL_BORDER_SIDES = [
+	"top",
+	"left",
+	"bottom",
+	"right"
+];
+/** TableBrcOperand.bordersToApply, [MS-DOC] 2.9.305: which edges one operand formats, as the bitwise OR of any subset. Only the four rectangular sides are listed -- 0x10/0x20 are the two diagonals, which ContentCellBorders has no member for and this package neither reads nor writes. */
+const BORDERS_TO_APPLY = {
+	top: 1,
+	left: 2,
+	bottom: 4,
+	right: 8
+};
+/** Brc80's own fixed size, [MS-DOC] 2.9.17: dptLineWidth (1) + brcType (1) + ico (1) + dptSpace/fShadow/fFrame/reserved (1). */
+const BRC80_SIZE = 4;
+/** Brc's own fixed size, [MS-DOC] 2.9.16: cv (4) + dptLineWidth (1) + brcType (1) + dptSpace/fShadow/fFrame/fReserved (2). */
+const BRC_SIZE = 8;
+/** Shd's own fixed size, [MS-DOC] 2.9.247: cvFore (4) + cvBack (4) + ipat (2). */
+const SHD_SIZE = 10;
+/** Shd80's own fixed size, [MS-DOC] 2.9.248: one 16-bit word packing icoFore (5 bits), icoBack (5 bits) and ipat (6 bits). */
+const SHD80_SIZE = 2;
+/** BrcType 0x00, [MS-DOC] 2.9.22: "No border." Distinct from the Brc80MayBeNil/BrcMayBeNil all-bits-set sentinel, and the spelling a real producer (LibreOffice) uses for an undecorated cell -- both mean the same thing and both are read as no border. */
+const BRC_TYPE_NONE = 0;
+const BRC_TYPE_SINGLE = 1;
+const BRC_TYPE_DOUBLE = 3;
+const BRC_TYPE_DOTTED = 6;
+const BRC_TYPE_DASHED = 7;
+/**
+* Every BrcType [MS-DOC] 2.9.22 defines for a cell border (0x00 through 0x1B), mapped onto the four members ContentStrokeStyle has. Values 0x02 and 0x04 are absent from the published enumeration entirely and so have no entry here; 0x00 is handled by the caller before this table is consulted.
+*
+* Three families collapse, each stated rather than silently folded -- the same deliberate narrowing xls-codec's own BIFF_BORDER_STYLE makes for BIFF8's dash tokens. The dash family (dotDash 0x08, dotDotDash 0x09, dashSmallGap 0x16, dashDotStroked 0x17) collapses to 'dashed', since ContentStrokeStyle names one dashed pattern rather than a vocabulary of them. Every genuinely multi-line border collapses to 'double': the triple line (0x0A), the nine thinThick/thickThin gap variants (0x0B-0x13), the double wave (0x15), the two three-dimensional borders (0x18/0x19), and outset/inset (0x1A/0x1B, which Brc80 forbids but Brc permits). And the single wavy line (0x14) collapses to 'solid', being one continuous stroke.
+*
+* Values from 0x40 to 0xE3 are the art/image page borders, which [MS-DOC] 2.9.22 permits only "if they describe a page border" -- never a cell border -- so they have no entry and read as no border at all rather than as an invented approximation of a picture. 0xFF ("This MUST be ignored") is likewise absent.
+*/
+const BRC_TYPE_STYLE = {
+	[BRC_TYPE_SINGLE]: "solid",
+	[BRC_TYPE_DOUBLE]: "double",
+	5: "solid",
+	[BRC_TYPE_DOTTED]: "dotted",
+	[BRC_TYPE_DASHED]: "dashed",
+	8: "dashed",
+	9: "dashed",
+	10: "double",
+	11: "double",
+	12: "double",
+	13: "double",
+	14: "double",
+	15: "double",
+	16: "double",
+	17: "double",
+	18: "double",
+	19: "double",
+	20: "solid",
+	21: "double",
+	22: "dashed",
+	23: "dashed",
+	24: "double",
+	25: "double",
+	26: "double",
+	27: "double"
+};
+/** The inverse of BRC_TYPE_STYLE: the one BrcType each ContentStrokeStyle member is written as. Every collapsed family above writes back as its own family's plainest member, since that is the only one the collapsed value can honestly claim to be. */
+const STYLE_BRC_TYPE = {
+	solid: BRC_TYPE_SINGLE,
+	dashed: BRC_TYPE_DASHED,
+	dotted: BRC_TYPE_DOTTED,
+	double: BRC_TYPE_DOUBLE
+};
+/** dptLineWidth's own unit, [MS-DOC] 2.9.16/2.9.17: "the width of the border in 1/8-point increments" for every brcType below 0x40, which is every type a cell border can carry. */
+const EIGHTHS_PER_POINT = 8;
+/** "Values of less than 2 are considered to be equivalent to 2" -- the specification's own floor, applied on read so a border stating 0 or 1 resolves to the width it actually renders at rather than to a widthPt ContentBorderSchema would reject for not being positive. */
+const MIN_DPT_LINE_WIDTH = 2;
+/** dptLineWidth is a single byte, so 255 eighths (31.875pt) is the widest border the format can state at all. */
+const MAX_DPT_LINE_WIDTH = 255;
+/** The colour a border with no colour of its own resolves to. [MS-DOC]'s automatic colour (Ico 0x00, or a COLORREF with fAuto set) "designates the default color for the application" and names no components, but ContentBorder.color is required, so a border stating one has to resolve to something. Black is what an automatic border renders as against a default background, and resolving to it keeps the border itself -- which genuinely exists and genuinely renders -- rather than dropping the border outright to avoid stating a colour for it. */
+const AUTOMATIC_BORDER_COLOR = {
+	r: 0,
+	g: 0,
+	b: 0
+};
+function borderFrom(dptLineWidth, brcType, color) {
+	const style = BRC_TYPE_STYLE[brcType];
+	if (style === void 0) return void 0;
+	const border = {
+		color: color ?? AUTOMATIC_BORDER_COLOR,
+		widthPt: Math.max(dptLineWidth, MIN_DPT_LINE_WIDTH) / EIGHTHS_PER_POINT
+	};
+	if (style !== "solid") border.style = style;
+	return border;
+}
+/** Whether all `length` bytes from `offset` are 0xFF -- the all-bits-set form both nil-border spellings are defined in terms of. */
+function allBitsSet(bytes, offset, length) {
+	for (let index = 0; index < length; index += 1) if (readUint8(bytes, offset + index) !== 255) return false;
+	return true;
+}
+/** One TC80 border field: a Brc80MayBeNil ([MS-DOC] 2.9.18) -- a Brc80 whose all-bits-set value "specifies that the region in question has no border". Returns undefined for that sentinel, for brcType 0x00 ("No border", the spelling LibreOffice writes instead), and for any brcType outside the cell-border range BRC_TYPE_STYLE covers. An ico outside the palette's own bound resolves through decorativeIcoColor to the automatic-colour fallback (borderFrom's own AUTOMATIC_BORDER_COLOR) rather than aborting the whole document read over one cosmetic byte -- see decorativeIcoColor's own note in color.ts. */
+function readBrc80(bytes, offset) {
+	if (allBitsSet(bytes, offset, 4)) return void 0;
+	const brcType = readUint8(bytes, offset + 1);
+	if (brcType === BRC_TYPE_NONE) return void 0;
+	return borderFrom(readUint8(bytes, offset), brcType, decorativeIcoColor(readUint8(bytes, offset + 2)));
+}
+/** The eight bytes of one TableBrcOperand.brc field: a BrcMayBeNil ([MS-DOC] 2.9.20) -- "If the last four bytes are 0xFFFFFFFF, the BrcMayBeNil is a NilBrc that specifies that the table cells in question have no border", otherwise a Brc ([MS-DOC] 2.9.16) whose own cv states the colour exactly. */
+function readBrc(bytes, offset) {
+	if (allBitsSet(bytes, offset + 4, 4)) return void 0;
+	const brcType = readUint8(bytes, offset + 5);
+	if (brcType === BRC_TYPE_NONE) return void 0;
+	return borderFrom(readUint8(bytes, offset + 4), brcType, readColorRef(bytes, offset));
+}
+/** Brc80MayBeNil's own no-border value, [MS-DOC] 2.9.18: "When all bits are set (0xFFFFFFFF when interpreted as a 4-byte unsigned integer), this structure specifies that the region in question has no border." */
+const NIL_BRC80 = [
+	255,
+	255,
+	255,
+	255
+];
+/** dptLineWidth for a border of `widthPt`, in the 1/8-point increments [MS-DOC] states it in. Refuses a width the single-byte field cannot hold rather than silently clamping it to a thinner border than the caller asked for, matching how every other out-of-range operand in this writer is handled. */
+function dptLineWidthFor(widthPt) {
+	const eighths = Math.round(widthPt * EIGHTHS_PER_POINT);
+	if (eighths < MIN_DPT_LINE_WIDTH || eighths > MAX_DPT_LINE_WIDTH) throw new DocFormatError(`a table cell border is ${widthPt}pt, outside the ${MIN_DPT_LINE_WIDTH / EIGHTHS_PER_POINT}..${MAX_DPT_LINE_WIDTH / EIGHTHS_PER_POINT}pt range [MS-DOC]'s own single-byte dptLineWidth can state in 1/8-point increments`);
+	return eighths;
+}
+/** One TC80 border field's own four bytes: the Brc80MayBeNil no-border sentinel for an absent border, otherwise a real Brc80 whose colour is the nearest Ico the fixed palette offers (see color.ts's nearestIco, and borderNeedsExactColor for how the exact colour still reaches the file). dptSpace, fShadow and fFrame are always zero -- ContentBorder models none of the three, so writing anything else would be inventing a fact the input never stated. */
+function writeBrc80(border) {
+	if (border === void 0) return [...NIL_BRC80];
+	return [
+		dptLineWidthFor(border.widthPt),
+		STYLE_BRC_TYPE[border.style ?? "solid"],
+		nearestIco(border.color),
+		0
+	];
+}
+/** One TableBrcOperand.brc field's own eight bytes: a real Brc carrying the border's colour exactly, as a COLORREF rather than a palette index. Only ever called for a border that exists, since a TableBrcOperand naming no sides is never emitted at all. */
+function writeBrc(border) {
+	return [
+		...colorRefBytes(border.color),
+		dptLineWidthFor(border.widthPt),
+		STYLE_BRC_TYPE[border.style ?? "solid"],
+		0,
+		0
+	];
+}
+/** Whether this border's colour survives the Ico palette Brc80 is limited to. When it does, TC80's own Brc80 already states the border exactly and the sprmTSetBrc precision layer would be pure duplication; when it does not, that layer is the only place the real colour can be stated. Compared on the written byte values rather than the floating-point components, so a colour that round-trips through colorRefBytes to the identical palette entry counts as exact. */
+function borderNeedsExactColor(border) {
+	const palette = icoColor(nearestIco(border.color));
+	if (palette === void 0) return true;
+	const wanted = colorRefBytes(border.color);
+	const approximated = colorRefBytes(palette);
+	return wanted[0] !== approximated[0] || wanted[1] !== approximated[1] || wanted[2] !== approximated[2];
+}
+/** ipatAuto, [MS-DOC] 2.9.121: "Clear, ST_Shd: clear" -- the pattern under which a cell simply shows its own cvBack, which is how both Word and LibreOffice spell a flat background colour, and the only pattern this package writes. */
+const IPAT_AUTO = 0;
+/** ipatSolid, [MS-DOC] 2.9.121: "Solid ST_Shd: solid" -- the cell is filled entirely with cvFore. */
+const IPAT_SOLID = 1;
+/**
+* One Shd ([MS-DOC] 2.9.247) as a flat background colour, or undefined where it states none.
+*
+* Only the two patterns that genuinely produce a flat fill resolve: ipatAuto, under which the cell shows cvBack (ECMA-376's own `clear` shading with a fill colour, which is what a real producer writes for a plain cell background), and ipatSolid, under which it shows cvFore. Every other Ipat -- the fourteen percentage fills, the stripe and crosshatch families, and ipatNil -- is a genuine pattern that Color cannot express, and reads as no background rather than as one of its two colours: reporting a 50% grey crosshatch as its own foreground colour would misstate what the cell actually shows. This is the same deliberate judgment xls-codec makes for BIFF8's own FillPattern enumeration, for the same reason, and it costs nothing on a round trip because this package's own writer emits ipatAuto and nothing else.
+*
+* A cvAuto colour under either pattern is likewise no background: it designates the application's own default, which for a cell background is "not shaded" rather than a colour to state. ShdAuto and ShdNil -- the two special values [MS-DOC] 2.9.247 names for "no shading is applied" -- both fall out of exactly that, with no separate check: each is a pair of cvAuto colours under ipatAuto.
+*/
+function readShd(bytes, offset) {
+	const ipat = readUint16LE(bytes, offset + 8);
+	if (ipat === IPAT_AUTO) return readColorRef(bytes, offset + 4);
+	if (ipat === IPAT_SOLID) return readColorRef(bytes, offset);
+}
+/** One Shd's own ten bytes: cvFore left automatic and the background stated as cvBack under ipatAuto, which is exactly how LibreOffice 26.2.5.2 writes a cell fill (confirmed against its own `.doc` output: a #ffff00 cell came back as cvFore cvAuto, cvBack `ff ff 00 00`, ipat 0x0000). An absent background writes ShdAuto -- the all-automatic value [MS-DOC] 2.9.247 defines as "no shading is applied" -- so an undecorated cell inside a row that has decorated ones still states its own lack of shading rather than inheriting a neighbour's. */
+function writeShd(background) {
+	return [
+		...autoColorRefBytes(),
+		...background === void 0 ? autoColorRefBytes() : colorRefBytes(background),
+		0,
+		0
+	];
+}
+/** Shd80Nil, [MS-DOC] 2.9.248: icoFore 0x1F, icoBack 0x1F, ipat 0x3F -- every bit set, "specifies that no shading is applied", and explicitly exempt from the Ico and Ipat bounds the fields otherwise carry. */
+const SHD80_NIL = 65535;
+/** One Shd80 ([MS-DOC] 2.9.248) as a flat background colour: the same ipatAuto/ipatSolid reading readShd applies, over the Ico palette rather than COLORREFs. This is the Word 97-era spelling of cell shading, superseded by Shd but still written -- alongside it -- by a real producer, so a file carrying only this one still reads. Never written by this package, which states shading through Shd alone. icoFore/icoBack are each a 5-bit field, so a value the 17-entry palette cannot hold is a real possibility rather than a format-level impossibility; decorativeIcoColor resolves that case to no background instead of aborting the whole document read. */
+function readShd80(value) {
+	if (value === SHD80_NIL) return void 0;
+	const icoFore = value & 31;
+	const icoBack = value >> 5 & 31;
+	const ipat = value >> 10 & 63;
+	if (ipat === IPAT_AUTO) return decorativeIcoColor(icoBack);
+	if (ipat === IPAT_SOLID) return decorativeIcoColor(icoFore);
+}
+/** A cell's four sides as a ContentCellBorders, or undefined when it has none -- the shape ContentTableCell.borders carries, with an absent side meaning that side has no border rather than an explicitly-null one. */
+function cellBordersFrom(sides) {
+	const borders = {};
+	let any = false;
+	for (const side of CELL_BORDER_SIDES) {
+		const border = sides[side];
+		if (border === void 0) continue;
+		borders[side] = border;
+		any = true;
+	}
+	return any ? borders : void 0;
+}
+//#endregion
+export { BORDERS_TO_APPLY, BRC80_SIZE, BRC_SIZE, CELL_BORDER_SIDES, SHD80_SIZE, SHD_SIZE, borderNeedsExactColor, cellBordersFrom, readBrc, readBrc80, readShd, readShd80, writeBrc, writeBrc80, writeShd };