@ricsam/excel-to-formula-engine 0.0.0 → 0.1.1

package/dist/types/src/xlsx/package.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Reads the OPC (zip) container of an .xlsx file and exposes its parts as
+ * parsed XML.
+ */
+export type XmlNode = Record<string, unknown>;
+export interface XlsxPackage {
+    /** Raw part bytes keyed by zip path, e.g. `"xl/worksheets/sheet1.xml"`. */
+    readonly files: Map<string, Uint8Array>;
+    /** Parse a part as XML, or undefined when the part is absent. */
+    xml(path: string): XmlNode | undefined;
+    text(path: string): string | undefined;
+    has(path: string): boolean;
+    /** Every part path beginning with the given prefix. */
+    list(prefix: string): string[];
+}
+export declare function readXlsxPackage(source: Blob | ArrayBuffer | Uint8Array): Promise<XlsxPackage>;
+/**
+ * fast-xml-parser gives a single child as an object and repeated children as an
+ * array. Parts we do not force into arrays go through this.
+ */
+export declare function asArray<T>(value: T | T[] | undefined): T[];
+export declare function attr(node: unknown, name: string): string | undefined;
+export declare function numAttr(node: unknown, name: string): number | undefined;
+export declare function boolAttr(node: unknown, name: string, fallback?: boolean): boolean;
+/** Text content of an element parsed by fast-xml-parser. */
+export declare function textOf(node: unknown): string;

package/dist/types/src/xlsx/styles.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Parses xl/styles.xml into the subset of formatting the engine can express.
+ *
+ * Excel's style model is indirect: a cell carries an index into `cellXfs`, and
+ * each `xf` points at a font, fill, border and number format. This flattens
+ * that into one record per `xf`.
+ */
+import type { CellStyle } from "@ricsam/formula-engine";
+import { type XlsxPackage } from "./package";
+export interface ExcelFormat {
+    style: CellStyle;
+    /** Number format code, e.g. `"0.00%"` or `"yyyy-mm-dd"`. */
+    numberFormat?: string;
+    /** True when the number format renders a date or a time. */
+    isDateFormat: boolean;
+}
+export interface StyleTable {
+    formats: ExcelFormat[];
+    /** Differential formats, referenced by conditional formatting rules. */
+    differentialFormats: CellStyle[];
+}
+export declare function parseStyles(pkg: XlsxPackage): StyleTable;

package/dist/types/src/xlsx/workbook.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Parses the workbook-level parts: the sheet list, defined names, the shared
+ * string table, and table definitions.
+ */
+import { type XlsxPackage } from "./package";
+export interface SheetEntry {
+    name: string;
+    /** Zip path of the worksheet part. */
+    partPath: string;
+    /** `visible`, `hidden` or `veryHidden`. */
+    state: string;
+}
+export interface DefinedName {
+    name: string;
+    /** Formula text as stored, e.g. `"Sheet1!$A$1:$B$5"`. */
+    formula: string;
+    /**
+     * Index of the sheet this name is scoped to, or undefined for a
+     * workbook-scoped name.
+     */
+    localSheetId?: number;
+    hidden: boolean;
+}
+export interface RawTable {
+    name: string;
+    displayName: string;
+    /** Range in A1 notation, including the header and totals rows. */
+    ref: string;
+    headerRowCount: number;
+    totalsRowCount: number;
+    columnNames: string[];
+}
+/** Read the shared string table, flattening rich text to plain text. */
+export declare function parseSharedStrings(pkg: XlsxPackage): string[];
+export declare function parseWorkbook(pkg: XlsxPackage): {
+    sheets: SheetEntry[];
+    definedNames: DefinedName[];
+    /** True when the file uses the 1904 date system rather than 1900. */
+    date1904: boolean;
+};
+/** Table parts referenced by one worksheet. */
+export declare function parseTables(pkg: XlsxPackage, worksheetPartPath: string): RawTable[];

package/dist/types/src/xlsx/worksheet.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Parses one xl/worksheets/sheetN.xml part.
+ *
+ * Cell values in Excel are typed by the `t` attribute and stored in `<v>`, with
+ * formulas alongside in `<f>`. Shared formulas are stored once on the group's
+ * master cell and re-derived here for every other member.
+ */
+import { type XlsxPackage } from "./package";
+export type CellKind = "number" | "string" | "boolean" | "error" | "date" | "empty";
+export interface RawCell {
+    reference: string;
+    colIndex: number;
+    rowIndex: number;
+    kind: CellKind;
+    /** Literal value, before date conversion. */
+    value: string | number | boolean | undefined;
+    /** Excel formula text without the leading `=`, when the cell has one. */
+    formula?: string;
+    /**
+     * How far this cell sits from the master cell of its shared-formula group.
+     * The formula's relative references are shifted by this much at translation
+     * time. Absent or zero for an ordinary formula.
+     */
+    formulaOffset?: {
+        cols: number;
+        rows: number;
+    };
+    /** Index into the style table's `formats`. */
+    styleIndex?: number;
+}
+export interface RawConditionalFormat {
+    /** Ranges the rule applies to, as written in the file (`"A1:B10 D1:D5"`). */
+    ranges: string[];
+    type: string;
+    operator?: string;
+    /** Rule formulas, in the order Excel stores them. */
+    formulas: string[];
+    text?: string;
+    /** Index into the style table's `differentialFormats`. */
+    dxfId?: number;
+    priority: number;
+    /** Colour-scale stops, for `colorScale` rules. */
+    colorScale?: {
+        cfvo: {
+            type: string;
+            val?: string;
+        }[];
+        colors: (string | undefined)[];
+    };
+    /** Present for `top10` rules. */
+    rank?: number;
+    bottom?: boolean;
+    percent?: boolean;
+    stopIfTrue?: boolean;
+}
+export interface RawWorksheet {
+    cells: RawCell[];
+    merges: string[];
+    columnWidths: Record<number, number>;
+    rowHeights: Record<number, number>;
+    frozen?: {
+        rows: number;
+        cols: number;
+    };
+    conditionalFormats: RawConditionalFormat[];
+    /** Hyperlink targets keyed by A1 reference. */
+    hyperlinks: Record<string, string>;
+}
+export declare function parseWorksheet(pkg: XlsxPackage, partPath: string, sharedStrings: string[]): RawWorksheet;
+/** Flatten a rich-text run container into plain text. */
+export declare function readRichText(node: unknown): string;
+export declare function readRelationships(pkg: XlsxPackage, partPath: string): Map<string, string>;

package/package.json

@@ -1,10 +1,62 @@
 {
   "name": "@ricsam/excel-to-formula-engine",
-  "version": "0.0.0",
-  "description": "OIDC trusted publishing setup package for @ricsam/excel-to-formula-engine",
+  "version": "0.1.1",
+  "description": "Convert an Excel .xlsx file into FormulaEngine WorkbookData, in the browser",
+  "type": "module",
+  "module": "./dist/index.mjs",
+  "main": "./dist/index.cjs",
+  "types": "./dist/types/index.d.ts",
+  "scripts": {
+    "test": "bun run fixtures && bun test",
+    "agent:test": "CLAUDECODE=1 bun run fixtures && CLAUDECODE=1 bun test",
+    "typecheck": "tsc --noEmit",
+    "fixtures": "bun tests/fixtures/build-fixtures.ts",
+    "demo": "bun build demo/demo.ts --target=browser --outfile=demo/demo.js",
+    "demo:serve": "bun run demo && bun demo/serve.ts",
+    "build": "bun build.ts"
+  },
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+    "excel",
+    "xlsx",
+    "spreadsheet",
+    "formula-engine",
+    "browser"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ricsam/excel-to-formula-engine.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ricsam/excel-to-formula-engine/issues"
+  },
+  "homepage": "https://github.com/ricsam/excel-to-formula-engine#readme",
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "fast-xml-parser": "^5.11.1",
+    "fflate": "^0.8.3"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.2",
+    "@types/bun": "^1.4.2",
+    "exceljs": "^4.4.0",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "@ricsam/formula-engine": "0.3.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false
 }