xlsxrb 0.1.13 → 0.1.15

data/sig/generated/xlsxrb/workbook_builder.rbs

@@ -75,6 +75,32 @@ module Xlsxrb
     # : (?rows: String?, ?cols: String?, ?sheet: String?) -> void
     def print_titles: (?rows: String?, ?cols: String?, ?sheet: String?) -> void
 
+    # Sets repeating title rows for pagination on the target or active sheet.
+    #
+    # @example Repeat first row
+    #   wb.repeat_rows(0)
+    #
+    # @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).
+    # @param sheet [String, nil] Target sheet name.
+    # @return [void]
+    # @api public
+    # : (Integer | String first, ?(Integer | String)? last, ?sheet: String?) -> void
+    def repeat_rows: (Integer | String first, ?(Integer | String)? last, ?sheet: String?) -> void
+
+    # Sets repeating title columns for pagination on the target or active sheet.
+    #
+    # @example Repeat columns A through C
+    #   wb.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.
+    # @param sheet [String, nil] Target sheet name.
+    # @return [void]
+    # @api public
+    # : (Integer | String first, ?(Integer | String)? last, ?sheet: String?) -> void
+    def repeat_columns: (Integer | String first, ?(Integer | String)? last, ?sheet: String?) -> void
+
     # Sets workbook structure and window protection.
     #
     # @param opts [Hash] Protection options (e.g. lock_structure: true, password: "secret").

data/sig/generated/xlsxrb/worksheet_builder.rbs

@@ -7,8 +7,11 @@ 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: (String name, ?strict_excel_mode: bool) -> void
+    # @param state [Symbol] Sheet visibility state (:visible, :hidden, or :very_hidden).
+    # : (String name, ?strict_excel_mode: bool, ?state: Symbol) -> void
+    def initialize: (String name, ?strict_excel_mode: bool, ?state: Symbol) -> void
+
+    attr_reader name: untyped
 
     # Defines or configures a named cell style.
     #
@@ -38,11 +41,25 @@ 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: (Array[untyped] | Hash[untyped, untyped] values, ?styles: untyped, ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?outline_level: Integer | nil) -> void
+    # : (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: (Array[untyped] | Hash[untyped, untyped] values, ?styles: untyped, ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?collapsed: bool, ?outline_level: Integer | nil) -> void
+
+    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 <<: (Array[untyped] | Hash[untyped, untyped] values) -> self
 
     # Sets column formatting and properties for one or multiple columns.
     #
@@ -54,14 +71,12 @@ 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: (Integer | String | Range[Integer | String] | Array[Integer | String] index, ?width: Float | Integer | nil, ?hidden: bool, ?custom_width: bool, ?outline_level: Integer | nil) -> void
+    # : (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: (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
 
     # Adds a chart to the worksheet.
     #
@@ -82,8 +97,8 @@ 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
-    def hyperlink: (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: (String | Integer cell, ?(String | Elements::Hyperlink)? url, ?display: String?, ?tooltip: String?, ?location: String?) -> void
 
     # Sets an auto-filter range on the sheet.
     #
@@ -114,12 +129,13 @@ 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: (String sqref, **untyped opts) -> void
+    # : (?String? sqref, **untyped opts) ?{ (DataValidationBuilder) -> void } -> void
+    def validate_data: (?String? sqref, **untyped opts) ?{ (DataValidationBuilder) -> void } -> void
 
     # Adds a conditional formatting rule to a cell range.
     #
@@ -132,16 +148,17 @@ 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: (String ref, columns: Array[String | Hash[Symbol, untyped]], ?name: String?, ?display_name: String?, ?style: String?, **untyped opts) -> void
+    # : (?String? ref, ?columns: Array[String | Hash[Symbol, untyped]]?, ?name: String?, ?display_name: String?, ?style: String?, **untyped opts) ?{ (TableBuilder) -> void } -> void
+    def table: (?String? ref, ?columns: Array[String | Hash[Symbol, untyped]]?, ?name: String?, ?display_name: String?, ?style: String?, **untyped opts) ?{ (TableBuilder) -> void } -> void
 
     # Adds a Pivot Table to the sheet.
     #
@@ -178,6 +195,26 @@ module Xlsxrb
     # : (sparklines: Array[String | Hash[Symbol, untyped]], ?type: (String | Symbol)?, **untyped opts) -> void
     def sparkline_group: (sparklines: Array[String | Hash[Symbol, untyped]], ?type: (String | Symbol)?, **untyped opts) -> void
 
+    # 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: String?, ?range: String?, ?type: (String | Symbol)?, **untyped opts) -> void
+
     # Merges a range of cells into a single cell.
     #
     # @example Merge with string range
@@ -264,6 +301,67 @@ module Xlsxrb
     # : (Symbol name, untyped value) -> void
     def print_options: (Symbol name, untyped value) -> void
 
+    # 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: (?String? range) -> String?
+
+    # 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: String?, ?cols: String?) -> Hash[Symbol, untyped]?
+
+    # 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: (Integer | String first, ?(Integer | String)? last) -> void
+
+    # 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: (Integer | String first, ?(Integer | String)? last) -> void
+
     # Sets sheet-level protection with optional password hashing.
     #
     # @param opts [Hash] Protection options (e.g. password: "secret", select_locked_cells: true).
@@ -318,6 +416,22 @@ module Xlsxrb
     # : (Symbol name, untyped value) -> void
     def sheet_view: (Symbol name, untyped value) -> void
 
+    # 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: (?Symbol | String | Hash[Symbol, untyped] | nil name, ?untyped value, **untyped opts) -> Hash[Symbol, untyped]
+
     # Inserts a horizontal page break before the specified row.
     #
     # @param row_num [Integer] 1-based row number.
@@ -334,6 +448,29 @@ module Xlsxrb
     # : (Integer | String col_index) -> void
     def page_break_col: (Integer | String col_index) -> void
 
+    # 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: (String name, String sqref, ?password: String?, **untyped opts) -> void
+
+    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: (String ref) -> void
+
+    alias add_cell_watch cell_watch
+
     # Builds and returns the in-memory {Elements::Worksheet}.
     #
     # @return [Elements::Worksheet]
@@ -346,4 +483,205 @@ module Xlsxrb
     # : Hash[String, StyleBuilder]
     attr_reader styles: untyped
   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: (?String? ref, ?columns: untyped, ?name: String?, ?display_name: String?, ?style: String?, **untyped opts) -> void
+
+    # : (untyped key) -> untyped
+    def []: (untyped key) -> untyped
+
+    # : (untyped key, untyped value) -> untyped
+    def []=: (untyped key, untyped value) -> untyped
+
+    # : (?String? val) -> String?
+    def ref: (?String? val) -> String?
+
+    # : (String val) -> String
+    def ref=: (String val) -> String
+
+    # : (*untyped cols) -> untyped
+    def columns: (*untyped cols) -> untyped
+
+    # : (untyped cols) -> untyped
+    def columns=: (untyped cols) -> untyped
+
+    # 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: (String | Hash[Symbol, untyped] col) -> void
+
+    alias add_column column
+
+    # : (?String? val) -> String?
+    def name: (?String? val) -> String?
+
+    # : (String val) -> String
+    def name=: (String val) -> String
+
+    # : (?String? val) -> String?
+    def display_name: (?String? val) -> String?
+
+    # : (String val) -> String
+    def display_name=: (String val) -> String
+
+    # : (?String? val) -> String?
+    def style: (?String? val) -> String?
+
+    # : (String val) -> String
+    def style=: (String val) -> String
+
+    # : (?bool? val) -> bool?
+    def show_row_stripes: (?bool? val) -> bool?
+
+    # : (bool val) -> bool
+    def show_row_stripes=: (bool val) -> bool
+
+    # : (?bool? val) -> bool?
+    def show_column_stripes: (?bool? val) -> bool?
+
+    # : (bool val) -> bool
+    def show_column_stripes=: (bool val) -> bool
+
+    # : (?bool? val) -> bool?
+    def show_first_column: (?bool? val) -> bool?
+
+    # : (bool val) -> bool
+    def show_first_column=: (bool val) -> bool
+
+    # : (?bool? val) -> bool?
+    def show_last_column: (?bool? val) -> bool?
+
+    # : (bool val) -> bool
+    def show_last_column=: (bool val) -> bool
+
+    # : (?Integer? val) -> Integer?
+    def total_row_count: (?Integer? val) -> Integer?
+
+    # : (Integer val) -> Integer
+    def total_row_count=: (Integer val) -> Integer
+
+    # : () -> Hash[Symbol, untyped]
+    def to_h: () -> Hash[Symbol, untyped]
+  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: (?String? sqref, **untyped opts) -> void
+
+    # : (untyped key) -> untyped
+    def []: (untyped key) -> untyped
+
+    # : (untyped key, untyped value) -> untyped
+    def []=: (untyped key, untyped value) -> untyped
+
+    # : (?String? val) -> String?
+    def sqref: (?String? val) -> String?
+
+    # : (String val) -> String
+    def sqref=: (String val) -> String
+
+    alias range sqref
+
+    alias range= sqref=
+
+    # : (?untyped val) -> untyped
+    def type: (?untyped val) -> untyped
+
+    # : (untyped val) -> untyped
+    def type=: (untyped val) -> untyped
+
+    # : (?untyped val) -> untyped
+    def operator: (?untyped val) -> untyped
+
+    # : (untyped val) -> untyped
+    def operator=: (untyped val) -> untyped
+
+    # : (?untyped val) -> untyped
+    def formula1: (?untyped val) -> untyped
+
+    # : (untyped val) -> untyped
+    def formula1=: (untyped val) -> untyped
+
+    # : (?untyped val) -> untyped
+    def formula2: (?untyped val) -> untyped
+
+    # : (untyped val) -> untyped
+    def formula2=: (untyped val) -> untyped
+
+    # : (?bool? val) -> bool?
+    def allow_blank: (?bool? val) -> bool?
+
+    # : (bool val) -> bool
+    def allow_blank=: (bool val) -> bool
+
+    # : (?bool? val) -> bool?
+    def show_input_message: (?bool? val) -> bool?
+
+    # : (bool val) -> bool
+    def show_input_message=: (bool val) -> bool
+
+    # : (?bool? val) -> bool?
+    def show_error_message: (?bool? val) -> bool?
+
+    # : (bool val) -> bool
+    def show_error_message=: (bool val) -> bool
+
+    # : (?String? val) -> String?
+    def error_title: (?String? val) -> String?
+
+    # : (String val) -> String
+    def error_title=: (String val) -> String
+
+    # : (?String? val) -> String?
+    def error_message: (?String? val) -> String?
+
+    # : (String val) -> String
+    def error_message=: (String val) -> String
+
+    alias error error_message
+
+    alias error= error_message=
+
+    # : (?String? val) -> String?
+    def prompt_title: (?String? val) -> String?
+
+    # : (String val) -> String
+    def prompt_title=: (String val) -> String
+
+    # : (?String? val) -> String?
+    def prompt_message: (?String? val) -> String?
+
+    # : (String val) -> String
+    def prompt_message=: (String val) -> String
+
+    alias prompt prompt_message
+
+    alias prompt= prompt_message=
+
+    # : (?untyped val) -> untyped
+    def error_style: (?untyped val) -> untyped
+
+    # : (untyped val) -> untyped
+    def error_style=: (untyped val) -> untyped
+
+    # : () -> Hash[Symbol, untyped]
+    def to_h: () -> Hash[Symbol, untyped]
+  end
 end