@node-projects/excelforge 2.4.0 → 3.1.0

package/README.md

@@ -1,8 +1,11 @@
 # ExcelForge 📊
 
-A **complete TypeScript library** for reading and writing Excel `.xlsx` files with **zero external dependencies**. Works in browsers, Node.js, Deno, Bun, and edge runtimes.
+[![npm version](https://badge.fury.io/js/%40node-projects%2Fexcelforge.svg)](https://badge.fury.io/js/%40node-projects%2Fexcelforge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Inspired by EPPlus (C#), ExcelForge gives you the full power of the OOXML spec — including real DEFLATE compression, round-trip editing of existing files, and rich property support.
+A **complete TypeScript library** for reading and writing Excel `.xlsx` and `.xlsm` (macro-enabled) files with **zero external dependencies**. Works in browsers, Node.js, Deno, Bun, and edge runtimes.
+
+ExcelForge gives you the full power of the OOXML spec — including real DEFLATE compression, round-trip editing of existing files, and rich property support.
 
 ---
 
@@ -13,22 +16,38 @@ Inspired by EPPlus (C#), ExcelForge gives you the full power of the OOXML spec
 | **Read existing files** | Load `.xlsx` from file, `Uint8Array`, `base64`, or `Blob` |
 | **Patch-only writes** | Re-serialise only changed sheets; preserve pivot tables, VBA, charts, unknown parts verbatim |
 | **Compression** | Full LZ77 + Huffman DEFLATE (levels 0–9). Typical XML compresses 80–85% |
-| **Cell Values** | Strings, numbers, booleans, dates, formulas, array formulas, rich text |
+| **Cell Values** | Strings, numbers, booleans, dates, formulas, array formulas, dynamic arrays, shared formulas, rich text |
 | **Styles** | Fonts, solid/pattern/gradient fills, all border styles, alignment, 30+ number format presets |
 | **Layout** | Merge cells, freeze/split panes, column widths, row heights, hide rows/cols, outline grouping |
-| **Charts** | Bar, column (stacked/100%), line, area, pie, doughnut, scatter, radar, bubble |
-| **Images** | PNG, JPEG, GIF — two-cell or one-cell anchors |
-| **Tables** | Styled Excel tables with totals row, filter buttons, column definitions |
-| **Conditional Formatting** | Cell rules, color scales, data bars, icon sets, top/bottom N, above/below average |
+| **Charts** | Bar, column (stacked/100%), line, area, pie, doughnut, scatter, radar, bubble; chart sheets; modern styling with 18 color palettes, gradients, data labels, shadows; chart templates |
+| **Images** | PNG, JPEG, GIF, BMP, SVG, WebP, ICO, EMF, WMF, TIFF — two-cell, one-cell, or absolute anchors |
+| **In-Cell Pictures** | Embed images directly inside cells via richData/metadata (Excel 365+) |
+| **Shapes** | 28 preset shapes (rect, ellipse, arrows, flowchart, etc.) with fill, line, text, rotation |
+| **WordArt** | Text effects with 20 preset transforms (arch, wave, inflate, etc.) |
+| **Tables** | Styled Excel tables with totals row, filter buttons, custom table styles, table slicers |
+| **Conditional Formatting** | Cell rules, color scales, data bars, icon sets (incl. custom), cross-worksheet refs |
 | **Data Validation** | Dropdowns, whole number, decimal, date, time, text length, custom formula |
 | **Sparklines** | Line, bar, stacked — with high/low/first/last/negative colors |
-| **Page Setup** | Paper size, orientation, margins, headers/footers (odd/even/first), print options |
+| **Pivot Tables** | Row/column/data fields, aggregation, calculated fields, grouping, custom styles, slicers |
+| **Page Setup** | Paper size, orientation, margins, headers/footers (odd/even/first), print options, page breaks |
 | **Protection** | Sheet protection with password, cell locking/hiding |
 | **Named Ranges** | Workbook and sheet-scoped |
-| **Auto Filter** | Dropdown filters on column headers |
+| **Connections** | OLEDB, ODBC, text/CSV, web — create, read, round-trip; query tables |
+| **Power Query** | Read M formulas from DataMashup; full round-trip preservation |
+| **External Links** | Cross-workbook references with sheet names and defined names |
+| **VBA Macros** | Create/read `.xlsm` with standard modules, class modules, document modules; code signing; full round-trip |
+| **Auto Filter** | Dropdown filters — value, date, custom, top-10, dynamic filters |
 | **Hyperlinks** | External URLs, mailto, internal navigation |
-| **Comments** | Cell comments with author |
+| **Form Controls** | Button, checkbox, combobox, listbox, radio, groupbox, label, scrollbar, spinner — with macro assignment |
+| **Dialog Sheets** | Excel 5 dialog sheets with dialog frame, OK/Cancel buttons, combo boxes |
+| **Comments** | Cell comments with author, rich text formatting |
+| **Themes** | Full Office theme XML with customizable colors and fonts |
 | **Multiple Sheets** | Any number, hidden/veryHidden, tab colors |
+| **Formula Engine** | 60+ functions including GETPIVOTDATA — tree-shakeable |
+| **Export** | CSV, JSON, HTML (with CF visualization, sparklines, charts, shapes, form controls), PDF (styled, paginated) |
+| **Encryption** | OOXML Agile Encryption with AES-256-CBC + SHA-512 via Web Crypto API |
+| **Digital Signatures** | Package signing (XML-DSig) + VBA code signing (PKCS#7/CMS, SHA-256) |
+| **Locale** | Configurable decimal/thousands separators, date format, currency symbol |
 | **Core Properties** | Title, author, subject, keywords, description, language, revision, category… |
 | **Extended Properties** | Company, manager, application, appVersion, hyperlinkBase, word/line/page counts… |
 | **Custom Properties** | Typed key-value store: string, int, decimal, bool, date, r8, i8 |
@@ -383,18 +402,354 @@ ws.addChart({
 
 Supported chart types: `bar`, `col`, `colStacked`, `col100`, `barStacked`, `bar100`, `line`, `lineStacked`, `area`, `pie`, `doughnut`, `scatter`, `radar`, `bubble`.
 
+**Modern chart styling (Excel 2019+):**
+
+```typescript
+ws.addChart({
+  type: 'column',
+  title: 'Styled Chart',
+  series: [{
+    name: 'Revenue', values: "'Sheet1'!$A$2:$D$2",
+    dataLabels: { showValue: true, position: 'outEnd' },
+    fillType: 'gradient',
+    gradientStops: [{ pos: 0, color: '4472C4' }, { pos: 100, color: 'B4C7E7' }],
+  }],
+  from: { col: 0, row: 5 }, to: { col: 8, row: 20 },
+  colorPalette: 'blue',    // 18 palettes: office, blue, orange, green, red, purple, teal...
+  shadow: true,
+  roundedCorners: true,
+  dataLabels: { showPercent: true },  // global data labels
+});
+```
+
+**Chart templates:**
+
+```typescript
+import { saveChartTemplate, applyChartTemplate, serializeChartTemplate, deserializeChartTemplate } from 'excelforge';
+
+// Save a chart's style as a template
+const template = saveChartTemplate(chart);
+const json = serializeChartTemplate(template);  // serialize to JSON string
+const restored = deserializeChartTemplate(json); // deserialize back
+
+// Apply template to a new chart
+const newChart = applyChartTemplate(template, {
+  series: [{ name: 'New', values: "'Sheet1'!$A$1:$A$5" }],
+  from: { col: 0, row: 0 }, to: { col: 5, row: 10 },
+});
+```
+
 ### Images
 
+Supported formats: `png`, `jpeg`, `gif`, `bmp`, `svg`, `webp`, `ico`, `emf`, `wmf`, `tiff`.
+
 ```typescript
 import { readFileSync } from 'fs';
 const imgData = readFileSync('./logo.png');
 
+// Floating image (two-cell anchor)
 ws.addImage({
   data:   imgData,          // Buffer, Uint8Array, or base64 string
   format: 'png',
   from:   { row: 1, col: 1 },
   to:     { row: 8, col: 4 },
 });
+
+// One-cell anchor with explicit pixel size
+ws.addImage({
+  data:   readFileSync('./icon.svg'),
+  format: 'svg',
+  from:   { row: 1, col: 6 },
+  width:  80,
+  height: 80,
+  altText: 'Company icon',
+});
+
+// Absolute positioning (not tied to any cell)
+ws.addImage({
+  data:   imgData,
+  format: 'png',
+  position: { x: 200, y: 100 },   // pixels from top-left of sheet
+  width:  120,
+  height: 80,
+});
+```
+
+### In-Cell Pictures
+
+Embed images directly inside cells (Excel 365+ feature). Uses richData/metadata internally.
+
+```typescript
+import type { CellImage } from '@node-projects/excelforge';
+
+ws.addCellImage({
+  data:    readFileSync('./photo.png'),
+  format:  'png',
+  cell:    'B2',          // cell reference
+  altText: 'Product photo',
+});
+```
+
+### Pivot tables
+
+```typescript
+const wb = new Workbook();
+
+// Source data sheet
+const wsData = wb.addSheet('Data');
+wsData.writeRow(1, 1, ['Region', 'Product', 'Sales', 'Units']);
+wsData.writeArray(2, 1, [
+  ['North', 'Widget', 12000, 150],
+  ['South', 'Widget', 9500,  120],
+  ['North', 'Gadget', 8700,  90],
+  ['South', 'Gadget', 11200, 140],
+]);
+
+// Pivot table on a separate sheet
+const wsPivot = wb.addSheet('Summary');
+wsPivot.addPivotTable({
+  name:        'SalesBreakdown',
+  sourceSheet: 'Data',
+  sourceRef:   'A1:D5',
+  targetCell:  'A1',
+  rowFields:   ['Region'],
+  colFields:   ['Product'],
+  dataFields:  [{ field: 'Sales', name: 'Sum of Sales', func: 'sum' }],
+  style:       'PivotStyleMedium9',
+  rowGrandTotals: true,
+  colGrandTotals: true,
+});
+
+await wb.writeFile('./pivot_report.xlsx');
+```
+
+Available aggregation functions: `sum`, `count`, `average`, `max`, `min`, `product`, `countNums`, `stdDev`, `stdDevp`, `var`, `varp`.
+
+### VBA macros
+
+ExcelForge can create, read, and round-trip `.xlsm` files with VBA macros. All module types are supported: standard modules, class modules, and document modules (auto-created for `ThisWorkbook` and each worksheet).
+
+```typescript
+import { Workbook, VbaProject } from './src/index.js';
+
+const wb = new Workbook();
+const ws = wb.addSheet('Sheet1');
+ws.setValue(1, 1, 'Hello');
+
+const vba = new VbaProject();
+
+// Standard module
+vba.addModule({
+  name: 'Module1',
+  type: 'standard',
+  code: 'Sub HelloWorld()\r\n    MsgBox "Hello from VBA!"\r\nEnd Sub\r\n',
+});
+
+// Class module
+vba.addModule({
+  name: 'MyClass',
+  type: 'class',
+  code: [
+    'Private pValue As String',
+    'Public Property Get Value() As String',
+    '    Value = pValue',
+    'End Property',
+    'Public Property Let Value(v As String)',
+    '    pValue = v',
+    'End Property',
+  ].join('\r\n') + '\r\n',
+});
+
+wb.vbaProject = vba;
+await wb.writeFile('./macros.xlsm');  // must use .xlsm extension
+```
+
+Reading VBA from existing files:
+
+```typescript
+const wb = await Workbook.fromFile('./macros.xlsm');
+if (wb.vbaProject) {
+  for (const mod of wb.vbaProject.modules) {
+    console.log(`${mod.name} (${mod.type}): ${mod.code.length} chars`);
+  }
+}
+
+// Modify and re-save — existing modules are preserved
+wb.vbaProject.addModule({ name: 'Module2', type: 'standard', code: '...' });
+wb.vbaProject.removeModule('OldModule');
+await wb.writeFile('./macros_updated.xlsm');
+```
+
+> **Note:** Document modules for `ThisWorkbook` and each worksheet are automatically created if not explicitly provided. VBA code uses `\r\n` line endings.
+
+### VBA UserForms
+
+ExcelForge supports creating VBA UserForm modules with form controls. UserForms are embedded in the VBA project with their designer data and can be viewed/edited in the VBA editor.
+
+```typescript
+import { Workbook, VbaProject } from 'excelforge';
+
+const wb = new Workbook();
+wb.addSheet('Sheet1').setValue(1, 1, 'UserForm Demo');
+
+const vba = new VbaProject();
+
+// Standard module to show the form
+vba.addModule({
+  name: 'Module1',
+  type: 'standard',
+  code: 'Sub ShowForm()\n  MyForm.Show\nEnd Sub',
+});
+
+// UserForm with controls
+vba.addModule({
+  name: 'MyForm',
+  type: 'userform',
+  controls: [
+    { type: 'Label', name: 'Label1', caption: 'Enter name:', left: 10, top: 10, width: 100, height: 18 },
+    { type: 'TextBox', name: 'TextBox1', caption: '', left: 10, top: 32, width: 160, height: 22 },
+    { type: 'CommandButton', name: 'btnOK', caption: 'OK', left: 50, top: 64, width: 72, height: 26 },
+  ],
+  code: [
+    'Private Sub btnOK_Click()',
+    '  MsgBox "Hello, " & TextBox1.Text',
+    '  Unload Me',
+    'End Sub',
+  ].join('\n'),
+});
+
+wb.vbaProject = vba;
+await wb.writeFile('./userform_demo.xlsm');
+```
+
+Supported control types: `CommandButton`, `TextBox`, `Label`, `CheckBox`, `OptionButton`, `ComboBox`, `ListBox`, `Frame`, `Image`, `ScrollBar`, `SpinButton`.
+
+### Workbook Calc Settings
+
+Control how Excel recalculates formulas when the workbook is opened.
+
+```typescript
+const wb = new Workbook();
+
+wb.calcSettings = {
+  calcMode: 'manual',       // 'auto' | 'manual' | 'autoNoTable'
+  iterate: true,             // enable iterative calculation
+  iterateCount: 200,         // max iterations
+  iterateDelta: 0.0001,      // convergence threshold
+  fullCalcOnLoad: false,     // don't force full recalc on open
+  calcOnSave: true,          // recalculate before saving
+  fullPrecision: true,       // use full 15-digit precision
+  concurrentCalc: false,     // disable multi-threaded calc
+};
+```
+
+Settings are preserved during round-trip editing. When reading an existing file, `wb.calcSettings` reflects the workbook's current calculation configuration.
+
+### OLE Objects
+
+Embed binary OLE objects (files, packages) into worksheets.
+
+```typescript
+const wb = new Workbook();
+const ws = wb.addSheet('Sheet1');
+
+ws.addOleObject({
+  name: 'EmbeddedFile',
+  progId: 'Package',           // OLE program ID
+  fileName: 'data.bin',        // display name
+  data: fileBytes,             // Uint8Array of the embedded content
+  from: { col: 1, row: 3 },   // top-left anchor
+  to: { col: 5, row: 10 },    // bottom-right anchor
+});
+
+await wb.writeFile('./with_ole.xlsx');
+```
+
+### Encryption
+
+Encrypt workbooks with a password using OOXML Agile Encryption (AES-256 + SHA-512).
+
+```typescript
+import { Workbook, encryptWorkbook, decryptWorkbook, isEncrypted } from 'excelforge';
+
+const wb = new Workbook();
+wb.addSheet('Secret').setValue(1, 1, 'Confidential');
+const xlsxData = await wb.build();
+
+// Encrypt
+const encrypted = await encryptWorkbook(xlsxData, 'myPassword');
+
+// Save encrypted file (still uses .xlsx extension)
+import { writeFileSync } from 'fs';
+writeFileSync('./protected.xlsx', encrypted);
+
+// Check if a file is encrypted
+console.log(isEncrypted(encrypted));  // true
+
+// Decrypt
+const decrypted = await decryptWorkbook(encrypted, 'myPassword');
+const wb2 = await Workbook.fromBytes(decrypted);
+```
+
+### PDF Export
+
+Export worksheets and workbooks as PDF documents with cell styling, pagination, and fit-to-width.
+
+```typescript
+import { Workbook, worksheetToPdf, workbookToPdf } from 'excelforge';
+
+const wb = new Workbook();
+const ws = wb.addSheet('Report');
+// ... populate cells with styles ...
+
+// Single worksheet PDF
+const pdf = worksheetToPdf(ws, {
+  paperSize: 'a4',
+  orientation: 'portrait',
+  fitToWidth: true,          // auto-scale to fit page width
+  gridLines: true,           // draw cell grid lines
+  headings: false,           // row/column headings
+  repeatRows: 1,             // repeat header row on each page
+  headerText: 'Sales Report',
+  footerText: 'Page &P of &N',
+  title: 'Sales Report',
+  author: 'ExcelForge',
+});
+
+import { writeFileSync } from 'fs';
+writeFileSync('./report.pdf', pdf);
+
+// Multi-sheet workbook PDF
+const wbPdf = workbookToPdf(wb, { footerText: 'Page &P / &N' });
+writeFileSync('./workbook.pdf', wbPdf);
+```
+
+### Digital Signatures
+
+Sign OOXML packages and VBA projects using RSA with SHA-256 via Web Crypto API.
+
+```typescript
+import { signPackage, signVbaProject, signWorkbook } from 'excelforge';
+
+// Sign the entire package
+const parts = new Map<string, Uint8Array>();
+parts.set('xl/workbook.xml', workbookBytes);
+parts.set('xl/worksheets/sheet1.xml', sheetBytes);
+
+const sigEntries = await signPackage(parts, {
+  certificate: pemCertificate,   // PEM-encoded X.509 certificate
+  privateKey: pemPrivateKey,     // PEM-encoded PKCS#8 private key
+});
+// sigEntries contains _xmlsignatures/sig1.xml, origin.sigs, and rels
+
+// Sign a VBA project
+const vbaSignature = await signVbaProject(vbaProjectBin, {
+  certificate: pemCertificate,
+  privateKey: pemPrivateKey,
+});
+
+// Or sign both at once
+const result = await signWorkbook(parts, { certificate, privateKey }, vbaProjectBin);
 ```
 
 ### Page setup
@@ -420,6 +775,244 @@ ws.headerFooter = {
 };
 ```
 
+### Page breaks
+
+```typescript
+// Add manual page breaks for printing
+ws.addRowBreak(20);    // page break after row 20
+ws.addRowBreak(40);    // page break after row 40
+ws.addColBreak(5);     // page break after column E
+
+// Read page breaks from an existing file
+const wb = await Workbook.fromBytes(data);
+const ws = wb.getSheet('Sheet1')!;
+for (const brk of ws.getRowBreaks()) {
+  console.log(`Row break at ${brk.id}, manual: ${brk.manual}`);
+}
+for (const brk of ws.getColBreaks()) {
+  console.log(`Col break at ${brk.id}, manual: ${brk.manual}`);
+}
+```
+
+Page breaks are fully preserved during round-trip editing, even when sheets are modified.
+
+### Named ranges
+
+```typescript
+// Define workbook-scoped named ranges
+wb.addNamedRange({ name: 'SalesData', ref: 'Data!$A$1:$A$5' });
+wb.addNamedRange({ name: 'Products', ref: 'Data!$B$1:$B$5', comment: 'Product list' });
+
+// Define sheet-scoped named range
+wb.addNamedRange({ name: 'LocalTotal', ref: 'Data!$A$6', scope: 'Data' });
+
+// Use in formulas
+ws.setFormula(1, 1, 'SUM(SalesData)');
+
+// Read named ranges from an existing file
+const wb2 = await Workbook.fromBytes(data);
+const ranges = wb2.getNamedRanges();         // all named ranges
+const sales = wb2.getNamedRange('SalesData'); // find by name
+console.log(sales?.ref);                      // "Data!$A$1:$A$5"
+
+// Remove a named range
+wb2.removeNamedRange('SalesData');
+```
+
+Named ranges (including scope and comments) are fully preserved during round-trip editing.
+
+### Connections & Power Query
+
+```typescript
+// Add a data connection (OLEDB, ODBC, text/CSV, web, etc.)
+wb.addConnection({
+  id: 1,
+  name: 'SalesDB',
+  type: 'oledb',  // 'odbc' | 'dao' | 'file' | 'web' | 'oledb' | 'text' | 'dsp'
+  connectionString: 'Provider=SQLOLEDB;Data Source=server;Initial Catalog=Sales;',
+  command: 'SELECT * FROM Orders',
+  commandType: 'sql',  // 'sql' | 'table' | 'default' | 'web' | 'oledb'
+  description: 'Sales database connection',
+  background: true,
+  saveData: true,
+});
+
+// Read connections from an existing file
+const wb2 = await Workbook.fromBytes(data);
+const conns = wb2.getConnections();           // all connections
+const sales = wb2.getConnection('SalesDB');   // find by name
+wb2.removeConnection('SalesDB');              // remove by name
+
+// Read Power Query M formulas (extracted from DataMashup)
+const queries = wb2.getPowerQueries();        // all queries
+const q = wb2.getPowerQuery('MyQuery');       // find by name
+console.log(q?.formula);                       // Power Query M code
+```
+
+Connections are fully preserved during round-trip editing. Power Query formulas (M code) stored in DataMashup binary blobs are automatically extracted for read access. Power Query/Power Pivot data models created in Excel are preserved verbatim during round-trip — you can safely open, modify cells, and save without losing any Power Query or Power Pivot features.
+
+### Form Controls
+
+```typescript
+// Add a button with a macro
+ws.addFormControl({
+  type: 'button',
+  from: { col: 1, row: 2 },
+  to:   { col: 3, row: 4 },
+  text: 'Run Report',
+  macro: 'Sheet1.RunReport',
+});
+
+// Button sized by width/height (no 'to' anchor needed)
+ws.addFormControl({
+  type: 'button',
+  from: { col: 1, row: 5 },
+  width: 120, height: 30,    // pixels
+  text: 'Compact Button',
+});
+
+// CheckBox linked to a cell
+ws.addFormControl({
+  type: 'checkBox',
+  from: { col: 1, row: 7 },
+  to:   { col: 3, row: 8 },
+  text: 'Enable Feature',
+  linkedCell: '$B$10',
+  checked: 'checked',   // 'checked' | 'unchecked' | 'mixed'
+});
+
+// ComboBox (dropdown) with input range
+ws.addFormControl({
+  type: 'comboBox',
+  from: { col: 1, row: 7 },
+  to:   { col: 3, row: 8 },
+  linkedCell: '$B$11',
+  inputRange: '$D$1:$D$5',
+  dropLines: 5,
+});
+
+// ListBox, OptionButton, GroupBox, Label, ScrollBar, Spinner
+ws.addFormControl({
+  type: 'scrollBar',
+  from: { col: 4, row: 6 },
+  to:   { col: 6, row: 7 },
+  linkedCell: '$B$14',
+  min: 0, max: 100, inc: 1, page: 10, val: 50,
+});
+
+// Read form controls from an existing file
+const wb2 = await Workbook.fromBytes(data);
+const controls = ws.getFormControls();
+for (const ctrl of controls) {
+  console.log(ctrl.type, ctrl.linkedCell, ctrl.macro);
+}
+```
+
+Supported control types: `button`, `checkBox`, `comboBox`, `listBox`, `optionButton`, `groupBox`, `label`, `scrollBar`, `spinner`. All control types support `macro` assignment and are fully preserved during round-trip editing.
+
+### Shapes
+
+```typescript
+ws.addShape({
+  type: 'roundRect',
+  from: { col: 1, row: 3 },
+  to:   { col: 5, row: 8 },
+  fillColor: '4472C4',
+  lineColor: '2F5496',
+  text: 'Process Step',
+  rotation: 0,
+});
+```
+
+Supported shape types: `rect`, `roundRect`, `ellipse`, `triangle`, `diamond`, `pentagon`, `hexagon`, `octagon`, `star5`, `star6`, `rightArrow`, `leftArrow`, `upArrow`, `downArrow`, `line`, `curvedConnector3`, `callout1`, `callout2`, `cloud`, `heart`, `lightningBolt`, `sun`, `moon`, `smileyFace`, `flowChartProcess`, `flowChartDecision`, `flowChartTerminator`, `flowChartDocument`.
+
+### WordArt
+
+```typescript
+ws.addWordArt({
+  text: 'SALE!',
+  preset: 'textArchUp',
+  font: { name: 'Impact', size: 48, bold: true },
+  fillColor: 'FF0000',
+  outlineColor: '990000',
+  from: { col: 1, row: 1 },
+  to:   { col: 8, row: 6 },
+});
+```
+
+Supported presets: `textPlain`, `textArchUp`, `textArchDown`, `textCircle`, `textWave1`, `textWave2`, `textInflate`, `textDeflate`, `textFadeUp`, `textFadeDown`, `textSlantUp`, `textSlantDown`, and more.
+
+### Themes
+
+```typescript
+wb.theme = {
+  name: 'Corporate Theme',
+  colors: [
+    { name: 'dk1', color: '000000' }, { name: 'lt1', color: 'FFFFFF' },
+    { name: 'dk2', color: '44546A' }, { name: 'lt2', color: 'E7E6E6' },
+    { name: 'accent1', color: '4472C4' }, { name: 'accent2', color: 'ED7D31' },
+    { name: 'accent3', color: 'A5A5A5' }, { name: 'accent4', color: 'FFC000' },
+    { name: 'accent5', color: '5B9BD5' }, { name: 'accent6', color: '70AD47' },
+    { name: 'hlink', color: '0563C1' }, { name: 'folHlink', color: '954F72' },
+  ],
+  majorFont: 'Calibri Light',
+  minorFont: 'Calibri',
+};
+```
+
+### Table Slicers
+
+```typescript
+ws.addTableSlicer({
+  name: 'RegionSlicer',
+  tableName: 'SalesTable',
+  columnName: 'Region',
+  caption: 'Filter by Region',
+  style: 'SlicerStyleLight1',
+});
+```
+
+### Pivot Slicers & Custom Pivot Styles
+
+```typescript
+wb.registerPivotStyle({
+  name: 'BrandedPivot',
+  elements: [
+    { type: 'headerRow', style: { font: { bold: true, color: 'FFFFFF' }, fill: { type: 'pattern', pattern: 'solid', fgColor: '4472C4' } } },
+  ],
+});
+
+wb.addPivotSlicer({
+  name: 'ProductSlicer',
+  pivotTableName: 'SalesPivot',
+  fieldName: 'Product',
+  caption: 'Product Filter',
+});
+```
+
+### External Links
+
+```typescript
+wb.addExternalLink({
+  target: 'file:///C:/Reports/Budget.xlsx',
+  sheets: [{ name: 'Sheet1' }, { name: 'Summary' }],
+});
+
+// Reference external data in formulas
+ws.setFormula(1, 1, '[1]Sheet1!A1');
+```
+
+### Locale Settings
+
+```typescript
+wb.locale = {
+  decimalSeparator: ',',
+  thousandsSeparator: '.',
+  dateFormat: 'DD.MM.YYYY',
+  currencySymbol: '€',
+};
+```
+
 ### Sheet protection
 
 ```typescript
@@ -498,8 +1091,17 @@ ExcelForge
 │   ├── StyleRegistry.ts    — interns fonts/fills/borders/xfs, emits styles.xml
 │   └── builders.ts         — fluent style() builder, Colors/NumFmt/Styles presets
 ├── features/
-│   ├── ChartBuilder.ts     — DrawingML chart XML for 15+ chart types
-│   └── TableBuilder.ts     — Excel table XML
+│   ├── ChartBuilder.ts     — DrawingML chart XML for 15+ chart types, templates, modern styling
+│   ├── TableBuilder.ts     — Excel table XML
+│   ├── PivotTableBuilder.ts — pivot table + cache XML
+│   ├── HtmlModule.ts       — HTML/CSS export with charts, images, sparklines, shapes
+│   ├── PdfModule.ts        — PDF export with cell styles, pagination, images
+│   ├── Encryption.ts       — OOXML Agile Encryption (AES-256-CBC + SHA-512)
+│   └── Signing.ts          — Digital signatures (XML-DSig + VBA PKCS#7/CMS)
+├── vba/
+│   ├── VbaProject.ts       — VBA project build/parse, module management
+│   ├── cfb.ts              — Compound Binary File (OLE2) reader & writer
+│   └── ovba.ts             — MS-OVBA compression/decompression
 └── utils/
     ├── zip.ts              — ZIP writer with full LZ77+Huffman DEFLATE
     ├── zipReader.ts        — ZIP reader (STORE + DEFLATE via DecompressionStream)
@@ -553,6 +1155,20 @@ document.getElementById('file').addEventListener('change', async (e) => {
 
 ## Changelog
 
+### v3.0 — More
+- **Form Controls** - create Form Controls
+- Wordart
+- Formula Objects
+- Chart Pages
+- Many more features....
+
+### v2.4 — Pivot Tables & VBA Macros
+
+- **Pivot tables** — create pivot tables with row/column/data fields, 11 aggregation functions, customisable styles
+- **VBA macros** — create, read, and round-trip `.xlsm` files with standard, class, and document modules
+- **CFB (OLE2) support** — MS-CFB reader/writer for vbaProject.bin, with MS-OVBA compression
+- **Automatic sheet modules** — document modules for ThisWorkbook and each worksheet are auto-generated
+
 ### v2.0 — Read, Modify, Compress
 
 - **Read existing XLSX files** — `Workbook.fromFile()`, `fromBytes()`, `fromBase64()`, `fromBlob()`