xlsxrb 0.1.10 → 0.1.12

data/docs/visual/VisualGallery.md

@@ -1136,8 +1136,8 @@ end
 ```text
 === Read Validation ===
 Row 0: A1: "Format" (Format ID: , Code: nil), B1: "Value" (Format ID: , Code: nil)
-Row 1: A2: "Positive Yen" (Format ID: , Code: nil), B2: 12500 (Format ID: 164, Code: "¥#,##0;[Red]¥-#,##0")
-Row 2: A3: "Negative Yen" (Format ID: , Code: nil), B3: -8000 (Format ID: 164, Code: "¥#,##0;[Red]¥-#,##0")
+Row 1: A2: "Positive Yen" (Format ID: , Code: nil), B2: 12500 (Format ID: 166, Code: "¥#,##0;[Red]¥-#,##0")
+Row 2: A3: "Negative Yen" (Format ID: , Code: nil), B3: -8000 (Format ID: 166, Code: "¥#,##0;[Red]¥-#,##0")
 ```
 
 <hr/>
@@ -1187,8 +1187,8 @@ end
 ```text
 === Read Validation ===
 Row 0: A1: "Format" (Format ID: , Code: nil), B1: "Value" (Format ID: , Code: nil)
-Row 1: A2: "Positive (Green)" (Format ID: , Code: nil), B2: 5000 (Format ID: 164, Code: "[Green]#,##0;[Red]-#,##0")
-Row 2: A3: "Negative (Red)" (Format ID: , Code: nil), B3: -2500 (Format ID: 164, Code: "[Green]#,##0;[Red]-#,##0")
+Row 1: A2: "Positive (Green)" (Format ID: , Code: nil), B2: 5000 (Format ID: 166, Code: "[Green]#,##0;[Red]-#,##0")
+Row 2: A3: "Negative (Red)" (Format ID: , Code: nil), B3: -2500 (Format ID: 166, Code: "[Green]#,##0;[Red]-#,##0")
 ```
 
 <hr/>
@@ -1239,9 +1239,9 @@ end
 ```text
 === Read Validation ===
 Row 0: A1: "Format" (Format ID: , Code: nil), B1: "Value" (Format ID: , Code: nil)
-Row 1: A2: "Half" (Format ID: , Code: nil), B2: 0.5 (Format ID: 164, Code: "# ?/?")
-Row 2: A3: "Third" (Format ID: , Code: nil), B3: 0.3333 (Format ID: 164, Code: "# ?/?")
-Row 3: A4: "Quarter" (Format ID: , Code: nil), B4: 0.75 (Format ID: 164, Code: "# ?/?")
+Row 1: A2: "Half" (Format ID: , Code: nil), B2: 0.5 (Format ID: 166, Code: "# ?/?")
+Row 2: A3: "Third" (Format ID: , Code: nil), B3: 0.3333 (Format ID: 166, Code: "# ?/?")
+Row 3: A4: "Quarter" (Format ID: , Code: nil), B4: 0.75 (Format ID: 166, Code: "# ?/?")
 ```
 
 <hr/>
@@ -1290,7 +1290,7 @@ end
 ```text
 === Read Validation ===
 Row 0: A1: "Format" (Format ID: , Code: nil), B1: "Value" (Format ID: , Code: nil)
-Row 1: A2: "Percent with 2 Decimals" (Format ID: , Code: nil), B2: 0.12345 (Format ID: 164, Code: "0.00%")
+Row 1: A2: "Percent with 2 Decimals" (Format ID: , Code: nil), B2: 0.12345 (Format ID: 166, Code: "0.00%")
 ```
 
 <hr/>
@@ -1340,8 +1340,8 @@ end
 ```text
 === Read Validation ===
 Row 0: A1: "Format" (Format ID: , Code: nil), B1: "Value" (Format ID: , Code: nil)
-Row 1: A2: "Scientific" (Format ID: , Code: nil), B2: 123456789.0 (Format ID: 164, Code: "0.00E+00")
-Row 2: A3: "Small Scientific" (Format ID: , Code: nil), B3: 1.234e-05 (Format ID: 164, Code: "0.00E+00")
+Row 1: A2: "Scientific" (Format ID: , Code: nil), B2: 123456789.0 (Format ID: 166, Code: "0.00E+00")
+Row 2: A3: "Small Scientific" (Format ID: , Code: nil), B3: 1.234e-05 (Format ID: 166, Code: "0.00E+00")
 ```
 
 <hr/>
@@ -2867,8 +2867,6 @@ Visual demonstration for Drawing Shapes.
 
 <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
@@ -2880,12 +2878,12 @@ 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.column(0..4, width: 12)
     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)
+    sheet.shape(preset: "rect", text: "Start", from_col: 0, from_row: 2, to_col: 1, to_row: 4)
+    sheet.shape(preset: "rightArrow", text: "Next", from_col: 1, from_row: 3, to_col: 2, to_row: 4)
+    sheet.shape(preset: "roundRect", text: "Processing", from_col: 2, from_row: 2, to_col: 4, to_row: 4)
   end
 end
 
@@ -4082,8 +4080,6 @@ Visual demonstration for Pivot Table.
 
 <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
@@ -4095,7 +4091,7 @@ 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.column(0..3, width: 14)
     sheet.row(%w[Region Quarter Sales Rep])
     sheet.row(["East", "Q1", 1000, "Alice"])
     sheet.row(["West", "Q1", 1500, "Bob"])
@@ -4104,12 +4100,22 @@ Xlsxrb.write(output_path) do |wb|
     sheet.row(["North", "Q1", 800, "Charlie"])
     sheet.row(["North", "Q2", 950, "Charlie"])
 
+    sheet.row([])
+    sheet.row([])
+    # Pre-populate summary cells in the pivot table target region (A10:D15) for headless renderers
+    sheet.row(["Sum of Sales", "Quarter", nil, nil])
+    sheet.row(["Region", "Q1", "Q2", "Grand Total"])
+    sheet.row(["East", 1000, 1200, 2200])
+    sheet.row(["North", 800, 950, 1750])
+    sheet.row(["West", 1500, 1800, 3300])
+    sheet.row(["Grand Total", 3300, 3950, 7250])
+
     sheet.pivot_table(
       "SalesData!A1:D7",
       row_fields: ["Region"],
       data_fields: [{ name: "Sales", subtotal: "sum" }],
       col_fields: ["Quarter"],
-      dest_ref: "F1",
+      dest_ref: "A10",
       name: "RegionalSalesSummary"
     )
   end
@@ -4135,6 +4141,14 @@ 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"
+Row 7: 
+Row 8: 
+Row 9: A10: "Sum of Sales", B10: "Quarter"
+Row 10: A11: "Region", B11: "Q1", C11: "Q2", D11: "Grand Total"
+Row 11: A12: "East", B12: 1000, C12: 1200, D12: 2200
+Row 12: A13: "North", B13: 800, C13: 950, D13: 1750
+Row 13: A14: "West", B14: 1500, C14: 1800, D14: 3300
+Row 14: A15: "Grand Total", B15: 3300, C15: 3950, D15: 7250
 ```
 
 <hr/>
@@ -4494,8 +4508,6 @@ Visual demonstration for Table Styles.
 
 <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
@@ -4507,7 +4519,10 @@ 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.column(0, width: 8)
+    sheet.column(1, width: 16)
+    sheet.column(2, width: 16)
+    sheet.column(3, width: 14)
     sheet.row(%w[ID Name Department Salary])
     sheet.row([101, "Alice Smith", "Engineering", 120_000])
     sheet.row([102, "Bob Jones", "Marketing", 95_000])
@@ -4548,8 +4563,6 @@ Demonstrates disabling visible grid lines in spreadsheet view.
 
 <div><img src="../../test/visual/baselines/view_show_grid_lines/page-1.png" width="100%" alt="Preview"/></div>
 
-<div><img src="../../test/visual/support/illustrations/view_show_grid_lines_page-2.png" width="100%" alt="Preview"/></div>
-
 ### DSL Code
 
 ```ruby
@@ -4593,8 +4606,6 @@ Demonstrates setting custom zoom scale in sheet view (e.g. 150%).
 
 <div><img src="../../test/visual/baselines/view_zoom_scale/page-1.png" width="100%" alt="Preview"/></div>
 
-<div><img src="../../test/visual/support/illustrations/view_zoom_scale_page-2.png" width="100%" alt="Preview"/></div>
-
 ### DSL Code
 
 ```ruby

data/lib/xlsxrb/chart_builder.rb

@@ -80,7 +80,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments for legend styling/layout.
     # @return [Object] The configured legend property.
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def legend(*args, **kwargs)
       @options[:legend] = kwargs.empty? ? args.first : kwargs
     end
@@ -91,7 +91,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments for plot area configuration.
     # @return [Object] The configured plot_area property.
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def plot_area(*args, **kwargs)
       @options[:plot_area] = kwargs.empty? ? args.first : kwargs
     end
@@ -102,7 +102,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object] The configured chart_space property.
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def chart_space(*args, **kwargs)
       @options[:chart_space] = kwargs.empty? ? args.first : kwargs
     end
@@ -113,7 +113,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object] The configured style property.
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String | Integer) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String | Integer)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String | Integer) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String | Integer)
     def style(*args, **kwargs)
       @options[:style] = kwargs.empty? ? args.first : kwargs
     end
@@ -124,7 +124,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object] The configured data_labels property.
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def data_labels(*args, **kwargs)
       @options[:data_labels] = kwargs.empty? ? args.first : kwargs
     end
@@ -135,7 +135,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Boolean, String]
     # @api public
-    #: (*(bool | String) args, **String | Integer | bool | nil kwargs) -> (bool | String)
+    #: (*(bool | String) args, **String | Numeric | bool | nil kwargs) -> (bool | String)
     def plot_visible_only(*args, **kwargs)
       @options[:plot_visible_only] = kwargs.empty? ? args.first : kwargs
     end
@@ -146,7 +146,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [String]
     # @api public
-    #: (*(String) args, **String | Integer | bool | nil kwargs) -> String
+    #: (*(String) args, **String | Numeric | bool | nil kwargs) -> String
     def display_blanks_as(*args, **kwargs)
       @options[:display_blanks_as] = kwargs.empty? ? args.first : kwargs
     end
@@ -157,7 +157,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object]
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def view3d(*args, **kwargs)
       @options[:view3d] = kwargs.empty? ? args.first : kwargs
     end
@@ -168,7 +168,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object]
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def category_axis(*args, **kwargs)
       @options[:category_axis] = kwargs.empty? ? args.first : kwargs
     end
@@ -179,7 +179,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Object]
     # @api public
-    #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+    #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
     def value_axis(*args, **kwargs)
       @options[:value_axis] = kwargs.empty? ? args.first : kwargs
     end
@@ -190,7 +190,7 @@ module Xlsxrb
     # @param kwargs [Hash] Keyword arguments.
     # @return [Boolean, String]
     # @api public
-    #: (*(bool | String) args, **String | Integer | bool | nil kwargs) -> (bool | String)
+    #: (*(bool | String) args, **String | Numeric | bool | nil kwargs) -> (bool | String)
     def show_legend_key(*args, **kwargs)
       @options[:show_legend_key] = kwargs.empty? ? args.first : kwargs
     end
@@ -258,7 +258,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [Object]
       # @api public
-      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
       def fill(*args, **kwargs)
         @options[:fill] = kwargs.empty? ? args.first : kwargs
       end
@@ -269,7 +269,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [Object]
       # @api public
-      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
       def line(*args, **kwargs)
         @options[:line] = kwargs.empty? ? args.first : kwargs
       end
@@ -280,7 +280,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [Object]
       # @api public
-      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
       def trendline(*args, **kwargs)
         @options[:trendline] = kwargs.empty? ? args.first : kwargs
       end
@@ -291,7 +291,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [Object]
       # @api public
-      #: (*(Hash[Symbol, String | Integer | bool | nil] | String) args, **String | Integer | bool | nil kwargs) -> (Hash[Symbol, String | Integer | bool | nil] | String)
+      #: (*(Hash[Symbol, String | Numeric | bool | nil] | String) args, **String | Numeric | bool | nil kwargs) -> (Hash[Symbol, String | Numeric | bool | nil] | String)
       def data_labels(*args, **kwargs)
         @options[:data_labels] = kwargs.empty? ? args.first : kwargs
       end
@@ -302,7 +302,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [Boolean, String]
       # @api public
-      #: (*(bool | String) args, **String | Integer | bool | nil kwargs) -> (bool | String)
+      #: (*(bool | String) args, **String | Numeric | bool | nil kwargs) -> (bool | String)
       def smooth(*args, **kwargs)
         @options[:smooth] = kwargs.empty? ? args.first : kwargs
       end
@@ -313,7 +313,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [String]
       # @api public
-      #: (*(String) args, **String | Integer | bool | nil kwargs) -> String
+      #: (*(String) args, **String | Numeric | bool | nil kwargs) -> String
       def shape(*args, **kwargs)
         @options[:shape] = kwargs.empty? ? args.first : kwargs
       end
@@ -324,7 +324,7 @@ module Xlsxrb
       # @param kwargs [Hash] Keyword arguments.
       # @return [String]
       # @api public
-      #: (*(String) args, **String | Integer | bool | nil kwargs) -> String
+      #: (*(String) args, **String | Numeric | bool | nil kwargs) -> String
       def type(*args, **kwargs)
         @options[:type] = kwargs.empty? ? args.first : kwargs
       end

data/lib/xlsxrb/dsl_helpers.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require_relative "elements/cell"
+require_relative "ooxml/utils"
+
+module Xlsxrb
+  # Internal helper module for normalizing and validating DSL arguments
+  # shared between {WorksheetBuilder} (in-memory) and {StreamWriter} (streaming).
+  #
+  # @api private
+  module DslHelpers
+    # Normalizes merge cell range string or coordinate components into a canonical range reference (e.g. "A1:C3").
+    #
+    # @param range [String, Hash, nil]
+    # @param row [Integer, nil]
+    # @param col_start [Integer, String, nil]
+    # @param col_end [Integer, String, nil]
+    # @param row_start [Integer, nil]
+    # @param row_end [Integer, nil]
+    # @param strict_excel_mode [Boolean]
+    # @return [String]
+    #: (untyped range, ?row: Integer?, ?col_start: (Integer | String)?, ?col_end: (Integer | String)?, ?row_start: Integer?, ?row_end: Integer?, ?strict_excel_mode: bool) -> String
+    def self.normalize_merge_range(range = nil, row: nil, col_start: nil, col_end: nil, row_start: nil, row_end: nil, strict_excel_mode: true)
+      if range.is_a?(Hash)
+        row = range[:row]
+        row_start = range[:row_start]
+        row_end = range[:row_end]
+        col_start = range[:col_start]
+        col_end = range[:col_end]
+        range = nil
+      end
+
+      if range
+        raise ArgumentError, "Invalid merge range format: '#{range}'. Expected format like 'A1:B2'." if strict_excel_mode && !range.match?(/\A[A-Za-z]{1,3}\d+(:[A-Za-z]{1,3}\d+)?\z/)
+
+        range
+      else
+        r_start = row || row_start || 0
+        r_end = row || row_end || 0
+        c_start = Elements::Cell.column_index(col_start || 0)
+        c_end = Elements::Cell.column_index(col_end || 0)
+        start_ref = "#{Elements::Cell.column_letter(c_start)}#{r_start + 1}"
+        end_ref = "#{Elements::Cell.column_letter(c_end)}#{r_end + 1}"
+        "#{start_ref}:#{end_ref}"
+      end
+    end
+
+    # Normalizes sheet protection options and hashes plain-text password if supplied.
+    #
+    # @param opts [Hash]
+    # @return [Hash]
+    #: (Hash[Symbol, untyped] opts) -> Hash[Symbol, untyped]
+    def self.normalize_protection_options(opts)
+      normalized = opts.dup
+      plain_password = normalized[:password]
+      needs_hash = plain_password.is_a?(String) && !plain_password.empty? &&
+                   normalized[:algorithm_name].nil? && normalized[:hash_value].nil? &&
+                   normalized[:salt_value].nil? && normalized[:spin_count].nil? &&
+                   !plain_password.match?(/\A[0-9A-Fa-f]{4}\z/)
+      if needs_hash
+        normalized.delete(:password)
+        normalized.merge!(Ooxml::Utils.hash_password(plain_password))
+      end
+      normalized
+    end
+
+    # Normalizes column index or letter or Range to an array of 0-based column integers.
+    #
+    # @param index [Integer, String, Symbol, Range, Array]
+    # @return [Array<Integer>]
+    #: (untyped index) -> Array[Integer]
+    def self.normalize_column_indices(index)
+      case index
+      when Range, Array
+        index.map { |i| Elements::Cell.column_index(i) }
+      else
+        [Elements::Cell.column_index(index)]
+      end
+    end
+
+    # Normalizes page margins into a compact hash.
+    #
+    # @param left [Float, nil]
+    # @param right [Float, nil]
+    # @param top [Float, nil]
+    # @param bottom [Float, nil]
+    # @param header [Float, nil]
+    # @param footer [Float, nil]
+    # @return [Hash{Symbol => Float}]
+    #: (?left: Float?, ?right: Float?, ?top: Float?, ?bottom: Float?, ?header: Float?, ?footer: Float?) -> Hash[Symbol, Float]
+    def self.normalize_page_margins(left: nil, right: nil, top: nil, bottom: nil, header: nil, footer: nil)
+      { left: left, right: right, top: top, bottom: bottom, header: header, footer: footer }.compact
+    end
+
+    # Normalizes table options hash.
+    #
+    # @param ref [String]
+    # @param columns [Array<String>, Array<Hash>]
+    # @param name [String, nil]
+    # @param display_name [String, nil]
+    # @param style [String, nil]
+    # @param opts [Hash]
+    # @return [Hash]
+    #: (String ref, columns: untyped, ?name: String?, ?display_name: String?, ?style: String?, **untyped opts) -> Hash[Symbol, untyped]
+    def self.normalize_table_options(ref, columns:, name: nil, display_name: nil, style: nil, **opts)
+      tbl = { ref: ref, columns: columns }
+      tbl[:name] = name if name
+      tbl[:display_name] = display_name if display_name
+      tbl[:style] = style if style
+      tbl.merge!(opts)
+      tbl
+    end
+  end
+end