xlsxrb 0.1.9 → 0.1.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>
+    
+    <!-- xlsxtream 3.1.0: 1.19s -->
+    <text x="150" y="85" text-anchor="end" class="label">xlsxtream 3.1.0</text>
+    <rect x="160" y="72" width="6.5" height="18" rx="3" fill="#64748b"/>
+    <text x="174.5" y="85" class="value">1.19 s</text>
+
+    <!-- xlsxrb (Streaming): 1.73s -->
+    <text x="150" y="120" text-anchor="end" class="label-accent">xlsxrb (Streaming)</text>
+    <rect x="160" y="107" width="9.5" height="18" rx="3" fill="#3b82f6"/>
+    <text x="177.5" y="120" class="value">1.73 s</text>
+
+    <!-- fast_excel 0.5.0: 1.89s -->
+    <text x="150" y="155" text-anchor="end" class="label">fast_excel 0.5.0</text>
+    <rect x="160" y="142" width="10.4" height="18" rx="3" fill="#64748b"/>
+    <text x="178.4" y="155" class="value">1.89 s</text>
+
+    <!-- xlsxrb (In-Memory): 3.84s -->
+    <text x="150" y="190" text-anchor="end" class="label-accent">xlsxrb (In-Memory)</text>
+    <rect x="160" y="177" width="21.1" height="18" rx="3" fill="#3b82f6"/>
+    <text x="189.1" y="190" class="value">3.84 s</text>
+
+    <!-- write_xlsx 1.15.0: 4.32s -->
+    <text x="150" y="225" text-anchor="end" class="label">write_xlsx 1.15.0</text>
+    <rect x="160" y="212" width="23.8" height="18" rx="3" fill="#64748b"/>
+    <text x="191.8" y="225" class="value">4.32 s</text>
+
+    <!-- caxlsx 4.5.0: 5.15s -->
+    <text x="150" y="260" text-anchor="end" class="label">caxlsx 4.5.0</text>
+    <rect x="160" y="247" width="28.3" height="18" rx="3" fill="#64748b"/>
+    <text x="196.3" y="260" class="value">5.15 s</text>
+
+    <!-- rubyXL 3.4.38: 38.81s -->
+    <text x="150" y="295" text-anchor="end" class="label">rubyXL 3.4.38</text>
+    <rect x="160" y="282" width="213.5" height="18" rx="3" fill="#64748b"/>
+    <text x="381.5" y="295" class="value">38.81 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): 3.17s -->
+    <text x="150" y="85" text-anchor="end" class="label-accent">xlsxrb (Streaming)</text>
+    <rect x="160" y="72" width="17.4" height="18" rx="3" fill="#3b82f6"/>
+    <text x="185.4" y="85" class="value">3.17 s</text>
+
+    <!-- simple_xlsx_reader: 4.48s -->
+    <text x="150" y="120" text-anchor="end" class="label">simple_xlsx_reader</text>
+    <rect x="160" y="107" width="24.6" height="18" rx="3" fill="#64748b"/>
+    <text x="192.6" y="120" class="value">4.48 s</text>
+
+    <!-- xlsxrb (In-Memory): 5.71s -->
+    <text x="150" y="155" text-anchor="end" class="label-accent">xlsxrb (In-Memory)</text>
+    <rect x="160" y="142" width="31.4" height="18" rx="3" fill="#3b82f6"/>
+    <text x="199.4" y="155" class="value">5.71 s</text>
+
+    <!-- creek 2.6.3: 8.14s -->
+    <text x="150" y="190" text-anchor="end" class="label">creek 2.6.3</text>
+    <rect x="160" y="177" width="44.8" height="18" rx="3" fill="#64748b"/>
+    <text x="212.8" y="190" class="value">8.14 s</text>
+
+    <!-- xsv 1.4.1: 14.61s -->
+    <text x="150" y="225" text-anchor="end" class="label">xsv 1.4.1</text>
+    <rect x="160" y="212" width="80.4" height="18" rx="3" fill="#64748b"/>
+    <text x="248.4" y="225" class="value">14.61 s</text>
+
+    <!-- roo 3.0.0: 15.69s -->
+    <text x="150" y="260" text-anchor="end" class="label">roo 3.0.0</text>
+    <rect x="160" y="247" width="86.3" height="18" rx="3" fill="#64748b"/>
+    <text x="254.3" y="260" class="value">15.69 s</text>
+
+    <!-- rubyXL 3.4.38: 37.13s -->
+    <text x="150" y="295" text-anchor="end" class="label">rubyXL 3.4.38</text>
+    <rect x="160" y="282" width="204.2" height="18" rx="3" fill="#64748b"/>
+    <text x="372.2" y="295" class="value">37.13 s</text>
+  </g>
+
+  <!-- Footer -->
+  <text x="480" y="455" text-anchor="middle" class="footer">Tested on Ruby 3.4+ 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.