docxmlater 0.31.0 → 1.0.0

package/README.md

@@ -1,51 +1,29 @@
 # docXMLater - Professional DOCX Framework
 
 [![npm version](https://img.shields.io/npm/v/docxmlater.svg)](https://www.npmjs.com/package/docxmlater)
-[![Tests](https://img.shields.io/badge/tests-635%20passing-brightgreen)](https://github.com/ItMeDiaTech/docXMLater)
+[![Tests](https://img.shields.io/badge/tests-1098%20passing-brightgreen)](https://github.com/ItMeDiaTech/docXMLater)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 A comprehensive, production-ready TypeScript/JavaScript library for creating, reading, and manipulating Microsoft Word (.docx) documents programmatically. Full OpenXML compliance with extensive API coverage and **100% test pass rate**.
 
-I do a lot of professional documentation work. From the solutions that exist out there for working with .docx files and therefore .xml files, they are not amazing. Most of the frameworks that exist that do give you everything you want... charge thousands a year. I decided to make my own framework to interact with these filetypes and focus on ease of usability. All functionality works with helper functions to interact with all aspects of a .docx / xml document.
+Built for professional documentation work, docXMLater provides a complete solution for programmatic DOCX manipulation with an intuitive API and helper functions for all aspects of document creation and modification.
 
-## ✨ Latest Updates - v0.31.0
+## Latest Updates - v1.0.0
 
-**ComplexField Support & Critical Bug Fixes!** Major enhancement release:
+**Production Release!** All major features complete:
 
-### New Features
-- **ComplexField Support:** Full implementation of begin/separate/end field structure per ECMA-376
-- **TOC Field Generator:** `createTOCField()` with all switches (\o, \h, \z, \u, \n, \t)
-- **Advanced Fields:** Foundation for cross-references, indexes, and dynamic content
-- **Style Color Fix:** Fixed critical bug where hex colors were corrupted during load/save
+### What's New in v1.0.0
 
-### What's New
-- `ComplexField` class for TOC, cross-references, and advanced field types
-- `createTOCField()` function with customizable options (levels, hyperlinks, styles)
-- Fixed style color parsing (colors no longer corrupted to size values)
-- New `XMLParser.extractSelfClosingTag()` for accurate XML parsing
-- 41 new comprehensive tests (StylesRoundTrip + ComplexField)
+- **Complete Feature Set:** All 102 major features implemented
+- **Table Styles:** Full support with 12 conditional formatting types
+- **Content Controls:** 9 control types (rich text, plain text, combo box, dropdown, date picker, checkbox, picture, building block, group)
+- **Field Types:** 11 field types (PAGE, NUMPAGES, DATE, TIME, FILENAME, AUTHOR, TITLE, REF, HYPERLINK, SEQ, TC/XE)
+- **Drawing Elements:** Shapes and textboxes with full positioning
+- **Document Properties:** Core, extended, and custom properties
+- **Production Ready:** Full ECMA-376 compliance, zero regressions
 
-### Field Support
-```typescript
-import { createTOCField, ComplexField } from 'docxmlater';
-
-// Create TOC with custom options
-const toc = createTOCField({
-  levels: '1-3',
-  hyperlinks: true,
-  omitPageNumbers: false
-});
-
-// Create custom complex field
-const field = new ComplexField({
-  instruction: ' PAGE \\* MERGEFORMAT ',
-  result: '1',
-  resultFormatting: { bold: true }
-});
-```
-
-**Test Results:** 635/635 tests passing (100% - up from 596)
+**Test Results:** 1,098/1,098 tests passing (100% - exceeding v1.0 goal by 29%)
 
 ## Quick Start
 
@@ -80,27 +58,27 @@ await doc.save("output.docx");
 
 ### Content Creation
 
-| Method                           | Description            | Example                          |
-| -------------------------------- | ---------------------- | -------------------------------- |
-| `createParagraph(text?)`         | Add paragraph          | `doc.createParagraph('Text')`    |
-| `createTable(rows, cols)`        | Add table              | `doc.createTable(3, 4)`          |
-| `addParagraph(para)`             | Add existing paragraph | `doc.addParagraph(myPara)`       |
-| `addTable(table)`                | Add existing table     | `doc.addTable(myTable)`          |
-| `addImage(image)`                | Add image              | `doc.addImage(myImage)`          |
-| `addTableOfContents(toc?)`       | Add TOC                | `doc.addTableOfContents()`       |
-| `insertParagraphAt(index, para)` | Insert at position     | `doc.insertParagraphAt(0, para)` |
+| Method                           | Description              | Example                          |
+| -------------------------------- | ------------------------ | -------------------------------- |
+| `createParagraph(text?)`         | Add paragraph            | `doc.createParagraph('Text')`    |
+| `createTable(rows, cols)`        | Add table                | `doc.createTable(3, 4)`          |
+| `addParagraph(para)`             | Add existing paragraph   | `doc.addParagraph(myPara)`       |
+| `addTable(table)`                | Add existing table       | `doc.addTable(myTable)`          |
+| `addImage(image)`                | Add image                | `doc.addImage(myImage)`          |
+| `addTableOfContents(toc?)`       | Add TOC                  | `doc.addTableOfContents()`       |
+| `insertParagraphAt(index, para)` | Insert at position       | `doc.insertParagraphAt(0, para)` |
 | `insertTableAt(index, table)`    | Insert table at position | `doc.insertTableAt(5, table)`    |
-| `insertTocAt(index, toc)`        | Insert TOC at position | `doc.insertTocAt(0, toc)`        |
+| `insertTocAt(index, toc)`        | Insert TOC at position   | `doc.insertTocAt(0, toc)`        |
 
 ### Content Manipulation
 
-| Method                                | Description                 | Returns   |
-| ------------------------------------- | --------------------------- | --------- |
-| `replaceParagraphAt(index, para)`     | Replace paragraph           | `boolean` |
-| `replaceTableAt(index, table)`        | Replace table               | `boolean` |
-| `moveElement(fromIndex, toIndex)`     | Move element to new position | `boolean` |
-| `swapElements(index1, index2)`        | Swap two elements           | `boolean` |
-| `removeTocAt(index)`                  | Remove TOC element          | `boolean` |
+| Method                            | Description                  | Returns   |
+| --------------------------------- | ---------------------------- | --------- |
+| `replaceParagraphAt(index, para)` | Replace paragraph            | `boolean` |
+| `replaceTableAt(index, table)`    | Replace table                | `boolean` |
+| `moveElement(fromIndex, toIndex)` | Move element to new position | `boolean` |
+| `swapElements(index1, index2)`    | Swap two elements            | `boolean` |
+| `removeTocAt(index)`              | Remove TOC element           | `boolean` |
 
 ### Content Retrieval
 
@@ -133,20 +111,21 @@ await doc.save("output.docx");
 
 ### Style Application
 
-| Method                                 | Description                     | Returns        |
-| -------------------------------------- | ------------------------------- | -------------- |
-| `applyStyleToAll(styleId, predicate)`  | Apply style to matching elements | `number`       |
-| `findElementsByStyle(styleId)`         | Find all elements using a style | `Array<Para\|Cell>` |
+| Method                                | Description                      | Returns             |
+| ------------------------------------- | -------------------------------- | ------------------- |
+| `applyStyleToAll(styleId, predicate)` | Apply style to matching elements | `number`            |
+| `findElementsByStyle(styleId)`        | Find all elements using a style  | `Array<Para\|Cell>` |
 
 **Example:**
+
 ```typescript
 // Apply Heading1 to all paragraphs containing "Chapter"
-const count = doc.applyStyleToAll('Heading1', (el) => {
-  return el instanceof Paragraph && el.getText().includes('Chapter');
+const count = doc.applyStyleToAll("Heading1", (el) => {
+  return el instanceof Paragraph && el.getText().includes("Chapter");
 });
 
 // Find all Heading1 elements
-const headings = doc.findElementsByStyle('Heading1');
+const headings = doc.findElementsByStyle("Heading1");
 ```
 
 ### Document Statistics
@@ -192,7 +171,10 @@ const para2 = Paragraph.create("Hello World");
 const para3 = Paragraph.create("Centered text", { alignment: "center" });
 
 // Create with just formatting
-const para4 = Paragraph.create({ alignment: "right", spacing: { before: 240 } });
+const para4 = Paragraph.create({
+  alignment: "right",
+  spacing: { before: 240 },
+});
 
 // Create with style
 const heading = Paragraph.createWithStyle("Chapter 1", "Heading1");
@@ -211,13 +193,13 @@ doc.addParagraph(heading);
 
 #### Paragraph Factory Methods
 
-| Method                                                | Description                    | Example                                 |
-| ----------------------------------------------------- | ------------------------------ | --------------------------------------- |
-| `Paragraph.create(text?, formatting?)`                | Create detached paragraph      | `Paragraph.create('Text')`              |
-| `Paragraph.create(formatting?)`                       | Create with formatting only    | `Paragraph.create({alignment: 'left'})` |
-| `Paragraph.createWithStyle(text, styleId)`            | Create with style              | `Paragraph.createWithStyle('', 'H1')`   |
-| `Paragraph.createEmpty()`                             | Create empty paragraph         | `Paragraph.createEmpty()`               |
-| `Paragraph.createFormatted(text, run?, paragraph?)`   | Create with dual formatting    | See example above                       |
+| Method                                              | Description                 | Example                                 |
+| --------------------------------------------------- | --------------------------- | --------------------------------------- |
+| `Paragraph.create(text?, formatting?)`              | Create detached paragraph   | `Paragraph.create('Text')`              |
+| `Paragraph.create(formatting?)`                     | Create with formatting only | `Paragraph.create({alignment: 'left'})` |
+| `Paragraph.createWithStyle(text, styleId)`          | Create with style           | `Paragraph.createWithStyle('', 'H1')`   |
+| `Paragraph.createEmpty()`                           | Create empty paragraph      | `Paragraph.createEmpty()`               |
+| `Paragraph.createFormatted(text, run?, paragraph?)` | Create with dual formatting | See example above                       |
 
 #### Paragraph Formatting Methods
 
@@ -237,54 +219,56 @@ doc.addParagraph(heading);
 
 #### Paragraph Manipulation Methods
 
-| Method                               | Description                 | Returns      |
-| ------------------------------------ | --------------------------- | ------------ |
-| `insertRunAt(index, run)`            | Insert run at position      | `this`       |
-| `removeRunAt(index)`                 | Remove run at position      | `boolean`    |
-| `replaceRunAt(index, run)`           | Replace run at position     | `boolean`    |
-| `findText(text, options?)`           | Find text in runs           | `number[]`   |
-| `replaceText(find, replace, options?)` | Replace text in runs       | `number`     |
-| `mergeWith(otherPara)`               | Merge another paragraph     | `this`       |
-| `clone()`                            | Clone paragraph             | `Paragraph`  |
+| Method                                 | Description             | Returns     |
+| -------------------------------------- | ----------------------- | ----------- |
+| `insertRunAt(index, run)`              | Insert run at position  | `this`      |
+| `removeRunAt(index)`                   | Remove run at position  | `boolean`   |
+| `replaceRunAt(index, run)`             | Replace run at position | `boolean`   |
+| `findText(text, options?)`             | Find text in runs       | `number[]`  |
+| `replaceText(find, replace, options?)` | Replace text in runs    | `number`    |
+| `mergeWith(otherPara)`                 | Merge another paragraph | `this`      |
+| `clone()`                              | Clone paragraph         | `Paragraph` |
 
 **Example:**
+
 ```typescript
-const para = doc.createParagraph('Hello World');
+const para = doc.createParagraph("Hello World");
 
 // Find and replace
-const indices = para.findText('World');  // [1]
-const count = para.replaceText('World', 'Universe', { caseSensitive: true });
+const indices = para.findText("World"); // [1]
+const count = para.replaceText("World", "Universe", { caseSensitive: true });
 
 // Manipulate runs
-para.insertRunAt(0, new Run('Start: ', { bold: true }));
-para.replaceRunAt(1, new Run('HELLO', { allCaps: true }));
+para.insertRunAt(0, new Run("Start: ", { bold: true }));
+para.replaceRunAt(1, new Run("HELLO", { allCaps: true }));
 
 // Merge paragraphs
-const para2 = Paragraph.create(' More text');
-para.mergeWith(para2);  // Combines runs
+const para2 = Paragraph.create(" More text");
+para.mergeWith(para2); // Combines runs
 ```
 
 ### Run (Text Span) Operations
 
-| Method                        | Description                  | Returns  |
-| ----------------------------- | ---------------------------- | -------- |
-| `clone()`                     | Clone run with formatting    | `Run`    |
-| `insertText(index, text)`     | Insert text at position      | `this`   |
-| `appendText(text)`            | Append text to end           | `this`   |
-| `replaceText(start, end, text)` | Replace text range          | `this`   |
+| Method                          | Description               | Returns |
+| ------------------------------- | ------------------------- | ------- |
+| `clone()`                       | Clone run with formatting | `Run`   |
+| `insertText(index, text)`       | Insert text at position   | `this`  |
+| `appendText(text)`              | Append text to end        | `this`  |
+| `replaceText(start, end, text)` | Replace text range        | `this`  |
 
 **Example:**
+
 ```typescript
-const run = new Run('Hello World', { bold: true });
+const run = new Run("Hello World", { bold: true });
 
 // Text manipulation
-run.insertText(6, 'Beautiful ');  // "Hello Beautiful World"
-run.appendText('!');               // "Hello Beautiful World!"
-run.replaceText(0, 5, 'Hi');      // "Hi Beautiful World!"
+run.insertText(6, "Beautiful "); // "Hello Beautiful World"
+run.appendText("!"); // "Hello Beautiful World!"
+run.replaceText(0, 5, "Hi"); // "Hi Beautiful World!"
 
 // Clone for reuse
 const copy = run.clone();
-copy.setColor('FF0000');  // Original unchanged
+copy.setColor("FF0000"); // Original unchanged
 ```
 
 ### Table Operations
@@ -304,19 +288,20 @@ copy.setColor('FF0000');  // Original unchanged
 
 #### Advanced Table Operations
 
-| Method                                      | Description                   | Returns       |
-| ------------------------------------------- | ----------------------------- | ------------- |
-| `mergeCells(startRow, startCol, endRow, endCol)` | Merge cells                   | `this`        |
-| `splitCell(row, col)`                       | Remove cell spanning          | `this`        |
-| `moveCell(fromRow, fromCol, toRow, toCol)`  | Move cell contents            | `this`        |
-| `swapCells(row1, col1, row2, col2)`         | Swap two cells                | `this`        |
-| `setColumnWidth(index, width)`              | Set specific column width     | `this`        |
-| `setColumnWidths(widths)`                   | Set all column widths         | `this`        |
-| `insertRows(startIndex, count)`             | Insert multiple rows          | `TableRow[]`  |
-| `removeRows(startIndex, count)`             | Remove multiple rows          | `boolean`     |
-| `clone()`                                   | Clone entire table            | `Table`       |
+| Method                                           | Description               | Returns      |
+| ------------------------------------------------ | ------------------------- | ------------ |
+| `mergeCells(startRow, startCol, endRow, endCol)` | Merge cells               | `this`       |
+| `splitCell(row, col)`                            | Remove cell spanning      | `this`       |
+| `moveCell(fromRow, fromCol, toRow, toCol)`       | Move cell contents        | `this`       |
+| `swapCells(row1, col1, row2, col2)`              | Swap two cells            | `this`       |
+| `setColumnWidth(index, width)`                   | Set specific column width | `this`       |
+| `setColumnWidths(widths)`                        | Set all column widths     | `this`       |
+| `insertRows(startIndex, count)`                  | Insert multiple rows      | `TableRow[]` |
+| `removeRows(startIndex, count)`                  | Remove multiple rows      | `boolean`    |
+| `clone()`                                        | Clone entire table        | `Table`      |
 
 **Example:**
+
 ```typescript
 const table = doc.createTable(3, 3);
 
@@ -330,12 +315,12 @@ table.moveCell(1, 1, 2, 2);
 table.swapCells(0, 0, 2, 2);
 
 // Batch row operations
-table.insertRows(1, 3);  // Insert 3 rows at position 1
-table.removeRows(4, 2);  // Remove 2 rows starting at position 4
+table.insertRows(1, 3); // Insert 3 rows at position 1
+table.removeRows(4, 2); // Remove 2 rows starting at position 4
 
 // Set column widths
-table.setColumnWidth(0, 2000);  // First column = 2000 twips
-table.setColumnWidths([2000, 3000, 2000]);  // All columns
+table.setColumnWidth(0, 2000); // First column = 2000 twips
+table.setColumnWidths([2000, 3000, 2000]); // All columns
 
 // Clone table for reuse
 const tableCopy = table.clone();
@@ -366,27 +351,28 @@ const tableCopy = table.clone();
 
 #### Style Manipulation
 
-| Method                  | Description                      | Returns   |
-| ----------------------- | -------------------------------- | --------- |
-| `style.clone()`         | Clone style                      | `Style`   |
-| `style.mergeWith(other)` | Merge properties from another style | `this`    |
+| Method                   | Description                         | Returns |
+| ------------------------ | ----------------------------------- | ------- |
+| `style.clone()`          | Clone style                         | `Style` |
+| `style.mergeWith(other)` | Merge properties from another style | `this`  |
 
 **Example:**
+
 ```typescript
 // Clone a style
-const heading1 = doc.getStyle('Heading1');
+const heading1 = doc.getStyle("Heading1");
 const customHeading = heading1.clone();
-customHeading.setRunFormatting({ color: 'FF0000' });
+customHeading.setRunFormatting({ color: "FF0000" });
 
 // Merge styles
 const baseStyle = Style.createNormalStyle();
 const overrideStyle = Style.create({
-  styleId: 'Override',
-  name: 'Override',
-  type: 'paragraph',
-  runFormatting: { bold: true, color: 'FF0000' }
+  styleId: "Override",
+  name: "Override",
+  type: "paragraph",
+  runFormatting: { bold: true, color: "FF0000" },
 });
-baseStyle.mergeWith(overrideStyle);  // baseStyle now has bold red text
+baseStyle.mergeWith(overrideStyle); // baseStyle now has bold red text
 ```
 
 #### Built-in Styles
@@ -409,90 +395,94 @@ baseStyle.mergeWith(overrideStyle);  // baseStyle now has bold red text
 
 #### Basic TOC Creation
 
-| Method                           | Description                  | Example                                    |
-| -------------------------------- | ---------------------------- | ------------------------------------------ |
-| `addTableOfContents(toc?)`       | Add TOC to document          | `doc.addTableOfContents()`                 |
-| `insertTocAt(index, toc)`        | Insert TOC at position       | `doc.insertTocAt(0, toc)`                  |
-| `removeTocAt(index)`             | Remove TOC at position       | `doc.removeTocAt(0)`                       |
+| Method                     | Description            | Example                    |
+| -------------------------- | ---------------------- | -------------------------- |
+| `addTableOfContents(toc?)` | Add TOC to document    | `doc.addTableOfContents()` |
+| `insertTocAt(index, toc)`  | Insert TOC at position | `doc.insertTocAt(0, toc)`  |
+| `removeTocAt(index)`       | Remove TOC at position | `doc.removeTocAt(0)`       |
 
 #### TOC Factory Methods
 
-| Method                                      | Description                      | Example                                         |
-| ------------------------------------------- | -------------------------------- | ----------------------------------------------- |
-| `TableOfContents.createStandard(title?)`    | Standard TOC (3 levels)          | `TableOfContents.createStandard()`              |
-| `TableOfContents.createSimple(title?)`      | Simple TOC (2 levels)            | `TableOfContents.createSimple()`                |
-| `TableOfContents.createDetailed(title?)`    | Detailed TOC (4 levels)          | `TableOfContents.createDetailed()`              |
-| `TableOfContents.createHyperlinked(title?)` | Hyperlinked TOC                  | `TableOfContents.createHyperlinked()`           |
-| `TableOfContents.createWithStyles(styles, opts?)` | TOC with specific styles   | `TableOfContents.createWithStyles(['H1','H3'])` |
-| `TableOfContents.createFlat(title?, styles?)` | Flat TOC (no indent)           | `TableOfContents.createFlat()`                  |
-| `TableOfContents.createNumbered(title?, format?)` | Numbered TOC               | `TableOfContents.createNumbered('TOC', 'roman')` |
-| `TableOfContents.createWithSpacing(spacing, opts?)` | TOC with custom spacing  | `TableOfContents.createWithSpacing(120)`        |
-| `TableOfContents.createWithHyperlinkColor(color, opts?)` | Custom hyperlink color | `TableOfContents.createWithHyperlinkColor('FF0000')` |
+| Method                                                   | Description              | Example                                              |
+| -------------------------------------------------------- | ------------------------ | ---------------------------------------------------- |
+| `TableOfContents.createStandard(title?)`                 | Standard TOC (3 levels)  | `TableOfContents.createStandard()`                   |
+| `TableOfContents.createSimple(title?)`                   | Simple TOC (2 levels)    | `TableOfContents.createSimple()`                     |
+| `TableOfContents.createDetailed(title?)`                 | Detailed TOC (4 levels)  | `TableOfContents.createDetailed()`                   |
+| `TableOfContents.createHyperlinked(title?)`              | Hyperlinked TOC          | `TableOfContents.createHyperlinked()`                |
+| `TableOfContents.createWithStyles(styles, opts?)`        | TOC with specific styles | `TableOfContents.createWithStyles(['H1','H3'])`      |
+| `TableOfContents.createFlat(title?, styles?)`            | Flat TOC (no indent)     | `TableOfContents.createFlat()`                       |
+| `TableOfContents.createNumbered(title?, format?)`        | Numbered TOC             | `TableOfContents.createNumbered('TOC', 'roman')`     |
+| `TableOfContents.createWithSpacing(spacing, opts?)`      | TOC with custom spacing  | `TableOfContents.createWithSpacing(120)`             |
+| `TableOfContents.createWithHyperlinkColor(color, opts?)` | Custom hyperlink color   | `TableOfContents.createWithHyperlinkColor('FF0000')` |
 
 #### TOC Configuration Methods
 
-| Method                              | Description                       | Values                              |
-| ----------------------------------- | --------------------------------- | ----------------------------------- |
-| `setIncludeStyles(styles)`          | Select specific heading styles    | `['Heading1', 'Heading3']`          |
-| `setNumbered(numbered, format?)`    | Enable/disable numbering          | `(true, 'roman')`                   |
-| `setNoIndent(noIndent)`             | Remove indentation                | `true/false`                        |
-| `setCustomIndents(indents)`         | Custom indents per level          | `[0, 200, 400]` (twips)             |
-| `setSpaceBetweenEntries(spacing)`   | Spacing between entries           | `120` (twips)                       |
-| `setHyperlinkColor(color)`          | Hyperlink color                   | `'0000FF'` (default blue)           |
-| `configure(options)`                | Bulk configuration                | See example below                   |
+| Method                            | Description                    | Values                     |
+| --------------------------------- | ------------------------------ | -------------------------- |
+| `setIncludeStyles(styles)`        | Select specific heading styles | `['Heading1', 'Heading3']` |
+| `setNumbered(numbered, format?)`  | Enable/disable numbering       | `(true, 'roman')`          |
+| `setNoIndent(noIndent)`           | Remove indentation             | `true/false`               |
+| `setCustomIndents(indents)`       | Custom indents per level       | `[0, 200, 400]` (twips)    |
+| `setSpaceBetweenEntries(spacing)` | Spacing between entries        | `120` (twips)              |
+| `setHyperlinkColor(color)`        | Hyperlink color                | `'0000FF'` (default blue)  |
+| `configure(options)`              | Bulk configuration             | See example below          |
 
 #### TOC Properties
 
-| Property             | Type                           | Default      | Description                           |
-| -------------------- | ------------------------------ | ------------ | ------------------------------------- |
-| `title`              | `string`                       | `'Table of Contents'` | TOC title                    |
-| `levels`             | `number` (1-9)                 | `3`          | Heading levels to include             |
-| `includeStyles`      | `string[]`                     | `undefined`  | Specific styles (overrides levels)    |
-| `showPageNumbers`    | `boolean`                      | `true`       | Show page numbers                     |
-| `useHyperlinks`      | `boolean`                      | `false`      | Use hyperlinks instead of page #s     |
-| `numbered`           | `boolean`                      | `false`      | Number TOC entries                    |
-| `numberingFormat`    | `'decimal'/'roman'/'alpha'`    | `'decimal'`  | Numbering format                      |
-| `noIndent`           | `boolean`                      | `false`      | Remove all indentation                |
-| `customIndents`      | `number[]`                     | `undefined`  | Custom indents in twips               |
-| `spaceBetweenEntries`| `number`                       | `0`          | Spacing in twips                      |
-| `hyperlinkColor`     | `string`                       | `'0000FF'`   | Hyperlink color (hex without #)       |
-| `tabLeader`          | `'dot'/'hyphen'/'underscore'/'none'` | `'dot'` | Tab leader character            |
+| Property              | Type                                 | Default               | Description                        |
+| --------------------- | ------------------------------------ | --------------------- | ---------------------------------- |
+| `title`               | `string`                             | `'Table of Contents'` | TOC title                          |
+| `levels`              | `number` (1-9)                       | `3`                   | Heading levels to include          |
+| `includeStyles`       | `string[]`                           | `undefined`           | Specific styles (overrides levels) |
+| `showPageNumbers`     | `boolean`                            | `true`                | Show page numbers                  |
+| `useHyperlinks`       | `boolean`                            | `false`               | Use hyperlinks instead of page #s  |
+| `numbered`            | `boolean`                            | `false`               | Number TOC entries                 |
+| `numberingFormat`     | `'decimal'/'roman'/'alpha'`          | `'decimal'`           | Numbering format                   |
+| `noIndent`            | `boolean`                            | `false`               | Remove all indentation             |
+| `customIndents`       | `number[]`                           | `undefined`           | Custom indents in twips            |
+| `spaceBetweenEntries` | `number`                             | `0`                   | Spacing in twips                   |
+| `hyperlinkColor`      | `string`                             | `'0000FF'`            | Hyperlink color (hex without #)    |
+| `tabLeader`           | `'dot'/'hyphen'/'underscore'/'none'` | `'dot'`               | Tab leader character               |
 
 **Example:**
+
 ```typescript
 // Basic TOC
 const simpleToc = TableOfContents.createStandard();
 doc.addTableOfContents(simpleToc);
 
 // Select specific styles (e.g., only Heading1 and Heading3)
-const customToc = TableOfContents.createWithStyles(['Heading1', 'Heading3']);
+const customToc = TableOfContents.createWithStyles(["Heading1", "Heading3"]);
 
 // Flat TOC with no indentation
-const flatToc = TableOfContents.createFlat('Contents');
+const flatToc = TableOfContents.createFlat("Contents");
 
 // Numbered TOC with roman numerals
-const numberedToc = TableOfContents.createNumbered('Table of Contents', 'roman');
+const numberedToc = TableOfContents.createNumbered(
+  "Table of Contents",
+  "roman"
+);
 
 // Custom hyperlink color (red instead of blue)
-const coloredToc = TableOfContents.createWithHyperlinkColor('FF0000');
+const coloredToc = TableOfContents.createWithHyperlinkColor("FF0000");
 
 // Advanced configuration
 const toc = TableOfContents.create()
-  .setIncludeStyles(['Heading1', 'Heading2', 'Heading3'])
-  .setNumbered(true, 'decimal')
-  .setSpaceBetweenEntries(120)  // 6pt spacing
-  .setHyperlinkColor('0000FF')
+  .setIncludeStyles(["Heading1", "Heading2", "Heading3"])
+  .setNumbered(true, "decimal")
+  .setSpaceBetweenEntries(120) // 6pt spacing
+  .setHyperlinkColor("0000FF")
   .setNoIndent(false);
 
 // Or use configure() for bulk settings
 toc.configure({
-  title: 'Table of Contents',
-  includeStyles: ['Heading1', 'CustomHeader'],
+  title: "Table of Contents",
+  includeStyles: ["Heading1", "CustomHeader"],
   numbered: true,
-  numberingFormat: 'alpha',
+  numberingFormat: "alpha",
   spaceBetweenEntries: 100,
-  hyperlinkColor: 'FF0000',
-  noIndent: true
+  hyperlinkColor: "FF0000",
+  noIndent: true,
 });
 
 // Insert at specific position
@@ -599,13 +589,104 @@ doc.insertTocAt(0, toc);
 
 ### Unit Conversion Utilities
 
-| Function                     | Description          | Example                     |
-| ---------------------------- | -------------------- | --------------------------- |
-| `inchesToTwips(inches)`      | Inches to twips      | `inchesToTwips(1)` // 1440  |
-| `inchesToEmus(inches)`       | Inches to EMUs       | `inchesToEmus(1)` // 914400 |
-| `cmToTwips(cm)`              | Centimeters to twips | `cmToTwips(2.54)` // 1440   |
-| `pointsToTwips(points)`      | Points to twips      | `pointsToTwips(12)` // 240  |
-| `pixelsToEmus(pixels, dpi?)` | Pixels to EMUs       | `pixelsToEmus(96)`          |
+#### Twips Conversions
+| Function                  | Description         | Example                     |
+| ------------------------- | ------------------- | --------------------------- |
+| `twipsToPoints(twips)`    | Twips to points     | `twipsToPoints(240)` // 12  |
+| `twipsToInches(twips)`    | Twips to inches     | `twipsToInches(1440)` // 1  |
+| `twipsToCm(twips)`        | Twips to cm         | `twipsToCm(1440)` // 2.54   |
+| `twipsToEmus(twips)`      | Twips to EMUs       | `twipsToEmus(1440)`         |
+
+#### EMUs (English Metric Units) Conversions
+| Function                    | Description          | Example                       |
+| --------------------------- | -------------------- | ----------------------------- |
+| `emusToTwips(emus)`         | EMUs to twips        | `emusToTwips(914400)` // 1440 |
+| `emusToInches(emus)`        | EMUs to inches       | `emusToInches(914400)` // 1   |
+| `emusToCm(emus)`            | EMUs to cm           | `emusToCm(914400)` // 2.54    |
+| `emusToPoints(emus)`        | EMUs to points       | `emusToPoints(914400)` // 72  |
+| `emusToPixels(emus, dpi?)`  | EMUs to pixels       | `emusToPixels(914400)` // 96  |
+
+#### Points Conversions
+| Function                 | Description        | Example                    |
+| ------------------------ | ------------------ | -------------------------- |
+| `pointsToTwips(points)`  | Points to twips    | `pointsToTwips(12)` // 240 |
+| `pointsToEmus(points)`   | Points to EMUs     | `pointsToEmus(72)`         |
+| `pointsToInches(points)` | Points to inches   | `pointsToInches(72)` // 1  |
+| `pointsToCm(points)`     | Points to cm       | `pointsToCm(72)` // 2.54   |
+
+#### Inches Conversions
+| Function                      | Description         | Example                       |
+| ----------------------------- | ------------------- | ----------------------------- |
+| `inchesToTwips(inches)`       | Inches to twips     | `inchesToTwips(1)` // 1440    |
+| `inchesToEmus(inches)`        | Inches to EMUs      | `inchesToEmus(1)` // 914400   |
+| `inchesToPoints(inches)`      | Inches to points    | `inchesToPoints(1)` // 72     |
+| `inchesToCm(inches)`          | Inches to cm        | `inchesToCm(1)` // 2.54       |
+| `inchesToPixels(inches, dpi)` | Inches to pixels    | `inchesToPixels(1, 96)` // 96 |
+
+#### Centimeters Conversions
+| Function                | Description      | Example                     |
+| ----------------------- | ---------------- | --------------------------- |
+| `cmToTwips(cm)`         | cm to twips      | `cmToTwips(2.54)` // 1440   |
+| `cmToEmus(cm)`          | cm to EMUs       | `cmToEmus(2.54)` // 914400  |
+| `cmToInches(cm)`        | cm to inches     | `cmToInches(2.54)` // 1     |
+| `cmToPoints(cm)`        | cm to points     | `cmToPoints(2.54)` // 72    |
+| `cmToPixels(cm, dpi?)`  | cm to pixels     | `cmToPixels(2.54, 96)` // 96|
+
+#### Pixels Conversions
+| Function                     | Description         | Example                        |
+| ---------------------------- | ------------------- | ------------------------------ |
+| `pixelsToEmus(pixels, dpi?)` | Pixels to EMUs      | `pixelsToEmus(96)` // 914400   |
+| `pixelsToInches(pixels, dpi?)`| Pixels to inches   | `pixelsToInches(96, 96)` // 1  |
+| `pixelsToTwips(pixels, dpi?)`| Pixels to twips     | `pixelsToTwips(96, 96)` // 1440|
+| `pixelsToCm(pixels, dpi?)`   | Pixels to cm        | `pixelsToCm(96, 96)` // 2.54   |
+| `pixelsToPoints(pixels, dpi?)`| Pixels to points   | `pixelsToPoints(96, 96)` // 72 |
+
+**Note:** Default DPI is 96 for pixel conversions
+
+### ZIP Archive Helper Methods
+
+#### File Operations
+| Method                          | Description               | Example                                      |
+| ------------------------------- | ------------------------- | -------------------------------------------- |
+| `addFile(path, content)`        | Add file to archive       | `handler.addFile('doc.xml', xmlContent)`     |
+| `updateFile(path, content)`     | Update existing file      | `handler.updateFile('doc.xml', newContent)`  |
+| `removeFile(path)`              | Remove file from archive  | `handler.removeFile('old.xml')`              |
+| `renameFile(oldPath, newPath)`  | Rename file               | `handler.renameFile('a.xml', 'b.xml')`       |
+| `copyFile(srcPath, destPath)`   | Copy file                 | `handler.copyFile('a.xml', 'copy-a.xml')`    |
+| `moveFile(srcPath, destPath)`   | Move file                 | `handler.moveFile('a.xml', 'folder/a.xml')`  |
+
+#### File Retrieval
+| Method                    | Description            | Returns         |
+| ------------------------- | ---------------------- | --------------- |
+| `getFile(path)`           | Get file object        | `ZipFile`       |
+| `getFileAsString(path)`   | Get file as string     | `string`        |
+| `getFileAsBuffer(path)`   | Get file as buffer     | `Buffer`        |
+| `hasFile(path)`           | Check if file exists   | `boolean`       |
+| `getFilePaths()`          | Get all file paths     | `string[]`      |
+| `getAllFiles()`           | Get all files          | `FileMap`       |
+
+#### Batch Operations
+| Method                          | Description                  | Returns        |
+| ------------------------------- | ---------------------------- | -------------- |
+| `removeFiles(paths[])`          | Remove multiple files        | `number`       |
+| `getFilesByExtension(ext)`      | Get files by extension       | `ZipFile[]`    |
+| `getTextFiles()`                | Get all text files           | `ZipFile[]`    |
+| `getBinaryFiles()`              | Get all binary files         | `ZipFile[]`    |
+| `getMediaFiles()`               | Get media files              | `ZipFile[]`    |
+
+#### Archive Information
+| Method             | Description               | Returns                  |
+| ------------------ | ------------------------- | ------------------------ |
+| `getFileCount()`   | Count files in archive    | `number`                 |
+| `getTotalSize()`   | Get total size in bytes   | `number`                 |
+| `getStats()`       | Get detailed statistics   | `{fileCount, size, ...}` |
+| `isEmpty()`        | Check if archive is empty | `boolean`                |
+
+#### Import/Export
+| Method                           | Description              | Returns              |
+| -------------------------------- | ------------------------ | -------------------- |
+| `exportFile(internal, external)` | Export file from archive | `Promise<void>`      |
+| `importFile(external, internal)` | Import file to archive   | `Promise<void>`      |
 
 ## Common Recipes
 
@@ -997,11 +1078,11 @@ const run = new Run("Text<w:t>value</w:t>", { cleanXmlFromText: false });
 
 **The Right Approach**: Use the framework's API methods instead of embedding XML:
 
-- ✅ Use `paragraph.addText()` multiple times for separate text runs
-- ✅ Use formatting options: `{bold: true}`, `{italic: true}`, etc.
-- ✅ Use `paragraph.addHyperlink()` for links
-- ❌ Don't pass XML strings to text methods
-- ❌ Don't try to embed `<w:t>` or other XML tags in your text
+- Use `paragraph.addText()` multiple times for separate text runs
+- Use formatting options: `{bold: true}`, `{italic: true}`, etc.
+- Use `paragraph.addHyperlink()` for links
+- Don't pass XML strings to text methods
+- Don't try to embed `<w:t>` or other XML tags in your text
 
 For more details, see the [corruption detection examples](examples/troubleshooting/).
 
@@ -1012,6 +1093,7 @@ For more details, see the [corruption detection examples](examples/troubleshooti
 **Cause**: The `pageBreakBefore` property conflicting with `keepNext`/`keepLines` properties. When a paragraph has both `pageBreakBefore` and keep properties set to true, Word's layout engine tries to satisfy contradictory constraints (insert break vs. keep together), resulting in massive whitespace as it struggles to resolve the conflict.
 
 **Why This Causes Problems**:
+
 - `pageBreakBefore` tells Word to insert a page break before the paragraph
 - `keepNext` tells Word to keep the paragraph with the next one (no break)
 - `keepLines` tells Word to keep all lines together (no break)
@@ -1025,13 +1107,14 @@ The framework now automatically prevents these conflicts by **prioritizing keep
 // When setting keepNext or keepLines, pageBreakBefore is automatically cleared
 const para = new Paragraph()
   .addText("Content")
-  .setPageBreakBefore(true)  // Set to true
-  .setKeepNext(true);         // Automatically clears pageBreakBefore
+  .setPageBreakBefore(true) // Set to true
+  .setKeepNext(true); // Automatically clears pageBreakBefore
 
 // Result: keepNext=true, pageBreakBefore=false (conflict resolved)
 ```
 
 **Why This Priority?**
+
 - Keep properties (`keepNext`/`keepLines`) represent explicit user intent to keep content together
 - Page breaks are often layout hints that may conflict with document flow
 - Removing `pageBreakBefore` eliminates whitespace while preserving the user's intention
@@ -1049,6 +1132,7 @@ const doc = await Document.load("document-with-conflicts.docx");
 ```
 
 **How It Works**:
+
 1. When `setKeepNext(true)` is called, `pageBreakBefore` is automatically set to `false`
 2. When `setKeepLines(true)` is called, `pageBreakBefore` is automatically set to `false`
 3. When parsing documents, if both properties exist, `pageBreakBefore` is cleared
@@ -1060,7 +1144,7 @@ If you need a page break despite keep properties, set it after:
 
 ```typescript
 const para = new Paragraph()
-  .setKeepNext(true)        // Set first
+  .setKeepNext(true) // Set first
   .setPageBreakBefore(true); // Override - you explicitly want this conflict
 
 // But note: This will cause layout issues (whitespace) in Word
@@ -1080,12 +1164,12 @@ Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md)
 
 **Critical Bug Fix Release:**
 
-- ✅ **Fixed Paragraph.getText()** - Now includes hyperlink text content (critical data loss bug)
-- ✅ **Added hyperlink integration tests** - 6 new comprehensive test cases
-- ✅ **Enhanced test suite** - 474/478 tests passing (98.1% pass rate)
-- ✅ **Fixed type safety** - XMLElement handling improvements across test files
-- ✅ **Improved StylesManager** - XML corruption detection moved before parser
-- ✅ **Hyperlink management** - Proper relationship ID clearing on URL updates
+- **Fixed Paragraph.getText()** - Now includes hyperlink text content (critical data loss bug)
+- **Added hyperlink integration tests** - 6 new comprehensive test cases
+- **Enhanced test suite** - 474/478 tests passing (98.1% pass rate)
+- **Fixed type safety** - XMLElement handling improvements across test files
+- **Improved StylesManager** - XML corruption detection moved before parser
+- **Hyperlink management** - Proper relationship ID clearing on URL updates
 
 **What This Fixes:**
 When using `para.addText('foo') + para.addHyperlink(link)`, the hyperlink text is now properly included in `paragraph.getText()`, preventing silent text loss.