xlsxrb 0.1.13 → 0.1.14

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 = []
@@ -44,8 +46,12 @@ module Xlsxrb
       @sheet_view = {}
       @row_breaks = []
       @col_breaks = []
+      @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 +87,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 +156,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 +167,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 +182,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 +206,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 +236,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 +284,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
@@ -380,6 +423,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 +567,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).
@@ -614,10 +781,54 @@ module Xlsxrb
       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[: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
       )
     end