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

package/README.md

@@ -1,45 +1,179 @@
-# @ricsam/excel-to-formula-engine
-
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@ricsam/excel-to-formula-engine`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+# excel-to-formula-engine
+
+Convert an Excel `.xlsx` file into [`@ricsam/formula-engine`](https://github.com/ricsam/formula-engine)
+`WorkbookData`, in the browser.
+
+```ts
+import { excelToFormulaEngine } from "@ricsam/excel-to-formula-engine";
+
+const data = await excelToFormulaEngine(blob);
+engine.addWorkbook({ workbookName: "Budget", data });
+```
+
+Pure TypeScript — no WASM, no native toolchain, no server round trip. An `.xlsx`
+is a ZIP of XML, so it unzips with [fflate](https://github.com/101arrowz/fflate)
+and parses with [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser).
+Ships as ESM and CJS with type declarations; ~48 kB per bundle, dependencies
+external.
+
+## Install
+
+```bash
+bun add @ricsam/excel-to-formula-engine @ricsam/formula-engine
+```
+
+## Usage
+
+`excelToFormulaEngine` accepts a `Blob` or `File` straight from a file input, or
+raw bytes as an `ArrayBuffer` / `Uint8Array`.
+
+```ts
+import { FormulaEngine } from "@ricsam/formula-engine";
+import { excelToFormulaEngine } from "@ricsam/excel-to-formula-engine";
+
+input.addEventListener("change", async () => {
+  const file = input.files?.[0];
+  if (!file) return;
+
+  const data = await excelToFormulaEngine(file);
+
+  const engine = FormulaEngine.buildEmpty();
+  engine.addWorkbook({ workbookName: file.name, data });
+
+  // Formulas are live — the engine recalculates them.
+  engine.getCellValue({
+    workbookName: file.name,
+    sheetName: "Data",
+    rowIndex: 4,
+    colIndex: 3,
+  });
+});
+```
+
+The whole workbook loads as a single undo step, so one `Ctrl-Z` reverts an
+import.
+
+### Diagnostics
+
+Anything that could not be translated is reported rather than silently dropped.
+`excelToFormulaEngineDetailed` returns the diagnostics beside the data; they are
+also stored in `data.workbookMetadata.diagnostics`.
+
+```ts
+const { data, diagnostics } = await excelToFormulaEngineDetailed(file);
+
+for (const diagnostic of diagnostics) {
+  console.warn(
+    `[${diagnostic.code}] ${diagnostic.sheetName}!${diagnostic.cellReference}`,
+    diagnostic.message
+  );
+}
+```
+
+### Options
+
+```ts
+await excelToFormulaEngine(file, {
+  sheets: ["Summary"],          // import only these sheets
+  styles: false,                // skip fills, fonts, borders
+  conditionalFormatting: false, // skip conditional formatting
+  tables: false,                // skip Excel tables
+  definedNames: false,          // skip defined names
+  cellMetadata: false,          // skip number formats and hyperlinks
+  convertDates: false,          // keep date serials as raw numbers
+});
+```
+
+## What gets translated
+
+| Excel | Engine | Notes |
+| --- | --- | --- |
+| Cell values | Cell content | Strings, numbers, booleans and error values keep their type. |
+| Formulas | Formulas | Kept as formulas, not as Excel's cached results — the engine recalculates. |
+| Shared formulas | Expanded formulas | Excel stores one formula per group; each member gets its references offset. |
+| Sheet order | Sheet order | Array order becomes tab order. |
+| Cross-sheet references | Unchanged | `Data!D5` parses identically. |
+| Excel tables | Tables | Structured references (`Sales[Amount]`) work. Tables without a header row are skipped. |
+| Defined names | Named expressions | Sheet-scoped names stay sheet-scoped. Built-ins like `_xlnm.Print_Area` are skipped. |
+| Fills, fonts, borders | `CellStyle` | Theme and indexed colours are resolved, including tints. |
+| Conditional formatting | Conditional styles | `cellIs`, `expression`, text rules and colour scales. See below. |
+| Dates | ISO strings | The engine has no date type, so `45306` becomes `"2024-01-15"`. |
+| Number formats, hyperlinks | Cell metadata | Stored for your UI; the engine does not interpret them. |
+| Merges, frozen panes, column widths, hidden sheets | Sheet metadata | Same — stored for your UI to apply. |
+
+### Formulas the engine cannot evaluate
+
+The engine implements around 40 functions. A formula using anything else — an
+Excel file will often reach for `VLOOKUP`, `TEXT`, `ROUND` or `SUMPRODUCT` — is
+**imported unchanged** and evaluates to `#NAME?`, with a warning diagnostic
+naming the function and the cell.
+
+This keeps the author's intent visible and editable in the cell, rather than
+replacing it with a frozen copy of whatever Excel last calculated. Everything
+needed to do the opposite is in the diagnostics if you prefer that trade.
+
+### Conditional formatting
+
+Excel's rule catalogue is much larger than the engine's, which has a formula
+rule and a two-stop gradient. These map across:
+
+- `cellIs` with every operator, including `between` / `notBetween`
+- `expression` (custom formula rules)
+- `containsText`, `notContainsText`, `beginsWith`, `endsWith`
+- `containsBlanks`, `notContainsBlanks`
+- `colorScale` → gradient (a three-colour scale loses its midpoint, with an
+  `info` diagnostic)
+
+Data bars, icon sets, `top10`, `aboveAverage` and duplicate rules are reported
+as `unsupported-conditional-format` and skipped.
+
+### Not imported
+
+Charts, images, shapes, pivot tables, macros, data validation, sparklines,
+comments, and cell protection. The engine has no representation for them.
+Password-protected and legacy `.xls` files are rejected with a clear error.
+
+## Demo
+
+```bash
+bun run demo:serve
+```
+
+Opens a page at <http://localhost:4321> where you can drop in a workbook and see
+it recalculated live. `demo/sample.xlsx` is there to try.
+
+## Development
+
+```bash
+bun install
+bun run fixtures   # generate .xlsx test fixtures with ExcelJS
+bun run test       # regenerates fixtures, then runs the suite
+bun run typecheck
+bun run build      # emit dist/ (ESM, CJS and .d.ts)
+```
+
+Fixtures are written by ExcelJS rather than hand-rolled XML, so the tests run
+against real OOXML — shared strings, shared formulas, style indirection, table
+parts and conditional formatting blocks as a spreadsheet application emits them.
+They are generated rather than committed, so `bun run test` builds them first.
+
+## Releasing
+
+Releases go out from `main` through [changesets](https://github.com/changesets/changesets)
+and npm [trusted publishing](https://docs.npmjs.com/trusted-publishers), so no
+npm token is stored in the repository — the publish job mints a short-lived
+OIDC token instead.
+
+```bash
+bunx changeset          # describe the change; pick patch / minor / major
+bunx changeset version  # fold pending changesets into package.json + CHANGELOG
+git commit -am "Release x.y.z"
+git push origin main    # .github/workflows/publish.yml builds, tests, publishes
+```
+
+`changeset publish` only publishes when the version in `package.json` is not
+already on npm, so pushing unrelated commits to `main` is safe.
+
+## License
+
+ISC