xlsxrb 0.1.13 → 0.1.15

data/lib/xlsxrb/worksheet_builder.rb

@@ -11,10 +11,12 @@ module Xlsxrb
   class WorksheetBuilder
     # @param name [String] The worksheet name.
     # @param strict_excel_mode [Boolean] Whether to enforce Microsoft Excel limits.
-    #: (String name, ?strict_excel_mode: bool) -> void
-    def initialize(name, strict_excel_mode: true)
+    # @param state [Symbol] Sheet visibility state (:visible, :hidden, or :very_hidden).
+    #: (String name, ?strict_excel_mode: bool, ?state: Symbol) -> void
+    def initialize(name, strict_excel_mode: true, state: :visible)
       @name = name
       @strict_excel_mode = strict_excel_mode
+      @state = state ? state.to_sym : :visible
       @rows = []
       @columns = []
       @charts = []
@@ -42,10 +44,17 @@ module Xlsxrb
       @shapes = []
       @sheet_properties = {}
       @sheet_view = {}
+      @sheet_format = {}
       @row_breaks = []
       @col_breaks = []
+      @protected_ranges = []
+      @cell_watches = []
+      @print_area = nil
+      @print_titles = nil
     end
 
+    attr_reader :name
+
     # Defines or configures a named cell style.
     #
     # @example Define a bold header style
@@ -81,11 +90,12 @@ module Xlsxrb
     # @param hidden [Boolean] Whether the row is hidden.
     # @param custom_height [Boolean] Whether custom row height is enforced.
     # @param outline_level [Integer, nil] Grouping/outline hierarchy level.
+    # @param collapsed [Boolean] Whether the row is collapsed.
     # @return [void]
     # @raise [ArgumentError] If limits are exceeded when strict_excel_mode is enabled.
     # @api public
-    #: (Array[untyped] | Hash[untyped, untyped] values, ?styles: untyped, ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?outline_level: Integer | nil) -> void
-    def row(values, styles: nil, height: nil, hidden: false, custom_height: false, outline_level: nil)
+    #: (Array[untyped] | Hash[untyped, untyped] values, ?styles: untyped, ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?collapsed: bool, ?outline_level: Integer | nil) -> void
+    def row(values, styles: nil, height: nil, hidden: false, custom_height: false, collapsed: false, outline_level: nil)
       row_index = @rows.size
       DslHelpers.validate_row_bounds!(row_index, height, strict_excel_mode: @strict_excel_mode)
 
@@ -149,6 +159,10 @@ module Xlsxrb
           col_index += 1
           next
         end
+        sb = @styles[style_name]
+        fmt_code = if sb&.num_fmt_id
+                     sb.num_fmt_id.is_a?(String) ? sb.num_fmt_id : Ooxml::Utils::BUILTIN_NUM_FMT_CODES[sb.num_fmt_id]
+                   end
         # If value is a Formula object or Hash with :formula, store it as the cell's formula
         cells[col_index] = if val.is_a?(Elements::Formula)
                              Elements::Cell.new(
@@ -156,7 +170,9 @@ module Xlsxrb
                                column_index: col_index,
                                value: val.cached_value,
                                formula: val,
-                               style_index: style_name
+                               style_index: style_name,
+                               raw_value: val.cached_value&.to_s,
+                               format_code: fmt_code
                              )
                            elsif val.is_a?(Hash) && val.key?(:formula)
                              f_obj = Elements::Formula.new(
@@ -169,14 +185,18 @@ module Xlsxrb
                                column_index: col_index,
                                value: val[:value],
                                formula: f_obj,
-                               style_index: style_name
+                               style_index: style_name,
+                               raw_value: val[:value]&.to_s,
+                               format_code: fmt_code
                              )
                            else
                              Elements::Cell.new(
                                row_index: row_index,
                                column_index: col_index,
                                value: val,
-                               style_index: style_name
+                               style_index: style_name,
+                               raw_value: val&.to_s,
+                               format_code: fmt_code
                              )
                            end
         col_index += 1
@@ -189,9 +209,25 @@ module Xlsxrb
         height: height,
         hidden: hidden,
         custom_height: custom_height || !height.nil?,
+        collapsed: collapsed,
         outline_level: outline_level
       )
     end
+    alias add_row row
+
+    # Appends a row to the worksheet and returns self for chaining.
+    #
+    # @example
+    #   sheet << ["A", 1] << ["B", 2]
+    #
+    # @param values [Array, Hash] Row cell values.
+    # @return [self]
+    # @api public
+    #: (Array[untyped] | Hash[untyped, untyped] values) -> self
+    def <<(values)
+      row(values)
+      self
+    end
 
     # Sets column formatting and properties for one or multiple columns.
     #
@@ -203,23 +239,24 @@ module Xlsxrb
     #
     # @param index [Integer, String, Range, Array] Column index (0-based), letter ("A"), or range ("A".."D").
     # @param width [Float, Integer, nil] Column width in character units (0 to 255).
-    # @param hidden [Boolean] Whether the column is hidden.
-    # @param custom_width [Boolean] Whether custom width is explicitly set.
-    # @param outline_level [Integer, nil] Grouping/outline level.
+    # @param style [Integer, Symbol, String, nil] Column style format or index.
     # @return [void]
     # @raise [ArgumentError] If width exceeds 255 in strict mode.
     # @api public
-    #: (Integer | String | Range[Integer | String] | Array[Integer | String] index, ?width: Float | Integer | nil, ?hidden: bool, ?custom_width: bool, ?outline_level: Integer | nil) -> void
-    def column(index, width: nil, hidden: false, custom_width: false, outline_level: nil)
+    #: (Integer | String | Range[Integer | String] | Array[Integer | String] index, ?width: Float | Integer | nil, ?hidden: bool, ?custom_width: bool, ?outline_level: Integer | nil, ?style: (Integer | Symbol | String)?) -> void
+    def column(index, width: nil, hidden: false, custom_width: false, outline_level: nil, style: nil)
       raise ArgumentError, "Column width #{width} must be between 0 and 255 characters (Excel limitation)" if @strict_excel_mode && width && (width.negative? || width > 255)
 
       DslHelpers.normalize_column_indices(index).each do |idx|
+        unmapped = style ? { style_index: style } : {}
         @columns << Elements::Column.new(
           index: idx,
           width: width,
           hidden: hidden,
           custom_width: custom_width || !width.nil?,
-          outline_level: outline_level
+          outline_level: outline_level,
+          style_index: style,
+          unmapped_data: unmapped
         )
       end
     end
@@ -250,8 +287,17 @@ module Xlsxrb
     # @param location [String, nil] Optional internal sheet location (e.g. "Sheet2!A1").
     # @return [void]
     # @api public
-    #: (String | Integer cell, ?String? url, ?display: String?, ?tooltip: String?, ?location: String?) -> void
+    #: (String | Integer cell, ?(String | Elements::Hyperlink)? url, ?display: String?, ?tooltip: String?, ?location: String?) -> void
     def hyperlink(cell, url = nil, display: nil, tooltip: nil, location: nil)
+      if url.is_a?(Elements::Hyperlink)
+        link = { cell: cell }
+        link[:url] = url.url if url.url
+        link[:display] = url.display || display if url.display || display
+        link[:tooltip] = url.tooltip || tooltip if url.tooltip || tooltip
+        link[:location] = url.location || location if url.location || location
+        @hyperlinks << link
+        return
+      end
       link = { cell: cell }
       link[:url] = url if url
       link[:display] = display if display
@@ -295,12 +341,21 @@ module Xlsxrb
 
     # Adds a data validation rule to a cell or range.
     #
-    # @param sqref [String] Target cell or range reference (e.g. "B2:B100").
+    # @param sqref [String, nil] Target cell or range reference (e.g. "B2:B100").
     # @param opts [Hash] Validation configuration (e.g. type: :list, formula1: '"Option1,Option2"').
+    # @yield [data_validation_builder] Optional configuration block.
     # @return [void]
     # @api public
-    #: (String sqref, **untyped opts) -> void
-    def validate_data(sqref, **opts)
+    #: (?String? sqref, **untyped opts) ?{ (DataValidationBuilder) -> void } -> void
+    def validate_data(sqref = nil, **opts)
+      if block_given?
+        builder = DataValidationBuilder.new(sqref, **opts)
+        yield builder
+        opts = builder.to_h
+        sqref = opts.delete(:sqref) || sqref
+      end
+      raise ArgumentError, "data validation sqref must be provided" unless sqref
+
       @data_validations << opts.merge(sqref: sqref)
     end
 
@@ -317,17 +372,32 @@ module Xlsxrb
 
     # Adds an Excel Table (ListObject) to the sheet.
     #
-    # @param ref [String] The table range (e.g. "A1:D20").
-    # @param columns [Array<String>] Column header names.
+    # @param ref [String, nil] The table range (e.g. "A1:D20").
+    # @param columns [Array<String>, nil] Column header names.
     # @param name [String, nil] Table name identifier.
     # @param display_name [String, nil] Table display name.
     # @param style [String, nil] Built-in table style name (e.g. "TableStyleMedium2").
     # @param opts [Hash] Additional table properties.
+    # @yield [table_builder] Optional configuration block.
     # @return [void]
     # @api public
-    #: (String ref, columns: Array[String | Hash[Symbol, untyped]], ?name: String?, ?display_name: String?, ?style: String?, **untyped opts) -> void
-    def table(ref, columns:, name: nil, display_name: nil, style: nil, **)
-      @tables << DslHelpers.normalize_table_options(ref, columns: columns, name: name, display_name: display_name, style: style, **)
+    #: (?String? ref, ?columns: Array[String | Hash[Symbol, untyped]]?, ?name: String?, ?display_name: String?, ?style: String?, **untyped opts) ?{ (TableBuilder) -> void } -> void
+    def table(ref = nil, columns: nil, name: nil, display_name: nil, style: nil, **opts)
+      opts = opts.dup
+      if block_given?
+        builder = TableBuilder.new(ref, columns: columns, name: name, display_name: display_name, style: style, **opts)
+        yield builder
+        opts = builder.to_h
+        ref = opts.delete(:ref) || ref
+        columns = opts.delete(:columns) || columns
+        name = opts.delete(:name) || name
+        display_name = opts.delete(:display_name) || display_name
+        style = opts.delete(:style) || style
+      end
+      raise ArgumentError, "table ref must be provided" unless ref
+      raise ArgumentError, "table columns must be provided" if columns.nil?
+
+      @tables << DslHelpers.normalize_table_options(ref, columns: columns, name: name, display_name: display_name, style: style, **opts)
     end
 
     # Adds a Pivot Table to the sheet.
@@ -380,6 +450,38 @@ module Xlsxrb
       @sparkline_groups << group
     end
 
+    # Adds a single sparkline to the sheet.
+    #
+    # @example Add a line sparkline
+    #   sheet.add_sparkline(location: "F1", range: "A1:E1")
+    #
+    # @example Add a column sparkline with high/low markers
+    #   sheet.add_sparkline(location: "F2", range: "A2:E2", type: :column, high: true, low: true)
+    #
+    # @example Add a win/loss sparkline
+    #   sheet.add_sparkline(location: "F3", range: "A3:E3", type: :win_loss)
+    #
+    # @param location [String, nil] Target cell for the sparkline (e.g. "F1").
+    # @param range [String, nil] Data range for the sparkline (e.g. "A1:E1").
+    # @param type [Symbol, String, nil] Sparkline type (:line, :column, :win_loss / :stacked).
+    # @param opts [Hash] Additional sparkline options.
+    # @return [void]
+    # @api public
+    #: (?location: String?, ?range: String?, ?type: (String | Symbol)?, **untyped opts) -> void
+    def add_sparkline(location: nil, range: nil, type: nil, **opts)
+      loc = location || opts.delete(:location_ref)
+      rng = range || opts.delete(:data_ref) || opts.delete(:data)
+      raise ArgumentError, "Missing required location: parameter for sparkline" unless loc
+      raise ArgumentError, "Missing required range: parameter for sparkline" unless rng
+
+      mapped_type = case type&.to_s
+                    when "win_loss" then "stacked"
+                    when nil, "" then nil
+                    else type.to_s
+                    end
+      sparkline_group(sparklines: [{ data_ref: rng.to_s, location_ref: loc.to_s }], type: mapped_type, **opts)
+    end
+
     # Merges a range of cells into a single cell.
     #
     # @example Merge with string range
@@ -492,6 +594,98 @@ module Xlsxrb
       @print_options[name] = value
     end
 
+    # Sets or gets the print area for the worksheet.
+    #
+    # @example Set print area range
+    #   sheet.print_area("A1:H50")
+    #
+    # @example Get print area range
+    #   sheet.print_area #=> "A1:H50"
+    #
+    # @param range [String, nil] Cell range (e.g. "A1:H50").
+    # @return [String, nil]
+    # @api public
+    #: (?String? range) -> String?
+    def print_area(range = nil)
+      return @print_area if range.nil?
+
+      @print_area = range
+    end
+
+    # Sets or gets repeating print titles (rows and/or columns) for pagination.
+    #
+    # @example Set repeating header rows
+    #   sheet.print_titles(rows: "1:2")
+    #
+    # @example Get repeating print titles
+    #   sheet.print_titles #=> { rows: "1:2", cols: nil }
+    #
+    # @param rows [String, nil] Repeating row range (e.g. "1:2").
+    # @param cols [String, nil] Repeating column range (e.g. "A:B").
+    # @return [Hash, nil]
+    # @api public
+    #: (?rows: String?, ?cols: String?) -> Hash[Symbol, untyped]?
+    def print_titles(rows: nil, cols: nil)
+      return @print_titles if rows.nil? && cols.nil?
+
+      @print_titles = { rows: rows, cols: cols }
+    end
+
+    # Sets repeating title rows to appear at the top of each printed page.
+    # Accepts 0-indexed row numbers (WriteXLSX / xlsxrb convention) or Excel range string ("1:2").
+    #
+    # @example Repeat first row
+    #   sheet.repeat_rows(0)
+    #
+    # @example Repeat rows 1 through 3
+    #   sheet.repeat_rows(0, 2)
+    #
+    # @param first [Integer, String] First row index (0-based) or range string (e.g. "1:2").
+    # @param last [Integer, String, nil] Optional last row index (0-based, defaults to first).
+    # @return [void]
+    # @api public
+    #: (Integer | String first, ?(Integer | String)? last) -> void
+    def repeat_rows(first, last = nil)
+      rows_str = if first.is_a?(String)
+                   first.include?(":") ? first : "#{first}:#{last || first}"
+                 else
+                   last ||= first
+                   "#{first + 1}:#{last + 1}"
+                 end
+      @print_titles = (@print_titles || {}).merge(rows: rows_str)
+    end
+
+    # Sets repeating title columns to appear at the left of each printed page.
+    # Accepts 0-indexed column numbers (0 => "A"), column names ("A", "B"), or range string ("A:B").
+    #
+    # @example Repeat column A
+    #   sheet.repeat_columns(0)
+    #
+    # @example Repeat columns A through C
+    #   sheet.repeat_columns("A", "C")
+    #
+    # @param first [Integer, String] First column index (0-based) or column name/range.
+    # @param last [Integer, String, nil] Optional last column index/name (defaults to first).
+    # @return [void]
+    # @api public
+    #: (Integer | String first, ?(Integer | String)? last) -> void
+    def repeat_columns(first, last = nil)
+      cols_str = if first.is_a?(String)
+                   first.include?(":") ? first : "#{first}:#{last || first}"
+                 else
+                   first_name = Utils.col_index_to_name(first)
+                   last_name = if last.is_a?(Integer)
+                                 Utils.col_index_to_name(last)
+                               elsif last
+                                 last.to_s
+                               else
+                                 first_name
+                               end
+                   "#{first_name}:#{last_name}"
+                 end
+      @print_titles = (@print_titles || {}).merge(cols: cols_str)
+    end
+
     # Sets sheet-level protection with optional password hashing.
     #
     # @param opts [Hash] Protection options (e.g. password: "secret", select_locked_cells: true).
@@ -561,6 +755,30 @@ module Xlsxrb
       @sheet_view[name] = value
     end
 
+    # Configures sheet format properties (e.g. default_row_height, default_col_width).
+    #
+    # @example Using keyword arguments
+    #   sheet.sheet_format(default_row_height: 24, default_col_width: 15)
+    #
+    # @example Using property name and value
+    #   sheet.sheet_format(:default_row_height, 24)
+    #
+    # @param name [Symbol, String, Hash, nil] Property name or hash of properties.
+    # @param value [Object, nil] Property value when name is provided.
+    # @param opts [Hash] Keyword arguments for sheet format properties.
+    # @return [Hash]
+    # @api public
+    #: (?Symbol | String | Hash[Symbol, untyped] | nil name, ?untyped value, **untyped opts) -> Hash[Symbol, untyped]
+    def sheet_format(name = nil, value = nil, **opts)
+      if name.is_a?(Hash)
+        @sheet_format.merge!(name)
+      elsif name && value
+        @sheet_format[name.to_sym] = value
+      end
+      @sheet_format.merge!(opts) unless opts.empty?
+      @sheet_format
+    end
+
     # Inserts a horizontal page break before the specified row.
     #
     # @param row_num [Integer] 1-based row number.
@@ -582,6 +800,34 @@ module Xlsxrb
       @col_breaks << col_index
     end
 
+    # Adds a protected range to the worksheet.
+    #
+    # @param name [String] Name of the protected range.
+    # @param sqref [String] Cell range (e.g. "A1:B10").
+    # @param password [String, nil] Optional password or hash.
+    # @param opts [Hash] Additional options.
+    # @return [void]
+    # @api public
+    #: (String name, String sqref, ?password: String?, **untyped opts) -> void
+    def protected_range(name, sqref, password: nil, **opts)
+      entry = { name: name.to_s, sqref: sqref.to_s }
+      entry[:password] = password if password
+      entry.merge!(opts) unless opts.empty?
+      @protected_ranges << DslHelpers.normalize_protection_options(entry)
+    end
+    alias add_protected_range protected_range
+
+    # Adds a cell watch to the worksheet.
+    #
+    # @param ref [String] Cell reference (e.g. "A1").
+    # @return [void]
+    # @api public
+    #: (String ref) -> void
+    def cell_watch(ref)
+      @cell_watches << ref.to_s
+    end
+    alias add_cell_watch cell_watch
+
     # Builds and returns the in-memory {Elements::Worksheet}.
     #
     # @return [Elements::Worksheet]
@@ -611,13 +857,77 @@ module Xlsxrb
       facade_meta[:images] = @images unless @images.empty?
       facade_meta[:shapes] = @shapes unless @shapes.empty?
       facade_meta[:sheet_properties] = @sheet_properties unless @sheet_properties.empty?
+      facade_meta[:sheet_format] = @sheet_format unless @sheet_format.empty?
       facade_meta[:sheet_view] = @sheet_view unless @sheet_view.empty?
       facade_meta[:row_breaks] = @row_breaks unless @row_breaks.empty?
       facade_meta[:col_breaks] = @col_breaks unless @col_breaks.empty?
+      facade_meta[:protected_ranges] = @protected_ranges unless @protected_ranges.empty?
+      facade_meta[:cell_watches] = @cell_watches unless @cell_watches.empty?
+      facade_meta[:print_area] = @print_area if @print_area
+      facade_meta[:print_titles] = @print_titles if @print_titles
+
+      hl_hash = {}
+      @hyperlinks.each do |h|
+        ref = h[:cell].to_s.upcase
+        entry = {}
+        entry[:url] = h[:url] if h[:url]
+        entry[:display] = h[:display] if h[:display]
+        entry[:tooltip] = h[:tooltip] if h[:tooltip]
+        entry[:location] = h[:location] if h[:location]
+        hl_hash[ref] = entry unless entry.empty?
+      end
+
+      cm_hash = {}
+      @comments.each do |c|
+        ref = (c[:ref] || c[:cell]).to_s.upcase
+        cm_hash[ref] = c
+      end
+
+      rows = if hl_hash.empty? && cm_hash.empty?
+               @rows
+             else
+               @rows.map do |row|
+                 new_cells = row.cells.map do |cell|
+                   hl = hl_hash[cell.ref]
+                   cm = cm_hash[cell.ref]
+                   if hl || cm
+                     cell.with(hyperlink: hl || cell.hyperlink, comment: cm || cell.comment)
+                   else
+                     cell
+                   end
+                 end
+                 row.with(cells: new_cells)
+               end
+             end
 
       Elements::Worksheet.new(
-        name: @name, rows: @rows, columns: @columns, charts: @charts,
-        unmapped_data: facade_meta.empty? ? {} : { facade: facade_meta }
+        name: @name, rows: rows, columns: @columns, charts: @charts,
+        conditional_formatting: @conditional_formats,
+        data_validations: @data_validations,
+        unmapped_data: facade_meta.empty? ? {} : { facade: facade_meta },
+        state: @state,
+        hyperlinks: hl_hash,
+        comments: @comments,
+        print_area: @print_area,
+        print_titles: @print_titles,
+        sparkline_groups: @sparkline_groups,
+        merged_cells: @merge_cells_ranges,
+        auto_filter: @auto_filter,
+        tables: @tables,
+        shapes: @shapes,
+        freeze_pane: @freeze_pane,
+        page_setup: @page_setup,
+        page_margins: @page_margins,
+        header_footer: @header_footer,
+        print_options: @print_options,
+        sheet_protection: @sheet_protection,
+        sheet_view: @sheet_view,
+        sheet_properties: @sheet_properties,
+        sheet_format: @sheet_format,
+        row_breaks: @row_breaks,
+        col_breaks: @col_breaks,
+        protected_ranges: @protected_ranges,
+        cell_watches: @cell_watches
       )
     end
 
@@ -626,4 +936,408 @@ module Xlsxrb
     #: Hash[String, StyleBuilder]
     attr_reader :styles
   end
+
+  # Builder context for configuring an Excel Table (ListObject) in block form.
+  #
+  # @api public
+  class TableBuilder
+    # @param ref [String, nil] Table range (e.g. "A1:D10").
+    # @param columns [Array, nil] Column header names or definition hashes.
+    # @param name [String, nil] Table name identifier.
+    # @param display_name [String, nil] Table display name.
+    # @param style [String, nil] Built-in table style name (e.g. "TableStyleMedium2").
+    # @param opts [Hash] Additional table properties.
+    #: (?String? ref, ?columns: untyped, ?name: String?, ?display_name: String?, ?style: String?, **untyped opts) -> void
+    def initialize(ref = nil, columns: nil, name: nil, display_name: nil, style: nil, **opts)
+      @options = opts.dup
+      @options[:ref] = ref if ref
+      @options[:columns] = columns.is_a?(Array) ? columns.dup : [columns] if columns
+      @options[:name] = name if name
+      @options[:display_name] = display_name if display_name
+      @options[:style] = style if style
+    end
+
+    #: (untyped key) -> untyped
+    def [](key)
+      @options[key.to_sym]
+    end
+
+    #: (untyped key, untyped value) -> untyped
+    def []=(key, value)
+      @options[key.to_sym] = value
+    end
+
+    #: (?String? val) -> String?
+    def ref(val = nil)
+      if val
+        @options[:ref] = val.to_s
+      else
+        @options[:ref]
+      end
+    end
+
+    #: (String val) -> String
+    def ref=(val)
+      @options[:ref] = val.to_s
+    end
+
+    #: (*untyped cols) -> untyped
+    def columns(*cols)
+      if cols.empty?
+        @options[:columns]
+      elsif cols.size == 1 && cols.first.is_a?(Array)
+        @options[:columns] = cols.first
+      else
+        @options[:columns] = cols
+      end
+    end
+
+    #: (untyped cols) -> untyped
+    def columns=(cols)
+      @options[:columns] = cols.is_a?(Array) ? cols : [cols]
+    end
+
+    # Appends a single column name or column definition.
+    #
+    # @param col [String, Hash] Column header name or definition.
+    # @return [void]
+    #: (String | Hash[Symbol, untyped] col) -> void
+    def column(col)
+      (@options[:columns] ||= []) << col
+    end
+    alias add_column column
+
+    #: (?String? val) -> String?
+    def name(val = nil)
+      if val
+        @options[:name] = val.to_s
+      else
+        @options[:name]
+      end
+    end
+
+    #: (String val) -> String
+    def name=(val)
+      @options[:name] = val.to_s
+    end
+
+    #: (?String? val) -> String?
+    def display_name(val = nil)
+      if val
+        @options[:display_name] = val.to_s
+      else
+        @options[:display_name]
+      end
+    end
+
+    #: (String val) -> String
+    def display_name=(val)
+      @options[:display_name] = val.to_s
+    end
+
+    #: (?String? val) -> String?
+    def style(val = nil)
+      if val
+        @options[:style] = val.to_s
+      else
+        @options[:style]
+      end
+    end
+
+    #: (String val) -> String
+    def style=(val)
+      @options[:style] = val.to_s
+    end
+
+    #: (?bool? val) -> bool?
+    def show_row_stripes(val = nil)
+      if val.nil?
+        @options[:show_row_stripes]
+      else
+        @options[:show_row_stripes] = val ? true : false
+      end
+    end
+
+    #: (bool val) -> bool
+    def show_row_stripes=(val)
+      @options[:show_row_stripes] = val ? true : false
+    end
+
+    #: (?bool? val) -> bool?
+    def show_column_stripes(val = nil)
+      if val.nil?
+        @options[:show_column_stripes]
+      else
+        @options[:show_column_stripes] = val ? true : false
+      end
+    end
+
+    #: (bool val) -> bool
+    def show_column_stripes=(val)
+      @options[:show_column_stripes] = val ? true : false
+    end
+
+    #: (?bool? val) -> bool?
+    def show_first_column(val = nil)
+      if val.nil?
+        @options[:show_first_column]
+      else
+        @options[:show_first_column] = val ? true : false
+      end
+    end
+
+    #: (bool val) -> bool
+    def show_first_column=(val)
+      @options[:show_first_column] = val ? true : false
+    end
+
+    #: (?bool? val) -> bool?
+    def show_last_column(val = nil)
+      if val.nil?
+        @options[:show_last_column]
+      else
+        @options[:show_last_column] = val ? true : false
+      end
+    end
+
+    #: (bool val) -> bool
+    def show_last_column=(val)
+      @options[:show_last_column] = val ? true : false
+    end
+
+    #: (?Integer? val) -> Integer?
+    def total_row_count(val = nil)
+      if val.nil?
+        @options[:total_row_count]
+      else
+        @options[:total_row_count] = val.to_i
+      end
+    end
+
+    #: (Integer val) -> Integer
+    def total_row_count=(val)
+      @options[:total_row_count] = val.to_i
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      @options.dup
+    end
+  end
+
+  # Builder context for configuring data validation rules in block form.
+  #
+  # @api public
+  class DataValidationBuilder
+    # @param sqref [String, nil] Target cell or range reference.
+    # @param opts [Hash] Additional validation properties.
+    #: (?String? sqref, **untyped opts) -> void
+    def initialize(sqref = nil, **opts)
+      @options = opts.dup
+      @options[:sqref] = sqref if sqref
+    end
+
+    #: (untyped key) -> untyped
+    def [](key)
+      @options[key.to_sym]
+    end
+
+    #: (untyped key, untyped value) -> untyped
+    def []=(key, value)
+      @options[key.to_sym] = value
+    end
+
+    #: (?String? val) -> String?
+    def sqref(val = nil)
+      if val
+        @options[:sqref] = val.to_s
+      else
+        @options[:sqref]
+      end
+    end
+
+    #: (String val) -> String
+    def sqref=(val)
+      @options[:sqref] = val.to_s
+    end
+    alias range sqref
+    alias range= sqref=
+
+    #: (?untyped val) -> untyped
+    def type(val = nil)
+      if val
+        @options[:type] = val
+      else
+        @options[:type]
+      end
+    end
+
+    #: (untyped val) -> untyped
+    def type=(val)
+      @options[:type] = val
+    end
+
+    #: (?untyped val) -> untyped
+    def operator(val = nil)
+      if val
+        @options[:operator] = val
+      else
+        @options[:operator]
+      end
+    end
+
+    #: (untyped val) -> untyped
+    def operator=(val)
+      @options[:operator] = val
+    end
+
+    #: (?untyped val) -> untyped
+    def formula1(val = nil)
+      if val
+        @options[:formula1] = val
+      else
+        @options[:formula1]
+      end
+    end
+
+    #: (untyped val) -> untyped
+    def formula1=(val)
+      @options[:formula1] = val
+    end
+
+    #: (?untyped val) -> untyped
+    def formula2(val = nil)
+      if val
+        @options[:formula2] = val
+      else
+        @options[:formula2]
+      end
+    end
+
+    #: (untyped val) -> untyped
+    def formula2=(val)
+      @options[:formula2] = val
+    end
+
+    #: (?bool? val) -> bool?
+    def allow_blank(val = nil)
+      if val.nil?
+        @options[:allow_blank]
+      else
+        @options[:allow_blank] = val ? true : false
+      end
+    end
+
+    #: (bool val) -> bool
+    def allow_blank=(val)
+      @options[:allow_blank] = val ? true : false
+    end
+
+    #: (?bool? val) -> bool?
+    def show_input_message(val = nil)
+      if val.nil?
+        @options[:show_input_message]
+      else
+        @options[:show_input_message] = val ? true : false
+      end
+    end
+
+    #: (bool val) -> bool
+    def show_input_message=(val)
+      @options[:show_input_message] = val ? true : false
+    end
+
+    #: (?bool? val) -> bool?
+    def show_error_message(val = nil)
+      if val.nil?
+        @options[:show_error_message]
+      else
+        @options[:show_error_message] = val ? true : false
+      end
+    end
+
+    #: (bool val) -> bool
+    def show_error_message=(val)
+      @options[:show_error_message] = val ? true : false
+    end
+
+    #: (?String? val) -> String?
+    def error_title(val = nil)
+      if val
+        @options[:error_title] = val.to_s
+      else
+        @options[:error_title]
+      end
+    end
+
+    #: (String val) -> String
+    def error_title=(val)
+      @options[:error_title] = val.to_s
+    end
+
+    #: (?String? val) -> String?
+    def error_message(val = nil)
+      if val
+        @options[:error] = val.to_s
+      else
+        @options[:error]
+      end
+    end
+
+    #: (String val) -> String
+    def error_message=(val)
+      @options[:error] = val.to_s
+    end
+    alias error error_message
+    alias error= error_message=
+
+    #: (?String? val) -> String?
+    def prompt_title(val = nil)
+      if val
+        @options[:prompt_title] = val.to_s
+      else
+        @options[:prompt_title]
+      end
+    end
+
+    #: (String val) -> String
+    def prompt_title=(val)
+      @options[:prompt_title] = val.to_s
+    end
+
+    #: (?String? val) -> String?
+    def prompt_message(val = nil)
+      if val
+        @options[:prompt] = val.to_s
+      else
+        @options[:prompt]
+      end
+    end
+
+    #: (String val) -> String
+    def prompt_message=(val)
+      @options[:prompt] = val.to_s
+    end
+    alias prompt prompt_message
+    alias prompt= prompt_message=
+
+    #: (?untyped val) -> untyped
+    def error_style(val = nil)
+      if val
+        @options[:error_style] = val
+      else
+        @options[:error_style]
+      end
+    end
+
+    #: (untyped val) -> untyped
+    def error_style=(val)
+      @options[:error_style] = val
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      @options.dup
+    end
+  end
 end