xlsxrb 0.1.13 → 0.1.14

data/lib/xlsxrb/stream_writer.rb

@@ -220,15 +220,30 @@ module Xlsxrb
       # @param hidden [Boolean] Whether the row is hidden.
       # @param custom_height [Boolean] Whether to flag as custom height.
       # @param outline_level [Integer, nil] Grouping/outline level (0 - 7).
+      # @param collapsed [Boolean] Whether the row is collapsed.
       # @return [void]
       # @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)
         raise Error, "Sheet '#{@sheet_name}' is no longer active. In streaming mode, you cannot write to a previous sheet." if @writer.current_sheet != @sheet_name
 
-        @writer.row(values, styles: styles, height: height, hidden: hidden, custom_height: custom_height, outline_level: outline_level)
+        @writer.row(values, styles: styles, height: height, hidden: hidden, custom_height: custom_height, 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
-      alias << row
 
       # Configures column width and properties.
       #
@@ -287,7 +302,7 @@ module Xlsxrb
       # @param location [String, nil] Destination location / URL (keyword alternative).
       # @return [void]
       # @api public
-      #: (String 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(...)
         raise Error, "Sheet '#{@sheet_name}' is no longer active. In streaming mode, you cannot write to a previous sheet." if @writer.current_sheet != @sheet_name
 
@@ -460,6 +475,30 @@ module Xlsxrb
         @writer.sparkline_group(...)
       end
 
+      # Adds a single sparkline to the sheet.
+      #
+      # @example Add a line sparkline
+      #   s.add_sparkline(location: "F1", range: "A1:E1")
+      #
+      # @example Add a column sparkline with high/low markers
+      #   s.add_sparkline(location: "F2", range: "A2:E2", type: :column, high: true, low: true)
+      #
+      # @example Add a win/loss sparkline
+      #   s.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(...)
+        raise Error, "Sheet '#{@sheet_name}' is no longer active. In streaming mode, you cannot write to a previous sheet." if @writer.current_sheet != @sheet_name
+
+        @writer.add_sparkline(...)
+      end
+
       # Sets workbook-level properties.
       #
       # @param opts [Hash] Workbook property options.
@@ -554,6 +593,32 @@ module Xlsxrb
 
         @writer.print_titles(...)
       end
+
+      # Sets repeating title rows to appear at the top of each printed page.
+      #
+      # @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).
+      # @return [void]
+      # @api public
+      #: (Integer | String first, ?(Integer | String)? last) -> void
+      def repeat_rows(first, last = nil)
+        raise Error, "Sheet '#{@sheet_name}' is no longer active. In streaming mode, you cannot write to a previous sheet." if @writer.current_sheet != @sheet_name
+
+        @writer.repeat_rows(first, last, sheet: @sheet_name)
+      end
+
+      # Sets repeating title columns to appear at the left of each printed page.
+      #
+      # @param first [Integer, String] First column index (0-based) or column name/range.
+      # @param last [Integer, String, nil] Optional last column index/name.
+      # @return [void]
+      # @api public
+      #: (Integer | String first, ?(Integer | String)? last) -> void
+      def repeat_columns(first, last = nil)
+        raise Error, "Sheet '#{@sheet_name}' is no longer active. In streaming mode, you cannot write to a previous sheet." if @writer.current_sheet != @sheet_name
+
+        @writer.repeat_columns(first, last, sheet: @sheet_name)
+      end
       # simplecov:enable
 
       # Splits sheet view into panes.
@@ -829,7 +894,8 @@ module Xlsxrb
       @sheet_entry_started = false
       @current_row_buffer = String.new(capacity: 65_536)
       @current_sheet_io = StringIO.new(@current_row_buffer)
-      @current_row_writer = Ooxml::WorksheetWriter.new(@current_sheet_io)
+      date1904 = @workbook_properties&.[](:date1904) ? true : false
+      @current_row_writer = Ooxml::WorksheetWriter.new(@current_sheet_io, date1904: date1904)
       @current_row_writer.instance_variable_set(:@started, true)
 
       @current_columns = []
@@ -883,7 +949,18 @@ module Xlsxrb
         row_buf.clear
       end
 
-      @current_row_writer = Ooxml::WorksheetWriter.new(zip_io)
+      if @current_columns && !@current_columns.empty? && @style_name_to_id
+        @current_columns.each do |col|
+          s = col[:style] || col[:style_index]
+          if s.is_a?(Symbol) || s.is_a?(String)
+            resolved = @style_name_to_id[s] || @style_name_to_id[s.to_s]
+            col[:style] = resolved if resolved
+          end
+        end
+      end
+
+      date1904 = @workbook_properties&.[](:date1904) ? true : false
+      @current_row_writer = Ooxml::WorksheetWriter.new(zip_io, date1904: date1904)
       @current_row_writer.start(
         columns: @current_columns,
         sheet_properties: @current_sheet_properties.empty? ? nil : @current_sheet_properties,
@@ -906,8 +983,8 @@ module Xlsxrb
     # @param outline_level [Integer, nil] Grouping/outline level (0 - 7).
     # @return [void]
     # @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)
       sheet if @current_sheet.nil?
 
       row_index = @current_row_index
@@ -931,36 +1008,60 @@ module Xlsxrb
       raise ArgumentError, "Row contains #{values.length} columns, exceeding Excel limit of 16_384 columns" if @strict_excel_mode && values.length > 16_384
 
       attrs = nil
-      if height || hidden || outline_level
+      if height || hidden || outline_level || collapsed
         attrs = {}
         attrs[:height] = height if height
         attrs[:hidden] = true if hidden
         attrs[:custom_height] = custom_height || !height.nil?
+        attrs[:collapsed] = true if collapsed
         attrs[:outline_level] = outline_level if outline_level
       end
 
       @current_row_writer.write_row_values(row_index, values, styles: styles, style_map: @style_name_to_id, sst: @sst, sst_index: @sst_index, attrs: attrs)
       start_sheet_entry if !@sheet_entry_started && @current_row_buffer.bytesize >= 65_536
     end
-    alias << row
+    alias add_row row
+
+    # Appends a row to the worksheet and returns self for chaining.
+    #
+    # @example
+    #   writer << ["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.
     #
     # @param index [Integer, String, Range, Array] Column index (0-based) or letter ("A".."D").
     # @param width [Float, Integer, nil] Column width in character units (0 - 255).
     # @param hidden [Boolean] Whether the column is hidden.
-    # @param custom_width [Boolean] Whether custom width is set.
-    # @param outline_level [Integer, nil] Grouping/outline level.
+    # @param style [Integer, Symbol, String, nil] Column style format or index.
     # @return [void]
     # @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)
 
       sheet if @current_sheet.nil?
 
+      style_id = if @style_name_to_id && style
+                   @style_name_to_id[style] || @style_name_to_id[style.to_s] || style
+                 else
+                   style
+                 end
       DslHelpers.normalize_column_indices(index).each do |idx|
-        @current_columns << { index: idx, width: width, hidden: hidden, custom_width: custom_width || !width.nil?, outline_level: outline_level }
+        entry = { index: idx, width: width, hidden: hidden, custom_width: custom_width || !width.nil?, outline_level: outline_level }
+        if style_id
+          entry[:style] = style_id
+          @current_row_writer&.set_column_style(idx, style_id)
+        end
+        @current_columns << entry
       end
     end
 
@@ -993,9 +1094,18 @@ module Xlsxrb
     # @param location [String, nil] Internal location.
     # @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)
       sheet if @current_sheet.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
+        @current_hyperlinks << link
+        return
+      end
       link = { cell: cell }
       link[:url] = url if url
       link[:display] = display if display
@@ -1134,6 +1244,38 @@ module Xlsxrb
       @current_sparkline_groups << group
     end
 
+    # Adds a single sparkline to the sheet.
+    #
+    # @example Add a line sparkline
+    #   writer.add_sparkline(location: "F1", range: "A1:E1")
+    #
+    # @example Add a column sparkline with high/low markers
+    #   writer.add_sparkline(location: "F2", range: "A2:E2", type: :column, high: true, low: true)
+    #
+    # @example Add a win/loss sparkline
+    #   writer.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.
     #
     # @param range [String, Hash, nil] Cell range (e.g. "A1:B2") or hash of coordinates.
@@ -1398,6 +1540,11 @@ module Xlsxrb
     #: (?rows: String?, ?cols: String?, ?sheet: String?) -> void
     def print_titles(rows: nil, cols: nil, sheet: nil)
       sheet_name = sheet || @current_sheet || "Sheet1"
+      existing = @defined_names.find { |dn| dn[:name] == "_xlnm.Print_Titles" && dn[:local_sheet_name] == sheet_name }
+      if existing && (rows.nil? || cols.nil?)
+        cols = Regexp.last_match(1).delete("$") if cols.nil? && existing[:value] =~ /'[^']*'!\$([A-Za-z]+:\$[A-Za-z]+)/
+        rows = Regexp.last_match(1).delete("$") if rows.nil? && existing[:value] =~ /'[^']*'!\$([0-9]+:\$[0-9]+)/
+      end
       parts = []
       parts << "'#{sheet_name}'!$#{cols.sub(":", ":$")}" if cols
       parts << "'#{sheet_name}'!$#{rows.sub(":", ":$")}" if rows
@@ -1406,6 +1553,55 @@ module Xlsxrb
       defined_name("_xlnm.Print_Titles", value, sheet: sheet_name)
     end
 
+    # Sets repeating title rows for pagination on the current or named sheet.
+    #
+    # @example Repeat first row
+    #   stream.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(first, last = nil, sheet: nil)
+      rows_str = if first.is_a?(String)
+                   first.include?(":") ? first : "#{first}:#{last || first}"
+                 else
+                   last ||= first
+                   "#{first + 1}:#{last + 1}"
+                 end
+      print_titles(rows: rows_str, sheet: sheet)
+    end
+
+    # Sets repeating title columns for pagination on the current or named sheet.
+    #
+    # @example Repeat columns A through C
+    #   stream.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(first, last = nil, sheet: 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(cols: cols_str, sheet: sheet)
+    end
+
     # Sets workbook protection.
     #
     # @param opts [Hash] Protection options.