# docx_creator

A powerful, developer-friendly Dart package for creating, reading, and editing DOCX documents. It features a fluent API, built-in PDF export, and robust HTML/Markdown parsing.

## Key Capabilities

- **Fluent Document Builder:** Chain methods to build complex documents quickly.
- **HTML & Markdown Parsing:** Convert web content directly into high-fidelity DOCX nodes.
- **PDF Export:** Native layout engine to generate PDFs from the same document AST.
- **Rich Styling:** Comprehensive support for typography, colors, borders, shading, and margins.
- **Complex Layouts:** Multi-level nested lists, tables with span support, headers, and footers.
- **Advanced Features:** Image embedding (base64/network/local), footnotes, table of contents, and background images.

---

## Fluent API Examples

### 1. Basic Document Structure
```dart
final doc = docx()
  .h1('Report Title')
  .p('Generated on ${DateTime.now()}')
  .pageBreak()
  .h2('Section 1')
  .p('This is a normal paragraph with some **bold** and *italic* text.', parseMarkdown: true)
  .quote('This is a blockquote for important callouts.')
  .code('void main() => print("Hello DOCX");')
  .build();
```

### 2. Rich Text & Paragraphs
```dart
final doc = docx().paragraph(
  DocxParagraph(
    align: DocxAlign.center,
    children: [
      DocxText('Normal text, '),
      DocxText.bold('Bold text, '),
      DocxText.italic('Italic, '),
      DocxText.boldItalic('Bold+Italic, '),
      DocxText.underline('Underlined, '),
      DocxText.superscript('2'),
      DocxText.subscript('sub'),
      DocxText.link('Dart', href: 'https://dart.dev'),
    ],
  )
).build();
```

### 3. Lists (Nested Support)
```dart
final doc = docx()
  .bullet(['Item 1', 'Item 2'])
  .numbered(['First', 'Second'])
  // Advanced nested lists via AST
  .list(DocxList(
    isOrdered: false,
    items: [
      DocxListItem.text('Level 0'),
      DocxListItem.text('Level 1', level: 1),
      DocxListItem.rich([DocxText.bold('Rich Item')], level: 2),
    ],
  ))
  .build();
```

### 4. Tables & Styling
```dart
final doc = docx().table([
  ['Header 1', 'Header 2'],
  ['Data A', 'Data B'],
], style: DocxTableStyle.professional).build();

// Complex tables with spans
final complexTable = DocxTable(
  rows: [
    DocxTableRow(cells: [
      DocxTableCell(children: [DocxParagraph(children: [DocxText('Span 2 Cols')])], colSpan: 2),
    ]),
    DocxTableRow(cells: [
      DocxTableCell.text('Cell 1'),
      DocxTableCell.text('Cell 2'),
    ]),
  ],
);
```

### 5. Sections, Headers & Footers
```dart
final doc = docx()
  .section(
    header: DocxHeader.styled('Company Confidential', color: DocxColor.red),
    footer: DocxFooter.pageNumbers(),
    pageSize: DocxPageSize.a4,
    orientation: DocxOrientation.portrait,
  )
  .h1('Content in Section 1')
  .build();
```

---

## Parsing Content

### HTML to DOCX
The HTML parser supports nested tags, CSS styles, and async image fetching.
```dart
final html = '''
  <div style="color: #FF0000">
    <h1>HTML Parsing</h1>
    <p>Supports <b>nested <i>formatting</i></b> and <a href="url">links</a>.</p>
    <img src="https://example.com/image.png" alt="Remote Image">
  </div>
''';
final nodes = await DocxParser.fromHtml(html);
final doc = docx().addNodes(nodes).build();
```

### Markdown to DOCX
```dart
final markdown = '''
# Markdown Support
- Lists
- Tables
- **Bold** and [Links](https://google.com)
''';
final nodes = await MarkdownParser.parse(markdown);
final doc = docx().addNodes(nodes).build();
```

---

## Exporting & Saving

### Save to File (DOCX)
```dart
final doc = docx().h1('Hello').build();
await doc.save('output.docx');
```

### Export to PDF
```dart
final doc = docx().h1('Export to PDF').build();
final pdfExporter = PdfExporter();
final pdfBytes = await pdfExporter.exportToBytes(doc);
// Save pdfBytes to file
```

---

## Project Structure & Architecture

- `lib/src/ast/`: Immutable nodes representing the document structure.
- `lib/src/builder/`: Fluent `DocxDocumentBuilder` implementation.
- `lib/src/parsers/`: Specialized logic for HTML and Markdown conversion.
- `lib/src/exporters/`: Generators for OpenXML (DOCX) and PDF formats.
- `lib/src/core/`: Enums, measurements (twips), and shared defaults.

### Design Principles
- **Composition:** Complex elements like `DocxTableCell` contain a list of `DocxBlock` elements.
- **Immutability:** AST nodes are mostly immutable, using `copyWith` patterns where needed.
- **Extensibility:** New exporters or parsers can be added by working with the core AST.
