xlsxrb 0.1.9 → 0.1.11

data/docs/PEER_LIBRARIES.md

@@ -0,0 +1,121 @@
+# Ruby XLSX Ecosystem & Peer Libraries
+
+The Ruby ecosystem is fortunate to have a rich set of mature, well-engineered XLSX libraries. Each library represents deliberate architectural choices tailored for specific problem spaces.
+
+This document provides a respectful overview of the peer libraries in the Ruby ecosystem, explains the underlying engineering tradeoffs (such as Streaming vs. In-Memory and Shared String Tables vs. Inline Strings), and shares comprehensive benchmark measurements.
+
+---
+
+## The Peer Libraries
+
+| Library | I/O | Official Self-Description / Focus | Best Fit (In Our View) |
+| :--- | :---: | :--- | :--- |
+| **[roo](https://rubygems.org/gems/roo)** | `R` | *"Roo can access the contents of various spreadsheet files (Excelx, LibreOffice, OpenOffice, CSV)."* | Unified interface for reading across diverse spreadsheet formats. |
+| **[creek](https://rubygems.org/gems/creek)** | `R` | *"A Ruby gem that streams and parses large Excel (xlsx and xlsm) files fast and efficiently."* | Streaming large spreadsheet uploads row-by-row with lightweight SAX parsing. |
+| **[xsv](https://rubygems.org/gems/xsv)** | `R` | *"A fast and lightweight xlsx parser that provides nothing a CSV parser wouldn't."* | High-speed, CSV-like tabular data ingestion without styling overhead. |
+| **[simple_xlsx_reader](https://rubygems.org/gems/simple_xlsx_reader)** | `R` | *"Read xlsx data the Ruby way"* — parses sheets into Ruby primitives with low memory. | Memory-conscious tabular data extraction directly into Ruby types. |
+| **[caxlsx / axlsx](https://rubygems.org/gems/caxlsx)** | `W` | *"Excel OOXML (xlsx) with charts, styles, images and autowidth columns"* with full schema validation. | Generating rich, styled business reports with charts, images, and visual design. |
+| **[write_xlsx](https://rubygems.org/gems/write_xlsx)** | `W` | Pure Ruby port of Perl's `Excel::Writer::XLSX` to create files in modern Excel 2007+ format. | Creating complex spreadsheets requiring exact Excel feature parity. |
+| **[xlsxtream](https://rubygems.org/gems/xlsxtream)** | `W` | *"A streaming XLSX spreadsheet writer"* allowing very efficient writing of CSV-style data. | Ultra-fast, low-memory streaming exports of massive tabular datasets. |
+| **[fast_excel](https://rubygems.org/gems/fast_excel)** | `W` | *"Ultra Fast Excel Writer"* — C-extension wrapper for `libxlsxwriter` with constant memory mode. | Maximum-throughput spreadsheet generation when C-extensions are available. |
+| **[rubyXL](https://rubygems.org/gems/rubyXL)** | `RW` | *"Allows the parsing, creation, and manipulation of Microsoft Excel (.xlsx/.xlsm) Documents."* | Full document DOM inspection, in-memory cell modification, and template editing. |
+| **[xlsxrb](https://github.com/niku/xlsxrb)** | `RW` | Pure Ruby library unifying streaming read/write ($O(1)$ memory) and in-memory manipulation with native encryption. | Unified reading, writing, template modification, and password encryption in pure Ruby. |
+
+
+---
+
+## Architectural Tradeoffs
+
+Spreadsheet libraries must balance multiple competing dimensions: memory consumption, execution speed, formatting capabilities, and strict specification compliance.
+
+### 1. Memory & Execution Model: Streaming vs. In-Memory
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Execution Models                       │
+├──────────────────────────────┬──────────────────────────────┤
+│       Streaming Model        │       In-Memory Model        │
+├──────────────────────────────┼──────────────────────────────┤
+│ • Processes rows on-the-fly  │ • Builds complete DOM tree   │
+│ • O(1) constant RAM footprint│ • Enables random cell access │
+│ • Cannot seek backward       │ • High RAM on large datasets │
+│ • Ideal for batch exports/ETL│ • Ideal for templates/edits  │
+└──────────────────────────────┴──────────────────────────────┘
+```
+
+* **Streaming Model** (`xlsxrb`, `xlsxtream`, `simple_xlsx_reader`, `roo`, `creek`, `xsv`):
+  Rows and cells are processed sequentially and flushed/discarded immediately. This keeps memory usage completely flat and predictable, regardless of whether the file has 10 rows or 1,000,000 rows. However, random access (e.g., modifying `cell("A1")` after writing row 100) is not possible.
+* **In-Memory Model** (`xlsxrb`, `caxlsx`, `write_xlsx`, `rubyXL`):
+  The entire workbook structure is parsed into Ruby objects, providing complete flexibility to inspect, modify, insert, or reorder cells and worksheets. The tradeoff is that memory consumption scales with the number of cells.
+
+---
+
+### 2. String Storage Architecture: Shared String Table (SST) vs. Inline Strings
+
+The OpenXML (ECMA-376) specification defines two ways to store text in cells:
+
+```xml
+<!-- 1. Shared String Table (SST): Deduplicated dictionary reference -->
+<c r="A1" t="s"><v>0</v></c>
+
+<!-- 2. Inline String: Raw text payload inside the cell -->
+<c r="A1" t="inlineStr"><is><t>Hello World</t></is></c>
+```
+
+#### Shared String Table (SST)
+* **How it works**: Strings across all worksheets are collected into a single central dictionary (`xl/sharedStrings.xml`). Cells only store numeric integer IDs pointing to dictionary entries.
+* **Strengths**:
+  * **Smaller file footprint**: Deduplication significantly reduces the uncompressed XML size (typically 50% to 80% smaller for business datasets with repetitive categories, statuses, dates, and labels).
+  * **Standard Microsoft Excel behavior**: Excel defaults to SST. Opening SST-based spreadsheets in Excel consumes less memory and renders faster.
+  * **Rich Text & Shared Styles**: Supports rich text formatting within strings.
+* **Tradeoff**:
+  * Writing requires managing a string table dictionary or making a multi-pass serialization, adding slight CPU overhead during generation.
+
+#### Inline Strings
+* **How it works**: Text is written directly into each `<c>` element (`<is><t>...</t></is>`) as the stream proceeds.
+* **Strengths**:
+  * **Raw Throughput**: Bypassing string deduplication allows immediate row-by-row flushing with minimal CPU overhead (as demonstrated by `xlsxtream`).
+* **Tradeoff**:
+  * Produces significantly larger raw XML files when strings repeat, and some third-party spreadsheet viewers or legacy tools have limited support for inline strings compared to SST.
+
+---
+
+## Detailed Benchmark Results
+
+The following benchmarks evaluate processing **1,000,000 cells** (100,000 rows × 10 columns) containing standard business data (integers, strings, floats, booleans, and dates) across 3 isolated subprocess runs.
+
+### Write Performance (1,000,000 cells)
+
+| Library | Version | Model | String Storage | Time (Median) | Time (Mean) | Peak Memory | GC Count |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| **xlsxrb (Streaming)** | - | Streaming | SST (Shared) | **0.95 s** | **0.95 s** | 67.6 MB | **34.0** |
+| **xlsxtream** | 3.1.0 | Streaming | Inline String | 1.16 s | 1.17 s | **17.0 MB** | 323.0 |
+| **fast_excel** | 0.5.0 | Streaming | SST (Shared) | 2.02 s | 2.14 s | 148.3 MB | 210.0 |
+| **xlsxrb (In-Memory)** | - | In-Memory | SST (Shared) | 2.42 s | 2.57 s | 209.0 MB | 16.0 |
+| **write_xlsx** | 1.15.0 | In-Memory | SST (Shared) | 4.39 s | 4.42 s | 217.4 MB | 25.0 |
+| **caxlsx** | 4.5.0 | In-Memory | Inline String | 5.28 s | 5.28 s | 177.4 MB | 24.0 |
+| **rubyXL** | 3.4.38 | In-Memory | Inline String | 43.13 s | 43.65 s | 2167.2 MB | 101.0 |
+
+### Read Performance (1,000,000 cells)
+
+| Library | Version | Model | Time (Median) | Time (Mean) | Peak Memory | GC Count |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| **xlsxrb (Streaming)** | - | Streaming | **1.73 s** | **1.72 s** | 136.2 MB | **45.0** |
+| **xlsxrb (In-Memory)** | - | In-Memory | 4.33 s | 4.46 s | 304.3 MB | 77.0 |
+| **simple_xlsx_reader** | 5.1.0 | Streaming | 4.38 s | 4.41 s | **32.8 MB** | 918.0 |
+| **creek** | 2.6.3 | Streaming | 7.12 s | 7.05 s | 840.1 MB | 419.0 |
+| **roo** | 3.0.0 | Streaming | 10.95 s | 10.33 s | 123.4 MB | 196.0 |
+| **xsv** | 1.4.1 | Streaming | 14.56 s | 14.59 s | 73.6 MB | 2028.0 |
+| **rubyXL** | 3.4.38 | In-Memory | 30.74 s | 30.78 s | 2289.6 MB | 146.0 |
+
+---
+
+## Reproducing Benchmarks Locally
+
+The benchmark suite leverages [`bundler/inline`](https://bundler.io/v2.5/guides/bundler_in_a_single_file_ruby_script.html) to run each library in an isolated subprocess (`Bundler.with_unbundled_env`), eliminating cross-gem pollution and ensuring accurate memory measurements.
+
+To run the suite on your machine:
+
+```bash
+ruby benchmark.rb 100000 10
+```

data/docs/assets/benchmark_results.svg

@@ -0,0 +1,144 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 480" width="100%" height="100%">
+  <defs>
+    <linearGradient id="bg-grad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#161b22"/>
+      <stop offset="100%" stop-color="#0d1117"/>
+    </linearGradient>
+  </defs>
+
+  <style>
+    .card { fill: #161b22; stroke: #30363d; stroke-width: 1px; rx: 8px; }
+    .title { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; font-size: 18px; font-weight: 700; fill: #f0f6fc; }
+    .subtitle { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; font-size: 12px; fill: #8b949e; }
+    .section-title { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; font-size: 14px; font-weight: 700; fill: #e6edf3; }
+    .label { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; font-size: 12px; fill: #c9d1d9; }
+    .label-accent { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; font-size: 12px; font-weight: 700; fill: #58a6ff; }
+    .value { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; font-size: 11px; font-weight: 600; fill: #ffffff; }
+    .grid { stroke: #21262d; stroke-width: 1px; stroke-dasharray: 4 4; }
+    .footer { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; font-size: 11px; fill: #8b949e; }
+  </style>
+
+  <!-- Container -->
+  <rect width="960" height="480" rx="12" fill="url(#bg-grad)" stroke="#30363d" stroke-width="1"/>
+
+  <!-- Main Header -->
+  <text x="480" y="38" text-anchor="middle" class="title">Ruby XLSX Performance Benchmarks (1,000,000 Cells)</text>
+  <text x="480" y="58" text-anchor="middle" class="subtitle">100,000 rows × 10 cols • Mixed business data • Linear time scale (0s – 40s)</text>
+
+  <!-- Left: Write Performance -->
+  <g transform="translate(35, 75)">
+    <rect width="430" height="350" class="card"/>
+    <text x="20" y="30" class="section-title">Write Execution Time</text>
+    <text x="20" y="46" font-family="sans-serif" font-size="10" fill="#8b949e">Time to generate 1M cells (Lower is faster)</text>
+    
+    <line x1="160.0" y1="65" x2="160.0" y2="320" class="grid"/>
+    <text x="160.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">0s</text>
+
+    <line x1="215.0" y1="65" x2="215.0" y2="320" class="grid"/>
+    <text x="215.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">10s</text>
+
+    <line x1="270.0" y1="65" x2="270.0" y2="320" class="grid"/>
+    <text x="270.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">20s</text>
+
+    <line x1="325.0" y1="65" x2="325.0" y2="320" class="grid"/>
+    <text x="325.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">30s</text>
+
+    <line x1="380.0" y1="65" x2="380.0" y2="320" class="grid"/>
+    <text x="380.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">40s</text>
+    
+    <!-- xlsxrb (Streaming): 0.95s -->
+    <text x="150" y="85" text-anchor="end" class="label-accent">xlsxrb (Streaming)</text>
+    <rect x="160" y="72" width="5.2" height="18" rx="3" fill="#3b82f6"/>
+    <text x="173.2" y="85" class="value">0.95 s</text>
+
+    <!-- xlsxtream 3.1.0: 1.16s -->
+    <text x="150" y="120" text-anchor="end" class="label">xlsxtream 3.1.0</text>
+    <rect x="160" y="107" width="6.4" height="18" rx="3" fill="#64748b"/>
+    <text x="174.4" y="120" class="value">1.16 s</text>
+
+    <!-- fast_excel 0.5.0: 2.02s -->
+    <text x="150" y="155" text-anchor="end" class="label">fast_excel 0.5.0</text>
+    <rect x="160" y="142" width="11.1" height="18" rx="3" fill="#64748b"/>
+    <text x="179.1" y="155" class="value">2.02 s</text>
+
+    <!-- xlsxrb (In-Memory): 2.42s -->
+    <text x="150" y="190" text-anchor="end" class="label-accent">xlsxrb (In-Memory)</text>
+    <rect x="160" y="177" width="13.3" height="18" rx="3" fill="#3b82f6"/>
+    <text x="181.3" y="190" class="value">2.42 s</text>
+
+    <!-- write_xlsx 1.15.0: 4.39s -->
+    <text x="150" y="225" text-anchor="end" class="label">write_xlsx 1.15.0</text>
+    <rect x="160" y="212" width="24.1" height="18" rx="3" fill="#64748b"/>
+    <text x="192.1" y="225" class="value">4.39 s</text>
+
+    <!-- caxlsx 4.5.0: 5.28s -->
+    <text x="150" y="260" text-anchor="end" class="label">caxlsx 4.5.0</text>
+    <rect x="160" y="247" width="29.0" height="18" rx="3" fill="#64748b"/>
+    <text x="197.0" y="260" class="value">5.28 s</text>
+
+    <!-- rubyXL 3.4.38: 43.13s -->
+    <text x="150" y="295" text-anchor="end" class="label">rubyXL 3.4.38</text>
+    <rect x="160" y="282" width="220.0" height="18" rx="3" fill="#64748b"/>
+    <text x="388.0" y="295" class="value">43.13 s</text>
+  </g>
+
+  <!-- Right: Read Performance -->
+  <g transform="translate(495, 75)">
+    <rect width="430" height="350" class="card"/>
+    <text x="20" y="30" class="section-title">Read Execution Time</text>
+    <text x="20" y="46" font-family="sans-serif" font-size="10" fill="#8b949e">Time to parse 1M cells (Lower is faster)</text>
+    
+    <line x1="160.0" y1="65" x2="160.0" y2="320" class="grid"/>
+    <text x="160.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">0s</text>
+
+    <line x1="215.0" y1="65" x2="215.0" y2="320" class="grid"/>
+    <text x="215.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">10s</text>
+
+    <line x1="270.0" y1="65" x2="270.0" y2="320" class="grid"/>
+    <text x="270.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">20s</text>
+
+    <line x1="325.0" y1="65" x2="325.0" y2="320" class="grid"/>
+    <text x="325.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">30s</text>
+
+    <line x1="380.0" y1="65" x2="380.0" y2="320" class="grid"/>
+    <text x="380.0" y="335" font-family="sans-serif" font-size="10" fill="#64748b" text-anchor="middle">40s</text>
+    
+    <!-- xlsxrb (Streaming): 1.73s -->
+    <text x="150" y="85" text-anchor="end" class="label-accent">xlsxrb (Streaming)</text>
+    <rect x="160" y="72" width="9.5" height="18" rx="3" fill="#3b82f6"/>
+    <text x="177.5" y="85" class="value">1.73 s</text>
+
+    <!-- xlsxrb (In-Memory): 4.33s -->
+    <text x="150" y="120" text-anchor="end" class="label-accent">xlsxrb (In-Memory)</text>
+    <rect x="160" y="107" width="23.8" height="18" rx="3" fill="#3b82f6"/>
+    <text x="191.8" y="120" class="value">4.33 s</text>
+
+    <!-- simple_xlsx_reader: 4.38s -->
+    <text x="150" y="155" text-anchor="end" class="label">simple_xlsx_reader</text>
+    <rect x="160" y="142" width="24.1" height="18" rx="3" fill="#64748b"/>
+    <text x="192.1" y="155" class="value">4.38 s</text>
+
+    <!-- creek 2.6.3: 7.12s -->
+    <text x="150" y="190" text-anchor="end" class="label">creek 2.6.3</text>
+    <rect x="160" y="177" width="39.2" height="18" rx="3" fill="#64748b"/>
+    <text x="207.2" y="190" class="value">7.12 s</text>
+
+    <!-- roo 3.0.0: 10.95s -->
+    <text x="150" y="225" text-anchor="end" class="label">roo 3.0.0</text>
+    <rect x="160" y="212" width="60.2" height="18" rx="3" fill="#64748b"/>
+    <text x="228.2" y="225" class="value">10.95 s</text>
+
+    <!-- xsv 1.4.1: 14.56s -->
+    <text x="150" y="260" text-anchor="end" class="label">xsv 1.4.1</text>
+    <rect x="160" y="247" width="80.1" height="18" rx="3" fill="#64748b"/>
+    <text x="248.1" y="260" class="value">14.56 s</text>
+
+    <!-- rubyXL 3.4.38: 30.74s -->
+    <text x="150" y="295" text-anchor="end" class="label">rubyXL 3.4.38</text>
+    <rect x="160" y="282" width="169.1" height="18" rx="3" fill="#64748b"/>
+    <text x="337.1" y="295" class="value">30.74 s</text>
+  </g>
+
+  <!-- Footer -->
+  <text x="480" y="455" text-anchor="middle" class="footer">Tested on Ruby 4.0+ in isolated subprocesses • Full GC and peak memory metrics in docs/PEER_LIBRARIES.md</text>
+</svg>

data/docs/visual/VisualGallery.md

@@ -251,6 +251,11 @@ This gallery showcases `xlsxrb` DSL usage side-by-side with the visual rendering
 <td align="center"><a href="#conditional-formatting">View Code &amp; Detail</a></td>
 </tr>
 <tr>
+<td><strong>Drawing Shapes</strong></td>
+<td align="center"><img src="../../test/visual/baselines/drawing_shapes/page-1.png" width="160" alt="Drawing Shapes"/></td>
+<td align="center"><a href="#drawing-shapes">View Code &amp; Detail</a></td>
+</tr>
+<tr>
 <td><strong>Embedded Images</strong></td>
 <td align="center"><img src="../../test/visual/baselines/embedded_images/page-1.png" width="160" alt="Embedded Images"/></td>
 <td align="center"><a href="#embedded-images">View Code &amp; Detail</a></td>
@@ -361,6 +366,11 @@ This gallery showcases `xlsxrb` DSL usage side-by-side with the visual rendering
 <td align="center"><a href="#page-paper-size-a3">View Code &amp; Detail</a></td>
 </tr>
 <tr>
+<td><strong>Pivot Table</strong></td>
+<td align="center"><img src="../../test/visual/baselines/pivot_table/page-1.png" width="160" alt="Pivot Table"/></td>
+<td align="center"><a href="#pivot-table">View Code &amp; Detail</a></td>
+</tr>
+<tr>
 <td><strong>Row Grouping</strong></td>
 <td align="center"><img src="../../test/visual/baselines/row_grouping/page-1.png" width="160" alt="Row Grouping"/></td>
 <td align="center"><a href="#row-grouping">View Code &amp; Detail</a></td>
@@ -396,6 +406,11 @@ This gallery showcases `xlsxrb` DSL usage side-by-side with the visual rendering
 <td align="center"><a href="#styles-fonts-fills">View Code &amp; Detail</a></td>
 </tr>
 <tr>
+<td><strong>Table Styles</strong></td>
+<td align="center"><img src="../../test/visual/baselines/table_styles/page-1.png" width="160" alt="Table Styles"/></td>
+<td align="center"><a href="#table-styles">View Code &amp; Detail</a></td>
+</tr>
+<tr>
 <td><strong>View Show Grid Lines</strong></td>
 <td align="center"><img src="../../test/visual/baselines/view_show_grid_lines/page-1.png" width="160" alt="View Show Grid Lines"/></td>
 <td align="center"><a href="#view-show-grid-lines">View Code &amp; Detail</a></td>
@@ -2844,6 +2859,55 @@ Row 0: A1: 90, B1: 45, C1: 72, D1: 88
 
 <hr/>
 
+## Drawing Shapes
+
+Visual demonstration for Drawing Shapes.
+
+### Rendered Output (LibreOffice Calc)
+
+<div><img src="../../test/visual/baselines/drawing_shapes/page-1.png" width="100%" alt="Preview"/></div>
+
+<div><img src="../../test/visual/baselines/drawing_shapes/page-2.png" width="100%" alt="Preview"/></div>
+
+### DSL Code
+
+```ruby
+# frozen_string_literal: true
+
+require "xlsxrb"
+
+output_path = ARGV[0] || "drawing_shapes.xlsx"
+
+Xlsxrb.write(output_path) do |wb|
+  wb.sheet("Shapes") do |sheet|
+    sheet.column(0..7, width: 15)
+    sheet.row(["Diagram with shapes and annotations"])
+    sheet.row([])
+    sheet.shape(preset: "rect", text: "Process Start", from_col: 1, from_row: 2, to_col: 3, to_row: 4)
+    sheet.shape(preset: "rightArrow", text: "Next", from_col: 4, from_row: 3, to_col: 5, to_row: 4)
+    sheet.shape(preset: "roundRect", text: "Processing", from_col: 6, from_row: 2, to_col: 8, to_row: 4)
+  end
+end
+
+puts "=== Read Validation ==="
+workbook = Xlsxrb.read(output_path).load
+sheet = workbook.sheets.first
+sheet.rows.each do |row|
+  row_cells = row.cells.map { |c| "#{c.ref}: #{c.value.inspect}" }
+  puts "Row #{row.index}: #{row_cells.join(", ")}"
+end
+```
+
+### Console Output
+
+```text
+=== Read Validation ===
+Row 0: A1: "Diagram with shapes and annotations"
+Row 1:
+```
+
+<hr/>
+
 ## Embedded Images
 
 Demonstrates embedding raster PNG images in cell ranges.
@@ -4010,6 +4074,71 @@ Print Options: {}
 
 <hr/>
 
+## Pivot Table
+
+Visual demonstration for Pivot Table.
+
+### Rendered Output (LibreOffice Calc)
+
+<div><img src="../../test/visual/baselines/pivot_table/page-1.png" width="100%" alt="Preview"/></div>
+
+<div><img src="../../test/visual/baselines/pivot_table/page-2.png" width="100%" alt="Preview"/></div>
+
+### DSL Code
+
+```ruby
+# frozen_string_literal: true
+
+require "xlsxrb"
+
+output_path = ARGV[0] || "pivot_table.xlsx"
+
+Xlsxrb.write(output_path) do |wb|
+  wb.sheet("SalesData") do |sheet|
+    sheet.column(0..3, width: 18)
+    sheet.row(%w[Region Quarter Sales Rep])
+    sheet.row(["East", "Q1", 1000, "Alice"])
+    sheet.row(["West", "Q1", 1500, "Bob"])
+    sheet.row(["East", "Q2", 1200, "Alice"])
+    sheet.row(["West", "Q2", 1800, "Bob"])
+    sheet.row(["North", "Q1", 800, "Charlie"])
+    sheet.row(["North", "Q2", 950, "Charlie"])
+
+    sheet.pivot_table(
+      "SalesData!A1:D7",
+      row_fields: ["Region"],
+      data_fields: [{ name: "Sales", subtotal: "sum" }],
+      col_fields: ["Quarter"],
+      dest_ref: "F1",
+      name: "RegionalSalesSummary"
+    )
+  end
+end
+
+puts "=== Read Validation ==="
+workbook = Xlsxrb.read(output_path).load
+sheet = workbook.sheets.first
+sheet.rows.each do |row|
+  row_cells = row.cells.map { |c| "#{c.ref}: #{c.value.inspect}" }
+  puts "Row #{row.index}: #{row_cells.join(", ")}"
+end
+```
+
+### Console Output
+
+```text
+=== Read Validation ===
+Row 0: A1: "Region", B1: "Quarter", C1: "Sales", D1: "Rep"
+Row 1: A2: "East", B2: "Q1", C2: 1000, D2: "Alice"
+Row 2: A3: "West", B3: "Q1", C3: 1500, D3: "Bob"
+Row 3: A4: "East", B4: "Q2", C4: 1200, D4: "Alice"
+Row 4: A5: "West", B5: "Q2", C5: 1800, D5: "Bob"
+Row 5: A6: "North", B6: "Q1", C6: 800, D6: "Charlie"
+Row 6: A7: "North", B7: "Q2", C7: 950, D7: "Charlie"
+```
+
+<hr/>
+
 ## Row Grouping
 
 Demonstrates outline grouping for rows.
@@ -4357,6 +4486,60 @@ Row 1: A2: "Normal Text" (font=, fill=), B2: "Highlighted Text" (font=Calibri, f
 
 <hr/>
 
+## Table Styles
+
+Visual demonstration for Table Styles.
+
+### Rendered Output (LibreOffice Calc)
+
+<div><img src="../../test/visual/baselines/table_styles/page-1.png" width="100%" alt="Preview"/></div>
+
+<div><img src="../../test/visual/baselines/table_styles/page-2.png" width="100%" alt="Preview"/></div>
+
+### DSL Code
+
+```ruby
+# frozen_string_literal: true
+
+require "xlsxrb"
+
+output_path = ARGV[0] || "table_styles.xlsx"
+
+Xlsxrb.write(output_path) do |wb|
+  wb.sheet("Table Example") do |sheet|
+    sheet.column(0..3, width: 20)
+    sheet.row(%w[ID Name Department Salary])
+    sheet.row([101, "Alice Smith", "Engineering", 120_000])
+    sheet.row([102, "Bob Jones", "Marketing", 95_000])
+    sheet.row([103, "Carol White", "Sales", 110_000])
+    sheet.row([104, "David Brown", "Engineering", 130_000])
+
+    sheet.table("A1:D5", columns: %w[ID Name Department Salary], name: "EmployeeTable", style: "TableStyleMedium9", total_row: false)
+  end
+end
+
+puts "=== Read Validation ==="
+workbook = Xlsxrb.read(output_path).load
+sheet = workbook.sheets.first
+sheet.rows.each do |row|
+  row_cells = row.cells.map { |c| "#{c.ref}: #{c.value.inspect}" }
+  puts "Row #{row.index}: #{row_cells.join(", ")}"
+end
+```
+
+### Console Output
+
+```text
+=== Read Validation ===
+Row 0: A1: "ID", B1: "Name", C1: "Department", D1: "Salary"
+Row 1: A2: 101, B2: "Alice Smith", C2: "Engineering", D2: 120000
+Row 2: A3: 102, B3: "Bob Jones", C3: "Marketing", D3: 95000
+Row 3: A4: 103, B4: "Carol White", C4: "Sales", D4: 110000
+Row 4: A5: 104, B5: "David Brown", C5: "Engineering", D5: 130000
+```
+
+<hr/>
+
 ## View Show Grid Lines
 
 Demonstrates disabling visible grid lines in spreadsheet view.