docs_gee 1.5.1

Pure Dart library for generating and reading DOCX and PDF documents with rich formatting, tables, lists. Cross-platform with no native dependencies.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.5.1 - 2026-10-15

Fixed

• DOCX title and author are now written. DocxDocument.title and .author were only used by the PDF generator; the DOCX output had no docProps/core.xml, so Word showed no metadata under File > Info. The part is now emitted (with its content type and package relationship) whenever either field is set, and documents without metadata are unchanged.
• Text that XML 1.0 forbids no longer corrupts the DOCX. Control characters such as the vertical tab, form feed or NUL, which text pasted from other applications often carries, made word/document.xml malformed and Word refused to open the file. They are now dropped wherever text is written (body, tables, headers, footers, metadata).
• Windows and classic Mac line endings. \r\n and a bare \r inside a run now become a line break, the same as \n, instead of leaving a raw carriage return in <w:t>.
• DocxReader kept only the break of a multi-line run. A run holding both text and <w:br/> (what the generator writes for 'a\nb', and what Word writes for Shift+Enter) was read back as a bare line break and its text was lost. The text is now kept, with each break as \n.
• DocxReader metadata decoding. title and author are read with a real XML parser, so entities such as & come back decoded instead of verbatim.

1.5.0 - 2026-08-24

Added

• Images in DOCX. DocxImage embeds PNG and JPEG bytes, reading the intrinsic pixel size straight from the file header, so a picture needs no explicit dimensions. width/height scale it, and giving only one keeps the aspect ratio. Add one with document.addImage(...); altText becomes the accessibility description and alignment places it on the page.
• Headers, footers and page numbers (DOCX). DocxHeaderFooter on DocxDocument.header / .footer repeats content on every page. DocxHeaderFooter.pageNumber() builds the usual Page 3 of 12 footer from the new DocxRun.pageNumber() and DocxRun.pageCount() field runs, which the word processor recalculates on open.
• Right-to-left text (DOCX). DocxParagraph.rtl emits <w:bidi/> and DocxRun.rtl emits <w:rtl/>, for Arabic, Hebrew and Persian. Both survive a read-back through DocxReader.
• Font size per run. DocxRun.fontSize (in points) overrides the document default in both DOCX and PDF output; the PDF line height grows with the tallest run on the line.
• Configurable table cell padding. DocxCellPadding on DocxTable.cellPadding (table-wide) or DocxTableCell.padding (per cell), declared in twips or through DocxCellPadding.points(...). Honoured by both generators and read back by DocxReader.

Changed

• Dropped the flutter: constraint from environment. Nothing under lib/ imports Flutter, and the bound made dart pub get refuse with "docs_gee requires the Flutter SDK", which had been failing the publish dry-run workflow since April and locked the package out of pure Dart projects.
• xml raised to ^7.0.0; the reader now uses its namespaceUri argument instead of the deprecated namespace.
• flutter_lints raised to ^6.0.0; the package analyzes clean under the stricter rule set.

Notes

• Headers, footers and images are DOCX-only; the PDF generator skips them.
• External hyperlinks inside a header or footer render as plain text: those parts resolve relationship ids against their own relationship file, which this library does not emit, and a dangling id would make Word reject the document.

1.4.2 - 2026-07-10

Changed

• Set the pubspec documentation: field so the pub.dev "Documentation" link points to the hosted docs at codigee.com/open-source/docs-gee.

1.4.1 - 2026-07-10

Changed

• Added a Documentation section to the README linking the hosted docs at codigee.com/open-source/docs-gee: overview, document-building guide, and the DocxReader & API reference.

1.4.0 - 2026-07-10

Added

• Superscript & subscript text runs via the new DocxScript enum (Script alias). Set script: DocxScript.superscript or DocxScript.subscript on a DocxRun for exponents (x²), chemical formulas (H₂O), ordinals and footnote markers.
  • DOCX: renders as the <w:vertAlign> run property.
  • PDF: rendered smaller with a baseline shift (text-rise operator).
  • Reader: <w:vertAlign> is parsed back, so scripts survive a full read → modify → write round-trip.

1.3.4 - 2026-06-07

Added

• DocxParagraph.empty() factory for inserting blank spacer paragraphs between content blocks.

1.3.3 - 2026-05-13

Changed

• Replaced the deprecated library docs_gee; directive with the modern unnamed library; declaration in the barrel file.
• Test suite cleanup via dart fix --apply — 47 auto-fixable lint info resolved across 9 test/example files (prefer_const_constructors, no_leading_underscores_for_local_identifiers, dangling_library_doc_comments). No production code affected.

1.3.2 - 2026-04-07

Changed

• Updated installation docs to ^1.3.2

1.3.1 - 2026-04-07

Changed

• Dart SDK constraint: >=3.2.0 <4.0.0
• Flutter constraint: >=3.16.0

1.3.0 - 2026-03-27

Added

DOCX Reader

• DocxReader class - Parse existing DOCX files into DocxDocument objects
  • DocxReader().read(Uint8List bytes) → DocxDocument
  • Full round-trip support: read → modify → write
  • DocumentReader type alias for format-agnostic code
• Supported features:
  • All paragraph styles (headings 1-4, subtitle, caption, quote, code block, footnote)
  • Text formatting (bold, italic, underline, strikethrough, color, background color)
  • Text alignment (left, center, right, justify)
  • Lists (bullet, dash, numbered, alpha, roman) with indent levels
  • Tables with borders, colspan, rowspan, cell properties
  • External hyperlinks and internal bookmark references
  • Page breaks and line breaks
  • Mixed content order (paragraphs and tables)
  • Document metadata (title, author) from docProps/core.xml
• Typed exceptions:
  • InvalidDocxArchiveException - invalid ZIP archive
  • MissingDocxPartException - missing required DOCX part
  • InvalidDocxXmlException - malformed XML content
• Graceful degradation:
  • Missing styles.xml / numbering.xml → default mappings
  • Unknown styles → fallback to normal
  • Images, charts, embedded objects → silently skipped
• New dependency: xml: ^6.0.0 (pure Dart XML parser)
• 124 tests covering round-trip, unit parsers, edge cases, and error handling

1.2.2 - 2026-02-27

Fixed

PDF Generator

• Accurate text width estimation - Replaced rough character-width approximation (0.5 * fontSize) with Adobe Helvetica AFM glyph-width table for precise text layout
  • Helvetica variants use per-character widths from the standard Adobe Font Metrics
  • Courier (monospace) uses correct 0.6 * fontSize per glyph
  • Includes width data for Latin-1 supplement and Polish characters
• Underline & strikethrough in table cells - Table cell text segments now render underline and strikethrough decorations correctly (previously only worked outside tables)
• Per-segment width calculation - Line width is now computed per text segment (respecting each segment's font) instead of joining all text and measuring as one

1.2.1 - 2026-02-23

Fixed

Page Breaks

• Windows Word compatibility - Page breaks now work correctly in Microsoft Word on Windows
  • Replaced <w:pageBreakBefore/> paragraph property with explicit <w:br w:type="page"/> run element
  • Applies to regular paragraphs, table cell paragraphs, and TOC page breaks
  • No API changes - pageBreakBefore: true works exactly the same way
• Unit tests - Added test/page_break_test.dart with 11 tests covering page break XML generation, DOCX and PDF output

1.2.0 - 2026-02-19

Added

Per-Cell Border Control

• Cell-level borders - Override table-level borders on individual cells
  • DocxCellBorders class with top, bottom, left, right borders
  • CellBorders type alias for format-agnostic code
  • Convenience constructors: .all(), .none(), .bottom()
  • Custom border per side with color, size, and style
  • Cell borders override table-level borders when set
  • Works in both DOCX (<w:tcBorders>) and PDF output
• borders parameter on DocxTableCell - Both constructor and .text() factory accept DocxCellBorders?
• Unit tests - Added test/cell_borders_test.dart with 26 tests covering model, XML generation, and PDF/DOCX output

1.1.2 - 2025-01-23

Fixed

PDF Generator

• Bullet points display correctly - Fixed encoding issue where bullet character (•) was displaying as "•"
  • Rewrote _escapePdfString to properly convert Unicode characters to WinAnsi octal escapes
• Extended character support - Added proper encoding for:
  • Typography: bullet (•), en-dash (–), em-dash (—), smart quotes (' ' " "), ellipsis (…), euro (€), trademark (™), copyright (©), registered (®)
  • German: Ä, Ö, Ü, ä, ö, ü, ß
  • French: À, Â, Ç, È, É, Ê, Ë, Î, Ï, Ô, Ù, Û, à, â, ç, è, é, ê, ë, î, ï, ô, ù, û
  • Polish: Ó, ó (native support), other Polish characters (ą, ę, ć, ź, ż, ń, ł, ś) fall back to base ASCII equivalents due to WinAnsi limitations

DOCX Generator

• List detection fix - Fixed issue where listDash, listNumberAlpha, and listNumberRoman styles didn't trigger inclusion of numbering.xml, causing lists to display incorrectly
• List level specification - Added explicit <w:ilvl w:val="0"/> to all list styles in styles.xml for consistent formatting

1.1.0 - 2025-01-21

Added

Line Breaks (Soft Return) - DOCX only

• Automatic \n conversion - Newline characters in text are now converted to <w:br/> line breaks
  • DocxParagraph.text('Line 1\nLine 2\nLine 3')
• Explicit line break runs - New DocxRun.lineBreak() constructor for manual line breaks
  • Allows different formatting before and after line break
  • DocxParagraph(runs: [DocxRun('Bold', bold: true), DocxRun.lineBreak(), DocxRun('Normal')])
• Line breaks create soft returns within a paragraph (like Shift+Enter in Word)

1.0.1 - 2024-12-21

Added

Hyperlinks

• External links - Link text to external URLs
  • DocxRun('text', hyperlink: 'https://example.com')
  • Automatic blue color and underline styling

Internal Links (Bookmarks)

• Bookmarks - Create named anchors in document
  • DocxParagraph.heading('Title', level: 1, bookmarkName: 'section1')
• Bookmark references - Link to internal bookmarks
  • DocxRun('Go to section', bookmarkRef: 'section1')

Table of Contents

• Automatic TOC generation
  • DocxDocument(includeTableOfContents: true)
  • Configurable title (tocTitle)
  • Configurable heading depth (tocMaxLevel: 1-4)
  • Word auto-updates TOC on document open

Fixed

• Repository URL in pubspec.yaml

1.0.0 - 2024-12-19

Added

Document Generation

• DocxGenerator - Generates Microsoft Word DOCX files
  • Pure Dart implementation using OOXML standard
  • Configurable default font name and size
  • Compatible with Word 2007+, Google Docs, LibreOffice
• PdfGenerator - Generates PDF documents
  • Pure Dart implementation (PDF 1.4 standard)
  • No native dependencies
  • Cross-platform support including Web

Document Model

• Document - Container for document content
  • Title and author metadata
  • Mixed content support (paragraphs and tables)
  • Creation and modification timestamps

Text Formatting

• TextRun - Rich text formatting
  • Bold, italic, underline, strikethrough
  • Text color (hex format)
  • Background/highlight color
• Text alignment - Left, center, right, justify

Paragraph Styles

• Headings (H1-H4)
• Subtitle
• Caption
• Block quote
• Code block (monospace)
• Footnote

Lists

• Bullet lists (•)
• Dash lists (–)
• Numbered lists (1, 2, 3)
• Alphabetic lists (a, b, c)
• Roman numeral lists (I, II, III)
• Nested lists up to 9 levels deep

Tables

• Basic table support with rows and cells
• Cell background colors
• Cell text alignment
• Table borders (all, none, outside only)
• Border styles (single, double, dashed, dotted)

Other Features

• Page breaks
• Emoji support (DOCX only - Word handles natively)
• Cross-platform: iOS, Android, Web, macOS, Windows, Linux

Documentation

• Complete API reference
• Usage examples for all features
• Platform-specific guides (Web, Mobile)