@shbernal/ts-xlsx 1.0.0

package/dist/customui/errors.d.ts

@@ -0,0 +1,15 @@
+import { XlsxError } from '../errors.ts';
+/**
+ * Thrown when a `customUI` ribbon-customisation part (`customUI/customUI.xml` or
+ * `customUI/customUI14.xml`) is present but cannot be parsed into a {@link CustomUiDocument} — malformed
+ * XML, a missing or unrecognised `<customUI>` root namespace, or nesting deep enough to look hostile.
+ * A workbook with no ribbon customisation never produces this: {@link Workbook.customUI} is an empty
+ * array instead.
+ *
+ * The parser treats the part as hostile input (a spreadsheet library parses untrusted files), so a
+ * malformed structure fails closed with this error rather than yielding a half-built tree.
+ */
+export declare class CustomUiParseError extends XlsxError {
+    readonly name = "CustomUiParseError";
+    readonly code = "malformed-input";
+}

package/dist/customui/errors.js

@@ -0,0 +1,15 @@
+import { XlsxError } from "../errors.js";
+/**
+ * Thrown when a `customUI` ribbon-customisation part (`customUI/customUI.xml` or
+ * `customUI/customUI14.xml`) is present but cannot be parsed into a {@link CustomUiDocument} — malformed
+ * XML, a missing or unrecognised `<customUI>` root namespace, or nesting deep enough to look hostile.
+ * A workbook with no ribbon customisation never produces this: {@link Workbook.customUI} is an empty
+ * array instead.
+ *
+ * The parser treats the part as hostile input (a spreadsheet library parses untrusted files), so a
+ * malformed structure fails closed with this error rather than yielding a half-built tree.
+ */
+export class CustomUiParseError extends XlsxError {
+    name = 'CustomUiParseError';
+    code = 'malformed-input';
+}

package/dist/customui/index.d.ts

@@ -0,0 +1,2 @@
+export { CustomUiParseError } from './errors.ts';
+export { CUSTOMUI_2006_NAMESPACE, CUSTOMUI_2007_REL_TYPE, CUSTOMUI_2009_NAMESPACE, CUSTOMUI_2010_REL_TYPE, type CustomUiDocument, isCustomUiRelType, parseCustomUi, type Ribbon, type RibbonControl, type RibbonControlKind, type RibbonDialect, type RibbonGroup, type RibbonTab, } from './ribbon.ts';

package/dist/customui/index.js

@@ -0,0 +1,7 @@
+// Native `customUI` ribbon read: project a typed, read-only view of the ribbon tree (tabs → groups →
+// controls + callback names) over the `customUI.xml` / `customUI14.xml` parts a macro workbook carries.
+// Those parts are preserved byte-for-byte on round-trip (see `src/core/preserved.ts`); this is a
+// projection over them, the same posture as the VBA read view (`src/vba`). Authoring/editing the ribbon
+// is out of scope — round-trip fidelity already comes from verbatim preservation.
+export { CustomUiParseError } from "./errors.js";
+export { CUSTOMUI_2006_NAMESPACE, CUSTOMUI_2007_REL_TYPE, CUSTOMUI_2009_NAMESPACE, CUSTOMUI_2010_REL_TYPE, isCustomUiRelType, parseCustomUi, } from "./ribbon.js";

package/dist/customui/ribbon.d.ts

@@ -0,0 +1,86 @@
+/** The `customUI` schema a part is written against — the read model keys off this, not the (frequently
+ * mis-copied) relationship type. `2007` is the original RibbonX (`customUI.xml`); `2010` is the later
+ * schema (`customUI14.xml`) that also carries backstage/QAT/commands. */
+export type RibbonDialect = '2007' | '2010';
+/** The `customUI` root namespaces, one per {@link RibbonDialect}. */
+export declare const CUSTOMUI_2006_NAMESPACE = "http://schemas.microsoft.com/office/2006/01/customui";
+export declare const CUSTOMUI_2009_NAMESPACE = "http://schemas.microsoft.com/office/2009/07/customui";
+export declare const CUSTOMUI_2007_REL_TYPE = "http://schemas.microsoft.com/office/2006/relationships/ui/extensibility";
+export declare const CUSTOMUI_2010_REL_TYPE = "http://schemas.microsoft.com/office/2007/relationships/ui/extensibility";
+/** Whether a package-root relationship Type URI points at a `customUI` ribbon part. */
+export declare function isCustomUiRelType(type: string): boolean;
+/**
+ * A control element inside a ribbon group. `kind` is the element's local name, narrowed to the closed
+ * set of RibbonX control elements ({@link RibbonControlKind}); an element outside that set is surfaced
+ * as `unknown` rather than dropped. The three identity attributes (`id` a document-defined control,
+ * `idQ` a qualified id, `idMso` a built-in control) and the two most-consulted display/behaviour
+ * attributes (`label`, `onAction`) are lifted out as typed conveniences; every attribute the element
+ * actually carried — including the many `get*` dynamic callbacks and layout hints not modelled here —
+ * is preserved verbatim in {@link attributes}, so nothing is lost. Container controls (a `menu`,
+ * `splitButton`, `gallery`, `dropDown`, `box`, …) carry their nested controls/items in {@link children}.
+ */
+export interface RibbonControl {
+    readonly kind: RibbonControlKind;
+    /** A document-defined control id. */
+    readonly id?: string;
+    /** A namespace-qualified control id (`idQ`), used to reference a control across add-ins. */
+    readonly idQ?: string;
+    /** The id of a built-in (Microsoft-defined) control this element repurposes or places against. */
+    readonly idMso?: string;
+    /** The static label, when the element carries one (a dynamic label uses `getLabel`, in {@link attributes}). */
+    readonly label?: string;
+    /** The callback procedure name invoked on activation — the macro a click runs. */
+    readonly onAction?: string;
+    /** Every attribute on the element, verbatim and entity-decoded. The typed fields above are lifted from
+     * here; this map is the complete record, including attributes this model does not lift out. */
+    readonly attributes: Readonly<Record<string, string>>;
+    /** Nested controls or items, for a container control; absent for a leaf control. */
+    readonly children?: readonly RibbonControl[];
+}
+/** The RibbonX control elements this reader recognises. `item` is a `dropDown`/`gallery`/`comboBox`
+ * entry; `unknown` is the fallback for any element outside this set (never silently dropped). */
+export type RibbonControlKind = 'button' | 'toggleButton' | 'checkBox' | 'editBox' | 'dropDown' | 'comboBox' | 'gallery' | 'menu' | 'dynamicMenu' | 'splitButton' | 'buttonGroup' | 'box' | 'labelControl' | 'separator' | 'menuSeparator' | 'dialogBoxLauncher' | 'control' | 'item' | 'unknown';
+/** A `<group>` within a ribbon tab: its identity/label attributes and the controls it contains. */
+export interface RibbonGroup {
+    readonly id?: string;
+    readonly idQ?: string;
+    readonly idMso?: string;
+    readonly label?: string;
+    /** Every attribute on the `<group>`, verbatim. */
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly controls: readonly RibbonControl[];
+}
+/** A `<tab>` within the ribbon: its identity/label attributes and the groups it contains. */
+export interface RibbonTab {
+    readonly id?: string;
+    readonly idQ?: string;
+    readonly idMso?: string;
+    readonly label?: string;
+    /** Every attribute on the `<tab>`, verbatim. */
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly groups: readonly RibbonGroup[];
+}
+/** The parsed `<ribbon>` element: whether it starts from a blank ribbon, and its custom tabs. Only the
+ * `<tabs>` subtree is modelled; `qat` and `contextualTabs` are not parsed in v1. */
+export interface Ribbon {
+    /** `startFromScratch="true"` reduces the built-in ribbon to a minimal set before custom tabs apply. */
+    readonly startFromScratch: boolean;
+    readonly tabs: readonly RibbonTab[];
+}
+/**
+ * A parsed `customUI` part. `dialect` records which schema it was written against (derived from the
+ * root namespace, the authoritative signal). `ribbon` is the parsed `<ribbon>` subtree, or `undefined`
+ * when the document customises only backstage/QAT/commands (which v1 does not parse). Future work can
+ * extend this with `backstage`/`qat` without changing the shape callers already depend on.
+ */
+export interface CustomUiDocument {
+    readonly dialect: RibbonDialect;
+    readonly ribbon?: Ribbon;
+}
+/**
+ * Parse a `customUI` part (raw UTF-8 bytes or its decoded text) into a {@link CustomUiDocument}.
+ *
+ * @throws {@link CustomUiParseError} if the XML is malformed, the root is not a `<customUI>` element in
+ *   a recognised namespace, or the tree nests beyond {@link MAX_DEPTH}.
+ */
+export declare function parseCustomUi(input: string | Uint8Array): CustomUiDocument;

package/dist/customui/ribbon.js

@@ -0,0 +1,180 @@
+// Turn a `customUI` ribbon-customisation part into a typed, read-only view of the ribbon tree.
+//
+// A `.xlsm` can carry two ribbon parts hung off the *package root* rels: `customUI/customUI.xml`
+// (Office 2007 RibbonX, namespace `.../2006/01/customui`) and `customUI/customUI14.xml` (Office 2010+,
+// namespace `.../2009/07/customui`, which adds backstage/QAT/commands). Both are preserved verbatim on
+// round-trip (see `src/core/preserved.ts`); this module adds a reader on top, mirroring how
+// `parseVbaProject` projects a read view over bytes the writer already round-trips opaquely.
+//
+// Scope (v1): the `<ribbon>` subtree only — tabs → groups → controls, plus each control's callback
+// names (the `onAction` a click invokes is the whole reason a macro workbook ships a ribbon). A
+// customUI document's `<commands>`, `<backstage>`, `<contextMenus>`, and the ribbon's `qat`/
+// `contextualTabs` are NOT parsed; they still round-trip byte-for-byte, they are just not surfaced here.
+//
+// Security posture: the part is untrusted input. The underlying `xmlEvents` scanner never expands
+// entities or DTDs (see `xml-read.ts`); on top of that this parser caps nesting depth and fails closed
+// with {@link CustomUiParseError} on any malformed or unrecognised structure rather than returning a
+// half-built tree.
+import { strFromU8 } from 'fflate';
+import { boolStrict, localName, xmlEvents } from "../xml/xml-read.js";
+import { CustomUiParseError } from "./errors.js";
+/** The `customUI` root namespaces, one per {@link RibbonDialect}. */
+export const CUSTOMUI_2006_NAMESPACE = 'http://schemas.microsoft.com/office/2006/01/customui';
+export const CUSTOMUI_2009_NAMESPACE = 'http://schemas.microsoft.com/office/2009/07/customui';
+// The OPC relationship Type URIs Office wires the two ribbon parts under, from the package-root rels.
+// Both end `/ui/extensibility` (the 2010 one confusingly carries `2007` in its path); the reader
+// matches on that suffix — {@link isCustomUiRelType} — exactly as the rest of the reader matches
+// preserved relationship types by local suffix.
+export const CUSTOMUI_2007_REL_TYPE = 'http://schemas.microsoft.com/office/2006/relationships/ui/extensibility';
+export const CUSTOMUI_2010_REL_TYPE = 'http://schemas.microsoft.com/office/2007/relationships/ui/extensibility';
+/** Whether a package-root relationship Type URI points at a `customUI` ribbon part. */
+export function isCustomUiRelType(type) {
+    return type.endsWith('/ui/extensibility');
+}
+// A hostile part could nest elements thousands deep; the recursive control mapper would then overflow
+// the call stack with an uncatchable RangeError. Capping tree depth keeps every failure a
+// CustomUiParseError. Real ribbons nest only a handful deep (tab > group > menu > submenu), so this
+// bound is unreachable by any legitimate document.
+const MAX_DEPTH = 256;
+const KNOWN_KINDS = new Set([
+    'button',
+    'toggleButton',
+    'checkBox',
+    'editBox',
+    'dropDown',
+    'comboBox',
+    'gallery',
+    'menu',
+    'dynamicMenu',
+    'splitButton',
+    'buttonGroup',
+    'box',
+    'labelControl',
+    'separator',
+    'menuSeparator',
+    'dialogBoxLauncher',
+    'control',
+    'item',
+]);
+/**
+ * Parse a `customUI` part (raw UTF-8 bytes or its decoded text) into a {@link CustomUiDocument}.
+ *
+ * @throws {@link CustomUiParseError} if the XML is malformed, the root is not a `<customUI>` element in
+ *   a recognised namespace, or the tree nests beyond {@link MAX_DEPTH}.
+ */
+export function parseCustomUi(input) {
+    const xml = typeof input === 'string' ? input : strFromU8(input);
+    let root;
+    try {
+        root = buildTree(xml);
+    }
+    catch (error) {
+        if (error instanceof CustomUiParseError)
+            throw error;
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CustomUiParseError(`malformed customUI XML: ${detail}`, { cause: error });
+    }
+    const customUi = findChild(root, 'customUI');
+    if (customUi === undefined) {
+        throw new CustomUiParseError('part has no <customUI> root element');
+    }
+    const dialect = dialectOf(customUi);
+    const ribbonEl = findChild(customUi, 'ribbon');
+    return ribbonEl === undefined ? { dialect } : { dialect, ribbon: toRibbon(ribbonEl) };
+}
+// Resolve the namespace bound to the customUI element's own name and map it to a dialect. A default
+// namespace (`xmlns=`) governs an unprefixed `<customUI>`; a prefixed `<p:customUI>` is governed by
+// that prefix's `xmlns:p`. Neither of the two known namespaces present means this is not a customUI part
+// this reader understands — fail closed rather than guess.
+function dialectOf(customUi) {
+    const colon = customUi.name.indexOf(':');
+    const nsAttr = colon === -1 ? 'xmlns' : `xmlns:${customUi.name.slice(0, colon)}`;
+    const ns = customUi.attrs[nsAttr];
+    if (ns === CUSTOMUI_2006_NAMESPACE)
+        return '2007';
+    if (ns === CUSTOMUI_2009_NAMESPACE)
+        return '2010';
+    throw new CustomUiParseError(`unrecognised customUI namespace: ${ns ?? '(none)'}`);
+}
+function toRibbon(ribbonEl) {
+    const tabsEl = findChild(ribbonEl, 'tabs');
+    const tabs = tabsEl === undefined ? [] : childrenNamed(tabsEl, 'tab').map(toTab);
+    return { startFromScratch: boolStrict(ribbonEl.attrs.startFromScratch), tabs };
+}
+function toTab(tabEl) {
+    return {
+        ...identity(tabEl.attrs),
+        attributes: tabEl.attrs,
+        groups: childrenNamed(tabEl, 'group').map(toGroup),
+    };
+}
+function toGroup(groupEl) {
+    return {
+        ...identity(groupEl.attrs),
+        attributes: groupEl.attrs,
+        controls: groupEl.children.map((child) => toControl(child)),
+    };
+}
+function toControl(el) {
+    const kind = KNOWN_KINDS.has(el.local)
+        ? el.local
+        : 'unknown';
+    return {
+        kind,
+        ...identity(el.attrs),
+        ...(el.attrs.onAction !== undefined ? { onAction: el.attrs.onAction } : {}),
+        attributes: el.attrs,
+        ...(el.children.length > 0 ? { children: el.children.map((child) => toControl(child)) } : {}),
+    };
+}
+// The id/label attributes lifted onto every tab, group, and control. Emitted only when present, so an
+// absent attribute stays absent (exactOptionalPropertyTypes) rather than becoming an explicit undefined.
+function identity(attrs) {
+    return {
+        ...(attrs.id !== undefined ? { id: attrs.id } : {}),
+        ...(attrs.idQ !== undefined ? { idQ: attrs.idQ } : {}),
+        ...(attrs.idMso !== undefined ? { idMso: attrs.idMso } : {}),
+        ...(attrs.label !== undefined ? { label: attrs.label } : {}),
+    };
+}
+// Build the element tree from the SAX event stream with an explicit stack (no recursion), capping depth
+// so a hostile part cannot force the later recursive walk to overflow. Text and comments carry no ribbon
+// meaning and are ignored. Throws CustomUiParseError on unbalanced markup; a lower-level SyntaxError from
+// the scanner is caught and re-wrapped by the caller.
+function buildTree(xml) {
+    const root = { name: '#root', local: '#root', attrs: {}, children: [] };
+    const stack = [root];
+    for (const event of xmlEvents(xml)) {
+        if (event.kind === 'open') {
+            const parent = stack[stack.length - 1];
+            if (parent === undefined)
+                throw new CustomUiParseError('unbalanced customUI markup');
+            const el = {
+                name: event.name,
+                local: localName(event.name),
+                attrs: event.attrs,
+                children: [],
+            };
+            parent.children.push(el);
+            if (!event.selfClosing) {
+                if (stack.length > MAX_DEPTH)
+                    throw new CustomUiParseError('customUI nesting too deep');
+                stack.push(el);
+            }
+        }
+        else if (event.kind === 'close') {
+            if (stack.length <= 1)
+                throw new CustomUiParseError('unbalanced customUI markup');
+            stack.pop();
+        }
+    }
+    if (stack.length !== 1)
+        throw new CustomUiParseError('unbalanced customUI markup');
+    return root;
+}
+function findChild(el, local) {
+    return el.children.find((child) => child.local === local);
+}
+function childrenNamed(el, local) {
+    return el.children.filter((child) => child.local === local);
+}

package/dist/entries/core.d.ts

@@ -0,0 +1,23 @@
+export { type CellAddress, columnToNumber, decodeAddress, decodeRange, encodeAddress, MAX_COLUMN, MAX_ROW, numberToColumn, type RangeAddress, } from '../core/address.ts';
+export type { AutoFilter, CustomFilter, CustomFilterOperator, CustomFilterPredicate, FilterColumn, FilterCriteria, ValuesFilter, } from '../core/autofilter.ts';
+export { Cell } from '../core/cell.ts';
+export { applyTint, type ColorResolutionContext, DEFAULT_INDEXED_COLORS, resolveColor, SYSTEM_INDEXED_COLORS, } from '../core/color-resolution.ts';
+export { Column } from '../core/column.ts';
+export type { Comment, CommentThread, Mention, Person } from '../core/comment-thread.ts';
+export type { CfValueObject, ConditionalFormatting, ConditionalFormattingRule, } from '../core/conditional-formatting.ts';
+export type { DataValidation, DataValidationEntry, DataValidationErrorStyle, DataValidationOperator, DataValidationType, } from '../core/data-validation.ts';
+export { type AnchoredImage, type AnchorPoint, type Extent, type ImageAnchor, type ImageEditAs, isOneCellAnchor, type OneCellAnchor, PX_TO_EMU, type TwoCellAnchor, type WorkbookImage, } from '../core/image.ts';
+export type { HeaderFooter, PageBreak, PageMargins, PageSetup, PrintOptions, } from '../core/page-setup.ts';
+export { type ParsedPivotField, type ParsedPivotSource, type ParsedPivotTable, type PivotCacheField, type PivotItem, type PivotMetric, type PivotNumericSummary, type PivotRecordCell, type PivotSourceKind, PivotTable, type PivotTableOptions, } from '../core/pivot-table.ts';
+export type { PreservedPart, PreservedRelationship, PreservedRootReference, PreservedWorksheetReference, } from '../core/preserved.ts';
+export type { SheetProtection, SheetProtectionCredential, SheetProtectionFlags, SheetProtectionOptions, } from '../core/protection.ts';
+export { Range } from '../core/range.ts';
+export { Row } from '../core/row.ts';
+export type { Alignment, Border, BorderEdge, BorderStyle, CellStyle, Color, DifferentialStyle, Fill, FillPatternType, Font, FontScheme, FontVerticalAlignment, GradientFill, GradientStop, HorizontalAlignment, NamedCellStyle, PatternFill, Protection, TableStyleNamespace, TableStyleTable, UnderlineStyle, VerticalAlignment, } from '../core/style.ts';
+export { Table, type TableColumn, type TableColumnStyle, type TableOptions, type TableRegion, type TableStyleInfo, } from '../core/table.ts';
+export { isTableStyleElementType, STRIPE_ELEMENT_TYPES, TABLE_STYLE_ELEMENT_TYPES, type TableStyle, type TableStyleElement, type TableStyleElementType, } from '../core/table-style.ts';
+export { DEFAULT_THEME_COLOR_SCHEME, DEFAULT_THEME_FONTS, parseThemeColorScheme, THEME_COLOR_SLOTS, type ThemeColorScheme, type ThemeColorSlot, type ThemeFontScheme, type ThemeOverrides, } from '../core/theme.ts';
+export { type CellValue, coerceCellValue, type DataTableFormulaValue, detectValueType, ERROR_CODES, type ErrorCode, type ErrorValue, type FormulaResult, type FormulaValue, type HyperlinkValue, isErrorCode, type RichTextRun, type RichTextValue, richTextToPlain, type SharedFormulaValue, ValueType, } from '../core/value.ts';
+export { type AddImageOptions, type AddWorksheetOptions, DEFAULT_WORKBOOK_VIEW, type DefinedName, type PreservedWorkbookReference, Workbook, type WorkbookProperties, type WorkbookView, } from '../core/workbook.ts';
+export type { WorkbookProtection, WorkbookProtectionCredentialAttr, } from '../core/workbook-protection.ts';
+export { type CellModel, type ColumnProperties, type OutlineProperties, type RowInput, type RowProperties, type SheetView, Worksheet, type WorksheetModel, type WorksheetProperties, type WorksheetState, } from '../core/worksheet.ts';

package/dist/entries/core.js

@@ -0,0 +1,20 @@
+// Entry barrel for `@shbernal/ts-xlsx/core` — the document model, with no serialisation attached.
+//
+// This is what a consumer imports to build or inspect a workbook in memory: the classes, the
+// property shapes, and the value vocabulary. It pulls in no ZIP, no XML writer and no BIFF12
+// decoder. Errors are not here — the whole failure taxonomy lives behind `/errors`, so that a
+// caller who only needs to branch on a failure never loads a codec to get the class.
+export { columnToNumber, decodeAddress, decodeRange, encodeAddress, MAX_COLUMN, MAX_ROW, numberToColumn, } from "../core/address.js";
+export { Cell } from "../core/cell.js";
+export { applyTint, DEFAULT_INDEXED_COLORS, resolveColor, SYSTEM_INDEXED_COLORS, } from "../core/color-resolution.js";
+export { Column } from "../core/column.js";
+export { isOneCellAnchor, PX_TO_EMU, } from "../core/image.js";
+export { PivotTable, } from "../core/pivot-table.js";
+export { Range } from "../core/range.js";
+export { Row } from "../core/row.js";
+export { Table, } from "../core/table.js";
+export { isTableStyleElementType, STRIPE_ELEMENT_TYPES, TABLE_STYLE_ELEMENT_TYPES, } from "../core/table-style.js";
+export { DEFAULT_THEME_COLOR_SCHEME, DEFAULT_THEME_FONTS, parseThemeColorScheme, THEME_COLOR_SLOTS, } from "../core/theme.js";
+export { coerceCellValue, detectValueType, ERROR_CODES, isErrorCode, richTextToPlain, ValueType, } from "../core/value.js";
+export { DEFAULT_WORKBOOK_VIEW, Workbook, } from "../core/workbook.js";
+export { Worksheet, } from "../core/worksheet.js";

package/dist/entries/csv.d.ts

@@ -0,0 +1,2 @@
+export { type CsvReadOptions, readCsv } from '../io/csv/read.ts';
+export { type CsvWriteOptions, writeCsv, writeCsvText } from '../io/csv/write.ts';

package/dist/entries/csv.js

@@ -0,0 +1,6 @@
+// Entry barrel for `@shbernal/ts-xlsx/csv` — delimited text in and out.
+//
+// The two directions are asymmetric in what they cost: writing needs only a worksheet and the
+// value vocabulary, while reading builds a `Workbook` and therefore pulls the model in whole.
+export { readCsv } from "../io/csv/read.js";
+export { writeCsv, writeCsvText } from "../io/csv/write.js";

package/dist/entries/customui.d.ts

@@ -0,0 +1 @@
+export { CUSTOMUI_2006_NAMESPACE, CUSTOMUI_2007_REL_TYPE, CUSTOMUI_2009_NAMESPACE, CUSTOMUI_2010_REL_TYPE, type CustomUiDocument, isCustomUiRelType, parseCustomUi, type Ribbon, type RibbonControl, type RibbonControlKind, type RibbonDialect, type RibbonGroup, type RibbonTab, } from '../customui/ribbon.ts';

package/dist/entries/customui.js

@@ -0,0 +1,3 @@
+// Entry barrel for `@shbernal/ts-xlsx/customui` — the read-only ribbon view over a macro
+// workbook's preserved `customUI` parts.
+export { CUSTOMUI_2006_NAMESPACE, CUSTOMUI_2007_REL_TYPE, CUSTOMUI_2009_NAMESPACE, CUSTOMUI_2010_REL_TYPE, isCustomUiRelType, parseCustomUi, } from "../customui/ribbon.js";

package/dist/entries/errors.d.ts

@@ -0,0 +1,7 @@
+export { CustomUiParseError } from '../customui/errors.ts';
+export { AuthoringError, InternalError, XlsxError, type XlsxErrorCode } from '../errors.ts';
+export { PackageReadError, type UnsupportedFormat, UnsupportedFormatError, } from '../io/opc/errors.ts';
+export { XlsbParseError } from '../io/xlsb/errors.ts';
+export { XlsxParseError } from '../io/xlsx/errors.ts';
+export { VbaAuthorError, VbaParseError } from '../vba/errors.ts';
+export { XmlParseError } from '../xml/errors.ts';

package/dist/entries/errors.js

@@ -0,0 +1,20 @@
+// Entry barrel for `@shbernal/ts-xlsx/errors` — the whole failure taxonomy, and nothing else.
+//
+// Every error class the library throws is exported here and from no other entry. That rule is
+// what keeps the entry barrels disjoint (a container-level failure belongs to no single codec:
+// `readXlsx` and `readXlsb` both raise `UnsupportedFormatError`), and it makes the answer to
+// "what can this throw at me?" one import rather than a hunt across codecs.
+//
+// It is also the cheapest thing in the package by an order of magnitude: the classes reach
+// nothing but each other, so a service that only needs to classify a failure — log it, map it to
+// an HTTP status, decide whether to retry — pays for the taxonomy and not for a parser.
+//
+// `XlsxError` is the one-line answer to "was that us?"; `XlsxErrorCode` is the kind of failure,
+// shared across classes on purpose (see `src/errors.ts`).
+export { CustomUiParseError } from "../customui/errors.js";
+export { AuthoringError, InternalError, XlsxError } from "../errors.js";
+export { PackageReadError, UnsupportedFormatError, } from "../io/opc/errors.js";
+export { XlsbParseError } from "../io/xlsb/errors.js";
+export { XlsxParseError } from "../io/xlsx/errors.js";
+export { VbaAuthorError, VbaParseError } from "../vba/errors.js";
+export { XmlParseError } from "../xml/errors.js";

package/dist/entries/vba.d.ts

@@ -0,0 +1,2 @@
+export { parseVbaProject, type VbaModule, type VbaModuleKind, type VbaProject, type VbaProjectSignature, type VbaProjectSignatureKind, } from '../vba/project.ts';
+export { addVbaReference, removeVbaModule, type VbaLibraryReference, } from '../vba/project-editor.ts';

package/dist/entries/vba.js

@@ -0,0 +1,7 @@
+// Entry barrel for `@shbernal/ts-xlsx/vba` — the native VBA read view and the structural edits.
+//
+// A deliberately narrower face than `src/vba/index.ts`, which is the *internal* barrel and also
+// carries the CFB writer, the MS-OVBA container primitives and the part-path constants that
+// `Workbook` and the codecs need. Those are implementation, not API.
+export { parseVbaProject, } from "../vba/project.js";
+export { addVbaReference, removeVbaModule, } from "../vba/project-editor.js";

package/dist/entries/xlsb.d.ts

@@ -0,0 +1 @@
+export { readXlsb } from '../io/xlsb/read.ts';

package/dist/entries/xlsb.js

@@ -0,0 +1,7 @@
+// Entry barrel for `@shbernal/ts-xlsx/xlsb` — the BIFF12 reader.
+//
+// `readXlsx` auto-detects and reads a binary `.xlsb` too, so most callers never name this; it is
+// public for the caller that holds bytes it already knows to be `.xlsb` and wants to say so. That
+// dispatch also means this entry is not the way to *avoid* the BIFF12 codec — importing
+// `/xlsx` loads it either way (see the per-entry budgets in `scripts/size-budget.ts`).
+export { readXlsb } from "../io/xlsb/read.js";

package/dist/entries/xlsx.d.ts

@@ -0,0 +1,5 @@
+export { editXlsxVbaAddReference, editXlsxVbaRemoveModule } from '../io/xlsx/edit-vba.ts';
+export { type ReadXlsxOptions, readXlsx } from '../io/xlsx/read.ts';
+export { type ReadSheetRowsOptions, readSheetRows, readWorkbookStream, } from '../io/xlsx/read-rows.ts';
+export { type WriteOptions, writeXlsx, writeXlsxAsync } from '../io/xlsx/write.ts';
+export { type CalcProperties, StreamedRow, WorkbookStreamWriter, type WorkbookStreamWriterOptions, WorksheetStreamWriter, } from '../io/xlsx/write-stream.ts';

package/dist/entries/xlsx.js

@@ -0,0 +1,18 @@
+// Entry barrel for `@shbernal/ts-xlsx/xlsx` — the XML codec: whole-workbook read and write, the
+// streaming pair, and the in-place VBA part edits.
+//
+// The streaming reader's entry points are public; the granular per-row/cell/sheet output shapes
+// (`StreamedRow`/`StreamedCell`/`StreamedSheet` as *read*) are intentionally left as inferred
+// structural types rather than named commitments while that surface settles. The streaming
+// *writer*'s whole surface is named: its incremental workbook/worksheet/row handles are classes
+// and their options are interfaces, so there is nothing structural left un-named. A styled row
+// hands back `Cell`, which belongs to `/core`.
+//
+// Streaming is not its own entry point. Measured, `read-rows` + `write-stream` reach every module
+// `read` + `write` do plus three — an entry that costs what the codec costs is an alias, not a
+// packaging boundary.
+export { editXlsxVbaAddReference, editXlsxVbaRemoveModule } from "../io/xlsx/edit-vba.js";
+export { readXlsx } from "../io/xlsx/read.js";
+export { readSheetRows, readWorkbookStream, } from "../io/xlsx/read-rows.js";
+export { writeXlsx, writeXlsxAsync } from "../io/xlsx/write.js";
+export { StreamedRow, WorkbookStreamWriter, WorksheetStreamWriter, } from "../io/xlsx/write-stream.js";

package/dist/errors.d.ts

@@ -0,0 +1,65 @@
+/**
+ * What kind of failure an {@link XlsxError} reports. This is the branch most callers want, and it is
+ * deliberately coarse: the four answers are the four different things a caller would *do* next.
+ *
+ * - `'unsupported-format'` — the input is not a container this library reads at all (a legacy `.xls`,
+ *   a blob that is not a spreadsheet). Nothing is wrong with the file; it is the wrong file *for us*.
+ * - `'malformed-input'` — a part we do read is corrupt or does not conform to its specification. The
+ *   file is broken, or hostile.
+ * - `'authoring'` — the caller described a document that cannot exist. The bug is in the calling code.
+ * - `'internal'` — an invariant this library maintains did not hold. It should be unreachable; if it
+ *   fires, the bug is ours.
+ *
+ * There is deliberately no "not implemented yet" code. Every candidate for one turned out to be an
+ * unreachable exhaustiveness guard (so: `'internal'`), and the one genuine feature gap — a binary
+ * `.xlsb` cannot be row-streamed — is already reported by {@link UnsupportedFormatError}'s `format`
+ * branch. A code with no throw site would be a promise the library does not keep.
+ */
+export type XlsxErrorCode = 'unsupported-format' | 'malformed-input' | 'authoring' | 'internal';
+/**
+ * The common ancestor of every error this library raises deliberately. `catch (e) { if (e instanceof
+ * XlsxError) … }` is the one-line answer to "was that us?", and {@link code} then says which kind of
+ * failure it was without naming a single subclass.
+ *
+ * Abstract on purpose: a failure always has a kind, so there is never a reason to throw the base.
+ * Every subclass fixes {@link code} to a literal, which makes the class hierarchy a discriminated
+ * union — narrowing on `error.code` narrows the type.
+ *
+ * The constructor is inherited from `Error`, so every subclass accepts `{cause}`; layers that wrap a
+ * lower-level failure are expected to pass it rather than flatten it into the message.
+ */
+export declare abstract class XlsxError extends Error {
+    abstract readonly code: XlsxErrorCode;
+}
+/**
+ * Thrown when the caller describes a document that cannot exist: a pivot table with no row field, a
+ * table whose columns do not span its range, a merge that overlaps another, a workbook with no
+ * worksheets. The document model, not a single argument, is what is wrong.
+ *
+ * **Where the line falls against native errors.** A single scalar that is out of range, unparseable,
+ * or the wrong type stays a native `RangeError` / `SyntaxError` / `TypeError` — those types exist for
+ * exactly that, every caller already reads them, and wrapping them would make this taxonomy a
+ * re-implementation of the language's. `AuthoringError` starts where a *composite* is internally
+ * inconsistent, or contradicts something a workbook can express. `getColumn(0)` is a `RangeError`;
+ * a table that names a column twice is an `AuthoringError`.
+ *
+ * It is always the calling code that is wrong, never the input file — a malformed file raises a
+ * `'malformed-input'` error instead.
+ */
+export declare class AuthoringError extends XlsxError {
+    readonly name = "AuthoringError";
+    readonly code = "authoring";
+}
+/**
+ * Thrown where an invariant the library itself maintains turns out not to hold — typically an index
+ * that a preceding pass proved to be in range, re-checked because `noUncheckedIndexedAccess` makes
+ * the possibility of `undefined` explicit and casting it away would be worse.
+ *
+ * No caller can provoke one, so it is not a failure mode to handle: seeing it means the bug is ours.
+ * It exists as a distinct type so that "unreachable" is *stated* rather than implied by a bare
+ * `Error`, which reads identically to a throw nobody has classified yet.
+ */
+export declare class InternalError extends XlsxError {
+    readonly name = "InternalError";
+    readonly code = "internal";
+}

package/dist/errors.js

@@ -0,0 +1,66 @@
+// The failure taxonomy every layer throws through.
+//
+// Typed error classes grew up one per subsystem that happened to want one, sharing no ancestor, so a
+// caller could not ask "did *this library* fail?" without naming all of them — while the model's own
+// validation threw bare `Error`, distinguishable only by string-matching the message. For a library
+// whose input is untrusted files, "was it my file or my call?" is a first-class question, and it had
+// no answer.
+//
+// Two levels of branch, deliberately non-redundant:
+//   - `code` says what *kind* of failure this is — the question a caller usually has.
+//   - `name` (and `instanceof`) says exactly which one — the question a caller occasionally has.
+// A code shared by several classes is the design, not an oversight: a `code` in 1:1 correspondence
+// with the classes would carry nothing the class did not already carry.
+//
+// Scalar argument validation stays *outside* this taxonomy — see {@link AuthoringError} for where the
+// line falls and why.
+//
+// This module sits below every layer that throws (`src/xml`, `src/core`, `src/io`, `src/vba`,
+// `src/customui` all import it), so it imports nothing itself; `scripts/check-layering.ts` enforces
+// that.
+/**
+ * The common ancestor of every error this library raises deliberately. `catch (e) { if (e instanceof
+ * XlsxError) … }` is the one-line answer to "was that us?", and {@link code} then says which kind of
+ * failure it was without naming a single subclass.
+ *
+ * Abstract on purpose: a failure always has a kind, so there is never a reason to throw the base.
+ * Every subclass fixes {@link code} to a literal, which makes the class hierarchy a discriminated
+ * union — narrowing on `error.code` narrows the type.
+ *
+ * The constructor is inherited from `Error`, so every subclass accepts `{cause}`; layers that wrap a
+ * lower-level failure are expected to pass it rather than flatten it into the message.
+ */
+export class XlsxError extends Error {
+}
+/**
+ * Thrown when the caller describes a document that cannot exist: a pivot table with no row field, a
+ * table whose columns do not span its range, a merge that overlaps another, a workbook with no
+ * worksheets. The document model, not a single argument, is what is wrong.
+ *
+ * **Where the line falls against native errors.** A single scalar that is out of range, unparseable,
+ * or the wrong type stays a native `RangeError` / `SyntaxError` / `TypeError` — those types exist for
+ * exactly that, every caller already reads them, and wrapping them would make this taxonomy a
+ * re-implementation of the language's. `AuthoringError` starts where a *composite* is internally
+ * inconsistent, or contradicts something a workbook can express. `getColumn(0)` is a `RangeError`;
+ * a table that names a column twice is an `AuthoringError`.
+ *
+ * It is always the calling code that is wrong, never the input file — a malformed file raises a
+ * `'malformed-input'` error instead.
+ */
+export class AuthoringError extends XlsxError {
+    name = 'AuthoringError';
+    code = 'authoring';
+}
+/**
+ * Thrown where an invariant the library itself maintains turns out not to hold — typically an index
+ * that a preceding pass proved to be in range, re-checked because `noUncheckedIndexedAccess` makes
+ * the possibility of `undefined` explicit and casting it away would be worse.
+ *
+ * No caller can provoke one, so it is not a failure mode to handle: seeing it means the bug is ours.
+ * It exists as a distinct type so that "unreachable" is *stated* rather than implied by a bare
+ * `Error`, which reads identically to a throw nobody has classified yet.
+ */
+export class InternalError extends XlsxError {
+    name = 'InternalError';
+    code = 'internal';
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './entries/core.ts';
+export * from './entries/csv.ts';
+export * from './entries/customui.ts';
+export * from './entries/errors.ts';
+export * from './entries/vba.ts';
+export * from './entries/xlsb.ts';
+export * from './entries/xlsx.ts';

package/dist/index.js

@@ -0,0 +1,19 @@
+// The convenience entry point: everything the package exports, under one specifier.
+//
+// It is a union of the subpath entry barrels in `src/entries/`, which are the real public faces —
+// `@shbernal/ts-xlsx/core`, `/xlsx`, `/xlsb`, `/csv`, `/vba`, `/customui`, `/errors`. Each symbol
+// is listed in exactly one of them, so there is no second list to keep in step here and a star
+// re-export cannot silently drop a name to an ambiguity. `scripts/check-layering.ts` holds the
+// entries disjoint and keeps this file's composition honest.
+//
+// Importing from here is the right default; it costs nothing extra to a bundler, because
+// `sideEffects: false` lets an unused module be dropped whole. Reach for a subpath when the
+// consumer has no bundler to do that for it, or when you want the module graph itself to say
+// which half of the library a service depends on.
+export * from "./entries/core.js";
+export * from "./entries/csv.js";
+export * from "./entries/customui.js";
+export * from "./entries/errors.js";
+export * from "./entries/vba.js";
+export * from "./entries/xlsb.js";
+export * from "./entries/xlsx.js";