@shbernal/ts-xlsx 1.0.0

package/dist/io/xlsx/read-styles.d.ts

@@ -0,0 +1,8 @@
+import { type Font } from '../../core/style.ts';
+import { type XmlAttributes } from '../../xml/xml-read.ts';
+import { type StyleTable } from '../style/xf-style.ts';
+export type FontDraft = {
+    -readonly [K in keyof Font]?: Font[K];
+};
+export declare function parseStyleTable(xml: string): StyleTable;
+export declare function applyFontChild(draft: FontDraft, local: string, attrs: XmlAttributes): void;

package/dist/io/xlsx/read-styles.js

@@ -0,0 +1,551 @@
+// The style-table reader: `xl/styles.xml` in, a flat table of resolved cell formats out. It is a
+// single streaming pass over the shared sub-tables (`<numFmts>`, `<fills>`, `<fonts>`, `<borders>`)
+// and the two xf tables (`<cellXfs>`, `<cellStyleXfs>`), flattening the id-indirection so a cell's
+// `s` index maps straight to its facets. A construct it does not recognise is skipped, never guessed.
+//
+// Only the parsing is XML-specific. What an xf resolves *to* — `XfStyle`, the built-in number
+// formats, applying an xf to a cell — is a property of the OOXML style model rather than of its
+// spelling, and lives above both codecs in `../style/xf-style.ts`; the `.xlsb` style reader builds
+// the same table from BIFF12 records.
+import { assignStyleFacets, isBorderStyle, isFillPatternType, isFontScheme, isFontVerticalAlignment, isHorizontalAlignment, isNamedUnderlineStyle, isVerticalAlignment, } from "../../core/style.js";
+import { boolPresent, boolStrict, closeEmptyElements, localName, xmlEvents, } from "../../xml/xml-read.js";
+import { numFmtCodeFor } from "../style/xf-style.js";
+import { parseColor } from "./styles.js";
+// The four sides plus the diagonal — the edge elements a <border> can hold, in the order the
+// schema lists them. This one tuple drives the edge-name union, the membership set (which drives
+// edge parsing without a per-name branch), and the "does any edge carry a style" scan below.
+const BORDER_EDGE_NAMES = ['left', 'right', 'top', 'bottom', 'diagonal'];
+const BORDER_EDGES = new Set(BORDER_EDGE_NAMES);
+// Style-table elements that commit on their close: a bare <font/>/<border/>/<patternFill/>/
+// <gradientFill/>/<xf/> or a self-closing border edge is expanded to open+close so each commits
+// exactly once in onClose, never in a duplicated (and easily-forgotten) self-closing branch.
+const STYLE_EMPTY_CLOSES = new Set([
+    'font',
+    'border',
+    'patternFill',
+    'gradientFill',
+    'xf',
+    ...BORDER_EDGES,
+]);
+// styles.xml is a shared table: <numFmts> defines custom format codes by id, <fills> lists
+// the fills, and <cellXfs> lists the cell formats, each naming a fill and a number format by
+// id. We flatten that indirection into one array — cellXfs index → resolved {fill, numFmt} —
+// so a cell/row/column style index maps straight to its facets. The schema orders <numFmts>
+// and <fills> before <cellXfs>, so both lookups are complete before an xf references them.
+export function parseStyleTable(xml) {
+    if (xml === '')
+        return { cellXfs: [], namedStyles: [] };
+    let fills = [];
+    let fonts = [];
+    let borders = [];
+    let numFmtCodes = new Map();
+    const xfStyles = [];
+    // The named-style layer: <cellStyleXfs> holds the base formats a cell's xfId links to; <cellStyles>
+    // labels them by name/builtinId. Parsed in parallel with cellXfs, then zipped and merged below.
+    const namedXfs = [];
+    let cellStyleNames = [];
+    // One streaming pass, but each top-level sub-table drives its own focused sub-parser over the slice
+    // of events between its open and close. The schema orders the shared tables (<numFmts>, <fonts>,
+    // <fills>, <borders>) before the xf tables, so their results are complete before an <xf> resolves
+    // against them. Every recognised container name is plural and unique to the styleSheet root — none
+    // appears inside a <dxf>'s singular <font>/<fill>/<border> children — so skipping an unrecognised
+    // section here drops exactly what the old flat pass gated off with its `in*` flags.
+    const events = closeEmptyElements(xmlEvents(xml), STYLE_EMPTY_CLOSES);
+    let next = events.next();
+    while (next.done !== true) {
+        const event = next.value;
+        if (event.kind === 'open' && !event.selfClosing) {
+            switch (localName(event.name)) {
+                case 'numFmts':
+                    numFmtCodes = parseNumFmts(events);
+                    break;
+                case 'fonts':
+                    fonts = parseFonts(events);
+                    break;
+                case 'fills':
+                    fills = parseFills(events);
+                    break;
+                case 'borders':
+                    borders = parseBorders(events);
+                    break;
+                case 'cellStyleXfs':
+                    namedXfs.push(...parseXfTable(events, 'cellStyleXfs', { fills, fonts, borders, numFmtCodes }));
+                    break;
+                case 'cellXfs':
+                    xfStyles.push(...parseXfTable(events, 'cellXfs', { fills, fonts, borders, numFmtCodes }));
+                    break;
+                case 'cellStyles':
+                    cellStyleNames = parseCellStyles(events);
+                    break;
+            }
+        }
+        next = events.next();
+    }
+    // Layer each cellXfs entry over the named style its xfId links to: a facet the direct format sets
+    // wins; one it leaves unset falls through to the named style. The xfId is carried through so the
+    // link survives a re-write. A draft only holds keys for facets it actually set, so the spread merge
+    // takes the named base and lets the direct entry override exactly what it names.
+    const cellXfs = xfStyles.map((xf) => {
+        if (xf.xfId === undefined)
+            return xf;
+        const named = namedXfs[xf.xfId];
+        return named === undefined ? xf : { ...named, ...xf };
+    });
+    // Zip the resolved cellStyleXfs facets with their cellStyles name/builtinId into the model's named
+    // styles, index for index (a cellStyle's xfId is its cellStyleXfs index).
+    const namedStyles = namedXfs.map((xf, index) => {
+        const label = cellStyleNames.find((entry) => entry.xfId === index);
+        const style = {};
+        assignStyleFacets(style, xf);
+        if (label?.name !== undefined)
+            style.name = label.name;
+        if (label?.builtinId !== undefined)
+            style.builtinId = label.builtinId;
+        return style;
+    });
+    // Font 0 is the workbook's declared default, so it is carried out whole as well as flattened onto
+    // the xfs that name it — see {@link StyleTable.defaultFont}.
+    const defaultFont = fonts[0];
+    return defaultFont === undefined ? { cellXfs, namedStyles } : { cellXfs, namedStyles, defaultFont };
+}
+// Pull events off the shared stream up to — and consuming — the close of `container`, yielding only
+// those strictly inside it. A sub-table parser loops this to completion (never breaking), so it drives
+// its own small state machine over exactly its section without closing the underlying generator, and
+// the outer pass resumes at the element after the container's close.
+function* until(events, container) {
+    let next = events.next();
+    while (next.done !== true) {
+        const event = next.value;
+        if (event.kind === 'close' && localName(event.name) === container)
+            return;
+        yield event;
+        next = events.next();
+    }
+}
+// <numFmts> entries are self-closing, so they are read on open. A code with no id, or the General
+// id 0, contributes nothing.
+function parseNumFmts(events) {
+    const codes = new Map();
+    for (const event of until(events, 'numFmts')) {
+        if (event.kind === 'open' && localName(event.name) === 'numFmt') {
+            const id = Number(event.attrs.numFmtId);
+            if (Number.isInteger(id) && id > 0 && event.attrs.formatCode !== undefined) {
+                codes.set(id, event.attrs.formatCode);
+            }
+        }
+    }
+    return codes;
+}
+function parseFonts(events) {
+    const fonts = [];
+    let fontDraft = null;
+    for (const event of until(events, 'fonts')) {
+        if (event.kind === 'open') {
+            const local = localName(event.name);
+            // A <font>'s children are self-closing, so they are read here on open.
+            if (local === 'font')
+                fontDraft = {};
+            else if (fontDraft !== null)
+                applyFontChild(fontDraft, local, event.attrs);
+        }
+        else if (event.kind === 'close' && localName(event.name) === 'font' && fontDraft !== null) {
+            fonts.push(Object.keys(fontDraft).length > 0 ? fontDraft : undefined);
+            fontDraft = null;
+        }
+    }
+    return fonts;
+}
+function parseFills(events) {
+    const fills = [];
+    let pattern = '';
+    let fgColor;
+    let bgColor;
+    // A gradient fill accumulates from <gradientFill> open to close; its stops fill in as <stop>/<color>
+    // pairs arrive. `fillSlotAt` marks where in `fills` the current <fill> began, so its close can keep a
+    // slot even when the fill body was neither a pattern nor a gradient — index alignment is load-bearing.
+    let gradientDraft = null;
+    let fillSlotAt = -1;
+    for (const event of until(events, 'fills')) {
+        if (event.kind === 'open') {
+            const attrs = event.attrs;
+            switch (localName(event.name)) {
+                case 'fill':
+                    // Mark where this <fill> starts so its close can guarantee exactly one slot — a fill body
+                    // that is neither <patternFill> nor <gradientFill> (or a gradient we could not parse) must
+                    // still consume an id, or every later fill index shifts and cells mis-resolve their fill.
+                    fillSlotAt = fills.length;
+                    break;
+                case 'patternFill':
+                    pattern = attrs.patternType ?? 'none';
+                    fgColor = undefined;
+                    bgColor = undefined;
+                    break;
+                case 'fgColor':
+                    fgColor = parseColor(attrs);
+                    break;
+                case 'bgColor':
+                    bgColor = parseColor(attrs);
+                    break;
+                case 'gradientFill':
+                    gradientDraft = {
+                        fill: {
+                            type: 'gradient',
+                            gradient: attrs.type === 'path' ? 'path' : 'linear',
+                            stops: [],
+                        },
+                        stopPosition: null,
+                        stopColor: undefined,
+                    };
+                    assignGradientNumbers(gradientDraft.fill, attrs);
+                    break;
+                case 'stop':
+                    if (gradientDraft !== null) {
+                        const position = Number(attrs.position);
+                        gradientDraft.stopPosition = Number.isFinite(position) ? position : 0;
+                        gradientDraft.stopColor = undefined;
+                    }
+                    break;
+                case 'color':
+                    // The colour of the open <stop>; committed to a GradientStop when the stop closes.
+                    if (gradientDraft !== null)
+                        gradientDraft.stopColor = parseColor(attrs);
+                    break;
+            }
+        }
+        else if (event.kind === 'close') {
+            switch (localName(event.name)) {
+                case 'patternFill':
+                    fills.push(toFill(pattern, fgColor, bgColor));
+                    break;
+                case 'stop':
+                    if (gradientDraft !== null && gradientDraft.stopPosition !== null) {
+                        const stop = {
+                            position: gradientDraft.stopPosition,
+                            color: gradientDraft.stopColor ?? {},
+                        };
+                        gradientDraft.fill.stops = [...gradientDraft.fill.stops, stop];
+                        gradientDraft.stopPosition = null;
+                        gradientDraft.stopColor = undefined;
+                    }
+                    break;
+                case 'gradientFill':
+                    if (gradientDraft !== null) {
+                        fills.push(gradientDraft.fill);
+                        gradientDraft = null;
+                    }
+                    break;
+                case 'fill':
+                    // Backstop the slot: if this <fill>'s body pushed nothing (unparsed/unknown content), keep an
+                    // empty slot so id alignment holds and later fills still resolve to the right cells.
+                    if (fills.length === fillSlotAt)
+                        fills.push(undefined);
+                    break;
+            }
+        }
+    }
+    return fills;
+}
+function parseBorders(events) {
+    const borders = [];
+    let borderDraft = null;
+    // Which edge of the current border a nested <color> belongs to; null between edges.
+    let currentEdge = null;
+    for (const event of until(events, 'borders')) {
+        if (event.kind === 'open') {
+            const local = localName(event.name);
+            const attrs = event.attrs;
+            if (local === 'border') {
+                borderDraft = {};
+                currentEdge = null;
+                if (boolStrict(attrs.diagonalUp))
+                    borderDraft.diagonalUp = true;
+                if (boolStrict(attrs.diagonalDown))
+                    borderDraft.diagonalDown = true;
+            }
+            else if (borderDraft !== null) {
+                // A border's edges and their <color> children are all read on open (each is self-closing bar a
+                // coloured edge, whose colour child is itself self-closing). An edge whose style is absent or
+                // an unrecognised token is dropped — the side simply carries no border.
+                if (BORDER_EDGES.has(local)) {
+                    if (attrs.style !== undefined && isBorderStyle(attrs.style)) {
+                        currentEdge = local;
+                        borderDraft[currentEdge] = { style: attrs.style };
+                    }
+                    else {
+                        currentEdge = null;
+                    }
+                }
+                else if (local === 'color' && currentEdge !== null) {
+                    const edge = borderDraft[currentEdge];
+                    if (edge !== undefined)
+                        borderDraft[currentEdge] = { style: edge.style, color: parseColor(attrs) };
+                }
+            }
+        }
+        else if (event.kind === 'close') {
+            const local = localName(event.name);
+            if (local === 'border') {
+                if (borderDraft !== null) {
+                    borders.push(borderToStyle(borderDraft));
+                    borderDraft = null;
+                    currentEdge = null;
+                }
+            }
+            else if (borderDraft !== null && BORDER_EDGES.has(local)) {
+                // A coloured edge closes after its <color> child; drop the edge context so a stray later
+                // <color> cannot attach to it.
+                currentEdge = null;
+            }
+        }
+    }
+    return borders;
+}
+// Both <cellXfs> and <cellStyleXfs> hold <xf> with identical structure; they differ only in which
+// table the result lands in and whether an xfId link is meaningful (only cellXfs entries link to a
+// named style). One parser serves both, told by `container` which it is reading.
+function parseXfTable(events, container, deps) {
+    const xfs = [];
+    const captureXfId = container === 'cellXfs';
+    // The xf being read; held from open to close so its <alignment>/<protection> children can attach
+    // before it is committed. null outside an <xf>.
+    let pendingXf = null;
+    for (const event of until(events, container)) {
+        if (event.kind === 'open') {
+            const local = localName(event.name);
+            if (local === 'xf') {
+                // Hold the xf open until its close so an <alignment>/<protection> child can attach first; a
+                // self-closing <xf/> is expanded to a close, so it commits there too, child-free.
+                pendingXf = resolveXf(event.attrs, deps, captureXfId);
+            }
+            else if (pendingXf !== null && local === 'alignment') {
+                // An xf's <alignment> child arrives before the xf closes; attach it to the pending xf.
+                const alignment = parseAlignment(event.attrs);
+                if (alignment !== undefined)
+                    pendingXf.alignment = alignment;
+            }
+            else if (pendingXf !== null && local === 'protection') {
+                // An xf's <protection> child likewise arrives before the xf closes.
+                const protection = parseProtection(event.attrs);
+                if (protection !== undefined)
+                    pendingXf.protection = protection;
+            }
+        }
+        else if (event.kind === 'close' && localName(event.name) === 'xf' && pendingXf !== null) {
+            xfs.push(pendingXf);
+            pendingXf = null;
+        }
+    }
+    return xfs;
+}
+// Resolve an <xf>'s facet ids against the shared sub-tables into a draft. `captureXfId` is set only
+// for cellXfs entries, the sole table whose xfId links to a named style.
+function resolveXf(attrs, deps, captureXfId) {
+    const fillId = Number(attrs.fillId);
+    const fill = Number.isInteger(fillId) ? deps.fills[fillId] : undefined;
+    const fontId = Number(attrs.fontId);
+    // Font id 0 is the workbook default font (a real Calibri-11-style face), not an absence — unlike
+    // border id 0, which is a genuinely empty border. So an xf naming font 0 resolves to that default
+    // face, giving every cell a concrete font to render.
+    const font = Number.isInteger(fontId) ? deps.fonts[fontId] : undefined;
+    const borderId = Number(attrs.borderId);
+    // Border id 0 is the empty default; only a custom border (id > 0) is an explicit one.
+    const border = Number.isInteger(borderId) && borderId > 0 ? deps.borders[borderId] : undefined;
+    const numFmt = resolveNumFmt(attrs.numFmtId, deps.numFmtCodes);
+    const draft = {};
+    if (fill)
+        draft.fill = fill;
+    if (numFmt !== undefined)
+        draft.numFmt = numFmt;
+    if (font)
+        draft.font = font;
+    if (border)
+        draft.border = border;
+    // The quote-prefix flag is an attribute on the xf itself (no shared sub-table); carry it only when
+    // set so an ordinary cell does not gain a spurious `quotePrefix: false`.
+    if (boolStrict(attrs.quotePrefix))
+        draft.quotePrefix = true;
+    // A cellXfs entry's xfId links it to a named style; capture it only when it points beyond the Normal
+    // default (0), so an ordinary cell carries no spurious named-style link.
+    if (captureXfId && attrs.xfId !== undefined) {
+        const xfId = Number(attrs.xfId);
+        if (Number.isInteger(xfId) && xfId > 0)
+            draft.xfId = xfId;
+    }
+    return draft;
+}
+// A <cellStyle> (inside <cellStyles>) names a cellStyleXfs entry by xfId; it is self-closing, so it
+// is read on open.
+function parseCellStyles(events) {
+    const names = [];
+    for (const event of until(events, 'cellStyles')) {
+        if (event.kind === 'open' && localName(event.name) === 'cellStyle') {
+            const attrs = event.attrs;
+            const xfId = Number(attrs.xfId);
+            if (Number.isInteger(xfId)) {
+                const entry = { xfId };
+                if (attrs.name !== undefined)
+                    entry.name = attrs.name;
+                if (attrs.builtinId !== undefined) {
+                    const builtinId = Number(attrs.builtinId);
+                    if (Number.isInteger(builtinId))
+                        entry.builtinId = builtinId;
+                }
+                names.push(entry);
+            }
+        }
+    }
+    return names;
+}
+// A <font> child element sets one facet on the draft. Boolean flags honour their `val`: a
+// bare tag or val="1"/"true" is on, val="0"/"false" is off (an explicit-false flag is not
+// truthy merely because the tag is present). An unrecognised child is ignored.
+export function applyFontChild(draft, local, attrs) {
+    switch (local) {
+        case 'b':
+            draft.bold = boolPresent(attrs.val);
+            break;
+        case 'i':
+            draft.italic = boolPresent(attrs.val);
+            break;
+        case 'strike':
+            draft.strike = boolPresent(attrs.val);
+            break;
+        case 'outline':
+            draft.outline = boolPresent(attrs.val);
+            break;
+        case 'u':
+            // A bare <u/> is a single underline; a named style (single/double/…) carries through; but
+            // val="none" is the explicit ABSENCE of an underline, so it must read back falsy — not the
+            // truthy string "none" that a consumer's `if (font.underline)` would mistake for underlined. An
+            // unrecognised token keeps the "is underlined" fact but drops the unknown style (a plain true).
+            draft.underline =
+                attrs.val === undefined
+                    ? true
+                    : attrs.val === 'none'
+                        ? false
+                        : isNamedUnderlineStyle(attrs.val)
+                            ? attrs.val
+                            : true;
+            break;
+        case 'vertAlign':
+            if (attrs.val !== undefined && isFontVerticalAlignment(attrs.val))
+                draft.vertAlign = attrs.val;
+            break;
+        case 'sz': {
+            const size = Number(attrs.val);
+            if (Number.isFinite(size))
+                draft.size = size;
+            break;
+        }
+        case 'color':
+            draft.color = parseColor(attrs);
+            break;
+        // `<name>` in a styles `<font>`, `<rFont>` in a rich-text run's `<rPr>` — the same font face.
+        case 'name':
+        case 'rFont':
+            if (attrs.val !== undefined)
+                draft.name = attrs.val;
+            break;
+        case 'family': {
+            const family = Number(attrs.val);
+            if (Number.isInteger(family))
+                draft.family = family;
+            break;
+        }
+        case 'charset': {
+            const charset = Number(attrs.val);
+            if (Number.isInteger(charset))
+                draft.charset = charset;
+            break;
+        }
+        case 'scheme':
+            if (attrs.val !== undefined && isFontScheme(attrs.val))
+                draft.scheme = attrs.val;
+            break;
+        default:
+            break;
+    }
+}
+// An xf's numFmtId resolves against the custom codes first, then the built-in table; the
+// General format (id 0) and any unrecognised id mean the cell carries no explicit format.
+function resolveNumFmt(raw, custom) {
+    return raw === undefined ? undefined : numFmtCodeFor(Number(raw), custom);
+}
+function toFill(pattern, fgColor, bgColor) {
+    // `none` (and an absent patternType) is the absence of a fill; an unrecognised token is dropped the
+    // same way — like the border-edge style above — so a foreign pattern we do not model leaves the cell
+    // unfilled rather than propagating a token the writer would later re-emit unvalidated.
+    if (!isFillPatternType(pattern) || pattern === 'none')
+        return undefined;
+    return {
+        type: 'pattern',
+        pattern,
+        ...(fgColor ? { fgColor } : {}),
+        ...(bgColor ? { bgColor } : {}),
+    };
+}
+// Copy the numeric <gradientFill> attributes (degree; the path insets) onto a gradient draft, keeping
+// only the finite ones so an absent or malformed attribute leaves the field its OOXML default (unset).
+function assignGradientNumbers(fill, attrs) {
+    for (const key of ['degree', 'left', 'right', 'top', 'bottom']) {
+        const value = Number(attrs[key]);
+        if (attrs[key] !== undefined && Number.isFinite(value))
+            fill[key] = value;
+    }
+}
+// An accumulated border with no styled edge and no diagonal direction is the empty default:
+// it carries nothing, so it resolves to undefined rather than an all-empty Border object.
+function borderToStyle(draft) {
+    const hasEdge = BORDER_EDGE_NAMES.some((edge) => draft[edge] !== undefined);
+    if (!hasEdge && draft.diagonalUp === undefined && draft.diagonalDown === undefined)
+        return undefined;
+    return draft;
+}
+// Read an <alignment> element's attributes into an Alignment, keeping only facets that differ
+// from the default. Boolean flags honour their parsed value — wrapText="0" is off, so it must
+// not fabricate a { wrapText: false } alignment — and an element carrying only defaults yields
+// undefined rather than an empty alignment object.
+function parseAlignment(attrs) {
+    const out = {};
+    // `general` is the default and reads back as no explicit horizontal alignment; an unrecognised
+    // token (like an out-of-enum vertical one) is dropped rather than trusted into the model.
+    if (attrs.horizontal !== undefined &&
+        attrs.horizontal !== 'general' &&
+        isHorizontalAlignment(attrs.horizontal)) {
+        out.horizontal = attrs.horizontal;
+    }
+    if (attrs.vertical !== undefined && isVerticalAlignment(attrs.vertical))
+        out.vertical = attrs.vertical;
+    if (attrs.textRotation !== undefined) {
+        const rotation = Number(attrs.textRotation);
+        if (Number.isFinite(rotation) && rotation !== 0)
+            out.textRotation = rotation;
+    }
+    if (boolStrict(attrs.wrapText))
+        out.wrapText = true;
+    if (attrs.indent !== undefined) {
+        const indent = Number(attrs.indent);
+        if (Number.isInteger(indent) && indent !== 0)
+            out.indent = indent;
+    }
+    if (boolStrict(attrs.shrinkToFit))
+        out.shrinkToFit = true;
+    if (attrs.readingOrder !== undefined) {
+        const order = Number(attrs.readingOrder);
+        if (Number.isInteger(order) && order !== 0)
+            out.readingOrder = order;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+// Read a <protection> element into a Protection, keeping only facets that differ from the OOXML
+// default. `locked` defaults to TRUE, so only an explicit `locked="0"` carries information (an
+// unlocked cell) — a default or explicit-true cell must not read back as { locked: true }; `hidden`
+// defaults to false, so only `hidden="1"` is carried. An element with only defaults yields undefined.
+function parseProtection(attrs) {
+    const out = {};
+    if (attrs.locked === '0' || attrs.locked === 'false')
+        out.locked = false;
+    if (boolStrict(attrs.hidden))
+        out.hidden = true;
+    return Object.keys(out).length > 0 ? out : undefined;
+}

package/dist/io/xlsx/read-worksheet.d.ts

@@ -0,0 +1,4 @@
+import type { Worksheet } from '../../core/worksheet.ts';
+import type { XfStyle } from '../style/xf-style.ts';
+import type { SharedString } from './cell-value.ts';
+export declare function parseWorksheet(xml: string, sheet: Worksheet, sharedStrings: readonly SharedString[], xfStyles: ReadonlyArray<XfStyle>): void;