xls-codec 2.0.2 → 4.0.0

package/dist/{xf-colors-CehHZtBy.d.cts → xf-colors-BB5MKq6R.d.cts}

@@ -1,10 +1,12 @@
 import { t as BlockCursor } from "./cursor-VMtw9uVP.cjs";
-import { Alignment, Color, ContentBorder } from "document-schema.js";
+import { Alignment, Color, ContentBorder, ContentCellFill, ContentCellPatternType } 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. */
+/** FLSSOLID: a solid fill -- "If this value is 1 ... then only icvFore is rendered" ([MS-XLS] CellXF). */
 declare const FILL_PATTERN_SOLID = 1;
+/** The inverse of FILL_PATTERN_TO_PATTERN_TYPE, built from it rather than restated by hand so the two can never drift apart. Every ContentCellPatternType this package's own writer is ever asked to state has an entry, since the SpreadsheetML half of the shared vocabulary is exactly FILL_PATTERN_TO_PATTERN_TYPE's own value set -- the WordprocessingML-only members (the percentN family and the stripe/cross families ST_Shd names) are absent, FillPattern having no equivalent for them at all. */
+declare const PATTERN_TYPE_TO_FILL_PATTERN: ReadonlyMap<ContentCellPatternType, number>;
 /** 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. */
@@ -56,12 +58,17 @@ interface XfBorderEdge {
 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. */
+/**
+ * Resolves a cell's own FillPattern/icvFore/icvBack triple to a real ContentCellFill (ExaDev/documents.js#951), or undefined for FLSNULL (no fill at all), for a reserved/unrecognised FillPattern value, or for FLSSOLID when its own icvFore does not resolve to a fixed RGB value (an "Automatic" or otherwise unmapped icv, which leaves nothing to state a solid fill's colour as).
+ *
+ * FLSSOLID resolves to a 'solid' fill of icvFore alone -- "If this value is 1 ... then only icvFore is rendered" ([MS-XLS] CellXF), so icvBack carries no meaning for it and is never consulted. Every other named FillPattern resolves to a real 'pattern' fill via FILL_PATTERN_TO_PATTERN_TYPE, carrying whichever of icvFore/icvBack resolves to a real colour (either may be an "Automatic" icv this package cannot express as a fixed RGB value, matching ContentCellFillSchema's own "a colour can defer instead of asserting" convention).
+ */
+declare function resolveFillBackground(fillPattern: number, foregroundIcv: number, backgroundIcv: number, palette: readonly Color[] | undefined): ContentCellFill | 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/background colours, and each of the four sides' own border style plus colour. fillBackgroundIcv carries no meaning for a solid fill (icvFore alone is rendered) but is real for every other named pattern, where it is the colour the pattern's gaps show through. 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 fillBackgroundIcv: number;
   readonly left: XfBorderEdge;
   readonly right: XfBorderEdge;
   readonly top: XfBorderEdge;
@@ -88,4 +95,4 @@ 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 };
+export { packXfDecorationWords as A, UNDECORATED_XF_FIELDS as C, borderStyleTokenFor as D, XfDecorationFields as E, resolveIcvColor as F, resolveVerticalAlignment as I, unpackXfAlignment as L, resolveBorderEdge as M, resolveFillBackground as N, horizAlignTokenFor as O, resolveHorizontalAlignment as P, unpackXfDecoration as R, PATTERN_TYPE_TO_FILL_PATTERN as S, XfBorderEdge 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, readLongRgbColor as j, longRgbBytesOf 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, XfAlignmentFields as w, PALETTE_ENTRY_COUNT as x, ICV_AUTOMATIC_FOREGROUND as y, vertAlignTokenFor as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xls-codec",
-  "version": "2.0.2",
+  "version": "4.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": {
@@ -68,9 +68,9 @@
   },
   "packageManager": "pnpm@11.6.0",
   "dependencies": {
-    "archive-codec": "^1.4.2",
-    "document-schema.js": "^5.6.0",
-    "excel-number-format": "^1.0.1"
+    "archive-codec": "^1.4.3",
+    "document-schema.js": "^6.0.0",
+    "excel-number-format": "^1.0.2"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",

package/dist/ptg-B2K8t3js.d.cts

@@ -1,21 +0,0 @@
-//#region src/biff/ptg.d.ts
-/** A 3D reference's sheet scope, resolved from its ixti through EXTERNSHEET and a self-referencing SupBook ([MS-XLS] 2.4.271, 2.4.106, 2.5.344): the first and last sheet of the reference, both direct BoundSheet8 indices into FormulaSheetContext.sheets. A single-sheet 3D reference has `firstSheetIndex === lastSheetIndex`. Defined here rather than alongside the globals reader that produces it, since resolving it into reference text is what this module exists to do. */
-interface SheetRange {
-  readonly firstSheetIndex: number;
-  readonly lastSheetIndex: number;
-}
-/** What a 3D reference's own ixti resolves against: the workbook's sheets in BoundSheet8 order (only the name is needed here), and each ixti's own resolved sheet range (undefined where this reader does not resolve it -- see WorkbookGlobals.sheetRanges, which this type's own sheetRanges field matches field-for-field). */
-interface FormulaSheetContext {
-  readonly sheets: readonly {
-    readonly name: string;
-  }[];
-  readonly sheetRanges: readonly (SheetRange | undefined)[];
-}
-/**
- * Parses a Formula record's compiled expression into the text a spreadsheet application would show, or returns undefined for a token this reader does not resolve -- a shared formula's PtgExp, an array constant's PtgArray, a defined name, a natural-language reference, or a 3D reference into a genuinely external workbook (see the module comment for the full list). The caller leaves ContentSheetCell.formula absent in that case, exactly as for any other unsupported construct.
- *
- * `rgce` is the formula's own token bytes, already sliced to their declared length (CellParsedFormula.cce) by the caller -- this function reads exactly that many bytes and nothing past them.
- */
-declare function parseFormulaText(rgce: Uint8Array<ArrayBuffer>, context: FormulaSheetContext): string | undefined;
-//#endregion
-export { SheetRange as n, parseFormulaText as r, FormulaSheetContext as t };

package/dist/ptg-B2K8t3js.d.ts

@@ -1,21 +0,0 @@
-//#region src/biff/ptg.d.ts
-/** A 3D reference's sheet scope, resolved from its ixti through EXTERNSHEET and a self-referencing SupBook ([MS-XLS] 2.4.271, 2.4.106, 2.5.344): the first and last sheet of the reference, both direct BoundSheet8 indices into FormulaSheetContext.sheets. A single-sheet 3D reference has `firstSheetIndex === lastSheetIndex`. Defined here rather than alongside the globals reader that produces it, since resolving it into reference text is what this module exists to do. */
-interface SheetRange {
-  readonly firstSheetIndex: number;
-  readonly lastSheetIndex: number;
-}
-/** What a 3D reference's own ixti resolves against: the workbook's sheets in BoundSheet8 order (only the name is needed here), and each ixti's own resolved sheet range (undefined where this reader does not resolve it -- see WorkbookGlobals.sheetRanges, which this type's own sheetRanges field matches field-for-field). */
-interface FormulaSheetContext {
-  readonly sheets: readonly {
-    readonly name: string;
-  }[];
-  readonly sheetRanges: readonly (SheetRange | undefined)[];
-}
-/**
- * Parses a Formula record's compiled expression into the text a spreadsheet application would show, or returns undefined for a token this reader does not resolve -- a shared formula's PtgExp, an array constant's PtgArray, a defined name, a natural-language reference, or a 3D reference into a genuinely external workbook (see the module comment for the full list). The caller leaves ContentSheetCell.formula absent in that case, exactly as for any other unsupported construct.
- *
- * `rgce` is the formula's own token bytes, already sliced to their declared length (CellParsedFormula.cce) by the caller -- this function reads exactly that many bytes and nothing past them.
- */
-declare function parseFormulaText(rgce: Uint8Array<ArrayBuffer>, context: FormulaSheetContext): string | undefined;
-//#endregion
-export { SheetRange as n, parseFormulaText as r, FormulaSheetContext as t };